You are here

Trying to learn Gimp scripting API (in Python)

This is how far I've got with my first experimental plugin. I have learned how to take the selection and it's alpha channel into account. But I don't know how to merge that dynamically created layer to the base image. At least it seems to be the good style that typical plugin affects the active layer rather than leaves a new layer floating around.

I also don't understand should I use those img.disable_undo() and img.enable_undo()? My script works without those just fine. Or perhaps I should use those related to undo groups? I have no idea what's the difference and generally suggested practice.

I think I'd be not asking here some very specific dumb questions, if I could find any decent reference online. I really tried to find some, but failed. Or perhaps I don't know how to search for it? I mean something like API documentation, where all the objects and their methods are described. And perhaps some best practices, too. Right now, most of my plugin research is lines of painful trial-error attempts, feels like very inefficient way to spend my time. The only reasonable reference about Gimp-Python scripting I've found is here: http://www.gimp.org/docs/python/index.html But it certainly is very, very incomplete.

The plugin code is attached.

AttachmentSize
test.py1.5 KB

A script or plug-in should never "disable" the undo history unless it is working on an image which it has created. Disabling ('gimp-image-undo-disable') wipes all undo history (and your user may not be very happy about that). It is a good idea to disable undo when your script creates a new image (as with scripts under "File->Create->Logos", for example), and then enable undo when your script has finished -- in this way no undo steps (from other images) will be lost (GIMP uses a finite amount of undo memory). For such "image creating" scripts, the user can readily undo and redo by deleting the image and rerunning the script (or perhaps the created image is just a temporary one and deleted before your script finishes).

Except for some very rare occasions, when working with an existing image you will want to wrap your script's actions inside an undo group (using 'gimp-image-undo-group-start' and 'gimp-image-undo-group-end'), thereby leaving the image's undo history intact. You want your user to be able to undo whatever your script does with one "Edit->Undo" (CTRL-Z) and this is accomplished by grouping all your scripts actions as one "group".

Keep in mind that 1) grouping undo steps does not reduce the amount of undo memory required and 2) undo histories are image-specific -- each image has its own undo history -- though the amount of memory allocated for all of these histories is finite. Most typically this will not be a concern, but occasionally you will wish to consider the effect your script has on the overall undo storage requirements.

As an example, I once wrote a script which generated a calendar overlay for a layer which was the result of creating about 90 new layers (three for each day in the month) and performing a good number of steps for each layer (moving, resizing, drawing, filling, etc). Rather than merely grouping all of those steps, I chose to perform all of that work on a separate, temporary image (for which I disabled the undo history) and thus there was only a single step added to the original image's undo group (pasting the newly rendered layer). Depending upon how much work is being done, working on a separate, undo-disabled image can result in not only retention of the user's undo memory cache, but speed benefits as well.

As for 'gimp-image-undo-freeze', it disables adding any steps to the image's undo history but, unlike 'gimp-image-undo-disable', it does not wipe the history clean. Since it is necessary that your image be in the same state after "thawing" a frozen undo as it was before "freezing", this functionality seems of rather limited usefulness (I've only used it once).

Subscribe to Comments for "Trying to learn Gimp scripting API (in Python)"