From dce20f5c75a56531a5afa1c0f307e3a6d02ae4e7 Mon Sep 17 00:00:00 2001 From: Crash Date: Sat, 27 Sep 2025 23:04:53 -0500 Subject: [PATCH 01/11] Update mousecursor changes change instances of "mouseCursor" to "mousecursor" --- api/dialog.md | 4 ++-- api/mousecursor.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/dialog.md b/api/dialog.md index 551a003..e004277 100644 --- a/api/dialog.md +++ b/api/dialog.md @@ -520,10 +520,10 @@ will be displayed the same at any UI scale. This property is enabled by default you don't need it you must explicitly set it to false. ```lua -dlg:modify{ id=canvasId, mouseCursor=newMouseCursor } +dlg:modify{ id=canvasId, mousecursor=newMouseCursor } ``` -Additionally, when using `Dialog:modify()`, the canvas `mouseCursor` property can be set to a [MouseCursor](mousecursor.md) value, changing the mouse cursor type. +Additionally, when using `Dialog:modify()`, the canvas `mousecursor` property can be set to a [MouseCursor](mousecursor.md) value, changing the mouse cursor type. ## Dialog:repaint() diff --git a/api/mousecursor.md b/api/mousecursor.md index 76d18ce..303dc45 100644 --- a/api/mousecursor.md +++ b/api/mousecursor.md @@ -3,7 +3,7 @@ Mouse cursor that can be set in a [canvas widget](dialog.md#dialogcanvas) using: ```lua -dialog:modify{ id=canvasId, mouseCursor=newMouseCursor } +dialog:modify{ id=canvasId, mousecursor=newMouseCursor } ``` ## MouseCursor.NONE From 5b1d46e9619bd6328c3fe76c70eba4ce515688be Mon Sep 17 00:00:00 2001 From: Crash Date: Sun, 28 Sep 2025 14:47:00 -0500 Subject: [PATCH 02/11] Add images to mousecursor --- api/mousecursor.md | 36 ++++++++++++++++++++++++++++++++ api/mousecursor/arrow.png | Bin 0 -> 237 bytes api/mousecursor/crosshair.png | Bin 0 -> 179 bytes api/mousecursor/grab.png | Bin 0 -> 222 bytes api/mousecursor/move.png | Bin 0 -> 254 bytes api/mousecursor/n_resize.png | Bin 0 -> 204 bytes api/mousecursor/ne_resize.png | Bin 0 -> 213 bytes api/mousecursor/none.png | Bin 0 -> 96 bytes api/mousecursor/not_allowed.png | Bin 0 -> 243 bytes api/mousecursor/pointer.png | Bin 0 -> 214 bytes api/mousecursor/se_resize.png | Bin 0 -> 238 bytes api/mousecursor/w_resize.png | Bin 0 -> 193 bytes 12 files changed, 36 insertions(+) create mode 100644 api/mousecursor/arrow.png create mode 100644 api/mousecursor/crosshair.png create mode 100644 api/mousecursor/grab.png create mode 100644 api/mousecursor/move.png create mode 100644 api/mousecursor/n_resize.png create mode 100644 api/mousecursor/ne_resize.png create mode 100644 api/mousecursor/none.png create mode 100644 api/mousecursor/not_allowed.png create mode 100644 api/mousecursor/pointer.png create mode 100644 api/mousecursor/se_resize.png create mode 100644 api/mousecursor/w_resize.png diff --git a/api/mousecursor.md b/api/mousecursor.md index 303dc45..ad5af35 100644 --- a/api/mousecursor.md +++ b/api/mousecursor.md @@ -8,36 +8,72 @@ dialog:modify{ id=canvasId, mousecursor=newMouseCursor } ## MouseCursor.NONE +![MouseCursor.NONE image (blank image)](mousecursor/none.png) + ## MouseCursor.ARROW +![MouseCursor.ARROW image](mousecursor/arrow.png) + ## MouseCursor.CROSSHAIR +![MouseCursor.CROSSHAIR image](mousecursor/crosshair.png) + ## MouseCursor.POINTER +![MouseCursor.POINTER image](mousecursor/pointer.png) + ## MouseCursor.NOT_ALLOWED +![MouseCursor.NOT_ALLOWED image](mousecursor/not_allowed.png) + ## MouseCursor.GRAB +![MouseCursor.GRAB image](mousecursor/grab.png) + ## MouseCursor.GRABBING +![MouseCursor.GRABBING image](mousecursor/grab.png) + ## MouseCursor.MOVE +![MouseCursor.MOVE image ](mousecursor/move.png) + ## MouseCursor.NS_RESIZE +![MouseCursor.NS_RESIZE image](mousecursor/n_resize.png) + ## MouseCursor.WE_RESIZE +![MouseCursor.WE_RESIZE image](mousecursor/w_resize.png) + ## MouseCursor.N_RESIZE +![MouseCursor.N_RESIZE image](mousecursor/n_resize.png) + ## MouseCursor.NE_RESIZE +![MouseCursor.NE_RESIZE image](mousecursor/ne_resize.png) + ## MouseCursor.E_RESIZE +![MouseCursor.E_RESIZE image](mousecursor/w_resize.png) + ## MouseCursor.SE_RESIZE +![MouseCursor.SE_RESIZE image](mousecursor/se_resize.png) + ## MouseCursor.S_RESIZE +![MouseCursor.S_RESIZE image](mousecursor/n_resize.png) + ## MouseCursor.SW_RESIZE +![MouseCursor.SW_RESIZE image](mousecursor/ne_resize.png) + ## MouseCursor.W_RESIZE +![MouseCursor.W_RESIZE image](mousecursor/w_resize.png) + ## MouseCursor.NW_RESIZE + +![MouseCursor.NW_RESIZE image](mousecursor/se_resize.png) diff --git a/api/mousecursor/arrow.png b/api/mousecursor/arrow.png new file mode 100644 index 0000000000000000000000000000000000000000..12628d3a0e0abd949dc11c8bbc863a9064381fc7 GIT binary patch literal 237 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}%ROBjLn2z= zPIKftpuoX0ecAnQ&-TCVY?IJT@;!3IGJJJ&jsgQ~vEupT*PqPat!Nf-%3e@YmBHa$ zhQpEfz@oc)I$ztaD0e0sy0OUGx9| literal 0 HcmV?d00001 diff --git a/api/mousecursor/crosshair.png b/api/mousecursor/crosshair.png new file mode 100644 index 0000000000000000000000000000000000000000..5e94764c7b8d9ae33b865030fcc0af2c2c3f4809 GIT binary patch literal 179 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}xt=bLArY-_ zryb-vV8G!#dE@{8Pv2~iHFL~(d%$^e^ukld9#LLSt}3hylOnP{yok{J=lne9VD_g9 zJk?k^w1kCf`FiRKm0Txyivet)rkAbZ1({g1K{P~`)a aEqaFY1C)Qd9moJ$%;4$j=d#Wzp$PydPD5S* literal 0 HcmV?d00001 diff --git a/api/mousecursor/grab.png b/api/mousecursor/grab.png new file mode 100644 index 0000000000000000000000000000000000000000..0c24807402d5a54a1fae41f5e9274c609434bfe2 GIT binary patch literal 222 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}Gdx`!Ln2z= zPWR?Jpupj>^yT06HnAo;IU*A-ELgi)`J=HN>((jzyJczxET26z5LhL+{pzVkYn4T5 zIkMJs4`gOEUy56}a=x3=+ymKc3*Hq=s5@ujx|Z z8*EpMKis)|@9+I?FmH)bc&N*FmQ&J&Sxh?OoUdP3a5AmAczDCH{Ryv`tnw_>!v$To Q0^P{q>FVdQ&MBb@0F2#K>;M1& literal 0 HcmV?d00001 diff --git a/api/mousecursor/move.png b/api/mousecursor/move.png new file mode 100644 index 0000000000000000000000000000000000000000..29a9004ae4d1b0676f9d7fdf0de955655f444c6b GIT binary patch literal 254 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}J3L(+Ln2zQ zPP@q0pupj}^y~lqKKggh29{i%^PsZGH&aGXH1ukaqEe7p(V9OurPbLyWZc4Lo=9d` zV>ad?2Yf>A+dr>tkrtTEc-X|RT=tov@I$r?-iTFu^X7h!6#gyAaIGc1 zZRUymhPS2K^EwNd^W-;FTT36|H~+AL@%F(PiU<4}#qIkU*Owa$udVoan73rPaaHxQ zz1(g5mc|>;RzE18U0o?WZPVr11yWU)ckA6bz$%u|9G1G}t2WRN44$rjF6*2UngCqo BVn6@@ literal 0 HcmV?d00001 diff --git a/api/mousecursor/n_resize.png b/api/mousecursor/n_resize.png new file mode 100644 index 0000000000000000000000000000000000000000..fb2df4222d518878023374a5d60e17cb9184f58d GIT binary patch literal 204 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}ZJsWUArY-_ z!yUOA40ybcrmx@rcX!+z3)h#c4Af8NDz}*U_^=k&Q$2;>+nS6qBlKg`-ky{zzf0C`^7$WA|%sO`E#8jY*7(8A5T-G@yGywo`u}S3s literal 0 HcmV?d00001 diff --git a/api/mousecursor/ne_resize.png b/api/mousecursor/ne_resize.png new file mode 100644 index 0000000000000000000000000000000000000000..038a2f89628c5a1f1572a18d1c422f78550f28ec GIT binary patch literal 213 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}{hlt4ArY-_ zr#kXA7;vy0{PAD^ap#h(4bh4VL!U98;FI?LQf`sZR~eDb2-66uWVH8!`ppG;^fVcyOc@wV4* z-I;WUms@Ylj+uGA!8N2v^{#_%LK#Et**#078}2g|95Z;y*2UbbYv8)$#9kqw(-=Hm L{an^LB{Ts5zTHww literal 0 HcmV?d00001 diff --git a/api/mousecursor/none.png b/api/mousecursor/none.png new file mode 100644 index 0000000000000000000000000000000000000000..7244b37f5c785d78eee7767f9a4aa6bef3263b07 GIT binary patch literal 96 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}Ql2i3ArY-_ n4>B?Wc})uc*XMaSfSB*u1QZw;-5D2j067evu6{1-oD!MdYG@ q%pdybPro)ZLH?|4)*emO3;Q4Iix{{~X8bgF9m7rr9&r=(!zXrZ2D**G M)78&qol`;+0QuHV=Kufz literal 0 HcmV?d00001 diff --git a/api/mousecursor/se_resize.png b/api/mousecursor/se_resize.png new file mode 100644 index 0000000000000000000000000000000000000000..f8e4d737f7cb9d98c293d36c22d2e615b7bcbb48 GIT binary patch literal 238 zcmeAS@N?(olHy`uVBq!ia0vp^3LwnE1|*BCs=fdz#^NA%Cx&(BWL^R}D?D8sLn2z= zPQT07pupj_^y|O%IpG$66cz4Vc)BwyQZs%2O3lBr3fC(SnV*T7H$A;zyLr*IPKE-} zxQO!%heB7FE>XR6K$2lLBi|XeG)4vkk@?G9cQn59Ke04smgthZDM_}>GR=#K{wNc@?yTpC+bFYmqis&&uMFqHC~ZzY@^A26blVHPy!o jn2pW8uM-a4(Ri5IE6&VbG;O9U(9H~Gy4|5~^YvZBC!Vx_+hqYv6L~*q Date: Sat, 4 Oct 2025 23:15:10 -0500 Subject: [PATCH 03/11] Document Dialog:file() parameters --- api/dialog.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/api/dialog.md b/api/dialog.md index e004277..fd8af85 100644 --- a/api/dialog.md +++ b/api/dialog.md @@ -453,29 +453,29 @@ Marks the end of both the last tab and the group of tabs to which it belongs. ```lua local dlg = Dialog() dlg:file{ id=string, - label=string, title=string, + filename=string, + basepath=string, open=boolean, save=boolean, - filename=string | { string1,string2,string3... }, + entry=boolean, filetypes={ string1,string2,string3... }, onchange=function } ``` Creates a text entry field + a button to select one file to open or save, possibilities: -* `open=true`: shows a dialog to open an existent file (this is the default mode). -* `save=true`: shows a dialog to select an existent file to overwrite or a new file to save. +* `open`: When true, shows a dialog to open an existing file (set to true by default). +* `save`: When true, shows a dialog to select an existing file to overwrite or a new file to save. -Arguments (table fields): +Other arguments: -* `load`: True if you want to show a dialog to the user to select an existent file to load/read. -* `save`: True if you want to show a dialog to the user to select a new file to save/write content. * `filename`: String of the selected filename to open or save. +* `title`: The title of the file select menu. * `filetypes`: Array of possible file types/extensions that the user can select. * `entry`: Show an entry field to edit the filename manually (false by default). -* `focus`: Focus this field by default. -* `onchange`: Function to be called when the filename is changed. +* `basepath`: The base path of the directory. Use [app.fs.joinPath()](app_fs.md#appfsjoinpath) for paths. +* `onchange`: Function to be called when the filename/path is changed. ## Dialog:canvas() From eb4611e34ae25d47e4a98ff0b8c2abbce72dc5d8 Mon Sep 17 00:00:00 2001 From: Crash Date: Sat, 4 Oct 2025 23:15:32 -0500 Subject: [PATCH 04/11] Reorder methods in app.md --- api/app.md | 142 ++++++++++++++++++++++++++--------------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/api/app.md b/api/app.md index fcab5e1..db0a236 100644 --- a/api/app.md +++ b/api/app.md @@ -130,6 +130,77 @@ This is a table with parameters specified as [`gui.xml`](https://github.com/aseprite/aseprite/blob/main/data/gui.xml) file. +## app.clipboard + +Check the [app.clipboard](app_clipboard.md#appclipboard) documentation. + +## app.command + +Check the [app.command](app_command.md#appcommand) documentation. + +## app.preferences + +Check the [app.preferences](app_preferences.md#apppreferences) documentation. + +## app.fs + +Check the [app.fs](app_fs.md#appfs) documentation. + +## app.theme + +Check the [app.theme](app_theme.md#apptheme) documentation. + +## app.os + +Check the [app.os](app_os.md#appos) documentation. + +## app.uiScale + +``` +local scale = app.uiScale +``` + +Returns the [UI Elements Scaling](https://www.aseprite.org/docs/preferences/) +value specified in *Edit > Preferences* as an scale factor (1 for 100%, 2 for 200%, etc.) + +## app.events + +Returns the [`Events`](events.md#events) object to associate functions +that can act like listeners of specific `app` events. E.g. + +```lua +app.events:on('sitechange', + function() + print('Now we are located in other sprite, layer, or frame') + end) +``` + +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. +* `'aftercommand'`: After executing any command in the program. + +The `'beforecommand'` and `'aftercommand'` events receive an `ev` +argument with the name of the command (`ev.name`) and the params +(`ev.params`). `'beforecommand'` includes a `ev.stopPropagation()` +function to cancel the event, e.g. in case that you've handled the +event in a custom way. + +E.g. This code catches the *Edit > Cut* command and convert it to a *Copy*: +```lua +app.events:on('beforecommand', + function(ev) + if ev.name == "Cut" then + app.command.Copy() -- call Copy command + ev.stopPropagation() -- and cancel the Cut + end + end) +``` + ## app.alert() ```lua @@ -228,39 +299,6 @@ app.transaction( end) ``` -## app.clipboard - -Check the [app.clipboard](app_clipboard.md#appclipboard) documentation. - -## app.command - -Check the [app.command](app_command.md#appcommand) documentation. - -## app.preferences - -Check the [app.preferences](app_preferences.md#apppreferences) documentation. - -## app.fs - -Check the [app.fs](app_fs.md#appfs) documentation. - -## app.theme - -Check the [app.theme](app_theme.md#apptheme) documentation. - -## app.os - -Check the [app.os](app_os.md#appos) documentation. - -## app.uiScale - -``` -local scale = app.uiScale -``` - -Returns the [UI Elements Scaling](https://www.aseprite.org/docs/preferences/) -value specified in *Edit > Preferences* as an scale factor (1 for 100%, 2 for 200%, etc.) - ## app.refresh() ```lua @@ -338,44 +376,6 @@ Simulates an user stroke in the canvas using the given tool. * `layer`: The [layer](layer.md#layer) where we want to use the tool/draw with the tool (by default [app.layer](app.md#applayer)) * `frame`: The [frame](frame.md#frame) where to draw (by default [app.frame](app.md#appframe)) -## app.events - -Returns the [`Events`](events.md#events) object to associate functions -that can act like listeners of specific `app` events. E.g. - -```lua -app.events:on('sitechange', - function() - print('Now we are located in other sprite, layer, or frame') - end) -``` - -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. -* `'aftercommand'`: After executing any command in the program. - -The `'beforecommand'` and `'aftercommand'` events receive an `ev` -argument with the name of the command (`ev.name`) and the params -(`ev.params`). `'beforecommand'` includes a `ev.stopPropagation()` -function to cancel the event, e.g. in case that you've handled the -event in a custom way. - -E.g. This code catches the *Edit > Cut* command and convert it to a *Copy*: -```lua -app.events:on('beforecommand', - function(ev) - if ev.name == "Cut" then - app.command.Copy() -- call Copy command - ev.stopPropagation() -- and cancel the Cut - end - end) -``` - # Deprecated Names The following fields were replaced with new alternatives (generally From 5fc54e34d07edf8c21b4b6a5a3bfb238b6b2368d Mon Sep 17 00:00:00 2001 From: Crash Date: Thu, 9 Oct 2025 22:22:43 -0500 Subject: [PATCH 05/11] Document clipboard image setting Also add clarification to app.preferences --- api/app_clipboard.md | 4 +++- api/app_preferences.md | 7 ++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/api/app_clipboard.md b/api/app_clipboard.md index 9a4a78f..036b324 100644 --- a/api/app_clipboard.md +++ b/api/app_clipboard.md @@ -20,7 +20,9 @@ Gets or sets the clipboard text. Returns `nil` if there is no text. local image = app.clipboard.image ``` -Gets or sets the clipboard [image](image.md#image). Returns `nil` if there is no image. +Gets or sets the clipboard [image](image.md#image). Returns `nil` if there is no image. It is recommended to set/get the value once when needed, as the operation may not always be available immediately (in some instances it may take a few milliseconds, see [#5341](https://github.com/aseprite/aseprite/issues/5341#issuecomment-3176395116)). + +Additionally, when calling a method on an image from the clipboard image, the image should be saved to a variable first, instead of calling the method directly on the property (this will not work: `app.clipboard.image:clear()`, see [#5341](https://github.com/aseprite/aseprite/issues/5341#issuecomment-3176395116)) ## app.clipboard.content diff --git a/api/app_preferences.md b/api/app_preferences.md index 1e046b8..7496a58 100644 --- a/api/app_preferences.md +++ b/api/app_preferences.md @@ -5,10 +5,11 @@ local value = app.preferences.section.option app.preferences.section.option = newValue ``` -Gets or sets the given preference `option` in the given `section`. You -can find valid `section` and `option` names in the +Gets or sets the given preference `option` in the given `section`. + +You can find valid `section` and `option` names in the [pref.xml](https://github.com/aseprite/aseprite/blob/main/data/pref.xml) -file. +file; each `option` corresponds to a preference in the [preferences menu](https://www.aseprite.org/docs/preferences#preferences). ## app.preferences.tool() From be48f5157f770958b925287f743ea12047f8d685 Mon Sep 17 00:00:00 2001 From: Crash Date: Fri, 10 Oct 2025 12:26:24 -0500 Subject: [PATCH 06/11] Document autofit and sizeHint dialog properties --- api/align.md | 2 ++ api/dialog.md | 92 +++++++++++++++++++++++++++++++-------------------- 2 files changed, 58 insertions(+), 36 deletions(-) diff --git a/api/align.md b/api/align.md index 95e2583..7c2766e 100644 --- a/api/align.md +++ b/api/align.md @@ -8,6 +8,8 @@ element in this enum might vary in the future. E.g. ```lua +local left = Align.LEFT +local top = Align.TOP local leftBottom = Align.LEFT | Align.BOTTOM local rightTop = Align.RIGHT | Align.TOP ``` diff --git a/api/dialog.md b/api/dialog.md index fd8af85..8f5f399 100644 --- a/api/dialog.md +++ b/api/dialog.md @@ -64,6 +64,7 @@ Where: local dlg = Dialog() local dlg = Dialog(string) local dlg = Dialog{ title=string, + autofit=align, notitlebar=false, resizeable=false, parent=otherDialog, @@ -86,9 +87,63 @@ kind of title bar (the dialog must be closed with a button inside it). `{ resizeable=false }` disables the user from resizing the dialog. +`{ autofit=align }` sets how the dialog will align when shown. See [Dialog.autofit](#dialogautofit). + Returns `nil` if there is no UI available, i.e. [app.isUIAvailable is `false`](app.md#appisuiavailable). +## Dialog.data + +```lua +local dlg = Dialog() +local data = dlg.data +dlg.data = data +``` + +Gets/sets a table with one field for each widget with a given `id`. +For each different kind of widget the field is of a different type: + +* [button](#dialogbutton)/[check](#dialogcheck)/[radio](#dialogradio): + The field is a boolean (true or + false) if the button is selected or was used to close the dialog. +* [entry](#dialogentry)/[label](#dialoglabel): A string of text. +* [slider](#dialogslider): An integer. +* [number](#dialognumber): An intenger or a + number depending on the number of decimals of the number field. +* [combobox](#dialogcombobox): A string with the + selected item. +* [color](#dialogcolor): A [Color](color.md#color). +* [shades](#dialogshades): A table with an array of [Color](color.md#color)s when `mode="sort"` + +## Dialog.bounds + +```lua +local dlg = Dialog() +local bounds = dlg.bounds +dlg.bounds = Rectangle(x, y, bounds.width, bounds.height) +``` + +Gets or sets the position and size (a [rectangle](rectangle.md#rectangle)) of +the dialog. This can be useful to align several dialog that must be +shown in the same *xy*-position. + +## Dialog.autofit + +```lua +local autofit = dlg.autofit +dlg.autofit = autofit +``` + +Gets or sets the dialog autofit, as an [Align](align.md#align) object. The setting will only visually take effect on the dialog after a [`Dialog:modify()`](#dialogmodify). When set, the dialog window will resize itself, anchoring at the specified value (eg. when autofitting with `Align.LEFT | Align.TOP`, the dialog bounds will shrink to the minimum size anchored at the top left of the dialog). + +## Dialog.sizeHint + +```lua +local sizeHint = dlg.sizeHint +``` + +Gets the minimum size (without cutoff) of the dialog window, as a [Size](size.md#Size). + ## Dialog:button() ```lua @@ -170,41 +225,6 @@ Creates a combo box/drop-down list. * `options`: Indicates a list of available options in the combobox. * `option`: Indicates the default selected option in the combobox (one of the `options`). -## Dialog.data - -```lua -local dlg = Dialog() -local data = dlg.data -dlg.data = data -``` - -Gets/sets a table with one field for each widget with a given `id`. -For each different kind of widget the field is of a different type: - -* [button](#dialogbutton)/[check](#dialogcheck)/[radio](#dialogradio): - The field is a boolean (true or - false) if the button is selected or was used to close the dialog. -* [entry](#dialogentry)/[label](#dialoglabel): A string of text. -* [slider](#dialogslider): An integer. -* [number](#dialognumber): An intenger or a - number depending on the number of decimals of the number field. -* [combobox](#dialogcombobox): A string with the - selected item. -* [color](#dialogcolor): A [Color](color.md#color). -* [shades](#dialogshades): A table with an array of [Color](color.md#color)s when `mode="sort"` - -## Dialog.bounds - -```lua -local dlg = Dialog() -local bounds = dlg.bounds -dlg.bounds = Rectangle(x, y, bounds.width, bounds.height) -``` - -Gets or sets the position and size (a [rectangle](rectangle.md#rectangle)) of -the dialog. This might be useful to align several dialog that must be -shown in the same *xy*-position. - ## Dialog:entry() ```lua @@ -252,7 +272,7 @@ local dlg = Dialog() dlg:modify{ title = "New Dialog Title" } ``` -Using the `dialog:modify` with a parameter `title` changes the dialog title. +Using the `dialog:modify` with a parameter `title` changes the dialog title. ## Dialog:newrow() From b4fde7f9b57029afe12ed3d5683886e2faf150b2 Mon Sep 17 00:00:00 2001 From: Crash <135138016+CrashTestJava@users.noreply.github.com> Date: Sun, 12 Oct 2025 20:52:26 -0500 Subject: [PATCH 07/11] Update Changes.md versions --- Changes.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Changes.md b/Changes.md index 7ee25b0..152e8bc 100644 --- a/Changes.md +++ b/Changes.md @@ -23,7 +23,16 @@ else -- Future versions will be 2, 3, etc. end ``` +## v1.3.16-beta1 +* [`app.apiVersion`](api/app.md#appapiversion) is `36` +* Added `ui` parameter to all commands for enabling/disabling user interaction through their dialogs [#3025](https://github.com/aseprite/aseprite/issues/3025) + +## v1.3.15.3 + +* [`app.apiVersion`](api/app.md#appapiversion) is `36` +* Enclose key names for plugin preferences with `["..."]` when it's required [#5412](https://github.com/aseprite/aseprite/issues/5412) + ## v1.3.15 * [`app.apiVersion`](api/app.md#appapiversion) is `35` @@ -403,4 +412,4 @@ end ## v1.2.10-beta2 * [`app`](api/app.md#app) - * `app.apiVersion` didn't exist (is `nil`) \ No newline at end of file + * `app.apiVersion` didn't exist (is `nil`) From 9d2116064940f6510a3f2f3c847f3f5563c5c916 Mon Sep 17 00:00:00 2001 From: Crash Date: Mon, 13 Oct 2025 15:30:08 -0500 Subject: [PATCH 08/11] Add TilesetMode and TilemapMode to sidebar.md --- sidebar.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sidebar.md b/sidebar.md index 652c606..a5668ff 100644 --- a/sidebar.md +++ b/sidebar.md @@ -29,6 +29,8 @@ Constants * [SelectionMode](api/selectionmode.md#selectionmode) * [SpriteSheetDataFormat](api/spritesheetdataformat.md#spritesheetdataformat) * [SpriteSheetType](api/spritesheettype.md#spritesheettype) + * [TilemapMode](api/tilemapmode.md#tilemapmode) + * [TilesetMode](api/tilesetmode.md#tilesetmode) * [WebSocketMessageType](api/websocketmessagetype.md#websocketmessagetype) Classes/objects From 0b1f36a8e5c0c1f745470260e5428d06fc6d5f60 Mon Sep 17 00:00:00 2001 From: Crash Date: Mon, 13 Oct 2025 15:30:41 -0500 Subject: [PATCH 09/11] Complete app.tool() documentation --- api/app.md | 63 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/api/app.md b/api/app.md index db0a236..0b88194 100644 --- a/api/app.md +++ b/api/app.md @@ -333,48 +333,57 @@ Redoes the latest undone operation in the ```lua app.useTool{ - tool=string, - color=Color, - bgColor=Color, - brush=Brush, - points={ Point, Point, .... }, - cel=Cel, - layer=Layer, - frame=Frame, - ink=Ink, - button=MouseButton.LEFT | MouseButton.RIGHT, - opacity=integer, - contiguous=false | true, - tolerance=integer, - freehandAlgorithm=0 | 1, - selection=SelectionMode.REPLACE | SelectionMode.ADD | SelectionMode.SUBTRACT | SelectionMode.INTERSECT, - tilemapMode=TilemapMode.PIXELS | TilemapMode.TILES, - tilesetMode=TilesetMode.MANUAL | TilesetMode.AUTO | TilesetMode.STACK, + tool=string | Tool, + color=Color, + bgColor=Color, + brush=Brush, + points={ Point, Point, ... }, + cel=Cel, + layer=Layer, + frame=Frame, + ink=Ink, + button=MouseButton.LEFT | MouseButton.RIGHT, + opacity=integer, + contiguous=boolean, + tolerance=integer, + freehandAlgorithm=0 | 1, + selection=SelectionMode.REPLACE | SelectionMode.ADD | SelectionMode.SUBTRACT | SelectionMode.INTERSECT, + tilemapMode=TilemapMode.PIXELS | TilemapMode.TILES, + tilesetMode=TilesetMode.MANUAL | TilesetMode.AUTO | TilesetMode.STACK, } ``` Simulates an user stroke in the canvas using the given tool. -* `tool`: A string with a well known tool ID (`rectangular_marquee`, +* `tool`: The tool to use. Can either be a [Tool](tool.md#tool) object or a string tool ID (`rectangular_marquee`, `elliptical_marquee`, `lasso`, `polygonal_lasso`, `magic_wand`, `pencil`, `spray`, `eraser`, `eyedropper`, `zoom`, `hand`, `move`, `slice`, `paint_bucket`, `gradient`, `line`, `curve`, `rectangle`, `filled_rectangle`, `ellipse`, `filled_ellipse`, `contour`, - `polygon`, `blur`, `jumble`) or a [tool](tool.md#tool) object -* `color`: A [color](color.md#color) object to draw with the given tool -* `brush`: A [brush](brush.md#brush) object to draw the points -* `points`: An array of [points](point.md#point) in the sprite canvas which - simulate the position of where the user put the mouse to draw with + `polygon`, `blur`, `jumble`). Defaults to [app.tool](#apptool). +* `color`: The color to draw with (foreground color), as a [Color](color.md#color) object. Defaults to [app.fgColor](#appfgcolor). +* `bgColor`: The background color to draw with, as a [Color](color.md#color) object. Defaults to [app.bgColor](#appbgcolor). +* `brush`: A [Brush](brush.md#brush) object for the tool to draw with. Defaults to the active brush. +* `points`: An array of [points](point.md#point) on the sprite canvas which + simulate the positions where a user would put their mouse to draw with the given tool. * `selection`: What to do with the selection, only for selection-like tools (`rectangular_marquee`, `magic_wand`, etc.). The default value when the [UI is enabled](#appisuiavailable) will be `app.preferences.selection.mode`, in CLI mode it's `SelectionMode.REPLACE`. -* And we can specify the `cel` or `layer`/`frame` where to draw: - * `cel`: The specific [cel](cel.md#cel) where we want to use the tool/draw with the tool (by default [app.cel](app.md#appcel)) - * `layer`: The [layer](layer.md#layer) where we want to use the tool/draw with the tool (by default [app.layer](app.md#applayer)) - * `frame`: The [frame](frame.md#frame) where to draw (by default [app.frame](app.md#appframe)) +* The draw location (`cel` or `layer`/`frame`) can be specified: + * `cel`: The specific [Cel](cel.md#cel) where we want to use the tool/draw with the tool (by default [app.cel](#appcel)). + * `layer`: The [Layer](layer.md#layer) to use the tool at (by default [app.layer](#applayer)). + * `frame`: The [Frame](frame.md#frame) to use the tool at (by default [app.frame](#appframe)). +* `ink`: The [Ink](ink.md#ink) type for the tool to use. +* `button`: The [MouseButton](mousebutton.md#mousebutton) to use, can either be `MouseButton.LEFT` or `MouseButton.RIGHT`. Defaults to `MouseButton.LEFT`. +* `opacity`: The opacity of the tool stroke, as an integer between `0` and `255`. Defaults to `255`. +* `tolerance`: The tolerance of the tool fill, as an integer between `0` and `255`. Defaults to `0`. +* `contiguous`: Contiguous mode toggle. Defaults to `true`. +* `freehandAlgorithm`: Changes the freehand algorithm. Can either be `0` (regular mode) or `1` (pixel-perfect mode). Defaults to `0`. +* `tilemapMode`: The [TilemapMode](tilemapmode.md#tilemapmode) of the tool. Defaults to `TilemapMode.PIXELS`. +* `tilesetMode`: The [TilesetMode](tilemapmode.md#tilemapmode) of the tool. Defaults to `TilesetMode.MANUAL`. # Deprecated Names From 313e9f307c52ec0afcf905fee357c816d30a8fc2 Mon Sep 17 00:00:00 2001 From: Crash Date: Mon, 13 Oct 2025 21:54:08 -0500 Subject: [PATCH 10/11] Expand sprite.palettes docs --- api/sprite.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/api/sprite.md b/api/sprite.md index ee72f60..b54670f 100644 --- a/api/sprite.md +++ b/api/sprite.md @@ -178,11 +178,14 @@ An array of [frames](frame.md#frame). ## Sprite.palettes -An array of [palettes](palette.md#palette). Generally it contains only one -palette (`sprite.palettes[1]`). +```lua +local palette = sprite.palettes[1] +``` + +An array of [palettes](palette.md#palette). In most cases, it only contains one +palette (`sprite.palettes[1]`), except in a very specific case. -In the future we'll support multiple palettes to create -[color cycling animations](https://en.wikipedia.org/wiki/Color_cycling). +In the event that two or more [indexed](https://www.aseprite.org/docs/color-mode#indexed) numbered files (eg. `spr_01.png`, `spr_02.png`, `spr_03.png` etc.) are [opened as a sequence](https://www.aseprite.org/docs/open#loading-image-sequences), each frame would have its own palette. This only occurs when there are at least two different indexed palettes, so the indexed palette for the `spr_01.png` frame would have different index-to-color mapping than the indexed palette for the `spr_02.png` (same with `spr_03.png`), hence the need for three sprite palettes. If two images/frames have the same indexed palette, they will share (so if `spr_01.png` and `spr_02.png` have the same palette, but `spr_03.png` has a different one, there would be `2` sprite palettes). ## Sprite.layers From 258b30f5cf7b6fc6fbc087aeaed0c8ef4213f8d4 Mon Sep 17 00:00:00 2001 From: Crash Date: Mon, 13 Oct 2025 22:05:28 -0500 Subject: [PATCH 11/11] Document app.defaultPalette --- api/app.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/api/app.md b/api/app.md index 0b88194..1b51b85 100644 --- a/api/app.md +++ b/api/app.md @@ -156,13 +156,17 @@ Check the [app.os](app_os.md#appos) documentation. ## app.uiScale -``` +```lua local scale = app.uiScale ``` Returns the [UI Elements Scaling](https://www.aseprite.org/docs/preferences/) value specified in *Edit > Preferences* as an scale factor (1 for 100%, 2 for 200%, etc.) +## app.defaultPalette + +Returns the user's default palette, as a [Palette](palette.md#palette). + ## app.events Returns the [`Events`](events.md#events) object to associate functions