## GParamSpec GParamSpec — Metadata for parameter specifications |

## Synopsis

    #include <glib-object.h>

    #define     G_TYPE_IS_PARAM                 (type)
    #define     G_PARAM_SPEC                    (pspec)
    #define     G_IS_PARAM_SPEC                 (pspec)
    #define     G_PARAM_SPEC_CLASS              (pclass)
    #define     G_IS_PARAM_SPEC_CLASS           (pclass)
    #define     G_PARAM_SPEC_GET_CLASS          (pspec)
    #define     G_PARAM_SPEC_TYPE               (pspec)
    #define     G_PARAM_SPEC_TYPE_NAME          (pspec)
    #define     G_PARAM_SPEC_VALUE_TYPE         (pspec)
                GParamSpec;
                GParamSpecClass;
    enum        GParamFlags;
    #define     G_PARAM_READWRITE
    #define     G_PARAM_MASK
    #define     G_PARAM_USER_SHIFT
    GParamSpec* g_param_spec_ref                (GParamSpec *pspec);
    void        g_param_spec_unref              (GParamSpec *pspec);
    void        g_param_spec_sink               (GParamSpec *pspec);
    GParamSpec* g_param_spec_ref_sink           (GParamSpec *pspec);
    void        g_param_value_set_default       (GParamSpec *pspec,
                                                 GValue *value);
    gboolean    g_param_value_defaults          (GParamSpec *pspec,
                                                 GValue *value);
    gboolean    g_param_value_validate          (GParamSpec *pspec,
                                                 GValue *value);
    gboolean    g_param_value_convert           (GParamSpec *pspec,
                                                 const GValue *src_value,
                                                 GValue *dest_value,
                                                 gboolean strict_validation);
    gint        g_param_values_cmp              (GParamSpec *pspec,
                                                 const GValue *value1,
                                                 const GValue *value2);
    const gchar* g_param_spec_get_name          (GParamSpec *pspec);
    const gchar* g_param_spec_get_nick          (GParamSpec *pspec);
    const gchar* g_param_spec_get_blurb         (GParamSpec *pspec);
    gpointer    g_param_spec_get_qdata          (GParamSpec *pspec,
                                                 GQuark quark);
    void        g_param_spec_set_qdata          (GParamSpec *pspec,
                                                 GQuark quark,
                                                 gpointer data);
    void        g_param_spec_set_qdata_full     (GParamSpec *pspec,
                                                 GQuark quark,
                                                 gpointer data,
                                                 GDestroyNotify destroy);
    gpointer    g_param_spec_steal_qdata        (GParamSpec *pspec,
                                                 GQuark quark);
    GParamSpec* g_param_spec_get_redirect_target
                                                (GParamSpec *pspec);
    gpointer    g_param_spec_internal           (GType param_type,
                                                 const gchar *name,
                                                 const gchar *nick,
                                                 const gchar *blurb,
                                                 GParamFlags flags);
                GParamSpecTypeInfo;
    GType       g_param_type_register_static    (const gchar *name,
                                                 const GParamSpecTypeInfo *pspec_info);
                GParamSpecPool;
    GParamSpecPool* g_param_spec_pool_new       (gboolean type_prefixing);
    void        g_param_spec_pool_insert        (GParamSpecPool *pool,
                                                 GParamSpec *pspec,
                                                 GType owner_type);
    void        g_param_spec_pool_remove        (GParamSpecPool *pool,
                                                 GParamSpec *pspec);
    GParamSpec* g_param_spec_pool_lookup        (GParamSpecPool *pool,
                                                 const gchar *param_name,
                                                 GType owner_type,
                                                 gboolean walk_ancestors);
    GParamSpec** g_param_spec_pool_list         (GParamSpecPool *pool,
                                                 GType owner_type,
                                                 guint *n_pspecs_p);
    GList*      g_param_spec_pool_list_owned    (GParamSpecPool *pool,
                                                 GType owner_type);

## Description

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

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.

## Details

### G_TYPE_IS_PARAM()

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

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

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

`pspec` : | a valid GParamSpec

### G_IS_PARAM_SPEC()

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

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

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

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

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

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

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

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

`pspec` : | a valid GParamSpec

