7.7 KiB
API changes in libpika and the PDB for resources
This explains changes to the PIKA API from v2 to v3, concerning resources.
The audience is plugin authors, and PIKA developers.
Resources
A resource is a chunk of data that can be installed with PIKA and is used by painting tools or for other rendering tasks. Usually known as brush, font, palette, pattern, gradient and so forth.
Resources are now first class objects
PikaResource is now a class in libpika.
It has subclasses:
- Brush
- Font
- Gradient
- Palette
- Pattern
Formerly, the PIKA API had functions operating on resources by name. Now, there are methods on resource objects. Methods take an instance of the object as the first argument, often called "self."
This means that where you formerly used a string name to refer to a resource object, now you usually should pass an instance of an object.
Changes to reference documents
libpika API reference
Shows classes Brush, Font, and so forth. The classes have instance methods taking the instance as the first argument.
Example:
gboolean gboolean pika_brush_delete(gcharray) => gboolean pika_brush_delete ( PikaBrush*)
The classes may also have class methods still taking string names.
Example:
gboolean pika_brush_id_is_valid (const gchar* id)
Is a class method (in the "Functions" section of the class) taking the ID (same as the name) to test whether such a brush is installed in Pika core.
PDB Browser
Remember the PDB Browser shows the C API. You must mentally convert to the API in bound languages.
Shows some procedures that now take type e.g. PikaBrush where formerly they took type gcharray i.e. strings.
Shows some procedures that take a string name of a brush. These are usually class methods.
Other changes to the API
Many of the Pika functions dealing with the context now take or return an instance of a resource.
Example:
gcharray* pika_context_get_brush (void) => PikaBrush* pika_context_get_brush (void)
A few functions have even more changed signature:
gint pika_palette_get_info (gcharray) =>
gint pika_palette_get_color_count (PikaPalette*)
The name and description of this function are changed to accurately describe that the function only returns an integer (formerly, the description said it also returned the name of the palette.)
New resource objects
FUTURE
Formerly there were no methods in the libpika API or the PDB for objects:
- Dynamics
- ColorProfile
- ToolPreset
These classes exist primarily so that plugins can let a user choose an instance, and pass the instance on to other procedures.
Traits
Informally, resources can have these traits:
- Nameable
- Creatable/Deleable
- Cloneable (Duplicatable)
- Editable
Some resource subclasses don't have all traits.
ID's and names
The ID and name of a resource are currently the same. (Some documents and method names may use either word, inconsistently.)
You usually use resource instances instead of their IDs. This will insulate your code from changes to PIKA re ID versus name.
A plugin should not use a resource's ID. A plugin should not show the ID/name to a user. The PIKA app shows the names of resources as a convenience to users, but usually shows resources visually, that is, iconically. An ID is opaque, that is, used internally by PIKA.
FUTURE: the ID and name of a resource are distinct. Different resource instances may have the same name. Methods returning lists of resources or resource names may return lists having duplicate names.
Resource instances are references to underlying data
A resource instance is a proxy, or reference, to the underlying data. Methods on the instance act on the underlying data. The underlying data is in PIKA's store of resources.
It is possible for a resource instance to be "invalid" that is, referring to underlying data that does not exist, usually when a user uninstalls the thing.
Creating Resources
Installing a resource is distinct from creating a resource.
PIKA lets you create some resources. You can't create fonts in PIKA, you can only install them. For those resources that PIKA lets you create, the act of creating it also installs it.
For resources that you can create in PIKA:
- some you create using menu items
- some you can create using the API
The API does not let you create a raster brush.
The API does let you create a parametric brush. For example, in Python:
brush = Pika.Brush.new("Foo")
creates a new parametric brush.
Note that the passed name is a proposed name. If the name is already in use, the new brush will have a different name. The brush instance will always be valid.
Getting Resources by ID
Currently, you usually ask the user to interactively choose a resource.
If you must get a reference to a resource for which you know the ID, you can new() the resource class and set it's ID property. See below.
FUTURE Resource classes have get_by_id() methods.
If such a named resource is currently installed, get_by_id() returns a valid instance of the resource class. If such a named resource is not currently installed, the method returns an error.
Uninitialized or invalid resource instances
You can create an instance of a resource class that is invalid.
For example, in Python:
brush = Pika.Brush()
brush.set_property("id", "Foo")
creates an instance that is invalid because there is no underlying data in the PIKA store (assuming a brush named "Foo" is not installed.)
Ordinarily, you would not use such a construct. Instead, you should use the new() method (for resource classes where it is defined) which creates, installs, and returns a valid instance except in dire circumstances (out of memory.)
Invalid resource instances due to uninstalls
A plugin may have a resource as a parameter.
An interactive plugin may show a chooser widget to let a user choose a resource. The user's choices may be saved in settings.
In the same sesssion of PIKA, or in a subsequent session, a user may invoke the plugin again. Then the saved settings are displayed in the plugin's dialog (when the second invocation is also interactive).
When, in the meantime (between invocations of the plugin) a user has uninstalled the reference resource, the resource, as a reference, is invalid. A well-written plugin should handle this case.
Resource classes have:
- is_valid() instance method
- id_is_valid(char * name) class method
Well-written plugins should use these methods to ensure that saved (deserialized) resource instances are valid before subsequently using them.
Naming and renaming
As mentioned above, currently names must be unique.
For some resources, the method rename(char * name) changes the name. The method fails if the new name is already used.
When the instance is invalid to start with (it has an ID that does not refer to any installed data) renaming it can succeed and then it creates a valid instance.
Duplicating
Duplicating a resource creates and installs the underlying data, under a new, generated name.
The duplicate() method on an instance returns a new instance.
Deleting
You can delete some resources. This uninstalls them. You can delete some brushes, palettes, and gradients, when they are writeable i.e. editable, which usually means that a user previously created them. You can't delete fonts and patterns.
You can delete using the delete() instance method
When you delete a resource, the instance (the proxy in a variable) continues to exist, but is invalid.
Resource lists
Some functions in PIKA return lists of resource names, representing the set of resources installed.
For example: pika_brushes_get_list.
This returns a list of strings, the ID's of the resources. The list will have no duplicates.
FUTURE: this will return a list of resource instances, and their names may have duplicates.
