Add various documentation

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
 ```

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

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
 

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()
 

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()
 
@@ -453,29 +473,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()
 
@@ -520,10 +540,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()