### GParamSpec

    typedef struct {
      GTypeInstance  g_type_instance;

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

All fields of the GParamSpec struct are private and should not be used directly, except for the following:

GTypeInstance `g_type_instance`; | private GTypeInstance portion
gchar *`name`; | name of this parameter
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 paremeter

### GParamSpecClass

    typedef struct {
      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);
    } GParamSpecClass;

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

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_set_validate()`.
`values_cmp` () | Compares `value1` with `value2` according to this type (recommended, the default is `memcmp()`), see `g_param_values_cmp()`.

### enum GParamFlags

    typedef enum
    {
      G_PARAM_READABLE            = 1 << 0,
      G_PARAM_WRITABLE            = 1 << 1,
      G_PARAM_CONSTRUCT	      = 1 << 2,
      G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
      G_PARAM_LAX_VALIDATION      = 1 << 4,
      G_PARAM_STATIC_NAME	      = 1 << 5,
    #ifndef G_DISABLE_DEPRECATED
      G_PARAM_PRIVATE	      = G_PARAM_STATIC_NAME,
    #endif
      G_PARAM_STATIC_NICK	      = 1 << 6,
      G_PARAM_STATIC_BLURB	      = 1 << 7
    } GParamFlags;

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

`G_PARAM_READABLE` | the parameter is readable
`G_PARAM_WRITABLE` | the parameter is writable
`G_PARAM_CONSTRUCT` | the parameter will be set upon object construction
`G_PARAM_CONSTRUCT_ONLY` | the parameter will 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_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_READWRITE

    #define	G_PARAM_READWRITE	(G_PARAM_READABLE | G_PARAM_WRITABLE)

GParamFlags value alias for `G_PARAM_READABLE` | `G_PARAM_WRITABLE`.

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

### g_param_spec_ref ()

    GParamSpec* g_param_spec_ref                (GParamSpec *pspec);

Increments the reference count of `pspec`.

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

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

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

`pspec` : | a valid GParamSpec
Returns : | the GParamSpec that was passed into this function

Since 2.10

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

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

`pspec` : | a valid GParamSpec
`value` : | a GValue of correct type for `pspec`
Returns : | whether `value` contains the canonical defualt 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.

`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()`.

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

`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);

Returns the name of a GParamSpec.

`pspec` : | a valid GParamSpec
Returns : | the name of `pspec`.

### g_param_spec_get_nick ()

    const gchar* g_param_spec_get_nick          (GParamSpec *pspec);

Returns the nickname of a GParamSpec.

`pspec` : | a valid GParamSpec
Returns : | the nickname of `pspec`.

### g_param_spec_get_blurb ()

    const gchar* g_param_spec_get_blurb         (GParamSpec *pspec);

Returns the short description of a GParamSpec.

`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()`.

`pspec` : | a valid GParamSpec
`quark` : | a GQuark, naming the user data pointer
Returns : | the user data pointer set, or `NULL`

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

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

`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 it's `destroy()` function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier.

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

### 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_override_property()` for an example of the use of this capability.

`pspec` : | a GParamSpec
Returns : | paramspec to which requests on this paramspec should be redirected, or `NULL` if 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.

`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

### GParamSpecTypeInfo

    typedef struct {
      /* 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);
    } GParamSpecTypeInfo;

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 it's memory does not need to be persistent across invocation of `g_param_type_register_static()`.

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_set_validate()`.
`values_cmp` () | Compares `value1` with `value2` according to `pspec` (recommended, the default is `memcmp()`), see `g_param_values_cmp()`.

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

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

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

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

`type_prefixing` : | Whether the pool will support type-prefixed property names.
Returns : | a newly allocated GParamSpecPool.

### g_param_spec_pool_insert ()

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

Inserts a GParamSpec in the pool.

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

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

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

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

`pool` : | a GParamSpecPool
`owner_type` : | the owner to look for
`n_pspecs_p` : | return location for the length of the returned array
Returns : | a newly allocated array containing pointers to all GParamSpecs owned by `owner_type` in the pool

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

`pool` : | a GParamSpecPool
`owner_type` : | the owner to look for
Returns : | a GList of all GParamSpecs owned by `owner_type` in the poolGParamSpecs.

## 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()`