GParamSpec: GObject Reference Manual

## GParamSpec GParamSpec — Metadata for parameter specifications |

## Functions

#define | G_TYPE_IS_PARAM()
#define | G_PARAM_SPEC()
#define | G_IS_PARAM_SPEC()
#define | G_PARAM_SPEC_CLASS()
#define | G_IS_PARAM_SPEC_CLASS()
#define | G_PARAM_SPEC_GET_CLASS()
#define | G_PARAM_SPEC_TYPE()
#define | G_PARAM_SPEC_TYPE_NAME()
#define | G_PARAM_SPEC_VALUE_TYPE()
GParamSpec * | g_param_spec_ref ()
void | g_param_spec_unref ()
void | g_param_spec_sink ()
GParamSpec * | g_param_spec_ref_sink ()
const GValue * | g_param_spec_get_default_value ()
void | g_param_value_set_default ()
gboolean | g_param_value_defaults ()
gboolean | g_param_value_validate ()
gboolean | g_param_value_convert ()
gint | g_param_values_cmp ()
const gchar * | g_param_spec_get_name ()
GQuark | g_param_spec_get_name_quark ()
const gchar * | g_param_spec_get_nick ()
const gchar * | g_param_spec_get_blurb ()
gpointer | g_param_spec_get_qdata ()
void | g_param_spec_set_qdata ()
void | g_param_spec_set_qdata_full ()
gpointer | g_param_spec_steal_qdata ()
GParamSpec * | g_param_spec_get_redirect_target ()
gpointer | g_param_spec_internal ()
GType | g_param_type_register_static ()
GParamSpecPool * | g_param_spec_pool_new ()
void | g_param_spec_pool_insert ()
void | g_param_spec_pool_remove ()
GParamSpec * | g_param_spec_pool_lookup ()
GParamSpec ** | g_param_spec_pool_list ()
GList * | g_param_spec_pool_list_owned ()

## Types and Values

struct | GParamSpec
struct | GParamSpecClass
enum | GParamFlags
#define | G_PARAM_STATIC_STRINGS
#define | G_PARAM_MASK
#define | G_PARAM_USER_SHIFT
struct | GParamSpecTypeInfo
| GParamSpecPool

## Includes

    #include <glib-object.h>

## Description

GParamSpec is an object structure that encapsulates the metadata required to specify parameters, such as e.g. GObject properties.

#### Parameter names

Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a '-'. All other characters are replaced by a '-' during construction. The result of this replacement is called the canonical name of the parameter.

## Functions

### G_TYPE_IS_PARAM()

    #define G_TYPE_IS_PARAM(type)		(G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)

Checks whether `type` "is a" `G_TYPE_PARAM`.

#### Parameters

type | a GType ID |

### G_PARAM_SPEC()

    #define G_PARAM_SPEC(pspec)		(G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))

Casts a derived GParamSpec object (e.g. of type GParamSpecInt) into a GParamSpec object.

#### Parameters

pspec | a valid GParamSpec |

### G_IS_PARAM_SPEC()

    #define G_IS_PARAM_SPEC(pspec)		(G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE ((pspec), G_TYPE_PARAM))

Checks whether `pspec` "is a" valid GParamSpec structure of type `G_TYPE_PARAM` or derived.

#### Parameters

pspec | a GParamSpec |

### G_PARAM_SPEC_CLASS()

    #define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))

Casts a derived GParamSpecClass structure into a GParamSpecClass structure.

#### Parameters

pclass | a valid GParamSpecClass |

### G_IS_PARAM_SPEC_CLASS()

    #define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))

Checks whether `pclass` "is a" valid GParamSpecClass structure of type `G_TYPE_PARAM` or derived.

#### Parameters

pclass | a GParamSpecClass |

### G_PARAM_SPEC_GET_CLASS()

    #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))

Retrieves the GParamSpecClass of a GParamSpec.

#### Parameters

pspec | a valid GParamSpec |

### G_PARAM_SPEC_TYPE()

    #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec))

Retrieves the GType of this `pspec` .

#### Parameters

pspec | a valid GParamSpec |

### G_PARAM_SPEC_TYPE_NAME()

    #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec)))

Retrieves the GType name of this `pspec` .

#### Parameters

pspec | a valid GParamSpec |

### G_PARAM_SPEC_VALUE_TYPE()

    #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type)

Retrieves the GType to initialize a GValue for this parameter.

#### Parameters

pspec | a valid GParamSpec |

### g_param_spec_ref ()

    GParamSpec *
    g_param_spec_ref (GParamSpec *pspec);

Increments the reference count of `pspec` .

[skip]

