GParamSpec

GParamSpec — Metadata for parameter specifications

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.