gmerlin
Data Structures | Defines | 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...

Defines

#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.

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.
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.

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

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.


Define 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
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