#### Parameters

pspec | a valid GParamSpec |

#### Returns

the GParamSpec that was passed into this function

### g_param_spec_unref ()

    void
    g_param_spec_unref (GParamSpec *pspec);

Decrements the reference count of a `pspec` .

[skip]

#### Parameters

pspec | a valid GParamSpec |

### g_param_spec_sink ()

    void
    g_param_spec_sink (GParamSpec *pspec);

The initial reference count of a newly created GParamSpec is 1, even though no one has explicitly called `g_param_spec_ref()` on it yet. So the initial reference count is flagged as "floating", until someone calls `g_param_spec_ref (pspec); g_param_spec_sink (pspec);` in sequence on it, taking over the initial reference count (thus ending up with a `pspec` that has a reference count of 1 still, but is not flagged "floating" anymore).

#### Parameters

pspec | a valid GParamSpec |

### g_param_spec_ref_sink ()

    GParamSpec *
    g_param_spec_ref_sink (GParamSpec *pspec);

Convenience function to ref and sink a GParamSpec.

[skip]

#### Parameters

pspec | a valid GParamSpec |

#### Returns

the GParamSpec that was passed into this function

Since: 2.10

### g_param_spec_get_default_value ()

    const GValue *
    g_param_spec_get_default_value (GParamSpec *pspec);

Gets the default value of `pspec` as a pointer to a GValue.

The GValue will remain value for the life of `pspec` .

#### Parameters

pspec | a GParamSpec |

#### Returns

a pointer to a GValue which must not be modified

Since: 2.38

### g_param_value_set_default ()

    void
    g_param_value_set_default (GParamSpec *pspec,
                               GValue *value);

Sets `value` to its default value as specified in `pspec` .

#### Parameters

pspec | a valid GParamSpec |
value | a GValue of correct type for `pspec` |

### g_param_value_defaults ()

    gboolean
    g_param_value_defaults (GParamSpec *pspec,
                            GValue *value);

Checks whether `value` contains the default value as specified in `pspec` .

#### Parameters

pspec | a valid GParamSpec |
value | a GValue of correct type for `pspec` |

#### Returns

whether `value` contains the canonical default for this `pspec`

### g_param_value_validate ()

    gboolean
    g_param_value_validate (GParamSpec *pspec,
                            GValue *value);

Ensures that the contents of `value` comply with the specifications set out by `pspec` . For example, a GParamSpecInt might require that integers stored in `value` may not be smaller than -42 and not be greater than +42. If `value` contains an integer outside of this range, it is modified accordingly, so the resulting value will fit into the range -42 .. +42.

#### Parameters

pspec | a valid GParamSpec |
value | a GValue of correct type for `pspec` |

#### Returns

whether modifying `value` was necessary to ensure validity

### g_param_value_convert ()

    gboolean
    g_param_value_convert (GParamSpec *pspec,
                           const GValue *src_value,
                           GValue *dest_value,
                           gboolean strict_validation);

Transforms `src_value` into `dest_value` if possible, and then validates `dest_value` , in order for it to conform to `pspec` . If `strict_validation` is `TRUE` this function will only succeed if the transformed `dest_value` complied to `pspec` without modifications.

See also `g_value_type_transformable()`, `g_value_transform()` and `g_param_value_validate()`.

#### Parameters

pspec | a valid GParamSpec |
src_value | souce GValue |
dest_value | destination GValue of correct type for `pspec` |
strict_validation | `TRUE` requires `dest_value` to conform to `pspec` without modifications |

#### Returns

`TRUE` if transformation and validation were successful, `FALSE` otherwise and `dest_value` is left untouched.

### g_param_values_cmp ()

    gint
    g_param_values_cmp (GParamSpec *pspec,
                        const GValue *value1,
                        const GValue *value2);

Compares `value1` with `value2` according to `pspec` , and return -1, 0 or +1, if `value1` is found to be less than, equal to or greater than `value2` , respectively.

#### Parameters

pspec | a valid GParamSpec |
value1 | a GValue of correct type for `pspec` |
value2 | a GValue of correct type for `pspec` |

#### Returns

-1, 0 or +1, for a less than, equal to or greater than result

### g_param_spec_get_name ()

    const gchar *
    g_param_spec_get_name (GParamSpec *pspec);

Get the name of a GParamSpec.

The name is always an "interned" string (as per `g_intern_string()`). This allows for pointer-value comparisons.

#### Parameters

pspec | a valid GParamSpec |

#### Returns

the name of `pspec` .

### g_param_spec_get_name_quark ()

    GQuark
    g_param_spec_get_name_quark (GParamSpec *pspec);

