Branch: refs/heads/master
Home: https://github.com/synfig/synfig
Commit: 011a34cd29a6d506dbb07fdd1f3b8e893265db53
https://github.com/synfig/synfig/commit/011a34cd29a6d506dbb07fdd1f3b8e893265db53
Author: rodolforg <rodolf...@users.noreply.github.com>
Date: 2023-05-21 (Sun, 21 May 2023)
Changed paths:
M synfig-studio/src/gui/instance.cpp
M synfig-studio/src/gui/pluginmanager.cpp
M synfig-studio/src/gui/pluginmanager.h
Log Message:
-----------
feat: plugins can have simple dialog and receive current time and selected
layer xpath (#2996)
Plugins can now present to user a simple (not dynamic) configuration dialog and
can also get the current state of the canvas (current time and selected layers).
### Configuration dialog
The dialog, if provided by the plugin, will be shown every time before the
plugin actually runs.
It is static: it will not enable/disable widget according to user interaction,
neither validate data unless the widgets themselves perform validation.
#### How to provide the configuration dialog
Synfig Studio will automatically search for a file in the plugin script folder,
with the same filename, except the extension, that must be ".ui".
- The .ui file must be in Glade format, as it will be constructed via
Gtk::Builder.
- Synfig Studio runs on Gtk3, not Gtk4, so write a compatible .ui file.
- Currently, we prefer to support Gtk 3.18. For now, avoid widgets provided
later than this version.
- The root widget of the .ui file will be embedded in a dialog with two
buttons: OK and Cancel.
- The root widget MUST be have its ID set as "`dialog_contents`".
- The configuration fields MUST be named (set "name", not "ID"). Keep in mind
that the field name will be used to identify the data to be passed to script;
so, set a unique name to each one.
- Supported control widgets (i.e. their data will be passed to plugin script):
- Entry,
- ComboBox (use item id),
- ComboBoxText (use item id),
- SpinButton,
- FileChooserButton (a single file per button, for now),
- ColorButtonChooser,
- FontButtonChooser (the font value will be in
[PangoDescription](https://docs.gtk.org/Pango/type_func.FontDescription.from_string.html)
format),
- CheckButton,
- Switch,
- ToggleButton,
- Scale,
- ScaleButton,
- SpinButton,
- Volume,
- AppChooserButton
- Currently it doesn't support RadioButton widget.
- You can use visual (e.g. Label) and helper (e.g. Containers) widgets freely.
#### How to get what was set by user on the configuration dialog
If the dialog exists and user presses its OK button, the plugin script will
receive, as its **second** argument, a filename.
If using Python, get it via `sys.argv[2]`.
The file contains a [JSON](https://json.org) dictionary. The dict entry named
"dialog" contains a nested dictionary with the data provided/chosen by user.
The file may contain extra data, such as the Canvas state, as described in next
section.
The "dialog" dictionary is a list of key-value pair, being the key the widget
name (not ID) and the value that one provided by user.
Notes:
- ComboBox(Text) value is the ID of selected item, not the text presented to
user.
- Boolean values (e.g. CheckButton) are "1" or "0".
- All field values will be passed as strings.
- The data file is temporary: it will deleted as soon as plugins finish running
(successfully or not)
##### Example of data file contents
```json
{
"dialog": {
"my_entry": "what user typed",
"the_checkbox": "1"
}
}
```
### Canvas State
Synfig Studio can now pass the current canvas view state, and the plugin script
can request them selectively.
These info are supported:
- current time (in seconds)
- the selected layers (list of pseudo XPath)
#### How to request
The metafile plugin.xml was extended to let plugin author tells Synfig Studio
what info it needs.
The `<exec>` element now has two optional attributes:
- To receive current time, add this attribute to "exec" element:
`current_time="mandatory"`.
- To receive XPath of selected layers, add this attribute to "exec" element:
`selected_layers="optional"`.
Both attribute accepts one of three possible values:
- "unused": plugin does not need this info, and such data will not be passed to
it (default)
- "mandatory": plugin depends on this info. If user does not provide it, an
error message will pop up warning him/her.
- "optional": plugin can run without that info, so if it does not exist, it is
not a problem.
Example: If `selected_layers="mandatory"` attribute exists, the user MUST
select at least one layer to run the plugin. Otherwise, Synfig Studio will warn
user and abort the plugin execution (by not starting it).
#### How to get the data
If any of the canvas state request attribute exists, the plugin script will
receive, as its **second** argument, a filename.
If using Python, get it via `sys.argv[2]`.
The file contains a [JSON](https://json.org) dictionary. The dict entry named
"canvas_state" contains a nested dictionary with the requested data. The file
may contain extra data, such as the Config Dialog entries, as described in
previous section.
The possible keys for "canvas_state" dict are:
- "current_time": value will be in seconds.
- "selected_layers": an JSON array of pseudo
[XPath](https://en.wikipedia.org/wiki/XPath) to selected layers.
Notes:
- Only the requested data will be in the file.
- The XPath for each layer is not 100% compliant.:
* It may start with a filename, if selected layer comes from an imported
`sif` file. In this case, it will be followed by `#` character, to mark the
file path end.
* It may have a starting ":" and that means the root canvas element of the
file.
* If it is an exported canvas (or from an exported value node), it won't have
the initial path, but its ID. So place properly `defs` path.
#### Examples of file contents
```json
{
"canvas_state": {
"current_time": "1.35"
}
}
```
Only "time" was requested
```json
{
"canvas_state": {
"selected_layers": [
":layer[2]"
]
}
}
```
Only "layers" was requested, and user only selected one layer before calling
the plugin. That layer is in the root canvas, being the second one from bottom
to top.
```json
{
"canvas_state": {
"current_time": "1.35",
"selected_layers": [
":layer[2]",
":layer[7]"
]
}
}
```
### Metadata
Plugin can now provide its author name, release name and version number.
The file `plugin.xml` now has new elements:
- element `<plugin>` now supports some metadata child elements:
- "author" : author name [string]
- "release" : release name [translatable string]
- "version" : version number [integer]
- "url" : url pointing to the plugin project/website [string]
- "description" : a description text to guide the user [translatable string]
For now, these information do not appear anywhere in the GUI.
They can be used in the future by a plugin manager dialog in Synfig Studio.
_______________________________________________
Synfig-devl mailing list
Synfig-devl@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/synfig-devl
