GObject Reference Manual | ||||
---|---|---|---|---|
Top | Description |
#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_STATIC_STRINGS #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);
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. The result of this replacement is called the canonical name of the parameter.
#define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
Checks whether type
"is a" G_TYPE_PARAM
.
|
a GType ID |
#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.
|
a valid GParamSpec |
#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.
|
a GParamSpec |
#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.
|
a valid GParamSpecClass |
#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.
|
a GParamSpecClass |
#define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
Retrieves the GParamSpecClass of a GParamSpec.
|
a valid GParamSpec |
#define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec))
Retrieves the GType of this pspec
.
|
a valid GParamSpec |
#define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
Retrieves the GType name of this pspec
.
|
a valid GParamSpec |
#define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type)
Retrieves the GType to initialize a GValue for this parameter.
|
a valid 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 other fields of the GParamSpec struct are private and should not be used directly.
GTypeInstance |
private GTypeInstance portion |
gchar * |
name of this parameter |
GParamFlags |
GParamFlags flags for this parameter |
GType |
the GValue type for this parameter |
GType |
GType type that uses (introduces) this paremeter |
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 |
the parent class |
GType |
the GValue type for this parameter |
|
The instance finalization function (optional), should chain up to the finalize method of the parent class. |
|
Resets a value to the default value for this type
(recommended, the default is g_value_reset() ), see
g_param_value_set_default() .
|
|
Ensures that the contents of value comply with the
specifications set out by this type (optional), see
g_param_value_set_validate() .
|
|
Compares value1 with value2 according to this type
(recommended, the default is memcmp() ), see g_param_values_cmp() .
|
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.
the parameter is readable | |
the parameter is writable | |
the parameter will be set upon object construction | |
the parameter will only be set upon object construction | |
upon parameter conversion (see g_param_value_convert() )
strict validation is not required
|
|
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 | |
internal | |
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 | |
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 |
#define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE)
GParamFlags value alias for G_PARAM_READABLE
| G_PARAM_WRITABLE
.
#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
#define G_PARAM_MASK (0x000000ff)
Mask containing the bits of GParamSpec.flags which are reserved for GLib.
#define G_PARAM_USER_SHIFT (8)
Minimum shift count to be used for user defined flags, to be stored in GParamSpec.flags.
GParamSpec* g_param_spec_ref (GParamSpec *pspec);
Increments the reference count of pspec
.
|
a valid GParamSpec |
Returns : |
the GParamSpec that was passed into this function |
void g_param_spec_unref (GParamSpec *pspec);
Decrements the reference count of a pspec
.
|
a valid GParamSpec |
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).
|
a valid GParamSpec |
GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec);
Convenience function to ref and sink a GParamSpec.
|
a valid GParamSpec |
Returns : |
the GParamSpec that was passed into this function |
Since 2.10
void g_param_value_set_default (GParamSpec *pspec, GValue *value);
Sets value
to its default value as specified in pspec
.
|
a valid GParamSpec |
|
a GValue of correct type for pspec
|
gboolean g_param_value_defaults (GParamSpec *pspec, GValue *value);
Checks whether value
contains the default value as specified in pspec
.
|
a valid GParamSpec |
|
a GValue of correct type for pspec
|
Returns : |
whether value contains the canonical default for this pspec
|
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.
|
a valid GParamSpec |
|
a GValue of correct type for pspec
|
Returns : |
whether modifying value was necessary to ensure validity
|
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()
.
|
a valid GParamSpec |
|
souce GValue |
|
destination GValue of correct type for pspec
|
|
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.
|
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.
|
a valid GParamSpec |
|
a GValue of correct type for pspec
|
|
a GValue of correct type for pspec
|
Returns : |
-1, 0 or +1, for a less than, equal to or greater than result |
const gchar* g_param_spec_get_name (GParamSpec *pspec);
Get the name of a GParamSpec.
|
a valid GParamSpec |
Returns : |
the name of pspec .
|
const gchar* g_param_spec_get_nick (GParamSpec *pspec);
Get the nickname of a GParamSpec.
|
a valid GParamSpec |
Returns : |
the nickname of pspec .
|
const gchar* g_param_spec_get_blurb (GParamSpec *pspec);
Get the short description of a GParamSpec.
|
a valid GParamSpec |
Returns : |
the short description of pspec .
|
gpointer g_param_spec_get_qdata (GParamSpec *pspec, GQuark quark);
Gets back user data pointers stored via g_param_spec_set_qdata()
.
|
a valid GParamSpec |
|
a GQuark, naming the user data pointer |
Returns : |
the user data pointer set, or NULL
|
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.
|
the GParamSpec to set store a user data pointer |
|
a GQuark, naming the user data pointer |
|
an opaque user data pointer |
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
.
|
the GParamSpec to set store a user data pointer |
|
a GQuark, naming the user data pointer |
|
an opaque user data pointer |
|
function to invoke with data as argument, when data needs to
be freed
|
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.
|
the GParamSpec to get a stored user data pointer from |
|
a GQuark, naming the user data pointer |
Returns : |
the user data pointer set, or NULL
|
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.
|
a GParamSpec |
Returns : |
paramspec to which requests on this paramspec should
be redirected, or NULL if none.
|
Since 2.4
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.
|
the GType for the property; must be derived from G_TYPE_PARAM |
|
the canonical name of the property |
|
the nickname of the property |
|
a short description of the property |
|
a combination of GParamFlags |
Returns : |
a newly allocated GParamSpec instance |
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 its memory
does not need to be persistent across invocation of
g_param_type_register_static()
.
guint16 |
Size of the instance (object) structure. |
guint16 |
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. |
|
Location of the instance initialization function (optional). |
GType |
The GType of values conforming to this GParamSpec |
|
The instance finalization function (optional). |
|
Resets a value to the default value for pspec
(recommended, the default is g_value_reset() ), see
g_param_value_set_default() .
|
|
Ensures that the contents of value comply with the
specifications set out by pspec (optional), see
g_param_value_set_validate() .
|
|
Compares value1 with value2 according to pspec
(recommended, the default is memcmp() ), see g_param_values_cmp() .
|
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.
|
0-terminated string used as the name of the new GParamSpec type. |
|
The GParamSpecTypeInfo for this GParamSpec type. |
Returns : |
The new type identifier. |
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.
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
.
|
Whether the pool will support type-prefixed property names. |
Returns : |
a newly allocated GParamSpecPool. |
void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type);
Inserts a GParamSpec in the pool.
|
a GParamSpecPool. |
|
the GParamSpec to insert |
|
a GType identifying the owner of pspec
|
void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec);
Removes a GParamSpec from the pool.
|
a GParamSpecPool |
|
the GParamSpec to remove |
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.
|
a GParamSpecPool |
|
the name to look for |
|
the owner to look for |
|
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.
|
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.
|
a GParamSpecPool |
|
the owner to look for |
|
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
|
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.
|
a GParamSpecPool |
|
the owner to look for |
Returns : |
a GList of all GParamSpecs owned by owner_type
in the poolGParamSpecs.
|