GObject Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GParamSpec

## Name

GParamSpec -- Meta data object for parameter specifications.

## Synopsis

    #include <gobject.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)
    struct      GParamSpec;
    struct      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);
    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);
    G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec);
    G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec);
    G_CONST_RETURN 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);
    gpointer    g_param_spec_internal           (GType param_type,
                                                 const gchar *name,
                                                 const gchar *nick,
                                                 const gchar *blurb,
                                                 GParamFlags flags);
    struct      GParamSpecTypeInfo;
    GType       g_param_type_register_static    (const gchar *name,
                                                 const GParamSpecTypeInfo *pspec_info);
    struct      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 meta data required to specify parameters, such as e.g. GObject properties.

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

Cast 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))

Check 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))

Cast 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))

Check 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))

Retrieve the GParamSpecClass of a GParamSpec.

`pspec` : | a valid GParamSpec

### G_PARAM_SPEC_TYPE()

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

Retrive 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)))

Retrive 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)

Retrive the GType to intiialize a GValue for this parameter.

`pspec` : | a valid GParamSpec

### struct GParamSpec

    struct GParamSpec
    {
      GTypeInstance  g_type_instance;

      gchar         *name;
      GParamFlags    flags;
      GType		 value_type;
      GType		 owner_type;	/* class using this property */

      /*< private >*/
      gchar         *_nick;
      gchar         *_blurb;
      GData		*qdata;
      guint          ref_count;
      guint		 param_id;	/* sort-criteria */
    };

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

### struct GParamSpecClass

    struct GParamSpecClass;

### 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_PRIVATE	      = 1 << 5
    } 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_PRIVATE` |

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

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

Decrement 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, eventhough no one has explicitely called g_param_spec_ref() on it yet. So the einital reference count is flagged as "floating", untill 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_value_set_default ()

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

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

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

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

This function 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 suceed 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 successfull, `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);

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

    G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec);

`pspec` : |
Returns : |

### g_param_spec_get_nick ()

    G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec);

`pspec` : |
Returns : |

### g_param_spec_get_blurb ()

    G_CONST_RETURN gchar* g_param_spec_get_blurb
                                                (GParamSpec *pspec);

`pspec` : |
Returns : |

### g_param_spec_get_qdata ()

    gpointer    g_param_spec_get_qdata          (GParamSpec *pspec,
                                                 GQuark quark);

`pspec` : |
`quark` : |
Returns : |

### g_param_spec_set_qdata ()

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

`pspec` : |
`quark` : |
`data` : |

### g_param_spec_set_qdata_full ()

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

`pspec` : |
`quark` : |
`data` : |
`destroy` : |

### g_param_spec_steal_qdata ()

    gpointer    g_param_spec_steal_qdata        (GParamSpec *pspec,
                                                 GQuark quark);

`pspec` : |
`quark` : |
Returns : |

### g_param_spec_internal ()

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

`param_type` : |
`name` : |
`nick` : |
`blurb` : |
`flags` : |
Returns : |

### 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);
    };

### g_param_type_register_static ()

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

`name` : |
`pspec_info` : |
Returns : |

### struct GParamSpecPool

    struct GParamSpecPool;

### g_param_spec_pool_new ()

    GParamSpecPool* g_param_spec_pool_new       (gboolean type_prefixing);

`type_prefixing` : |
Returns : |

### g_param_spec_pool_insert ()

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

`pool` : |
`pspec` : |
`owner_type` : |

### g_param_spec_pool_remove ()

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

`pool` : |
`pspec` : |

### g_param_spec_pool_lookup ()

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

`pool` : |
`param_name` : |
`owner_type` : |
`walk_ancestors` : |
Returns : |

### g_param_spec_pool_list ()

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

`pool` : |
`owner_type` : |
`n_pspecs_p` : |
Returns : |

### g_param_spec_pool_list_owned ()

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

`pool` : |
`owner_type` : |
Returns : |

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

<<< Previous Page | Home | Up | Next Page >>>
Varargs Value Collection | Signals