PIKApp/devel-docs/PIKA3-plug-in-porting-guide/API-for-resources.md

# 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.