Properties API Reference (obs_properties_t)
===========================================
Properties are used to enumerate available settings for a libobs object.
Typically this is used to automatically generate user interface widgets,
though can be used to enumerate available and/or valid values for
specific settings as well.
.. type:: obs_properties_t
Properties object (not reference counted).
.. type:: obs_property_t
A property object (not reference counted).
.. code:: cpp
#include <obs.h>
General Functions
-----------------
.. function:: obs_properties_t *obs_properties_create(void)
:return: A new properties object.
---------------------
.. function:: obs_properties_t *obs_properties_create_param(void *param, void (*destroy)(void *param))
Creates a new properties object with specific private data *param*
associated with the object, and is automatically freed with the
object when the properties are destroyed via the *destroy* function.
:return: A new properties object.
---------------------
.. function:: void obs_properties_destroy(obs_properties_t *props)
---------------------
.. function:: void obs_properties_set_flags(obs_properties_t *props, uint32_t flags)
uint32_t obs_properties_get_flags(obs_properties_t *props)
:param flags: 0 or a bitwise OR combination of one of the following
values:
- OBS_PROPERTIES_DEFER_UPDATE - A hint that tells the
front-end to defers updating the settings until the
user has finished editing all properties rather than
immediately updating any settings
---------------------
.. function:: void obs_properties_set_param(obs_properties_t *props, void *param, void (*destroy)(void *param))
void *obs_properties_get_param(obs_properties_t *props)
Sets custom data associated with this properties object. If private
data is already associated with the object, that private data will be
destroyed before assigning new private data to it.
---------------------
.. function:: void obs_properties_apply_settings(obs_properties_t *props, obs_data_t *settings)
Applies settings to the properties by calling all the necessary
modification callbacks
---------------------
.. function:: obs_properties_t *obs_properties_get_parent(obs_properties_t *props)
---------------------
Property Object Functions
-------------------------
.. function:: obs_property_t *obs_properties_add_bool(obs_properties_t *props, const char *name, const char *description)
Adds a boolean property.
:param name: Setting identifier string
:param description: Localized name shown to user
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_int(obs_properties_t *props, const char *name, const char *description, int min, int max, int step)
Adds an integer property.
:param name: Setting identifier string
:param description: Localized name shown to user
:param min: Minimum value
:param max: Maximum value
:param step: Step value
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_float(obs_properties_t *props, const char *name, const char *description, double min, double max, double step)
:param name: Setting identifier string
:param description: Localized name shown to user
:param min: Minimum value
:param max: Maximum value
:param step: Step value
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_int_slider(obs_properties_t *props, const char *name, const char *description, int min, int max, int step)
:param name: Setting identifier string
:param description: Localized name shown to user
:param min: Minimum value
:param max: Maximum value
:param step: Step value
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_float_slider(obs_properties_t *props, const char *name, const char *description, double min, double max, double step)
:param name: Setting identifier string
:param description: Localized name shown to user
:param min: Minimum value
:param max: Maximum value
:param step: Step value
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_text(obs_properties_t *props, const char *name, const char *description, enum obs_text_type type)
:param name: Setting identifier string
:param description: Localized name shown to user
:param type: Can be one of the following values:
- **OBS_TEXT_DEFAULT** - Single line of text
- **OBS_TEXT_PASSWORD** - Single line of text (passworded)
- **OBS_TEXT_MULTILINE** - Multi-line text
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_path(obs_properties_t *props, const char *name, const char *description, enum obs_path_type type, const char *filter, const char *default_path)
Adds a 'path' property. Can be a directory or a file.
If target is a file path, the filters should be this format, separated by
double semi-colens, and extensions separated by space::
"Example types 1 and 2 (*.ex1 *.ex2);;Example type 3 (*.ex3)"
:param name: Setting identifier string
:param description: Localized name shown to user
:param type: Can be one of the following values:
- **OBS_PATH_FILE** - File (for reading)
- **OBS_PATH_FILE_SAVE** - File (for writing)
- **OBS_PATH_DIRECTORY** - Directory
:param filter: If type is a file path, then describes the file filter
that the user can browse. Items are separated via
double semi-colens. If multiple file types in a
filter, separate with space.
:param default_path: The default path to start in, or *NULL*
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_list(obs_properties_t *props, const char *name, const char *description, enum obs_combo_type type, enum obs_combo_format format)
Adds an integer/string/floating point item list. This would be
implemented as a combo box in user interface.
:param name: Setting identifier string
:param description: Localized name shown to user
:param type: Can be one of the following values:
- **OBS_COMBO_TYPE_EDITABLE** - Can be edited.
Only used with string lists.
- **OBS_COMBO_TYPE_LIST** - Not editable.
:param format: Can be one of the following values:
- **OBS_COMBO_FORMAT_INT** - Integer list
- **OBS_COMBO_FORMAT_FLOAT** - Floating point
list
- **OBS_COMBO_FORMAT_STRING** - String list
:return: The property
Important Related Functions:
- :c:func:`obs_property_list_add_string`
- :c:func:`obs_property_list_add_int`
- :c:func:`obs_property_list_add_float`
- :c:func:`obs_property_list_insert_string`
- :c:func:`obs_property_list_insert_int`
- :c:func:`obs_property_list_insert_float`
- :c:func:`obs_property_list_item_remove`
- :c:func:`obs_property_list_clear`
---------------------
.. function:: obs_property_t *obs_properties_add_color(obs_properties_t *props, const char *name, const char *description)
Adds a color property.
:param name: Setting identifier string
:param description: Localized name shown to user
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback)
Adds a button property. This property does not actually store any
settings; it's used to implement a button in user interface if the
properties are used to generate user interface.
:param name: Setting identifier string
:param description: Localized name shown to user
:return: The property
Relevant data types used with this function:
.. code:: cpp
typedef bool (*obs_property_clicked_t)(obs_properties_t *props,
obs_property_t *property, void *data);
---------------------
.. function:: obs_property_t *obs_properties_add_font(obs_properties_t *props, const char *name, const char *description)
Adds a font property.
:param name: Setting identifier string
:param description: Localized name shown to user
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_editable_list(obs_properties_t *props, const char *name, const char *description, enum obs_editable_list_type type, const char *filter, const char *default_path)
Adds a list in which the user can add/insert/remove items.
:param name: Setting identifier string
:param description: Localized name shown to user
:param type: Can be one of the following values:
- **OBS_EDITABLE_LIST_TYPE_STRINGS** - An
editable list of strings.
- **OBS_EDITABLE_LIST_TYPE_FILES** - An
editable list of files.
- **OBS_EDITABLE_LIST_TYPE_FILES_AND_URLS** -
An editable list of files and URLs.
:param filter: File filter to use if a file list
:param default_path: Default path if a file list
:return: The property
---------------------
.. function:: obs_property_t *obs_properties_add_frame_rate(obs_properties_t *props, const char *name, const char *description)
Adds a frame rate property.
:param name: Setting identifier string
:param description: Localized name shown to user
:return: The property
Important Related Functions:
- :c:func:`obs_property_frame_rate_option_add`
- :c:func:`obs_property_frame_rate_fps_range_add`
- :c:func:`obs_property_frame_rate_option_insert`
- :c:func:`obs_property_frame_rate_fps_range_insert`
---------------------
.. function:: obs_property_t *obs_properties_add_group(obs_properties_t *props, const char *name, const char *description, enum obs_group_type type, obs_properties_t *group)
Adds a property group.
:param name: Setting identifier string
:param description: Localized name shown to user
:param type: Can be one of the following values:
- **OBS_GROUP_NORMAL** - A normal group with just a name and content.
- **OBS_GROUP_CHECKABLE** - A checkable group with a checkbox, name and content.
:param group: Group to add
:return: The property
Important Related Functions:
- :c:func:`obs_property_group_type`
- :c:func:`obs_property_group_content`
- :c:func:`obs_properties_get_parent`
---------------------
Property Enumeration Functions
------------------------------
.. function:: obs_property_t *obs_properties_first(obs_properties_t *props)
:return: The first property in the properties object.
---------------------
.. function:: obs_property_t *obs_properties_get(obs_properties_t *props, const char *property)
:param property: The name of the property to get
:return: A specific property or *NULL* if not found
---------------------
.. function:: bool obs_property_next(obs_property_t **p)
:param p: Pointer to the pointer of the next property
:return: *true* if successful, *false* if no more properties
---------------------
.. function:: const char * obs_property_name(obs_property_t *p)
:return: The setting identifier string of the property
*(Author's Note: "name" was a bad name to use here. Should have been
"setting")*
---------------------
.. function:: const char * obs_property_description(obs_property_t *p)
:return: The actual localized display name of the property
*(Author's note: This one should have been the "name")*
---------------------
.. function:: const char * obs_property_long_description(obs_property_t *p)
:return: A detailed description of what the setting is used for.
Usually used with things like tooltips.
---------------------
.. function:: enum obs_property_type obs_property_get_type(obs_property_t *p)
:return: One of the following values:
- OBS_PROPERTY_INVALID
- OBS_PROPERTY_BOOL
- OBS_PROPERTY_INT
- OBS_PROPERTY_FLOAT
- OBS_PROPERTY_TEXT
- OBS_PROPERTY_PATH
- OBS_PROPERTY_LIST
- OBS_PROPERTY_COLOR
- OBS_PROPERTY_BUTTON
- OBS_PROPERTY_FONT
- OBS_PROPERTY_EDITABLE_LIST
- OBS_PROPERTY_FRAME_RATE
- OBS_PROPERTY_GROUP
---------------------
.. function:: bool obs_property_enabled(obs_property_t *p)
---------------------
.. function:: bool obs_property_visible(obs_property_t *p)
---------------------
.. function:: int obs_property_int_min(obs_property_t *p)
---------------------
.. function:: int obs_property_int_max(obs_property_t *p)
---------------------
.. function:: int obs_property_int_step(obs_property_t *p)
---------------------
.. function:: enum obs_number_type obs_property_int_type(obs_property_t *p)
---------------------
.. function:: double obs_property_float_min(obs_property_t *p)
---------------------
.. function:: double obs_property_float_max(obs_property_t *p)
---------------------
.. function:: double obs_property_float_step(obs_property_t *p)
---------------------
.. function:: enum obs_number_type obs_property_float_type(obs_property_t *p)
---------------------
.. function:: enum obs_text_type obs_property_text_type(obs_property_t *p)
---------------------
.. function:: enum obs_path_type obs_property_path_type(obs_property_t *p)
---------------------
.. function:: const char * obs_property_path_filter(obs_property_t *p)
---------------------
.. function:: const char * obs_property_path_default_path(obs_property_t *p)
---------------------
.. function:: enum obs_combo_type obs_property_list_type(obs_property_t *p)
---------------------
.. function:: enum obs_combo_format obs_property_list_format(obs_property_t *p)
---------------------
.. function:: bool obs_property_list_item_disabled(obs_property_t *p, size_t idx)
---------------------
.. function:: size_t obs_property_list_item_count(obs_property_t *p)
---------------------
.. function:: const char *obs_property_list_item_name(obs_property_t *p, size_t idx)
---------------------
.. function:: const char *obs_property_list_item_string(obs_property_t *p, size_t idx)
---------------------
.. function:: long long obs_property_list_item_int(obs_property_t *p, size_t idx)
---------------------
.. function:: double obs_property_list_item_float(obs_property_t *p, size_t idx)
---------------------
.. function:: enum obs_editable_list_type obs_property_editable_list_type(obs_property_t *p)
---------------------
.. function:: const char *obs_property_editable_list_filter(obs_property_t *p)
---------------------
.. function:: const char *obs_property_editable_list_default_path(obs_property_t *p)
---------------------
.. function:: size_t obs_property_frame_rate_options_count(obs_property_t *p)
---------------------
.. function:: const char *obs_property_frame_rate_option_name(obs_property_t *p, size_t idx)
---------------------
.. function:: const char *obs_property_frame_rate_option_description( obs_property_t *p, size_t idx)
---------------------
.. function:: size_t obs_property_frame_rate_fps_ranges_count(obs_property_t *p)
---------------------
.. function:: struct media_frames_per_second obs_property_frame_rate_fps_range_min( obs_property_t *p, size_t idx)
---------------------
.. function:: struct media_frames_per_second obs_property_frame_rate_fps_range_max( obs_property_t *p, size_t idx)
---------------------
.. function:: enum obs_group_type obs_property_group_type(obs_property_t *p)
:return: One of the following values:
- OBS_COMBO_INVALID
- OBS_GROUP_NORMAL
- OBS_GROUP_CHECKABLE
---------------------
.. function:: obs_properties_t *obs_property_group_content(obs_property_t *p)
---------------------
Property Modification Functions
-------------------------------
.. function:: void obs_property_set_modified_callback(obs_property_t *p, obs_property_modified_t modified)
void obs_property_set_modified_callback2(obs_property_t *p, obs_property_modified2_t modified2, void *priv)
Allows the ability to change the properties depending on what
settings are used by the user.
Relevant data types used with these functions:
.. code:: cpp
typedef bool (*obs_property_modified_t)(obs_properties_t *props,
obs_property_t *property, obs_data_t *settings);
typedef bool (*obs_property_modified2_t)(void *priv,
obs_properties_t *props, obs_property_t *property,
obs_data_t *settings);
---------------------
.. function:: bool obs_property_modified(obs_property_t *p, obs_data_t *settings)
---------------------
.. function:: bool obs_property_button_clicked(obs_property_t *p, void *obj)
---------------------
.. function:: void obs_property_set_visible(obs_property_t *p, bool visible)
---------------------
.. function:: void obs_property_set_enabled(obs_property_t *p, bool enabled)
---------------------
.. function:: void obs_property_set_description(obs_property_t *p, const char *description)
Sets the displayed localized name of the property, shown to the user.
---------------------
.. function:: void obs_property_set_long_description(obs_property_t *p, const char *long_description)
Sets the localized long description of the property, usually shown to
a user via tooltip.
---------------------
.. function:: void obs_property_int_set_limits(obs_property_t *p, int min, int max, int step)
---------------------
.. function:: void obs_property_float_set_limits(obs_property_t *p, double min, double max, double step)
---------------------
.. function:: void obs_property_list_clear(obs_property_t *p)
---------------------
.. function:: size_t obs_property_list_add_string(obs_property_t *p, const char *name, const char *val)
Adds a string to a string list.
---------------------
.. function:: size_t obs_property_list_add_int(obs_property_t *p, const char *name, long long val)
Adds an integer to a integer list.
---------------------
.. function:: size_t obs_property_list_add_float(obs_property_t *p, const char *name, double val)
Adds a floating point to a floating point list.
---------------------
.. function:: void obs_property_list_insert_string(obs_property_t *p, size_t idx, const char *name, const char *val)
Inserts a string in to a string list.
---------------------
.. function:: void obs_property_list_insert_int(obs_property_t *p, size_t idx, const char *name, long long val)
Inserts an integer in to an integer list.
---------------------
.. function:: void obs_property_list_insert_float(obs_property_t *p, size_t idx, const char *name, double val)
Inserts a floating point in to a floating point list.
---------------------
.. function:: void obs_property_list_item_disable(obs_property_t *p, size_t idx, bool disabled)
---------------------
.. function:: void obs_property_list_item_remove(obs_property_t *p, size_t idx)
---------------------
.. function:: size_t obs_property_frame_rate_option_add(obs_property_t *p, const char *name, const char *description)
---------------------
.. function:: size_t obs_property_frame_rate_fps_range_add(obs_property_t *p, struct media_frames_per_second min, struct media_frames_per_second max)
---------------------
.. function:: void obs_property_frame_rate_clear(obs_property_t *p)
---------------------
.. function:: void obs_property_frame_rate_options_clear(obs_property_t *p)
---------------------
.. function:: void obs_property_frame_rate_fps_ranges_clear(obs_property_t *p)
---------------------
.. function:: void obs_property_frame_rate_option_insert(obs_property_t *p, size_t idx, const char *name, const char *description)
---------------------
.. function:: void obs_property_frame_rate_fps_range_insert(obs_property_t *p, size_t idx, struct media_frames_per_second min, struct media_frames_per_second max)