diff --git a/Changes.md b/Changes.md index 61c19e2..e1bd1f7 100644 --- a/Changes.md +++ b/Changes.md @@ -28,7 +28,7 @@ end * [`app.apiVersion`](api/app.md#appapiversion) is `33` * Added `Dialog:separator()` more in line with other widgets [#4989](https://github.com/aseprite/aseprite/issues/4989) (thanks to [@MapleGecko](https://github.com/aseprite/aseprite/pull/5181)) -* Added uuid field to layers [#5033](https://github.com/aseprite/aseprite/issues/5033) +* Added [uuid field](api/layer.md#layeruuid) to layers [#5033](https://github.com/aseprite/aseprite/issues/5033) * Added `os.rename()` and `os.remove()` functions * Added `fitCriteria` parameter to `app.command.ChangePixelFormat` command [#4781](https://github.com/aseprite/aseprite/issues/4781) * Fixed `cel.image:clear()` cannot be undone [#5015](https://github.com/aseprite/aseprite/issues/5015) @@ -37,9 +37,9 @@ end ## v1.3.13 * [`app.apiVersion`](api/app.md#appapiversion) is `32` -* New `app.clipboard` API [#2073](https://github.com/aseprite/aseprite/issues/2073) -* New `beforesitechange` event [#4785](https://github.com/aseprite/aseprite/issues/4785) -* New `plugin.version` and `plugin.displayName` properties [#4904](https://github.com/aseprite/aseprite/issues/4904) +* New [`app.clipboard`](api/app_clipboard.md#appclipboard) API [#2073](https://github.com/aseprite/aseprite/issues/2073) +* New [`beforesitechange`](api/app.md#appevents) event [#4785](https://github.com/aseprite/aseprite/issues/4785) +* New [`plugin.version`](api/plugin.md#pluginversion) and [`plugin.displayName`](api/plugin.md#plugindisplayname) properties [#4904](https://github.com/aseprite/aseprite/issues/4904) * Don't allow to set invalid pixel ratios for sprites [#3285](https://github.com/aseprite/aseprite/issues/3285) * Fixed `Image:drawImage()` when `BlendMode.SRC` is used [#5001](https://github.com/aseprite/aseprite/issues/5001) @@ -52,20 +52,20 @@ end ## v1.3.11-beta1 * [`app.apiVersion`](api/app.md#appapiversion) is `30` -* Added `GraphicsContext` for images: `Image.context` property [#4330](https://github.com/aseprite/aseprite/issues/4330) +* Added `GraphicsContext` for images: [`Image.context`](api/image.md#imagecontext) property [#4330](https://github.com/aseprite/aseprite/issues/4330) * Added `ui`/`flatten`/`filename` parameters to `app.command.DuplicateSprite` command [#4755](https://github.com/aseprite/aseprite/issues/4755) ## v1.3.10 * [`app.apiVersion`](api/app.md#appapiversion) is `30` -* Added `app.editor.zoom`/`scroll` properties [#4722](https://github.com/aseprite/aseprite/issues/4722) -* New option (`Dialog:show{ hand=true }`) to enable Hand tool in the active editor with a modal dialog (thanks to [@lampysprites](https://github.com/aseprite/aseprite/pull/4465)) +* Added [`app.editor.zoom`](api/editor.md#editorzoom)/[`scroll`](api/editor.md#editorscroll) properties [#4722](https://github.com/aseprite/aseprite/issues/4722) +* New option ([`Dialog:show{ hand=true }`](api/dialog.md#dialogshow)) to enable Hand tool in the active editor with a modal dialog (thanks to [@lampysprites](https://github.com/aseprite/aseprite/pull/4465)) ## v1.3.9.2 * [`app.apiVersion`](api/app.md#appapiversion) is `29` -* New `app.fgTile`/`bgTile` properties to get/set the foreground/background tile [#4403](https://github.com/aseprite/aseprite/issues/4403) -* Added `Site.tilemapMode` property +* New [`fgTile`](api/app.md#appfgtile)/[`bgTile`](api/app.md#appbgtile) properties to get/set the foreground/background tile [#4403](https://github.com/aseprite/aseprite/issues/4403) +* Added [`Site.tilemapMode`](api/site.md#sitetilemapmode) property * Added `x` and `y` params to `app.command.Paste()` * Fixed `app.command.Cut`/`Paste` in `-batch` mode [#4354](https://github.com/aseprite/aseprite/issues/4354) * Fixed `app.command.Cancel()` command when used from scripts diff --git a/README.md b/README.md index 636155e..a7a421d 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ a little experiment, so you have six options to approach your idea: Globals namespaces * [app](api/app.md#app) + * [app.clipboard](api/app_clipboard.md#appclipboard) * [app.command](api/app_command.md#appcommand) * [app.fs](api/app_fs.md#appfs) * [app.os](api/app_os.md#appos) @@ -75,6 +76,7 @@ Classes/objects * [Events](api/events.md#events) * [Frame](api/frame.md#frame) * [GraphicsContext](api/graphicscontext.md#graphicscontext) + * [Grid](api/grid.md#grid) * [Image](api/image.md#image) * [ImageSpec](api/imagespec.md#imagespec) * [KeyEvent](api/keyevent.md#keyevent) @@ -109,6 +111,6 @@ Lua libraries * [Table Manipulation](https://www.lua.org/manual/5.3/manual.html#6.6) * [Mathematical Functions](https://www.lua.org/manual/5.3/manual.html#6.7) * [Operating System Facilities](https://www.lua.org/manual/5.3/manual.html#6.9) - * Some functions like `os.remove`, `os.rename`, `os.exit`, `os.tmpname` are not available yet + * Some functions like `os.exit`, `os.tmpname` are not available yet * Other functions like `os.execute` and `io.open` will ask for permissions to the user * [The Debug Library](https://www.lua.org/manual/5.3/manual.html#6.10) diff --git a/api/app.md b/api/app.md index 5ee5ed4..4795921 100644 --- a/api/app.md +++ b/api/app.md @@ -97,6 +97,14 @@ Gets or sets the current foreground [color](color.md#color). Gets or sets the current background [color](color.md#color). Remember that some commands use the background color to clear the active layer. +## app.fgTile + +Gets or sets the current foreground [tile](tile.md#tile). + +## app.bgTile + +Gets or sets the current background [tile](tile.md#tile). + ## app.isUIAvailable Returns true if the UI is available. E.g. if this is true you can use @@ -329,6 +337,7 @@ app.events:on('sitechange', Available events for `app`: * `'sitechange'`: When the user selects other sprite, layer, or frame. +* `'beforesitechange'`: Before the user switches to other sprite, layer, or frame. * `'fgcolorchange'`: When the [Foreground color](https://www.aseprite.org/docs/color-bar/#foreground-color) in the color bar is changed. * `'bgcolorchange'`: When the [Background color](https://www.aseprite.org/docs/color-bar/#background-color) in the color bar is changed. * `'beforecommand'`: Before executing any command in the program. diff --git a/api/app_clipboard.md b/api/app_clipboard.md new file mode 100644 index 0000000..9a4a78f --- /dev/null +++ b/api/app_clipboard.md @@ -0,0 +1,71 @@ +## app.clipboard + +A set of functions to handle the clipboard. + +When calling a function with clipboard write access in a script, Aseprite will ask the user if they want to allow the function to run or stop the script. + +![security popup](image/security.png) + +## app.clipboard.text + +```lua +local text = app.clipboard.text +``` + +Gets or sets the clipboard text. Returns `nil` if there is no text. + +## app.clipboard.image + +```lua +local image = app.clipboard.image +``` + +Gets or sets the clipboard [image](image.md#image). Returns `nil` if there is no image. + +## app.clipboard.content + +```lua +local content = app.clipboard.content +``` + +Gets the content of the clipboard, as a table. Values: + +* `image`: An [image](image.md#image) object or `nil` +* `selection`: A [selection](selection.md#selection) object or `nil` +* `palette`: A [palette](palette.md#palette) object or `nil` +* `tileset`: A [tileset](tileset.md#tileset) object or `nil` +* `text`: A string or `nil` + +Depending on what is copied, each value will be set differently. Case table: + +| |An image is copied in Aseprite |An image is copied externally|Text is copied|A portion of the Palette is copied | +|-------------|------------------------------------|-----------------------------|--------------|---------------------------------------------------------| +|`image` |[Image](image.md#image) |[Image](image.md#image) |`nil` |`nil` | +|`selection`|[Selection](selection.md#selection) |`nil` |`nil` |`nil` | +|`palette` |Sprite [palette](palette.md#palette)|`nil` |`nil` |`nil` | +|`tileset` |`nil` |`nil` |`nil` |`nil` | +|`text` |`nil` |`nil` |String |String of selected colors in hex codes, seperated by `\n`| + +## app.clipboard.hasText + +```lua +local hasText = app.clipboard.hasText +``` + +Returns true if the last item copied to the clipboard was text. + +## app.clipboard.hasImage + +```lua +local hasImage = app.clipboard.hasImage +``` + +Returns true if the last item copied to the clipboard was an [image](image.md#image). + +## app.clipboard.clear() + +```lua +app.clipboard.clear() +``` + +Clears the clipboard. \ No newline at end of file diff --git a/api/app_fs.md b/api/app_fs.md index 9bbd8ec..cb5db1c 100644 --- a/api/app_fs.md +++ b/api/app_fs.md @@ -1,6 +1,6 @@ # app.fs -A set of function to handle file names and the file system. +A set of functions to handle file names and the file system. # Path & File Name Manipulation diff --git a/api/app_os.md b/api/app_os.md index 099461f..70c86df 100644 --- a/api/app_os.md +++ b/api/app_os.md @@ -1,6 +1,6 @@ # app.os -A set of function to get properties about the running Operating System +A set of functions to get properties about the running Operating System platform. ## app.os.name diff --git a/api/dialog.md b/api/dialog.md index a106e32..463998a 100644 --- a/api/dialog.md +++ b/api/dialog.md @@ -344,6 +344,7 @@ dlg:show{ wait=false, bounds=Rectangle(), autoscrollbars=false, + hand=false } ``` @@ -367,6 +368,8 @@ to make it go out of the window/screen (depending if you are using single window UI or multiple windows UI) then scrollbars will be shown into your dialog when its content doesn't fit its bounds. +If `{ hand=true }`, this enables the hand tool in the editor while the dialog is active. See the *Edit > Replace Color* menu for an example. Only useful if `{ wait=true }`. + ## Dialog:slider() ```lua diff --git a/api/editor.md b/api/editor.md index 903ed02..d2db60d 100644 --- a/api/editor.md +++ b/api/editor.md @@ -30,6 +30,26 @@ local point = app.editor.mousePos Returns a [point](point.md#point) indicating the mouse position on the screen. +## Editor.zoom + +```lua +app.editor.zoom = 0.33333333333 +local zoom = app.editor.zoom + +local percentage = zoom * 100 -- 33.3% +``` + +Gets or sets the editor zoom as a float. To get a percentage, multiply by 100. + +## Editor.scroll + +```lua +local scroll = app.editor.scroll +app.editor.scroll = scroll +``` + +Gets or sets the editor scroll (coordinates of sprite pixel to center the editor at) as a table, with values `x` and `y` as floats. + ## Editor:askPoint() ```lua diff --git a/api/grid.md b/api/grid.md new file mode 100644 index 0000000..19a9583 --- /dev/null +++ b/api/grid.md @@ -0,0 +1,26 @@ +## Grid + +This is an object that defines the grid for a [tileset](tileset.md#tileset). + +## Grid() + +```lua +Grid() +Grid(otherGrid) +``` + +## Grid.tileSize + +```lua +local tileSize = grid.tileSize +``` + +Returns the [tile](tile.md#tile) width and height of a [tileset](tileset.md#tileset), as a [size](size.md#size). + +## Grid.origin + +```lua +local point = grid.origin +``` + +Returns the origin of the grid as a [point](point.md#point). \ No newline at end of file diff --git a/api/image.md b/api/image.md index 589b9f5..37c33d3 100644 --- a/api/image.md +++ b/api/image.md @@ -126,6 +126,14 @@ local cel = image.cel Returns the [cel](cel.md#cel) to which this image belongs or `nil` if this image is not associated to a cel. +## Image.context + +```lua +local gc = image.context +``` + +The [GraphicsContext](graphicscontext.md#graphicscontext) object for this image. + ## Image.bytes ```lua diff --git a/api/image/security.png b/api/image/security.png new file mode 100644 index 0000000..f9beb7f Binary files /dev/null and b/api/image/security.png differ diff --git a/api/layer.md b/api/layer.md index b03fcf2..9a7334b 100644 --- a/api/layer.md +++ b/api/layer.md @@ -78,6 +78,14 @@ stack in descending order. For example, a layer with index `1` will lie beneath a layer with index `2`, assuming the layers share the same parent. +## Layer.uuid + +```lua +local uuid = layer.uuid +``` + +Returns the [uuid](uuid.md#uuid) of the layer. + ## Layer.isImage Gets whether or not the layer contains [cels](cel.md#cel) with diff --git a/api/plugin.md b/api/plugin.md index ac8b639..6c99859 100644 --- a/api/plugin.md +++ b/api/plugin.md @@ -65,6 +65,14 @@ Extensions > Add Extension*. Name of the extension. +## Plugin.displayName + +Display name of the extension. + +## Plugin.version + +Version of the extension. + ## Plugin.path Path where the extension is installed. diff --git a/api/sprite.md b/api/sprite.md index 1a6066e..da49951 100644 --- a/api/sprite.md +++ b/api/sprite.md @@ -193,6 +193,19 @@ end An array of [slices](slice.md#slice). +## Sprite.tilesets + +```lua +for i,tileset in ipairs(s.tilesets) do + -- ... +end +for i = 1,#s.tilesets do + -- s.tilesets[i] +end +``` + +An array of [tilesets](tileset.md#tileset). + ## Sprite.backgroundLayer Returns the [background diff --git a/api/tileset.md b/api/tileset.md index d19b605..783621f 100644 --- a/api/tileset.md +++ b/api/tileset.md @@ -1,20 +1,49 @@ # Tileset +A set of [tiles](tile.md#tile). + ## Tileset.name -## Tileset.grid +```lua +local name = tileset.name +tileset.name = name +``` + +Gets or sets the name of this tileset. ## Tileset.baseIndex +```lua +local baseindex = tileset.baseIndex +tileset.baseIndex = baseindex +``` + +Gets or sets the base index of this tileset. + ## Tileset.color ## Tileset.data +```lua +local data = tileset.data +tileset.data = data +``` + +Gets or sets the user-defined data related to this tileset (a text string). + ## Tileset.properties Access user-defined and extension-defined [properties](properties.md#properties) of this tileset. +## Tileset.grid + +```lua +local grid = tileset.grid +``` + +Returns the [grid](grid.md#grid) of this tileset. + ## Tileset:tile() ```lua diff --git a/sidebar.md b/sidebar.md index 53f7bfa..4a6ef94 100644 --- a/sidebar.md +++ b/sidebar.md @@ -5,6 +5,7 @@ Globals namespaces * [app](api/app.md#app) + * [app.clipboard](api/app_clipboard.md#appclipboard) * [app.command](api/app_command.md#appcommand) * [app.fs](api/app_fs.md#appfs) * [app.os](api/app_os.md#appos) @@ -39,6 +40,7 @@ Classes/objects * [Events](api/events.md#events) * [Frame](api/frame.md#frame) * [GraphicsContext](api/graphicscontext.md#graphicscontext) + * [Grid](api/grid.md#grid) * [Image](api/image.md#image) * [ImageSpec](api/imagespec.md#imagespec) * [KeyEvent](api/keyevent.md#keyevent) @@ -62,5 +64,6 @@ Classes/objects * [Tool](api/tool.md#tool) * [TouchEvent](api/touchevent.md#touchevent) * [Version](api/version.md#version) + * [Uuid](api/uuid.md#uuid) * [WebSocket](api/websocket.md#websocket) * [Window](api/window.md#window)