Gets the GQuark for the name.

#### Parameters

pspec | a GParamSpec |

#### Returns

the GQuark for `pspec->name` .

Since: 2.46

### g_param_spec_get_nick ()

    const gchar *
    g_param_spec_get_nick (GParamSpec *pspec);

Get the nickname of a GParamSpec.

#### Parameters

pspec | a valid GParamSpec |

#### Returns

the nickname of `pspec` .

### g_param_spec_get_blurb ()

    const gchar *
    g_param_spec_get_blurb (GParamSpec *pspec);

Get the short description of a GParamSpec.

#### Parameters

pspec | a valid GParamSpec |

#### Returns

the short description of `pspec` .

### g_param_spec_get_qdata ()

    gpointer
    g_param_spec_get_qdata (GParamSpec *pspec,
                            GQuark quark);

Gets back user data pointers stored via `g_param_spec_set_qdata()`.

#### Parameters

pspec | a valid GParamSpec |
quark | a GQuark, naming the user data pointer |

#### Returns

the user data pointer set, or `NULL`.

[transfer none]

### g_param_spec_set_qdata ()

    void
    g_param_spec_set_qdata (GParamSpec *pspec,
                            GQuark quark,
                            gpointer data);

Sets an opaque, named pointer on a GParamSpec. The name is specified through a GQuark (retrieved e.g. via `g_quark_from_static_string()`), and the pointer can be gotten back from the `pspec` with `g_param_spec_get_qdata()`. Setting a previously set user data pointer, overrides (frees) the old pointer set, using `NULL` as pointer essentially removes the data stored.

#### Parameters

pspec | the GParamSpec to set store a user data pointer |
quark | a GQuark, naming the user data pointer |
data | an opaque user data pointer |

### g_param_spec_set_qdata_full ()

    void
    g_param_spec_set_qdata_full (GParamSpec *pspec,
                                 GQuark quark,
                                 gpointer data,
                                 GDestroyNotify destroy);

This function works like `g_param_spec_set_qdata()`, but in addition, a `void (*destroy) (gpointer)` function may be specified which is called with `data` as argument when the `pspec` is finalized, or the data is being overwritten by a call to `g_param_spec_set_qdata()` with the same `quark` .

[skip]

#### Parameters

pspec | the GParamSpec to set store a user data pointer |
quark | a GQuark, naming the user data pointer |
data | an opaque user data pointer |
destroy | function to invoke with `data` as argument, when `data` needs to be freed |

### g_param_spec_steal_qdata ()

    gpointer
    g_param_spec_steal_qdata (GParamSpec *pspec,
                              GQuark quark);

Gets back user data pointers stored via `g_param_spec_set_qdata()` and removes the `data` from `pspec` without invoking its `destroy()` function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier.

#### Parameters

pspec | the GParamSpec to get a stored user data pointer from |
quark | a GQuark, naming the user data pointer |

#### Returns

the user data pointer set, or `NULL`.

[transfer none]

### g_param_spec_get_redirect_target ()

    GParamSpec *
    g_param_spec_get_redirect_target (GParamSpec *pspec);

If the paramspec redirects operations to another paramspec, returns that paramspec. Redirect is used typically for providing a new implementation of a property in a derived type while preserving all the properties from the parent type. Redirection is established by creating a property of type GParamSpecOverride. See `g_object_class_override_property()` for an example of the use of this capability.

#### Parameters

pspec | a GParamSpec |

#### Returns

paramspec to which requests on this paramspec should be redirected, or `NULL` if none.

[transfer none]

Since: 2.4

### g_param_spec_internal ()

    gpointer
    g_param_spec_internal (GType param_type,
                           const gchar *name,
                           const gchar *nick,
                           const gchar *blurb,
                           GParamFlags flags);

Creates a new GParamSpec instance.

A property name consists of segments consisting of ASCII letters and digits, separated by either the '-' or '_' character. The first character of a property name must be a letter. Names which violate these rules lead to undefined behaviour.

When creating and looking up a GParamSpec, either separator can be used, but they cannot be mixed. Using '-' is considerably more efficient and in fact required when using property names as detail strings for signals.

Beyond the name, GParamSpecs have two more descriptive strings associated with them, the `nick` , which should be suitable for use as a label for the property in a property editor, and the `blurb` , which should be a somewhat longer description, suitable for e.g. a tooltip. The `nick` and `blurb` should ideally be localized.

[skip]

#### Parameters

param_type | the GType for the property; must be derived from G_TYPE_PARAM |
name | the canonical name of the property |
nick | the nickname of the property |
blurb | a short description of the property |
flags | a combination of GParamFlags |

