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.

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.

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.

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.

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.

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.

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.

G_PARAM_SPEC_TYPE()

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

Retrieves the GType of this pspec .

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 .

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.

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

GParamSpec *
g_param_spec_ref (GParamSpec *pspec);

Increments the reference count of pspec .

g_param_spec_unref ()

void
g_param_spec_unref (GParamSpec *pspec);

Decrements the reference count of a pspec .

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

g_param_spec_ref_sink ()

GParamSpec *
g_param_spec_ref_sink (GParamSpec *pspec);

Convenience function to ref and sink a GParamSpec.

Since 2.10

g_param_spec_get_default_value ()

const GValue *
g_param_spec_get_default_value (GParamSpec *param);

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 .

g_param_value_defaults ()

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

Checks whether value contains the default value as specified in 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.

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

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.

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.

g_param_spec_get_nick ()

const gchar *
g_param_spec_get_nick (GParamSpec *pspec);

Get the nickname of a GParamSpec.

g_param_spec_get_blurb ()

const gchar *
g_param_spec_get_blurb (GParamSpec *pspec);

Get the short description of a GParamSpec.

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

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.

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 .

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.

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.

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.

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.

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.

g_param_spec_pool_insert ()

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

Inserts a GParamSpec in the pool.

g_param_spec_pool_remove ()

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

Removes a GParamSpec from the pool.

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.

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.

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.

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.

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

enum GParamFlags

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

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

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.