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:
data Instance
name Name of the parameter
v Value
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:
data Instance
name Name of the parameter
v Value
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:
src Source

bg_parameter_info_t* bg_parameter_info_copy_array ( const bg_parameter_info_t src  ) 

Copy a NULL terminated parameter array.

Parameters:
src Source 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:
info A 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:
info 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.

Parameters:
dst Destination
src Source
info Parameter 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:
val A parameter value
type Type of the parameter

bg_parameter_info_t* bg_parameter_info_concat_arrays ( bg_parameter_info_t const **  srcs  ) 

Concatenate multiple arrays into one.

Parameters:
srcs NULL 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:
info A parameter info
val The 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:
info A parameter info
name The 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_doc Pointer to the xml document
xml_parameters Pointer 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:
info Parameter array
xml_parameters Pointer 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:
info Parameter array
filename File to dump to
Used for debugging


doxygen