## IpatchParamProp

IpatchParamProp — GParamSpec extended properties

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #define             IPATCH_PARAM_USER_SHIFT
    void                ipatch_param_install_property       (GParamSpec *prop_spec);
    GParamSpec *        ipatch_param_find_property          (const char *name);
    GParamSpec **       ipatch_param_list_properties        (guint *n_properties);
    GParamSpec *        ipatch_param_set                    (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             ...);
    void                ipatch_param_set_valist             (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             va_list args);
    void                ipatch_param_set_property           (GParamSpec *spec,
                                                             const char *property_name,
                                                             const GValue *value);
    void                ipatch_param_get                    (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             ...);
    void                ipatch_param_get_valist             (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             va_list args);
    gboolean            ipatch_param_get_property           (GParamSpec *spec,
                                                             const char *property_name,
                                                             GValue *value);

## Description

Extensions to standard GParamSpec include flags (for compact single bit data extensions) and GValue based extensions. An example of usage is the IPATCH_PARAM_UNIQUE flag which indicates a parameter that should be unique amongst sibling items and the "string-max-length" integer GValue which specifies a max length of a GParamSpecString parameter.

## Details

### IPATCH_PARAM_USER_SHIFT

    #define IPATCH_PARAM_USER_SHIFT  (G_PARAM_USER_SHIFT + 12)

### ipatch_param_install_property ()

    void                ipatch_param_install_property       (GParamSpec *prop_spec);

Install a new GParamSpec property which can be used to extend existing GParamSpec types or define common parameters shared by all types. An example property is the "string-max-length" property which defines a max length for use with GParamSpecString properties.

`prop_spec` : | Specification for the new GParamSpec property. Ownership of the GParamSpec is taken over by this function. The name field of the GParamSpec should be a static string and is used as the property's ID.

### ipatch_param_find_property ()

    GParamSpec *        ipatch_param_find_property          (const char *name);

Lookup a GParamSpec property by name.

`name` : | Name of GParamSpec property
Returns : | The matching GParamSpec or `NULL` if not found. The GParamSpec is internal and should NOT be modified or freed.

### ipatch_param_list_properties ()

    GParamSpec **       ipatch_param_list_properties        (guint *n_properties);

Get a list of all registered GParamSpec properties.

`n_properties` : | Output: Length of returned array
Returns : | An array of GParamSpecs which should be freed when finished.

### ipatch_param_set ()

    GParamSpec *        ipatch_param_set                    (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             ...);

Set extended parameter properties. Parameter properties are used to extend existing GParamSpec types. "string-max-length" is an example of an extended property, which is used for GParamSpecString parameters to define the max allowed length.

`spec` : | Parameter spec to set extended properties of
`first_property_name` : | Name of first property to set
`...` : | Value of first property to set and optionally followed by more property name/value pairs, terminated with `NULL` name.
Returns : | The `spec` pointer for convenience, makes it easy to create/install a parameter spec and set its properties at the same time.

### ipatch_param_set_valist ()

    void                ipatch_param_set_valist             (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             va_list args);

Like `ipatch_param_set()` but uses a va_list.

`spec` : | Parameter spec to set extended properties of
`first_property_name` : | Name of first property to set
`args` : | Value of first property to set and optionally followed by more property name/value pairs, terminated with `NULL` name.

### ipatch_param_set_property ()

    void                ipatch_param_set_property           (GParamSpec *spec,
                                                             const char *property_name,
                                                             const GValue *value);

Set a single extended parameter property of a GParamSpec.

`spec` : | Parameter spec to set an extended property of
`property_name` : | Name of property to set
`value` : | Value to set the the property to. The value's type must be the same as the parameter property's type.

### ipatch_param_get ()

    void                ipatch_param_get                    (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             ...);

Get extended parameter properties. Parameter properties are used to extend existing GParamSpec types. "string-max-length" is an example of an extended property, which is used for GParamSpecString parameters to define the max allowed length.

`spec` : | Parameter spec to get extended properties from
`first_property_name` : | Name of first property to get
`...` : | Pointer to store first property value and optionally followed by more property name/value pairs, terminated with `NULL` name.

### ipatch_param_get_valist ()

    void                ipatch_param_get_valist             (GParamSpec *spec,
                                                             const char *first_property_name,
                                                             va_list args);

Like `ipatch_param_get()` but uses a va_list.

`spec` : | Parameter spec to get extended properties from
`first_property_name` : | Name of first property to get
`args` : | Pointer to store first property value and optionally followed by more property name/value pairs, terminated with `NULL` name.

### ipatch_param_get_property ()

    gboolean            ipatch_param_get_property           (GParamSpec *spec,
                                                             const char *property_name,
                                                             GValue *value);

Get a single extended parameter property from a GParamSpec.

`spec` : | Parameter spec to get an extended property from
`property_name` : | Name of property to get
`value` : | An initialized value to store the property value in. The value's type must be a type that the property can be transformed to.
Returns : | `TRUE` if the parameter property is set, `FALSE` otherwise (in which case `value` will contain the default value for this property).