Add help and tooltips for tileset atlas mode

Signed-off-by: Tomas Slusny <[email protected]>

Author: deathbeam

docs/manual/editing-tilesets.rst

@@ -10,7 +10,7 @@ tileset.
 Two Types of Tileset
 --------------------
 
-A tileset is a collection of tiles. Tiled currently supports two types
+A tileset is a collection of tiles. Tiled currently supports three types
 of tilesets, which are chosen when creating a new tileset:
 
 Based on Tileset Image
@@ -21,6 +21,13 @@ Based on Tileset Image
    between or around their tiles or those that have extruded the border
    pixels of each tile to avoid color bleeding.
 
+Tileset Atlas
+   This tileset uses a single image but allows you to define custom tile
+   regions that can vary in size and position. This is useful for tilesets
+   with varied tile sizes, y-sorting, multi-tile objects, or when you need
+   to dynamically adjust tile boundaries. Tiles can be arranged, moved, and
+   resized using the *Rearrange Tiles* mode (see :ref:`rearranging-tiles`).
+
 Collection of Images
    In this type of tileset each tile refers to its own image file. It
    is useful when the tiles aren't the same size, or when the packing
@@ -175,6 +182,34 @@ both tile layers and tile objects.
    Collision shapes rendered on the map. This map is from `Owyn's Adventure
    <https://store.steampowered.com/app/1020940/Owyns_Adventure/>`__.
 
+.. _rearranging-tiles:
+
+Rearranging Tiles (Atlas Tilesets)
+-----------------------------------
+
+When working with a Tileset Atlas, you can customize the tile regions using the
+*Rearrange Tiles* mode. This mode allows you to move, resize, create, and delete
+tile regions within the tileset image. Click the *Rearrange Tiles* |rearrange-tiles-icon|
+button in the toolbar to enter this mode.
+
+When in Rearrange Tiles mode, the following mouse controls are available:
+
+* **Left-click and drag on a tile** - Moves the tile to a new position
+* **Left-click and drag on a tile corner** - Resizes the tile
+* **Left-click and drag on empty space** - Creates a new tile region
+* **Right-click and drag** - Deletes all tiles overlapping the selection area
+* **Hold Shift** - Disables grid snapping for precise positioning
+
+This is particularly useful for:
+
+* Creating tilesets with varied tile sizes
+* Implementing y-sorting with tiles of different heights
+* Defining multi-tile objects as single tiles
+* Adjusting tile boundaries after importing an image
+
+.. |rearrange-tiles-icon|
+   image:: ../../src/tiled/resources/images/22/stock-tool-move-22.png
+
 .. _tile-animation-editor:
 
 Tile Animation Editor

src/tiled/newtilesetdialog.ui

@@ -68,16 +68,25 @@
          <property name="text">
           <string>Based on Tileset Image</string>
          </property>
+         <property name="toolTip">
+          <string>A single image containing a grid of fixed-size tiles</string>
+         </property>
         </item>
         <item>
          <property name="text">
           <string>Tileset Atlas</string>
          </property>
+         <property name="toolTip">
+          <string>A single image with custom tile regions that can be rearranged (useful for varied tile sizes, y-sorting, etc.)</string>
+         </property>
         </item>
         <item>
          <property name="text">
           <string>Collection of Images</string>
          </property>
+         <property name="toolTip">
+          <string>A collection of individual tile images</string>
+         </property>
         </item>
        </widget>
       </item>

src/tiled/tileseteditor.cpp

@@ -377,6 +377,19 @@ void TilesetEditor::setCurrentDocument(Document *document)
 
         currentChanged(tilesetView->currentIndex());
         selectionChanged();
+        setRelocateTiles(mRelocateTiles->isChecked());
+
+        // Use detailed tooltip for atlas tileset
+        if (tilesetDocument && tilesetDocument->tileset()->isAtlas()) {
+            mRelocateTiles->setToolTip(tr("Rearrange Tiles") + QLatin1String("\n\n") +
+                                        tr("Left-click and drag to move tiles") + QLatin1String("\n") +
+                                        tr("Left-click tile corners to resize") + QLatin1String("\n") +
+                                        tr("Left-click empty space to create new tiles") + QLatin1String("\n") +
+                                        tr("Right-click and drag to delete tiles") + QLatin1String("\n") +
+                                        tr("Hold Shift to disable grid snapping"));
+        } else {
+            mRelocateTiles->setToolTip(tr("Rearrange Tiles"));
+        }
     } else {
         currentChanged(QModelIndex());
     }
@@ -956,6 +969,18 @@ void TilesetEditor::setRelocateTiles(bool relocateTiles)
     if (relocateTiles) {
         mWangDock->setVisible(false);
         mTileCollisionDock->setVisible(false);
+
+        // Only show rearrange mode hint for atlas tilesets
+        if (mCurrentTilesetDocument && mCurrentTilesetDocument->tileset()->isAtlas()) {
+            mStatusInfoLabel->setText(tr("Rearrange Mode: Left-click to move/resize tiles | Right-click to delete | Shift to disable snapping"));
+        }
+    } else {
+        // Restore atlas hint if we're viewing an atlas tileset
+        if (mCurrentTilesetDocument && mCurrentTilesetDocument->tileset()->isAtlas()) {
+            mStatusInfoLabel->setText(tr("Atlas Tileset: Use 'Rearrange Tiles' mode to customize tile regions"));
+        } else {
+            mStatusInfoLabel->clear();
+        }
     }
 }