176 lines
6.4 KiB
Markdown
176 lines
6.4 KiB
Markdown
|
|
|
|
## About this document
|
|
|
|
This describes *some* changes needed to port a Scriptfu script to PIKA 3:
|
|
- changes in types
|
|
- changes in PDB signatures for multi-layer support
|
|
- changes in error messages
|
|
- changes in logging
|
|
|
|
It does *not* document:
|
|
- PDB procedures whose names have changed (see pdb-calls.md)
|
|
- PDB procedures that have been removed (see removed_functions.md)
|
|
- PDB procedures that have been added
|
|
- other changes in signature where arguments are reordered or changed in number
|
|
|
|
## Changes in types of PDB signatures
|
|
|
|
Calls from a script to PIKA are calls to PDB procedures.
|
|
PDB procedures are documented in terms of C and GLib types.
|
|
|
|
This table summarizes the changes:
|
|
|
|
| Purpose | Old C type | New C type | Old Scheme type | New Scheme type |
|
|
| ---------------|-----------------------|-----------------------| ----------------|-----------------------|
|
|
| Pass file name | gchar*, gchar* | GFile | string string | string |
|
|
| Recv file name | gchar* | GFile | string | string |
|
|
| pass drawable | PikaDrawable | gint, PikaObjectArray | int (an ID) | int (a length) vector |
|
|
| Pass obj array | gint, PikaInt32Array | gint, PikaObjectArray | int vector | int vector |
|
|
| Recv obj array | gint, PikaInt32Array | gint, PikaObjectArray | int vector | int vector |
|
|
| Pass set of str | gint, PikaStringArray | GStrv | int list | list |
|
|
| Recv set of str | gint, PikaStringArray | GStrv | int list | list |
|
|
|
|
(Where "obj" means an object of a PIKA type such as PikaDrawable or similar.)
|
|
|
|
### Use one string for a filename instead of two.
|
|
|
|
Formerly a PDB procedure taking a filename (usually a full path) required two strings (two gchar* .)
|
|
Now such PDB procedures require a GFile.
|
|
|
|
In Scheme, where formerly you passed two strings, now pass one string.
|
|
|
|
Formerly a script passed the second string for a URI, to specify a remote file.
|
|
Formerly, in most cases you passed an empty second string.
|
|
Now, the single string in a script can be either a local file path or a remote URI.
|
|
|
|
Example:
|
|
|
|
(pika-file-load RUN-NONINTERACTIVE "/tmp/foo" "")
|
|
=> (pika-file-load RUN-NONINTERACTIVE "/tmp/foo")
|
|
|
|
|
|
### PDB procedures still return a string for a filename
|
|
|
|
All PDB procedures returning a filename return a single string to Scheme scripts.
|
|
That is unchanged.
|
|
|
|
Formerly a PDB signature for a procedure returning a filename
|
|
specifies a returned type gchar*, but now specifies a returned type GFile.
|
|
But a Scheme script continues to receive a string.
|
|
|
|
The returned string is either a local file path or a URI.
|
|
|
|
|
|
### Use a vector of drawables for PDB procedures that now take an array of drawables
|
|
|
|
Formerly, some PDB procedures took a single PikaDrawable,
|
|
but now they take an array of PikaDrawable ( type PikaObjectArray.)
|
|
(Formerly, no PDB procedure took an array of drawables.
|
|
Some that formerly took a single drawable still take a single drawable.
|
|
See the list below. )
|
|
|
|
For such PDB procedures, in Scheme pass a numeric length and a vector of numeric drawable ID's.
|
|
|
|
These changes support a user selecting multiple layers for an operation.
|
|
|
|
Example:
|
|
|
|
(pika-edit-copy drawable) => (pika-edit-copy 1 (vector drawable))
|
|
|
|
(pika-edit-copy 2) => (pika-edit-copy 1 '#(2))
|
|
|
|
### The PDB procedures which formerly took single Drawable and now take PikaObjectArray
|
|
|
|
- Many of the file load/save procedures.
|
|
- pika-color-picker
|
|
- pika-edit-copy
|
|
- pika-edit-cut
|
|
- pika-edit-named-copy
|
|
- pika-edit-named-cut
|
|
- pika-file-save
|
|
- pika-image-pick-color
|
|
- pika-selection-float
|
|
- pika-xcf-save
|
|
|
|
|
|
### Receiving an array of drawables
|
|
|
|
Formerly a PDB procedure returning an array of drawables (or other PIKA objects)
|
|
had a signature specifying a returned gint and PikaInt32Array.
|
|
Now the signature specifies a returned gint and PikaObjectArray.
|
|
A script receives an int and a vector.
|
|
The elements of the vector are numeric ID's,
|
|
but are opaque to scripts
|
|
(a script can pass them around, but should not for example use arithmetic on them.)
|
|
|
|
No changes are needed to a script.
|
|
|
|
|
|
Example:
|
|
|
|
(pika-image-get-layers image)
|
|
|
|
Will return a list whose first element is a length,
|
|
and whose second element is a vector of drawables (Scheme numerics for drawable ID's)
|
|
|
|
In the ScriptFu console,
|
|
|
|
(pika-image-get-layers (car (pika-image-new 10 30 1)))
|
|
|
|
would print:
|
|
|
|
(0 #())
|
|
|
|
Meaning a list length of zero, and an empty vector.
|
|
(Since a new image has no layers.)
|
|
|
|
### Passing or receiving a set of strings
|
|
|
|
Formerly, you passed an integer count of strings, and a list of strings.
|
|
Now you only pass the list.
|
|
ScriptFu converts to/from the C type GStrv
|
|
(which is an object knowing its own length.)
|
|
An example is the PDB procedure file-gih-save.
|
|
|
|
Formerly, you received an integer count of strings, and a list of strings.
|
|
Now you only receive the list
|
|
(and subsequently get its length using "(length list)").
|
|
Examples are the many PDB procedures whose name ends in "-list".
|
|
Remember that the result of a call to the PDB is a list of values,
|
|
in this case the result is a list containing a list,
|
|
and for example you get the list of strings like "(car (pika-fonts-get-list ".*"))"
|
|
|
|
## Changes in error messages
|
|
|
|
ScriptFu is now more forgiving.
|
|
|
|
Formerly, ScriptFu would not accept a call construct where the argument count was wrong,
|
|
except for the case when you provided one argument to a PDB procedure
|
|
that took zero arguments (sometimes called a nullary function.)
|
|
|
|
Now, when a script has the wrong count of arguments to a PDB procedure:
|
|
|
|
- too many actual arguments: ScriptFu will give a warning to the console
|
|
and call the PDB procedure with a prefix of the actual arguments.
|
|
This is now true no matter how many arguments the PDB procedure takes.
|
|
Extra arguments in the script are ignored by Scriptfu,
|
|
not evaluated and not passed to the PDB.
|
|
|
|
- too few actual arguments: ScriptFu will give a warning to the console
|
|
and call the PDB procedure with the given actual arguments.
|
|
The warning will say the expected Scheme formal type of the first missing actual argument.
|
|
Usually the PDB procedure will fail and return its own error message.
|
|
|
|
When you suspect errors in a script,
|
|
it is now important to run PIKA from a console to see warnings.
|
|
|
|
|
|
## ScriptFu logging
|
|
|
|
ScriptFu now does some logging using GLib logging.
|
|
When you define in the environment "G_MESSAGES_DEBUG=scriptfu"
|
|
ScriptFu will print many messages to the console.
|
|
|
|
This is mostly useful for PIKA developers.
|
