gmerlin
Data Structures | Macros | Typedefs | Enumerations | Functions
Parameter description

Data Structures

union  bg_parameter_value_t
 Container for a parameter value. More...
 
struct  bg_parameter_info_s
 Parmeter description. More...
 

Macros

#define BG_PARAMETER_SYNC   (1<<0)
 Apply the value whenever the widgets value changes. More...
 
#define BG_PARAMETER_HIDE_DIALOG   (1<<1)
 Don't make a configuration widget (for objects, which change values themselves) More...
 
#define BG_PARAMETER_NO_SORT   (1<<2)
 Don't make a list sortable. More...
 
#define BG_PARAMETER_PLUGIN   (1<<3)
 Parameter refers to a plugin. More...
 
#define BG_PARAMETER_OWN_SECTION   (1<<4)
 For parameters of the type BG_PARAMETER_SECTION: Following parameters should be stored in an own section. More...
 
#define BG_PARAMETER_GLOBAL_PRESET   (1<<5)
 Typedef for parmeter description. More...
 

Typedefs

typedef void(* bg_set_parameter_func_t )(void *data, const char *name, const bg_parameter_value_t *v)
 Generic prototype for setting parameters in a module. More...
 
typedef int(* bg_get_parameter_func_t )(void *data, const char *name, bg_parameter_value_t *v)
 Generic prototype for getting parameters from a module. More...
 

Enumerations

enum  bg_parameter_type_t {
  BG_PARAMETER_SECTION,
  BG_PARAMETER_CHECKBUTTON,
  BG_PARAMETER_INT,
  BG_PARAMETER_FLOAT,
  BG_PARAMETER_SLIDER_INT,
  BG_PARAMETER_SLIDER_FLOAT,
  BG_PARAMETER_STRING,
  BG_PARAMETER_STRING_HIDDEN,
  BG_PARAMETER_STRINGLIST,
  BG_PARAMETER_COLOR_RGB,
  BG_PARAMETER_COLOR_RGBA,
  BG_PARAMETER_FONT,
  BG_PARAMETER_DEVICE,
  BG_PARAMETER_FILE,
  BG_PARAMETER_DIRECTORY,
  BG_PARAMETER_MULTI_MENU,
  BG_PARAMETER_MULTI_LIST,
  BG_PARAMETER_MULTI_CHAIN,
  BG_PARAMETER_TIME,
  BG_PARAMETER_POSITION,
  BG_PARAMETER_BUTTON
}
 Parameter type. More...
 

Functions

void bg_parameter_info_copy (bg_parameter_info_t *dst, const bg_parameter_info_t *src)
 Copy a single parameter info. More...
 
bg_parameter_info_tbg_parameter_info_copy_array (const bg_parameter_info_t *src)
 Copy a NULL terminated parameter array. More...
 
void bg_parameter_info_set_const_ptrs (bg_parameter_info_t *info)
 Set the const pointers of a dynamically allocated parameter info. More...
 
void bg_parameter_info_destroy_array (bg_parameter_info_t *info)
 Free a NULL terminated parameter array. More...
 
void bg_parameter_value_copy (bg_parameter_value_t *dst, const bg_parameter_value_t *src, const bg_parameter_info_t *info)
 Copy a parameter value. More...
 
void bg_parameter_value_free (bg_parameter_value_t *val, bg_parameter_type_t type)
 Free a parameter value. More...
 
bg_parameter_info_tbg_parameter_info_concat_arrays (bg_parameter_info_t const **srcs)
 Concatenate multiple arrays into one. More...
 
int bg_parameter_get_selected (const bg_parameter_info_t *info, const char *val)
 Get the index for a multi-options parameter. More...
 
const bg_parameter_info_tbg_parameter_find (const bg_parameter_info_t *info, const char *name)
 Find a parameter info. More...
 
bg_parameter_info_tbg_xml_2_parameters (xmlDocPtr xml_doc, xmlNodePtr xml_parameters)
 Convert a libxml2 node into a parameter array. More...
 
void bg_parameters_2_xml (const bg_parameter_info_t *info, xmlNodePtr xml_parameters)
 Convert a parameter array into a libxml2 node. More...
 
void bg_parameters_dump (const bg_parameter_info_t *info, const char *filename)
 Dump a parameter array into a xml file. More...
 

Detailed Description

Parameters are universal data containers, which are the basis for all configuration mechanisms.

A configurable module foo, should provide at least 2 functions. One, which lets the application get a null-terminated array of parameter description and one of type bg_set_parameter_func_t. It's up to the module, if the parameter array is allocated per instance or if it's just a static array. Some parameters (e.g. window coordinates) are not configured by a dialog. Instead, they are changed by the module. For these parameters, set BG_PARAMETER_HIDE_DIALOG for the flags and provide another function of type bg_get_parameter_func_t, which lets the core read the updated value.

Macro Definition Documentation

#define BG_PARAMETER_SYNC   (1<<0)

Apply the value whenever the widgets value changes.

#define BG_PARAMETER_HIDE_DIALOG   (1<<1)

Don't make a configuration widget (for objects, which change values themselves)

#define BG_PARAMETER_NO_SORT   (1<<2)

Don't make a list sortable.

#define BG_PARAMETER_PLUGIN   (1<<3)

Parameter refers to a plugin.

#define BG_PARAMETER_OWN_SECTION   (1<<4)

For parameters of the type BG_PARAMETER_SECTION: Following parameters should be stored in an own section.

#define BG_PARAMETER_GLOBAL_PRESET   (1<<5)

Typedef for parmeter description.

For parameters of the type BG_PARAMETER_SECTION: There should be one preset for all following sections

Typedef Documentation

