See /scripts/test/test-i18n.scm,
which has tests and documents use cases.
Some incidental refactoring and editing of comments.
(cherry picked from commit ea238e4e5a)
GIMP 3.0 enforces stricter parameter range checks
compared to GIMP 2.10. As a result, scripts that are the
right datatype but go outside the parameter range will
fail. In GimpProcedure, we have checks if a no-validate
flag is set to bypass these constraints.
This patch adds those checks to Script-fu so it also knows
to not check ranges if no-validate is set.
(cherry picked from commit 1f1404dc93)
In particular, we want the new Script-Fu plug-in to be able to handle
their progress status themselves, which is possible with
(gimp-progress-set-text) except that it is far too quickly overriden
because each procedure call generates a new progress message.
I hesitated to make (gimp-pdb-proc-exists) public but I don't think it's
a good idea as it would be redundant with gimp_pdb_procedure_exists() in
the C API.
Instead, just implement (gimp-pdb-procedure-exists) specifically for
Script-Fu, with a name mapped to the C function.
… gimp_procedure_is_internal().
I realized we were already naming these "internal procedures" in the
Procedure Browser and this is in fact a better naming than "core
procedure".
Since the move of GimpUnit from some weird int/enum mixed type into a
proper object type, this was not usable anymore in Script-Fu.
Functions like (gimp-text-layer-new) were therefore broken. It now works
again.
After the few specific args (drawable/filter ID, opacity, blend mode, op
name…), the op argument names can be passed either as string or with the
new argument name syntax. The error message though focus on argument
name type.
Also fix the argument count for the various possible cases (when
configuring with (gimp-drawable-filter-configure) or
(gimp-drawable-merge|append-new-filter), the start arg count is
different).
This syntax is now the official syntax for non-core PDB procedures.
I.e. that while core procedures will still use ordered arguments (e.g.:
`(gimp-image-get-layers 1)`), plug-in PDB procedures called from
Script-Fu will have named arguments in any order.
Say for instance that you want to call python-fu-foggify from Script-Fu.
Whereas we used to run:
> (python-fu-foggify RUN-NONINTERACTIVE 1 (car (gimp-image-get-layers 1)) "Clouds" '(50 4 4) 1.0 50.0)
Now we should call:
> (python-fu-foggify #:image 1 #:drawables (car (gimp-image-get-layers 1)) #:opacity 50.0 #:color '(50 4 4))
Now we can note:
* Every argument is preceded by a #:label which is the argument name.
This makes these calls much more readable (some plug-in procedures can
have dozen of arguments and these end up as list of integers, floats
and strings, which are hard to read and hard to debug) and semantic.
* Order doesn't matter anymore. For instance here, I put #:opacity
before #:color.
* As a direct consequence, we can drop any argument which we wish to
keep with default value. E.g. in the old style, we had to put the
#:run-mode, #:name ("Clouds") and #:turbulence (1.0) because we were
changing the last argument #:opacity (50.0). Now we can drop all 3
default arguments.
Having non-ordered argument is in fact the starter of this feature,
because it is already the case for calling PDB procedures in the libgimp
API (and therefore in all GIR bindings). By saying that the order of PDB
procedures is not part of the API, we actually allow to add arguments
and even to reorder them in the future without breaking existing scripts
in the 3.0 series.
This became even more serious when I was considering to make the generic
metadata arguments public. Since they are appended to the end, after all
plug-in-specific arguments, if I do this, adding any argument in an
export plug-in would break order. It won't matter anymore!
Note that it doesn't matter for core PDB procedures (where this syntax
is not used) because these are also C functions and therefore order and
number of arguments matter anyway. Also these don't have dozens of
arguments.
As a helper for Script-Fu developer, in particular as we already
released 2 RCs and therefore some people already started to port their
scripts, the old syntax will still work yet will produce a warning
showing how to call the same thing with the new syntax. For instance,
with the above first call, the warning will be:
> (script-fu:2059912): scriptfu-WARNING **: 22:54:47.507: Calling Plug-In PDB procedures with arguments as an ordered list is deprecated.
> Please use named arguments: (python-fu-foggify #:run-mode 1 #:image 1 #:drawables (2) #:name "Clouds" #:color '(50 4 4) #:turbulence 1.000000 #:opacity 50.000000)
Note that the argument name syntax is coming from the Racket scheme
variant: https://docs.racket-lang.org/arguments/index.html
Common Lisp has a similar syntax, either with just a colon, or also a
sharp + colon (it's unclear to me the difference, something about
interned vs. uninterned symbols).
After discussion with Liam on IRC, we decided to go with the #: syntax
of Racket.
In particular (gimp-drawable-filter-configure),
(gimp-drawable-merge-filter) and (gimp-drawable-append-filter) are
proper Script-fu methods.
I had to rename the PDB procedures for the 2 latter because they were
clashing with these wrapper. I had not realized that private PDB
procedures are still visible by Script-fu. This is not so glop. :-/
Right now, it doesn't look so useful compared to the -new- one-liner
variant procedures. But it will make sense when I will add aux input C
procedure wrappers.
Marshalled PDB procedures into script-fu can now convert a filter ID
into the proper object. For instance, here would be the code to append a
new gaussian blur filter to the drawable with ID 2 (with specific
settings), then making invisible:
```script-fu
(define filter (gimp-drawable-append-new-filter 2 "gegl:gaussian-blur" "hello" LAYER-MODE-COLOR-ERASE 1.0 "std-dev-x" 20 "abyss-policy" "none"))
(gimp-drawable-filter-set-visible filter FALSE)
(gimp-drawable-update 2 0 0 -1 -1)
```
I moved the code to transform scheme values into GValues depending on a
GParamSpec out of script_fu_marshal_procedure_call() into a shared
function script_fu_marshal_arg_to_value().
It is like a compiler warning, and should not be a full g_warning,
which should mean something will probably fail.
Passing fewer args is a feature since 3.0: the PDB will use defaults.
Several types functions were using the wording "float" historically to
mean double-precision, e.g. the float array type (which was in fact a
double array). Or the scanner function gimp_scanner_parse_float() was in
fact returning a double value. What if we wanted someday to actually add
float (usually this naming means in C the single-precision IEEE 754
floating point representation) support? How would we name this?
Now technically it's not entirely wrong (a double is still a floating
point). So I've been wondering if that is because maybe we never planned
to have float and double precision may be good enough for all usage in a
plug-in API (which doesn't have to be as generic so the higher precision
is enough)? But how can we be sure? Also we already had some functions
using the wording double (e.g. gimp_procedure_add_double_argument()), so
let's just go the safe route and use the accurate wording.
The additional change in PDB is internal, but there too, I was also
finding very confusing that we were naming double-precision float as
'float' type. So I took the opportunity to update this. It doesn't
change any signature.
In fact the whole commit doesn't change any type or code logic, only
naming, except for one bug fix in the middle which I encountered while
renaming: in gimp_scanner_parse_deprecated_color(), I discovered a
hidden bug in scanning (color-hsv*) values, which was mistakenly using a
double type for an array of float.
So an editor recognizes them.
Renames script-fu.init to init.scm since that is a Scheme convention.
Scheme interpreter maintainers expect that name.
The same name as upstream TinyScheme.
When mingled with plugin scripts, they needed a non-standard suffix .init.
Which makes an editor not recognize them.
Which deviates from Scheme convention for the main init script: init.scm.
The separate directory is also a place for script authors
to put Scheme scripts they don't want loaded automatically,
but when a script calls Scheme load function.
No change to observable behavior in the app or ScriptFu tools.
As suggested by reviewers, use a better word.
Regular denotes size.
Procedure is the same word used in the classes in the code.
Procedure denotes a general procedure, without specialization.
Renames only where visible externally by script authors.
Internally, some functions are still named "_regular".
That can be changed later as a style issue.
Building on prior commits, with a few small fixes to them.
First demonstrable changes towards #12605.
Font map plugin is ported as a test case.
Old-style plugins using script-fu-register still work.
Refactor: extract methods for int and float range errors
Enhance by naming the called PDB procedure
This helps script authors find the location of an error.
These errors can occur either when first authoring a plugin,
when a user stresses a plugin in a way not previously tested,
or when a called PDB procedure or plugin changes an argument type or range.
Note that calls from SF scripts to other SF plugins
are not always via a PDB call and then not range checked.
GimpExportOptions is incomplete.
It exists so the API is stable.
For now, ScriptFu eat and ignore actual args,
binding to NULL, in calls to PDB procedures
file-export-foo having formal args of this type.
Unlikely that in the future ScriptFu will do anything else:
if a plugin needs export options, use another language.
The few file exporters used by existing ScriptFu scripts
(file-gbr-export and file-pat-export)
don't honor export options.
This commit renames the GimpVectors
object to GimpPath in both app/core and
in libgimp. It also renames the files
to gimppath.[ch] and updates the relevant
build and translation files.
There are still outstanding gimp_vectors_* ()
functions on the app side that need to be renamed
in a subsequent commit.
This benefits script authors and testers of ScriptFu.
Now a call to (display "foo") in a plugin goes to the terminal where GIMP started.
Whether interactive or in batch mode.
Make TS errors go to an error port instead of the output port.
Tool plugins: Console, Eval, Server get error messages from the error port.
TextConsole not changed. Tools behave per new doc "ScriptFu Tools" at dev web site.
Driveby fix of SF Server: send whole message instead of byte by byte.
Driveby comments and more semantic checking of set-output-port in TS.
Add test plugin test-display.scm
There are no plug-ins which uses GimpRGB for procedure argument, nor is there
any base PDB procedure. We don't pass this type anymore through from/to
core/plug-ins. So let's clean the whole code out as a next step to get rid of
GimpRGB from our codebase!
Fix unreported issue that new-style dialog using GimpProcedureDialog
does not display progress.
Change progress reporting to use app's status bar, for all scripts,
old and new style.
As before, report progress whenever a script calls a PDB procedure,
by putting the procedure name in the status bar.
Eliminate progress bar widget from old-style script dialog.
Since it was failing on Wayland, and since it is inconsitent
with new style dialog using GimpProcedureDialog.
Allow (script-fu-use-v3) in script, or in SF Console.
Definitive description is in script-fu/docs/using-v3-binding.md
Makes SF interpret v3 of SF dialect.
- marshals single return value from PDB without wrapping in list
- marshals boolean return value from PDB as #t #f instead of integers
- marshals boolean to PDB from #t and #f or TRUE and FALSE
- marshals void return from PDB as () instead of (#t), but that is moot.
The version of SF dialect is distinct from the version of the PDB API.
Dialect v3 is opt-in: the initial dialect of all SF tools remains v2.
Commit also allows #t,#f for defaults of SF-TOGGLE instead of TRUE, FALSE
but that is an independent enhancement (but closely related.)
Affects interpreter state of the current process.
Not an attribute per se of a plugin.
While in this state, a plugin should not call PDB procedures
which are themselves v2 script plugins,
or a few utility scripts in script-fu-util.scm,
but that is rarely needed.
Does not remove symbols TRUE and FALSE from dialect.
A script can also call (script-fu-use-v2) to revert.
That is also discouraged but useful e.g. for testing.
Extract methods related to color into new file.
So method names document what is being done.
So related code is together.
Ditto for resource.
No functional change.
Preparing for changes to reset/default and changes to representation of pixels
in lists of differing lengths rgb vs rgba.
For the time being, only the same format as GimpRGB params is supported, which
means creating a color either as CSS strings or as RGBA list values, which means
that we can only input sRGB values right now in ScriptFu (even when calling
GeglColor-using API).
This is the second part to fix issue #10811.
Substantive change is call gimp_item_get_by_id instead of gimp_drawable...
And a few type changes from GimpDrawable* to GObject*.
Lots of renaming of functions, substituting "item" for "drawable."
Update comments.
Made one function static that was already private.
Fix the test case gimp_vectors_set_selected
I added a few specific validations for range types (int, double…), and a
generic validation at the end, meant to catch all yet uncaught invalid
argument cases (yet with less details on the what and why).
Changes only to ScriptFu.
The third term (the default) of a SF-FONT etc. spec is now ignored.
Test case is SF>Test>Sphere. There are still crashing issues
related but separate.
The gimp_procedure_run() already existed, though it was with an ordered
GimpValueArray array of arguments. Its usage feels redundant to the series of
gimp_pdb_run_procedure*() functions (which is confusing), but
gimp_procedure_run() was actually a bit more generic, because it does not
necessarily calls GimpProcedure-s through the PDB! For instance, it can runs a
local GimpProcedure, such as the case of one procedure which would want to call
another procedure in the same plug-in, but without having to go through PDB. Of
course, for local code, you may as well run relevant functions directly, yet it
makes sense that if one of the redundant-looking function is removed, it should
be the more specific one. Also gimp_procedure_run() feels a lot simpler and
logical, API wise.
A main difference in usage is that now, plug-in developers have to first
explicitly look up the GimpPdbProcedure with gimp_pdb_lookup_procedure() when
they wish to call PDB procedures on the wire. This was done anyway in the
gimp_pdb_run_procedure*() code, now it's explicit (rather than calling by name
directly).
Concretely:
* gimp_pdb_run_procedure(), gimp_pdb_run_procedure_config() and
gimp_pdb_run_procedure_valist() are removed.
* gimp_procedure_run() API is modified to use a variable args list instead of a
GimpValueArray.
* gimp_procedure_run_config() and gimp_procedure_run_valist() are added.
* gimp_procedure_run_config() in particular will be the one used in bindings
which don't have variable args support through a (rename-to
gimp_procedure_run) annotation.
