Rename editor fields

example/lib/board_editor_page.dart

@@ -17,7 +17,7 @@ class _BoardEditorPageState extends State<BoardEditorPage> {
   /// 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<BoardEditorPage> {
       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<BoardEditorPage> {
           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(

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<Piece>], 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<ChessBoardEditor> {
                       ),
                     ),
                   ),
-                if (widget.pointerToolMode == PointerToolMode.drag &&
+                if (widget.pointerMode == EditorPointerMode.drag &&
                     piece != null)
                   Draggable(
                     hitTestBehavior: HitTestBehavior.translucent,
@@ -187,12 +193,12 @@ class _BoardEditorState extends State<ChessBoardEditor> {
   }
 
   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);
     }
   }
 }

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<SquareId> 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,
     ),