diff --git a/example/lib/board_editor_page.dart b/example/lib/board_editor_page.dart index 7320898..14085d0 100644 --- a/example/lib/board_editor_page.dart +++ b/example/lib/board_editor_page.dart @@ -17,7 +17,7 @@ class _BoardEditorPageState extends State { /// The piece to add when a square is touched. If null, will delete the piece. dc.Piece? pieceToAddOnTouch; - PointerToolMode pointerMode = PointerToolMode.drag; + EditorPointerMode pointerMode = EditorPointerMode.drag; @override Widget build(BuildContext context) { @@ -35,8 +35,8 @@ class _BoardEditorPageState extends State { orientation: dc.Side.white, pieces: pieces, settings: settings, - pointerToolMode: pointerMode, - onTouchedSquare: (squareId) => setState(() { + pointerMode: pointerMode, + onEditedSquare: (squareId) => setState(() { if (pieceToAddOnTouch != null) { pieces[squareId] = pieceToAddOnTouch!; } else { @@ -60,18 +60,18 @@ class _BoardEditorPageState extends State { squareSize: boardEditor.squareSize, settings: settings, pieceEdition: - pointerMode == PointerToolMode.edit ? pieceToAddOnTouch : null, + pointerMode == EditorPointerMode.edit ? pieceToAddOnTouch : null, pieceTapped: (role) => setState(() { pieceToAddOnTouch = dc.Piece(role: role, color: side); - pointerMode = PointerToolMode.edit; + pointerMode = EditorPointerMode.edit; }), pointerMode: pointerMode, deleteTapped: () => setState(() { pieceToAddOnTouch = null; - pointerMode = PointerToolMode.edit; + pointerMode = EditorPointerMode.edit; }), pointerModeTapped: () => setState(() { - pointerMode = PointerToolMode.drag; + pointerMode = EditorPointerMode.drag; }), ); @@ -118,10 +118,10 @@ class PieceMenu extends StatelessWidget { /// The piece that is currently being edited. /// - /// If null while [pointerMode] is [PointerToolMode.edit], the user is in delete mode. + /// If null while [pointerMode] is [EditorPointerMode.edit], the user is in delete mode. final dc.Piece? pieceEdition; - final PointerToolMode pointerMode; + final EditorPointerMode pointerMode; final BoardEditorSettings settings; final Function(dc.Role role) pieceTapped; final Function() deleteTapped; @@ -135,7 +135,7 @@ class PieceMenu extends StatelessWidget { mainAxisSize: MainAxisSize.min, children: [ Container( - color: pointerMode == PointerToolMode.drag + color: pointerMode == EditorPointerMode.drag ? Colors.green : Colors.transparent, child: GestureDetector( @@ -173,7 +173,7 @@ class PieceMenu extends StatelessWidget { }, ).toList(), Container( - color: pointerMode == PointerToolMode.edit && pieceEdition == null + color: pointerMode == EditorPointerMode.edit && pieceEdition == null ? Colors.red : Colors.transparent, child: GestureDetector( diff --git a/lib/src/widgets/board_editor.dart b/lib/src/widgets/board_editor.dart index 64885fc..b05562b 100644 --- a/lib/src/widgets/board_editor.dart +++ b/lib/src/widgets/board_editor.dart @@ -9,7 +9,7 @@ import 'piece.dart'; import 'positioned_square.dart'; /// Controls the behavior of pointer events on the board editor. -enum PointerToolMode { +enum EditorPointerMode { /// The default mode where pieces can be dragged around the board. drag, @@ -22,9 +22,9 @@ enum PointerToolMode { /// /// This widget can be used as the basis for a fully fledged board editor, similar to https://lichess.org/editor. /// The logic for creating a board editor should be implemented by the consumer of this widget. -/// This widget only provides the visual representation of the board and the pieces on it, and responds to pointer events through the [onTouchedSquare], [onDroppedPiece], and [onDiscardedPiece] callbacks. +/// This widget only provides the visual representation of the board and the pieces on it, and responds to pointer events through the [onEditedSquare], [onDroppedPiece], and [onDiscardedPiece] callbacks. /// -/// Use the [pointerToolMode] property to switch between dragging pieces and adding/removing pieces from the board using pan gestures. +/// Use the [pointerMode] property to switch between dragging pieces and adding/removing pieces from the board using pan gestures. /// /// A [writeFen] method is provided by this package to convert the current state /// of the board editor to a FEN string. @@ -34,9 +34,9 @@ class ChessBoardEditor extends StatefulWidget with BoardGeometry { required this.size, required this.orientation, required this.pieces, - this.pointerToolMode = PointerToolMode.drag, + this.pointerMode = EditorPointerMode.drag, this.settings = const BoardEditorSettings(), - this.onTouchedSquare, + this.onEditedSquare, this.onDroppedPiece, this.onDiscardedPiece, }); @@ -57,13 +57,17 @@ class ChessBoardEditor extends StatefulWidget with BoardGeometry { final BoardEditorSettings settings; /// The current mode of the pointer tool. - final PointerToolMode pointerToolMode; + final EditorPointerMode pointerMode; - /// Called when the given square was touched or hovered over. - final void Function(SquareId square)? onTouchedSquare; + /// Called when the given square was edited by the user. + /// + /// This is called when the user touches or hover over a square while in edit mode (i.e. [pointerMode] is [EditorPointerMode.edit]). + final void Function(SquareId square)? onEditedSquare; /// Called when a piece has been dragged to a new destination square. /// + /// This is active only when [pointerMode] is [EditorPointerMode.drag]. + /// /// If `origin` is not `null`, the piece was dragged from that square of the board editor. /// Otherwise, it was dragged from outside the board editor. /// Each square of the board is a [DragTarget], so to drop your own piece widgets @@ -72,6 +76,8 @@ class ChessBoardEditor extends StatefulWidget with BoardGeometry { onDroppedPiece; /// Called when a piece that was originally at the given `square` was dragged off the board. + /// + /// This is active only when [pointerMode] is [EditorPointerMode.drag]. final void Function(SquareId square)? onDiscardedPiece; @override @@ -107,7 +113,7 @@ class _BoardEditorState extends State { ), ), ), - if (widget.pointerToolMode == PointerToolMode.drag && + if (widget.pointerMode == EditorPointerMode.drag && piece != null) Draggable( hitTestBehavior: HitTestBehavior.translucent, @@ -187,12 +193,12 @@ class _BoardEditorState extends State { } void _onTouchedEvent(Offset localPosition) { - if (widget.pointerToolMode == PointerToolMode.drag) { + if (widget.pointerMode == EditorPointerMode.drag) { return; } final squareId = widget.offsetSquareId(localPosition); if (squareId != null) { - widget.onTouchedSquare?.call(squareId); + widget.onEditedSquare?.call(squareId); } } } diff --git a/test/widgets/board_editor_test.dart b/test/widgets/board_editor_test.dart index 44319ce..9b15465 100644 --- a/test/widgets/board_editor_test.dart +++ b/test/widgets/board_editor_test.dart @@ -57,15 +57,15 @@ void main() { }); testWidgets( - 'touching a square triggers the onTouchedSquare callback when the board pointer tool mode is `edit`', + 'touching a square triggers the onEditedSquare callback when the board pointer tool mode is `edit`', (WidgetTester tester) async { for (final orientation in Side.values) { SquareId? tappedSquare; await tester.pumpWidget( buildBoard( pieces: {}, - pointerToolMode: PointerToolMode.edit, - onTouchedSquare: (square) => tappedSquare = square, + pointerMode: EditorPointerMode.edit, + onEditedSquare: (square) => tappedSquare = square, orientation: orientation, ), ); @@ -83,13 +83,13 @@ void main() { }); testWidgets( - 'touching a square does not trigger the onTouchedSquare callback when the board pointer tool mode is `drag`', + 'touching a square does not trigger the onEditedSquare callback when the board pointer tool mode is `drag`', (WidgetTester tester) async { SquareId? tappedSquare; await tester.pumpWidget( buildBoard( pieces: {}, - onTouchedSquare: (square) => tappedSquare = square, + onEditedSquare: (square) => tappedSquare = square, ), ); @@ -100,14 +100,14 @@ void main() { expect(tappedSquare, null); }); - testWidgets('pan movements trigger the onTouchedSquare callback', + testWidgets('pan movements trigger the onEditedSquare callback', (WidgetTester tester) async { final Set touchedSquares = {}; await tester.pumpWidget( buildBoard( pieces: {}, - pointerToolMode: PointerToolMode.edit, - onTouchedSquare: (square) => touchedSquares.add(square), + pointerMode: EditorPointerMode.edit, + onEditedSquare: (square) => touchedSquares.add(square), ), ); @@ -252,8 +252,8 @@ void main() { Widget buildBoard({ required Pieces pieces, Side orientation = Side.white, - PointerToolMode pointerToolMode = PointerToolMode.drag, - void Function(SquareId square)? onTouchedSquare, + EditorPointerMode pointerMode = EditorPointerMode.drag, + void Function(SquareId square)? onEditedSquare, void Function(SquareId? origin, SquareId destination, Piece piece)? onDroppedPiece, void Function(SquareId square)? onDiscardedPiece, @@ -262,9 +262,9 @@ Widget buildBoard({ home: ChessBoardEditor( size: boardSize, orientation: orientation, - pointerToolMode: pointerToolMode, + pointerMode: pointerMode, pieces: pieces, - onTouchedSquare: onTouchedSquare, + onEditedSquare: onEditedSquare, onDiscardedPiece: onDiscardedPiece, onDroppedPiece: onDroppedPiece, ),