|  |  |  | GObject Reference Manual |  | 
|---|
| GParamSpecGParamSpec — Metadata for parameter specifications | 
#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_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); 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.
#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 | 
#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.
| pspec: | 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.
| pspec: | 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.
| pclass: | 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.
| pclass: | 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.
| pspec: | a valid GParamSpec | 
#define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec))
Retrieves the GType of this pspec.
| 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.
| 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.
| pspec: | 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 fields of the GParamSpec struct are private and should not be used directly, except for the following:
| 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 | 
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 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 valueto the default value for this type
  (recommended, the default isg_value_reset()), seeg_param_value_set_default(). | 
| value_validate() | Ensures that the contents of valuecomply with the 
  specifications set out by this type (optional), seeg_param_value_set_validate(). | 
| values_cmp() | Compares value1withvalue2according to this type
  (recommended, the default ismemcmp()), seeg_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_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 | 
#define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE)
GParamFlags value alias for G_PARAM_READABLE | G_PARAM_WRITABLE.
#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.
| 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.
| 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 (
in sequence on it, taking over the initial reference count (thus
ending up with a pspec); g_param_spec_sink (pspec);pspec that has a reference count of 1 still, but is
not flagged "floating" anymore).
| pspec: | a valid GParamSpec | 
void g_param_value_set_default (GParamSpec *pspec, GValue *value);
Sets value to its default value as specified in pspec.
| pspec: | a valid GParamSpec | 
| value: | 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.
| pspec: | a valid GParamSpec | 
| value: | a GValue of correct type for pspec | 
| Returns : | whether valuecontains the canonical defualt for thispspec | 
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.
| pspec: | a valid GParamSpec | 
| value: | a GValue of correct type for pspec | 
| Returns : | whether modifying valuewas 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().
| pspec: | a valid GParamSpec | 
| src_value: | souce GValue | 
| dest_value: | destination GValue of correct type for pspec | 
| strict_validation: | TRUErequiresdest_valueto conform topspecwithout modifications | 
| Returns : | TRUEif transformation and validation were successfull,FALSEotherwise anddest_valueis 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.
| 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 | 
const gchar* g_param_spec_get_name (GParamSpec *pspec);
Returns the name of a GParamSpec.
| pspec: | a valid GParamSpec | 
| Returns : | the name of pspec. | 
const gchar* g_param_spec_get_nick (GParamSpec *pspec);
Returns the nickname of a GParamSpec.
| pspec: | a valid GParamSpec | 
| Returns : | the nickname of pspec. | 
const gchar* g_param_spec_get_blurb (GParamSpec *pspec);
Returns the short description of a GParamSpec.
| pspec: | 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().
| pspec: | a valid GParamSpec | 
| quark: | 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.
| pspec: | the GParamSpec to set store a user data pointer | 
| quark: | a GQuark, naming the user data pointer | 
| data: | 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.
| 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 dataas argument, whendataneeds 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 it's destroy() function 
(if any was set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier.
| 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 | 
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 perserving all the properties from the parent
type. Redirection is established by creating a property
of type GParamSpecOverride. See g_object_override_property()
for an example of the use of this capability.
| pspec: | a GParamSpec | 
| Returns : | paramspec to which requests on this paramspec should
  be redirected, or NULLif 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.
| 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 | 
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 it's memory 
does not need to be persistent across invocation of 
g_param_type_register_static().
| guint16 instance_size; | Size of the instance (object) structure. | 
| guint16 n_preallocs; | Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). | 
| 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 valueto the default value forpspec(recommended, the default isg_value_reset()), seeg_param_value_set_default(). | 
| value_validate() | Ensures that the contents of valuecomply with the 
  specifications set out bypspec(optional), seeg_param_value_set_validate(). | 
| values_cmp() | Compares value1withvalue2according topspec(recommended, the default ismemcmp()), seeg_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. 
| 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. | 
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.
| type_prefixing: | 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.
| pool: | a GParamSpecPool. | 
| pspec: | the GParamSpec to insert | 
| owner_type: | a GType identifying the owner of pspec | 
void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec);
Removes a GParamSpec from the pool.
| pool: | a GParamSpecPool | 
| pspec: | 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.
| 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 withparam_nameowned by an ancestor ofowner_type. | 
| Returns : | The found GParamSpec, or NULLif 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. 
| pool: | a GParamSpecPool | 
| owner_type: | the owner to look for | 
| n_pspecs_p: | return location for the length of the returned array | 
| Returns : | a newly allocated array containing pointers to all 
  GParamSpecs owned by owner_typein 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. 
| pool: | a GParamSpecPool | 
| owner_type: | the owner to look for | 
| Returns : | a GList of all GParamSpecs owned by owner_typein 
  the poolGParamSpecs. | 
| << Varargs Value Collection | Signals >> |