GstPreset

## GstPreset GstPreset — helper interface for element presets |

## Synopsis

    #include <gst/gst.h>

                        GstPreset;
    struct              GstPresetInterface;
    gchar **            gst_preset_get_preset_names         (GstPreset *preset);
    gchar **            gst_preset_get_property_names       (GstPreset *preset);
    gboolean            gst_preset_load_preset              (GstPreset *preset,
                                                             const gchar *name);
    gboolean            gst_preset_save_preset              (GstPreset *preset,
                                                             const gchar *name);
    gboolean            gst_preset_rename_preset            (GstPreset *preset,
                                                             const gchar *old_name,
                                                             const gchar *new_name);
    gboolean            gst_preset_delete_preset            (GstPreset *preset,
                                                             const gchar *name);
    gboolean            gst_preset_set_meta                 (GstPreset *preset,
                                                             const gchar *name,
                                                             const gchar *tag,
                                                             const gchar *value);
    gboolean            gst_preset_get_meta                 (GstPreset *preset,
                                                             const gchar *name,
                                                             const gchar *tag,
                                                             gchar **value);
    gboolean            gst_preset_set_app_dir              (const gchar *app_dir);
    const gchar *       gst_preset_get_app_dir              (void);

## Object Hierarchy

      GInterface
       +----GstPreset

## Description

This interface offers methods to query and manipulate parameter preset sets. A preset is a bunch of property settings, together with meta data and a name. The name of a preset serves as key for subsequent method calls to manipulate single presets. All instances of one type will share the list of presets. The list is created on demand, if presets are not used, the list is not created.

The interface comes with a default implementation that serves most plugins. Wrapper plugins will override most methods to implement support for the native preset format of those wrapped plugins. One method that is useful to be overridden is `gst_preset_get_property_names()`. With that one can control which properties are saved and in which order.

The default implementation supports presets located in a system directory, application specific directory and in the users home directory. When getting a list of presets individual presets are read and overlaid in 1) system, 2) application and 3) user order. Whenever an earlier entry is newer, the later entries will be updated.

## Details

### GstPreset

    typedef struct _GstPreset GstPreset;

Opaque GstPreset data structure.

### struct GstPresetInterface

    struct GstPresetInterface {
      GTypeInterface parent;

      /* methods */
      gchar**      (*get_preset_names)    (GstPreset *preset);

      gchar**      (*get_property_names)  (GstPreset *preset);

      gboolean     (*load_preset)         (GstPreset *preset, const gchar *name);
      gboolean     (*save_preset)         (GstPreset *preset, const gchar *name);
      gboolean     (*rename_preset)       (GstPreset *preset, const gchar *old_name,
                                           const gchar *new_name);
      gboolean     (*delete_preset)       (GstPreset *preset, const gchar *name);

      gboolean     (*set_meta)            (GstPreset *preset, const gchar *name,
                                           const gchar *tag, const gchar *value);
      gboolean     (*get_meta)            (GstPreset *preset, const gchar *name,
                                           const gchar *tag, gchar **value);
    };

GstPreset interface.

GTypeInterface `parent`; | parent interface type.
`get_preset_names` () | virtual method to get list of presets
`get_property_names` () | virtual methods to get properties that are persistent
`load_preset` () | virtual methods to load a preset into properties
`save_preset` () | virtual methods to save properties into a preset
`rename_preset` () | virtual methods to rename a preset
`delete_preset` () | virtual methods to remove a preset
`set_meta` () | virtual methods to set textual meta data to a preset
`get_meta` () | virtual methods to get textual meta data from a preset

### gst_preset_get_preset_names ()

    gchar **            gst_preset_get_preset_names         (GstPreset *preset);

Get a copy of preset names as a NULL terminated string array.

`preset` : | a GObject that implements GstPreset
Returns : | list with names, ue `g_strfreev()` after usage. [transfer full][array zero-terminated=1][element-type gchar*]

### gst_preset_get_property_names ()

    gchar **            gst_preset_get_property_names       (GstPreset *preset);

Get a the names of the GObject properties that can be used for presets.

`preset` : | a GObject that implements GstPreset
Returns : | an array of property names which should be freed with `g_strfreev()` after use. [transfer full][array zero-terminated=1][element-type gchar*]

### gst_preset_load_preset ()

    gboolean            gst_preset_load_preset              (GstPreset *preset,
                                                             const gchar *name);

Load the given preset.

`preset` : | a GObject that implements GstPreset
`name` : | preset name to load
Returns : | `TRUE` for success, `FALSE` if e.g. there is no preset with that `name`

### gst_preset_save_preset ()

    gboolean            gst_preset_save_preset              (GstPreset *preset,
                                                             const gchar *name);

Save the current object settings as a preset under the given name. If there is already a preset by this `name` it will be overwritten.

`preset` : | a GObject that implements GstPreset
`name` : | preset name to save
Returns : | `TRUE` for success, `FALSE`

### gst_preset_rename_preset ()

    gboolean            gst_preset_rename_preset            (GstPreset *preset,
                                                             const gchar *old_name,
                                                             const gchar *new_name);

Renames a preset. If there is already a preset by the `new_name` it will be overwritten.

`preset` : | a GObject that implements GstPreset
`old_name` : | current preset name
`new_name` : | new preset name
Returns : | `TRUE` for success, `FALSE` if e.g. there is no preset with `old_name`

### gst_preset_delete_preset ()

    gboolean            gst_preset_delete_preset            (GstPreset *preset,
                                                             const gchar *name);

Delete the given preset.

`preset` : | a GObject that implements GstPreset
`name` : | preset name to remove
Returns : | `TRUE` for success, `FALSE` if e.g. there is no preset with that `name`

### gst_preset_set_meta ()

    gboolean            gst_preset_set_meta                 (GstPreset *preset,
                                                             const gchar *name,
                                                             const gchar *tag,
                                                             const gchar *value);

Sets a new `value` for an existing meta data item or adds a new item. Meta data `tag` names can be something like e.g. "comment". Supplying `NULL` for the `value` will unset an existing value.

`preset` : | a GObject that implements GstPreset
`name` : | preset name
`tag` : | meta data item name
`value` : | new value
Returns : | `TRUE` for success, `FALSE` if e.g. there is no preset with that `name`

### gst_preset_get_meta ()

    gboolean            gst_preset_get_meta                 (GstPreset *preset,
                                                             const gchar *name,
                                                             const gchar *tag,
                                                             gchar **value);

Gets the `value` for an existing meta data `tag`. Meta data `tag` names can be something like e.g. "comment". Returned values need to be released when done.

`preset` : | a GObject that implements GstPreset
`name` : | preset name
`tag` : | meta data item name
`value` : | value. [out callee-allocates]
Returns : | `TRUE` for success, `FALSE` if e.g. there is no preset with that `name` or no value for the given `tag`

### gst_preset_set_app_dir ()

    gboolean            gst_preset_set_app_dir              (const gchar *app_dir);

Sets an extra directory as an absolute path that should be considered when looking for presets. Any presets in the application dir will shadow the system presets.

`app_dir` : | the application specific preset dir
Returns : | `TRUE` for success, `FALSE` if the dir already has been set

### gst_preset_get_app_dir ()

    const gchar *       gst_preset_get_app_dir              (void);

Gets the directory for application specific presets if set by the application.

Returns : | the directory or `NULL`, don't free or modify the string