Scripting: Added Tile.image for accessing a tile's image data

Usually one could load the image based on Tile.imageFileName, but when a
tile's image has been set directly using Tile.setImage, this is not
possible. This can happen for example when an importer has used this
function since there was no external image file to refer to, or it used
an unsupported image format.

Tile.image now provides convenient access to the tile's image, falling
back to the Tileset's image when the tile has no individual image.

As such, this function also provides access to the tileset's image,
which would ideally be available through Tileset.image, but this
property was already taken and used for the image file name. To free up
this property in the future it is now deprecated. Extensions should
switch to the new Tileset.imageFileName property.

Part of issue mapeditor#3630

NEWS.md

@@ -2,13 +2,14 @@
 
 * Added --project command-line parameter for use when exporting (#3797)
 * Scripting: Added API for working with worlds (#3539)
+* Scripting: Added Tile.image for accessing a tile's image data
+* Scripting: Made Tileset.margin and Tileset.tileSpacing writable
 * JSON format: Fixed tile order when loading a tileset using the old format
 * Godot export: Fixed positioning of tile collision shapes (by Ryan Petrie, #3862)
 * tmxrasterizer: Added --hide-object and --show-object arguments (by Lars Luz, #3819)
-* Scripting: Made Tileset.margin and Tileset.tileSpacing writable
 * tmxrasterizer: Added --frames and --frame-duration arguments to export animated maps as multiple images (#3868)
 * tmxviewer: Added support for viewing JSON maps (#3866)
-* Windows: Fixed the support for WebP images (updated to Qt 6.5.3, #3661)
+* Windows: Fixed the support for WebP images (updated to Qt 6.6.1, #3661)
 * Fixed mouse handling issue when zooming while painting (#3863)
 * Fixed possible crash after a scripted tool disappears while active
 * TMX format: Embedded images are now also supported on tilesets and image layers

docs/scripting-doc/index.d.ts

@@ -2431,6 +2431,17 @@ declare class Tile extends TiledObject {
    */
   imageFileName : string
 
+  /**
+   * Returns the image of this tile, or the image of its tileset if it doesn't
+   * have an individual one.
+   *
+   * You can assign an {@link Image} to this property to change the tile's
+   * image. See {@link setImage} for more information.
+   *
+   * @since 1.10.3
+   */
+  image: Image;
+
   /**
    * The source rectangle (in pixels) for this tile.
    *
@@ -2474,7 +2485,15 @@ declare class Tile extends TiledObject {
   /**
    * Sets the image of this tile.
    *
-   * @warning This function has no undo and does not affect the saved tileset!
+   * You should prefer to set the {@link imageFileName} when possible. This
+   * function is mostly useful when the image data is loaded from a custom
+   * format.
+   *
+   * If an image is set directly on a tile, instead of setting the {@link
+   * imageFileName}, when saving the tileset the image data will be embedded
+   * for formats that support this (currently only TMX/TSX).
+   *
+   * @warning This function has no undo!
    */
   setImage(image : Image) : void
 }
@@ -3454,6 +3473,13 @@ declare class Tileset extends Asset {
    * repeatedly setting up the tiles in response to changing parameters.
    *
    * @note Map files are supported tileset image source as well.
+   *
+   * @since 1.10.3
+   */
+  imageFileName : string
+
+  /**
+   * @deprecated Use {@link imageFileName} instead.
    */
   image : string
 
@@ -4716,6 +4742,7 @@ declare class ColorButton extends Qt.QWidget {
    */
   colorChanged: Signal<color>;
 }
+
 /**
  * Widget with a button which opens a file picker dialog
  * and displays the path in the dialog.
@@ -4740,11 +4767,11 @@ declare class FileEdit extends Qt.QWidget {
    */
   filter: FileFilter;
 }
+
 /**
  * A widget that displays an {@link Image} on your dialog.
  */
 declare class ImageWidget extends Qt.QWidget {
-
   /**
    * The image to be displayed in the widget
    */

src/tiled/editabletile.cpp

@@ -48,6 +48,11 @@ EditableTile::~EditableTile()
         setObject(nullptr);
 }
 
+ScriptImage *EditableTile::image() const
+{
+    return new ScriptImage(tile()->image().toImage());
+}
+
 EditableObjectGroup *EditableTile::objectGroup() const
 {
     if (!mAttachedObjectGroup) {

src/tiled/editabletile.h

@@ -42,6 +42,7 @@ class EditableTile : public EditableObject
     Q_PROPERTY(QSize size READ size)
     Q_PROPERTY(QString type READ className WRITE setClassName)  // compatibility with Tiled < 1.9
     Q_PROPERTY(QString imageFileName READ imageFileName WRITE setImageFileName)
+    Q_PROPERTY(Tiled::ScriptImage *image READ image WRITE setImage)
     Q_PROPERTY(QRect imageRect READ imageRect WRITE setImageRect)
     Q_PROPERTY(qreal probability READ probability WRITE setProbability)
     Q_PROPERTY(Tiled::EditableObjectGroup *objectGroup READ objectGroup WRITE setObjectGroup)
@@ -76,6 +77,7 @@ class EditableTile : public EditableObject
     int height() const;
     QSize size() const;
     QString imageFileName() const;
+    ScriptImage *image() const;
     QRect imageRect() const;
     qreal probability() const;
     EditableObjectGroup *objectGroup() const;

src/tiled/editabletileset.cpp

@@ -245,7 +245,7 @@ void EditableTileset::setName(const QString &name)
         tileset()->setName(name);
 }
 
-void EditableTileset::setImage(const QString &imageFilePath)
+void EditableTileset::setImageFileName(const QString &imageFilePath)
 {
     if (isCollection() && tileCount() > 0) {
         ScriptManager::instance().throwError(QCoreApplication::translate("Script Errors", "Can't set the image of an image collection tileset"));

src/tiled/editabletileset.h

@@ -35,7 +35,8 @@ class EditableTileset : public EditableAsset
     Q_OBJECT
 
     Q_PROPERTY(QString name READ name WRITE setName)
-    Q_PROPERTY(QString image READ image WRITE setImage)
+    Q_PROPERTY(QString image READ imageFileName WRITE setImageFileName) // deprecated
+    Q_PROPERTY(QString imageFileName READ imageFileName WRITE setImageFileName)
     Q_PROPERTY(QList<QObject*> tiles READ tiles)
     Q_PROPERTY(QList<QObject*> wangSets READ wangSets)
     Q_PROPERTY(int tileCount READ tileCount)
@@ -108,7 +109,7 @@ class EditableTileset : public EditableAsset
     AssetType::Value assetType() const override { return AssetType::Tileset; }
 
     const QString &name() const;
-    QString image() const;
+    QString imageFileName() const;
     int tileCount() const;
     int columnCount() const;
     int nextTileId() const;
@@ -156,7 +157,7 @@ class EditableTileset : public EditableAsset
 
 public slots:
     void setName(const QString &name);
-    void setImage(const QString &imageFilePath);
+    void setImageFileName(const QString &imageFilePath);
     void setTileWidth(int width);
     void setTileHeight(int height);
     void setTileSize(QSize size);
@@ -199,7 +200,7 @@ inline const QString &EditableTileset::name() const
     return tileset()->name();
 }
 
-inline QString EditableTileset::image() const
+inline QString EditableTileset::imageFileName() const
 {
     return tileset()->imageSource().toString(QUrl::PreferLocalFile);
 }