#### Returns

a newly allocated GParamSpec instance.

[type GObject.ParamSpec]

### g_param_type_register_static ()

    GType
    g_param_type_register_static (const gchar *name,
                                  const GParamSpecTypeInfo *pspec_info);

Registers `name` as the name of a new static type derived from G_TYPE_PARAM. The type system uses the information contained in the GParamSpecTypeInfo structure pointed to by `info` to manage the GParamSpec type and its instances.

#### Parameters

name | 0-terminated string used as the name of the new GParamSpec type. |
pspec_info | The GParamSpecTypeInfo for this GParamSpec type. |

#### Returns

The new type identifier.

### g_param_spec_pool_new ()

    GParamSpecPool *
    g_param_spec_pool_new (gboolean type_prefixing);

Creates a new GParamSpecPool.

If `type_prefixing` is `TRUE`, lookups in the newly created pool will allow to specify the owner as a colon-separated prefix of the property name, like "GtkContainer:border-width". This feature is deprecated, so you should always set `type_prefixing` to `FALSE`.

#### Parameters

type_prefixing | Whether the pool will support type-prefixed property names. |

#### Returns

a newly allocated GParamSpecPool.

[transfer none]

### g_param_spec_pool_insert ()

    void
    g_param_spec_pool_insert (GParamSpecPool *pool,
                              GParamSpec *pspec,
                              GType owner_type);

Inserts a GParamSpec in the pool.

#### Parameters

pool | a GParamSpecPool. |
pspec | the GParamSpec to insert |
owner_type | a GType identifying the owner of `pspec` |

### g_param_spec_pool_remove ()

    void
    g_param_spec_pool_remove (GParamSpecPool *pool,
                              GParamSpec *pspec);

Removes a GParamSpec from the pool.

#### Parameters

pool | a GParamSpecPool |
pspec | the GParamSpec to remove |

### g_param_spec_pool_lookup ()

    GParamSpec *
    g_param_spec_pool_lookup (GParamSpecPool *pool,
                              const gchar *param_name,
                              GType owner_type,
                              gboolean walk_ancestors);

Looks up a GParamSpec in the pool.

#### Parameters

pool | a GParamSpecPool |
param_name | the name to look for |
owner_type | the owner to look for |
walk_ancestors | If `TRUE`, also try to find a GParamSpec with `param_name` owned by an ancestor of `owner_type` . |

#### Returns

The found GParamSpec, or `NULL` if no matching GParamSpec was found.

[transfer none]

### g_param_spec_pool_list ()

    GParamSpec **
    g_param_spec_pool_list (GParamSpecPool *pool,
                            GType owner_type,
                            guint *n_pspecs_p);

Gets an array of all GParamSpecs owned by `owner_type` in the pool.

#### Parameters

pool | a GParamSpecPool |
owner_type | the owner to look for |
n_pspecs_p | return location for the length of the returned array. | [out]

#### Returns

a newly allocated array containing pointers to all GParamSpecs owned by `owner_type` in the pool.

[array length=n_pspecs_p][transfer container]

### g_param_spec_pool_list_owned ()

    GList *
    g_param_spec_pool_list_owned (GParamSpecPool *pool,
                                  GType owner_type);

Gets an GList of all GParamSpecs owned by `owner_type` in the pool.

#### Parameters

pool | a GParamSpecPool |
owner_type | the owner to look for |

#### Returns

a GList of all GParamSpecs owned by `owner_type` in the poolGParamSpecs.

[transfer container][element-type GObject.ParamSpec]

## Types and Values

### struct GParamSpec

    struct GParamSpec {
      GTypeInstance  g_type_instance;

      const gchar   *name;          /* interned string */
      GParamFlags    flags;
      GType		 value_type;
      GType		 owner_type; /* class or interface using this property */
    };

All other fields of the GParamSpec struct are private and should not be used directly.

#### Members

GTypeInstance `g_type_instance`; | private GTypeInstance portion |
const gchar *`name`; | name of this parameter: always an interned string |
GParamFlags `flags`; | GParamFlags flags for this parameter |
GType `value_type`; | the GValue type for this parameter |
GType `owner_type`; | GType type that uses (introduces) this parameter |

### struct GParamSpecClass

    struct GParamSpecClass {
      GTypeClass      g_type_class;

      GType		  value_type;

      void	        (*finalize)		(GParamSpec   *pspec);

      /* GParam methods */
      void          (*value_set_default)    (GParamSpec   *pspec,
    					 GValue       *value);
      gboolean      (*value_validate)       (GParamSpec   *pspec,
    					 GValue       *value);
      gint          (*values_cmp)           (GParamSpec   *pspec,
    					 const GValue *value1,
    					 const GValue *value2);
    };