typedef void(* bg_set_parameter_func_t)(void *data, const char *name, const bg_parameter_value_t *v)

Generic prototype for setting parameters in a module.

Parameters
dataInstance
nameName of the parameter
vValue

This function is usually called from "Apply" buttons in config dialogs. It's called subsequently for all defined püarameters. After that, it must be called with a NULL argument for the name to signal, that all parameters are set. Modules can do some additional setup stuff then. If not, the name == NULL case must be handled nevertheless.

typedef int(* bg_get_parameter_func_t)(void *data, const char *name, bg_parameter_value_t *v)

Generic prototype for getting parameters from a module.

Parameters
dataInstance
nameName of the parameter
vValue
Returns
1 if a parameter was found and set, 0 else.

Provide this function, if your module changes parameters by itself. Set the BG_PARAMETER_HIDE_DIALOG to prevent building config dialogs for those parameters.

Enumeration Type Documentation

Parameter type.

These define both the data type and the appearance of an eventual configuration widget.

Enumerator
BG_PARAMETER_SECTION 

Dummy type. It contains no data but acts as a separator in notebook style configuration windows.

BG_PARAMETER_CHECKBUTTON 

Bool.

BG_PARAMETER_INT 

Integer spinbutton.

BG_PARAMETER_FLOAT 

Float spinbutton.

BG_PARAMETER_SLIDER_INT 

Integer slider.

BG_PARAMETER_SLIDER_FLOAT 

Float slider.

BG_PARAMETER_STRING 

String (one line only)

BG_PARAMETER_STRING_HIDDEN 

Encrypted string (displays as ***)

BG_PARAMETER_STRINGLIST 

Popdown menu with string values.

BG_PARAMETER_COLOR_RGB 

RGB Color.

BG_PARAMETER_COLOR_RGBA 

RGBA Color.

BG_PARAMETER_FONT 

Font (contains fontconfig compatible fontname)

BG_PARAMETER_DEVICE 

Device.

BG_PARAMETER_FILE 

File.

BG_PARAMETER_DIRECTORY 

Directory.

BG_PARAMETER_MULTI_MENU 

Menu with config- and infobutton.

BG_PARAMETER_MULTI_LIST 

List with config- and infobutton.

BG_PARAMETER_MULTI_CHAIN 

Several subitems (including suboptions) can be arranged in a chain.

BG_PARAMETER_TIME 

Time.

BG_PARAMETER_POSITION 

Position (x/y coordinates, scaled 0..1)

BG_PARAMETER_BUTTON 

Pressing the button causes set_parameter to be called with NULL value.

Function Documentation

void bg_parameter_info_copy ( bg_parameter_info_t dst,
const bg_parameter_info_t src 
)

Copy a single parameter info.

Parameters
srcSource
dstDestination
bg_parameter_info_t* bg_parameter_info_copy_array ( const bg_parameter_info_t src)

Copy a NULL terminated parameter array.

Parameters
srcSource array
Returns
A newly allocated parameter array, whose contents are copied from src.

Use bg_parameter_info_destroy_array to free the returned array.

void bg_parameter_info_set_const_ptrs ( bg_parameter_info_t info)

Set the const pointers of a dynamically allocated parameter info.

Parameters
infoA parameter info

This copied the adresses of the *_nc pointers to their constant equivalents. Use this for each parameter in routines, which dynamically allocate parameter infos.

void bg_parameter_info_destroy_array ( bg_parameter_info_t info)

Free a NULL terminated parameter array.

Parameters
infoParameter array
void bg_parameter_value_copy ( bg_parameter_value_t dst,
const bg_parameter_value_t src,
const bg_parameter_info_t info 
)

Copy a parameter value.

Parameters
dstDestination
srcSource
infoParameter description

Make sure, that dst is either memset to 0 or contains data, which was created by bg_parameter_value_copy

void bg_parameter_value_free ( bg_parameter_value_t val,
bg_parameter_type_t  type 
)

Free a parameter value.

Parameters
valA parameter value
typeType of the parameter
bg_parameter_info_t* bg_parameter_info_concat_arrays ( bg_parameter_info_t const **  srcs)

Concatenate multiple arrays into one.

Parameters
srcsNULL terminated array of source arrays
Returns
A newly allocated array
int bg_parameter_get_selected ( const bg_parameter_info_t info,
const char *  val 
)

Get the index for a multi-options parameter.

Parameters
infoA parameter info
valThe value
Returns
The index of val in the multi_names array

If val does not occur in the multi_names[] array, try the default value. If that fails as well, return 0.

const bg_parameter_info_t* bg_parameter_find ( const bg_parameter_info_t info,
const char *  name 
)

Find a parameter info.

Parameters
infoA parameter info
nameThe name of the the parameter
Returns
Parameter info matching name or NULL

This function looks for a parameter info with the given name in an array or parameters. Sub-parameters are also searched.

bg_parameter_info_t* bg_xml_2_parameters ( xmlDocPtr  xml_doc,
xmlNodePtr  xml_parameters 
)

Convert a libxml2 node into a parameter array.

Parameters
xml_docPointer to the xml document
xml_parametersPointer to the xml node containing the parameters
Returns
A newly allocated array

See the libxml2 documentation for more infos

void bg_parameters_2_xml ( const bg_parameter_info_t info,
xmlNodePtr  xml_parameters 
)

Convert a parameter array into a libxml2 node.

Parameters
infoParameter array
xml_parametersPointer to the xml node for the parameters

See the libxml2 documentation for more infos

void bg_parameters_dump ( const bg_parameter_info_t info,
const char *  filename 
)

Dump a parameter array into a xml file.

Parameters
infoParameter array
filenameFile to dump to

Used for debugging