:right-sidebar: True

Preset
===================================================================

.. currentmodule:: gi.repository.Gst





.. class:: Preset(*args, **kwargs)
   :no-contents-entry:






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 :func:`~gi.repository.Gst.Preset.get_property_names`.
With that one can control which properties are saved and in which order.
When implementing support for read-only presets, one should set the vmethods
for :func:`~gi.repository.Gst.Preset.save_preset` and :func:`~gi.repository.Gst.Preset.delete_preset` to :const:`None`.
Applications can use :func:`~gi.repository.Gst.Preset.is_editable` to check for that.

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. Since 1.8 you can also provide extra paths
where to find presets through the GST_PRESET_PATH environment variable.
Presets found in those paths will be considered as "app presets".




Methods
-------

.. rst-class:: interim-class

.. class:: Preset
   :no-index:


   .. method:: delete_preset(name: str) -> bool

      Delete the given preset.






      :param name: preset name to remove




   .. classmethod:: get_app_dir() -> str | None

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









   .. method:: get_meta(name: str, tag: str) -> ~typing.Tuple[bool, str]

      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.






      :param name: preset name

      :param tag: meta data item name




   .. method:: get_preset_names() -> list[str]

      Get a copy of preset names as a :const:`None` terminated string array.









   .. method:: get_property_names() -> list[str]

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









   .. method:: is_editable() -> bool

      Check if one can add new presets, change existing ones and remove presets.


      .. versionadded:: 1.6








   .. method:: load_preset(name: str) -> bool

      Load the given preset.






      :param name: preset name to load




   .. method:: rename_preset(old_name: str, new_name: str) -> bool

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






      :param old_name: current preset name

      :param new_name: new preset name




   .. method:: save_preset(name: str) -> bool

      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.






      :param name: preset name to save




   .. classmethod:: set_app_dir() -> bool

      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.









   .. method:: set_meta(name: str, tag: str, value: str | None = None) -> bool

      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 :const:`None` for the
      ``value`` will unset an existing value.






      :param name: preset name

      :param tag: meta data item name

      :param value: new value












Virtual Methods
---------------

.. rst-class:: interim-class

.. class:: Preset
   :no-index:
   

   .. method:: do_delete_preset(name: str) -> bool

      Delete the given preset.






      :param name: preset name to remove




   .. method:: do_get_meta(name: str, tag: str) -> ~typing.Tuple[bool, str]

      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.






      :param name: preset name

      :param tag: meta data item name




   .. method:: do_get_preset_names() -> list[str]

      Get a copy of preset names as a :const:`None` terminated string array.









   .. method:: do_get_property_names() -> list[str]

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









   .. method:: do_load_preset(name: str) -> bool

      Load the given preset.






      :param name: preset name to load




   .. method:: do_rename_preset(old_name: str, new_name: str) -> bool

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






      :param old_name: current preset name

      :param new_name: new preset name




   .. method:: do_save_preset(name: str) -> bool

      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.






      :param name: preset name to save




   .. method:: do_set_meta(name: str, tag: str, value: str | None = None) -> bool

      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 :const:`None` for the
      ``value`` will unset an existing value.






      :param name: preset name

      :param tag: meta data item name

      :param value: new value