Scripting: Added tiled.color to create color values

Supported forms are tiled.color(name), which supports for example "red"
or "#ff0000" as color names, or tiled.color(r,g,b,a), with values from
0-1.

Unfortunately, the similar Qt.color and Qt.rgba functions can't be used
because they require the QtQuick module to be loaded (see
QQuickColorProvider in src/quick/util/qquickglobal.cpp). They would work
only when the Tiled extensions were written in QML and imported the
QtQuick module. Tiled could provide its own QQmlColorProvider
implementation, but not without relying on private Qt headers.

Object.setColorProperty is now no longer necessary and has hence been
deprecated.

NEWS.md

@@ -13,6 +13,7 @@
 * Scripting: Added Image.copy overload that takes a rectangle
 * Scripting: Added Tileset.imageFileName and ImageLayer.imageFileName
 * Scripting: Added FilePath.localFile and FileEdit.fileName (string alternatives to Qt.QUrl properties)
+* Scripting: Added tiled.color to create color values
 * Scripting: Made Tileset.margin and Tileset.tileSpacing writable
 * Scripting: Restored compatibility for MapObject.polygon (#3845)
 * Scripting: Fixed issues with editing properties after setting class values from script

docs/scripting-doc/index.d.ts

@@ -391,12 +391,12 @@ declare namespace Qt {
      * Controls whether this widget is visible.
      * When toggling this property, the dialog layout will automatically adjust itself
      * based on the visible widgets.
-     * Qt documentation: [QWidget.visible](https://doc.qt.io/qt-6/qwidget.html#visible-prop);
+     * Qt documentation: [QWidget::visible](https://doc.qt.io/qt-6/qwidget.html#visible-prop);
      */
     visible: boolean;
     /**
      * If false, the widget cannot be interacted with.
-     * Qt documentation: [QWidget.enabled](https://doc.qt.io/qt-6/qwidget.html#enabled-prop)
+     * Qt documentation: [QWidget::enabled](https://doc.qt.io/qt-6/qwidget.html#enabled-prop)
      */
     enabled: boolean;
     /**
@@ -992,7 +992,7 @@ declare class ObjectGroup extends Layer {
 /**
  * A type alias used to describe the possible values in object properties.
  */
-type TiledObjectPropertyValue = number | string | boolean | ObjectRef | FilePath | MapObject | PropertyValue | undefined
+type TiledObjectPropertyValue = number | string | boolean | color | ObjectRef | FilePath | MapObject | PropertyValue | undefined
 
 /**
  * An interface used to describe object properties.
@@ -1038,16 +1038,15 @@ declare class TiledObject {
   property(name: string): TiledObjectPropertyValue;
 
   /**
-   * Sets the value of the custom property with the given name. Supported
-   * types are `bool`, `number`, `string`, {@link FilePath},
-   * {@link ObjectRef}, {@link MapObject} and {@link PropertyValue}.
+   * Sets the value of the custom property with the given name.
+   *
+   * Supported types are `bool`, `number`, `string`, {@link color},
+   * {@link FilePath}, {@link ObjectRef}, {@link MapObject} and
+   * {@link PropertyValue}.
    *
    * @note When setting a `number`, the property type will be set to either
    * `int` or `float`, depending on whether it is a whole number. To force
    * the property to be `float`, use {@link setFloatProperty}.
-   *
-   * @note This function does not support setting `color` properties. Use
-   * {@link setColorProperty} instead.
    */
   setProperty(name: string, value: TiledObjectPropertyValue): void;
 
@@ -1059,16 +1058,14 @@ declare class TiledObject {
    * a member of the previous member's value. The last name in the list
    * identifies the property to set.
    *
-   * Supported types are `bool`, `number`, `string`, {@link FilePath},
-   * {@link ObjectRef}, {@link MapObject} and {@link PropertyValue}.
+   * Supported types are `bool`, `number`, `string`, {@link color},
+   * {@link FilePath}, {@link ObjectRef}, {@link MapObject} and
+   * {@link PropertyValue}.
    *
    * @note When setting a `number`, the property type will be set to either
    * `int` or `float`, depending on whether it is a whole number. To force
    * the property to be `float`, use {@link setFloatProperty}.
    *
-   * @note This function does not support setting `color` properties. Use
-   * {@link setColorProperty} instead.
-   *
    * @since 1.11
    */
   setProperty(path: string[], value: TiledObjectPropertyValue): void;
@@ -1080,6 +1077,7 @@ declare class TiledObject {
    * The color is specified as a string "#RGB", "#RRGGBB" or "#AARRGGBB".
    *
    * @since 1.10
+   * @deprecated Use {@link setProperty} with a value created by {@link tiled.color} instead.
    */
   setColorProperty(name: string, value: color): void;
 
@@ -1092,6 +1090,7 @@ declare class TiledObject {
    * defaults to 255.
    *
    * @since 1.10
+   * @deprecated Use {@link setProperty} with a value created by {@link tiled.color} instead.
    */
   setColorProperty(name: string, red: number, green: number, blue: number, alpha?: number): void;
 
@@ -2155,10 +2154,10 @@ declare class Image {
   setPixel(x: number, y: number, index_or_rgb: number): void;
 
   /**
-   * Sets the color at the specified location to the given color by
-   * string (supports values like "#rrggbb").
+   * Sets the color at the specified location to the given color (supports
+   * values like "#rrggbb" or those created by {@link tiled.color}).
    */
-  setPixelColor(x: number, y: number, color: string): void;
+  setPixelColor(x: number, y: number, color: color): void;
 
   /**
    * Fills the image with the given 32-bit unsigned color value (ARGB) or color
@@ -2167,10 +2166,10 @@ declare class Image {
   fill(index_or_rgb: number): void;
 
   /**
-   * Fills the image with the given color by string (supports values like
-   * "#rrggbb").
+   * Fills the image with the given color (supports values like
+   * "#rrggbb" or those created by {@link tiled.color}).
    */
-  fill(color: string): void;
+  fill(color: color): void;
 
   /**
    * Loads the image from the given file name. When no format is given it
@@ -2214,10 +2213,10 @@ declare class Image {
   setColor(index: number, rgb: number): void;
 
   /**
-   * Sets the color at the given index in the color table to a color by
-   * string (supports values like "#rrggbb").
+   * Sets the color at the given index in the color table to a color (supports
+   * values like "#rrggbb" or those created by {@link tiled.color}).
    */
-  setColor(index: number, color: string) : void;
+  setColor(index: number, color: color) : void;
 
   /**
    * Sets the color table given by an array of either 32-bit color values
@@ -3505,6 +3504,8 @@ declare class WangSet extends TiledObject {
  * and "#AARRGGBB" respectively. For example, the color red corresponds to a
  * triplet of "#FF0000" and a slightly transparent blue to a quad of
  * "#800000FF".
+ *
+ * Use {@link tiled.color} to create a color value.
  */
 interface color {}
 
@@ -4518,6 +4519,24 @@ declare namespace tiled {
    */
   export function mapFormatForFile(fileName: string): MapFormat | undefined;
 
+  /**
+   * Creates a {@link color} based on the given color name (i.e. red or #ff0000).
+   *
+   * See [QColor::fromString](https://doc.qt.io/qt-6/qcolor.html#fromString)
+   * for the accepted color names.
+   *
+   * @since 1.11
+   */
+  export function color(name: string): color;
+
+  /**
+   * Creates a {@link color} with the RGB value r, g, b, and the alpha-channel
+   * (transparency) value of a (which defaults to 1.0).
+   *
+   * @since 1.11
+   */
+  export function color(r: number, g: number, b: number, a?: number): color;
+
   /**
    * Creates a {@link FilePath} object with the given URL.
    */

src/tiled/scriptmodule.cpp

@@ -240,6 +240,16 @@ MapEditor *ScriptModule::mapEditor() const
     return nullptr;
 }
 
+QColor ScriptModule::color(const QString &name) const
+{
+    return QColor::fromString(name);
+}
+
+QColor ScriptModule::color(float r, float g, float b, float a) const
+{
+    return QColor::fromRgbF(r, g, b, a);
+}
+
 FilePath ScriptModule::filePath(const QUrl &path) const
 {
     return { path };

src/tiled/scriptmodule.h

@@ -105,6 +105,8 @@ class ScriptModule : public QObject
     TilesetEditor *tilesetEditor() const;
     MapEditor *mapEditor() const;
 
+    Q_INVOKABLE QColor color(const QString &name) const;
+    Q_INVOKABLE QColor color(float r, float g, float b, float a = 1.0f) const;
     Q_INVOKABLE Tiled::FilePath filePath(const QUrl &path) const;
     Q_INVOKABLE Tiled::ObjectRef objectRef(int id) const;
     Q_INVOKABLE QVariant propertyValue(const QString &typeName, const QJSValue &value) const;