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 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 --------------------- .. 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) Allows the ability to change the properties depending on what settings are used by the user. 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:: 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)