The class structure for the GParamSpec type. Normally, GParamSpec classes are filled by `g_param_type_register_static()`.

#### Members

GTypeClass `g_type_class`; | the parent class |
GType `value_type`; | the GValue type for this parameter |
`finalize` () | The instance finalization function (optional), should chain up to the finalize method of the parent class. |
`value_set_default` () | Resets a `value` to the default value for this type (recommended, the default is `g_value_reset()`), see `g_param_value_set_default()`. |
`value_validate` () | Ensures that the contents of `value` comply with the specifications set out by this type (optional), see `g_param_value_validate()`. |
`values_cmp` () | Compares `value1` with `value2` according to this type (recommended, the default is `memcmp()`), see `g_param_values_cmp()`. |

### enum GParamFlags

Through the GParamFlags flag values, certain aspects of parameters can be configured. See also G_PARAM_STATIC_STRINGS.

#### Members

G_PARAM_READABLE | the parameter is readable |
G_PARAM_WRITABLE | the parameter is writable |
G_PARAM_READWRITE | alias for `G_PARAM_READABLE` | `G_PARAM_WRITABLE` |
G_PARAM_CONSTRUCT | the parameter will be set upon object construction |
G_PARAM_CONSTRUCT_ONLY | the parameter can only be set upon object construction |
G_PARAM_LAX_VALIDATION | upon parameter conversion (see `g_param_value_convert()`) strict validation is not required |
G_PARAM_STATIC_NAME | the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 |
G_PARAM_PRIVATE | internal |
G_PARAM_STATIC_NICK | the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 |
G_PARAM_STATIC_BLURB | the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 |
G_PARAM_EXPLICIT_NOTIFY | calls to `g_object_set_property()` for this property will not automatically result in a "notify" signal being emitted: the implementation must call `g_object_notify()` themselves in case the property actually changes. Since: 2.42. |
G_PARAM_DEPRECATED | the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26 |

### G_PARAM_STATIC_STRINGS

    #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)

GParamFlags value alias for `G_PARAM_STATIC_NAME` | `G_PARAM_STATIC_NICK` | `G_PARAM_STATIC_BLURB`.

Since 2.13.0

### G_PARAM_MASK

    #define G_PARAM_MASK		(0x000000ff)

Mask containing the bits of GParamSpec.flags which are reserved for GLib.

### G_PARAM_USER_SHIFT

    #define G_PARAM_USER_SHIFT (8)

Minimum shift count to be used for user defined flags, to be stored in GParamSpec.flags. The maximum allowed is 10.

### struct GParamSpecTypeInfo

    struct GParamSpecTypeInfo {
      /* type system portion */
      guint16         instance_size;                               /* obligatory */
      guint16         n_preallocs;                                 /* optional */
      void		(*instance_init) (GParamSpec   *pspec); /* optional */

      /* class portion */
      GType           value_type;				       /* obligatory */
      void          (*finalize)             (GParamSpec   *pspec); /* optional */
      void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
    					 GValue       *value);
      gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
    					 GValue       *value);
      gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
    					 const GValue *value1,
    					 const GValue *value2);
    };

This structure is used to provide the type system with the information required to initialize and destruct (finalize) a parameter's class and instances thereof. The initialized structure is passed to the `g_param_type_register_static()` The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of `g_param_type_register_static()`.

#### Members

guint16 `instance_size`; | Size of the instance (object) structure. |
guint16 `n_preallocs`; | Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the slice allocator now. |
`instance_init` () | Location of the instance initialization function (optional). |
GType `value_type`; | The GType of values conforming to this GParamSpec |
`finalize` () | The instance finalization function (optional). |
`value_set_default` () | Resets a `value` to the default value for `pspec` (recommended, the default is `g_value_reset()`), see `g_param_value_set_default()`. |
`value_validate` () | Ensures that the contents of `value` comply with the specifications set out by `pspec` (optional), see `g_param_value_validate()`. |
`values_cmp` () | Compares `value1` with `value2` according to `pspec` (recommended, the default is `memcmp()`), see `g_param_values_cmp()`. |

### GParamSpecPool

    typedef struct _GParamSpecPool GParamSpecPool;

A GParamSpecPool maintains a collection of GParamSpecs which can be quickly accessed by owner and name. The implementation of the GObject property system uses such a pool to store the GParamSpecs of the properties all object types.

## See Also

g_object_class_install_property(), `g_object_set()`, `g_object_get()`, `g_object_set_property()`, `g_object_get_property()`, `g_value_register_transform_func()`