Parameter names

A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the - or _ character. The first character of a property name must be a letter. These are the same rules as for signal naming (see g_signal_new()).

When creating and looking up a GParamSpec, either separator can be used, but they cannot be mixed. Using - is considerably more efficient, and is the ‘canonical form’. Using _ is discouraged.

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

GParamSpec *
g_param_spec_ref (GParamSpec *pspec);

Increments the reference count of pspec .

[skip]

g_param_spec_unref ()

void
g_param_spec_unref (GParamSpec *pspec);

Decrements the reference count of a pspec .

[skip]

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.

[skip]

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 valid for the life of pspec .

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 .

g_param_value_defaults ()

gboolean
g_param_value_defaults (GParamSpec *pspec,
                        const 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_is_valid ()

gboolean
g_param_value_is_valid (GParamSpec *pspec,
                        const GValue *value);

Return whether the contents of value comply with the specifications set out by pspec .

Since: 2.74

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

gboolean
g_param_spec_is_valid_name (const gchar *name);

Validate a property name for a GParamSpec. This can be useful for dynamically-generated properties which need to be validated at run-time before actually trying to create them.

See canonical parameter names for details of the rules for valid names.

Since: 2.66

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

GQuark
g_param_spec_get_name_quark (GParamSpec *pspec);

Gets the GQuark for the name.

Since: 2.46

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 .

[skip]

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.

See canonical parameter names for details of the rules for name . Names which violate these rules lead to undefined behaviour.

Beyond the name, GParamSpecs have two more descriptive strings, the nick and blurb , which may be used as a localized label and description. For GTK and related libraries these are considered deprecated and may be omitted, while for other libraries such as GStreamer and its plugins they are essential. When in doubt, follow the conventions used in the surrounding code and supporting libraries.

[skip]

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

  gboolean      (*value_is_valid)       (GParamSpec   *pspec,
                                         const GValue *value);
};

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_STATIC_STRINGS

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.

It is recommended to use this for all properties by default, as it allows for internal performance improvements in GObject.

It is very rare that a property would have a dynamically constructed name, nickname or 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().

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.