| GObject Reference Manual | |||
|---|---|---|---|
| <<< Previous Page | Home | Up | Next Page >>> | 
GParamSpec is an object structure that encapsulates the meta data required to specify parameters, such as e.g. GObject properties.
| #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)) | 
Cast 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)) | 
Check whether pspec "is a" valid GParamSpec structure of type G_TYPE_PARAM or derived.
| pspec : | 
| #define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass)) | 
Cast 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)) | 
Check whether pclass "is a" valid GParamSpecClass structure of type G_TYPE_PARAM or derived.
| pclass : | 
| #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass)) | 
Retrieve the GParamSpecClass of a GParamSpec.
| pspec : | a valid GParamSpec | 
| #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec)) | 
Retrive the GType of this pspec.
| pspec : | a valid GParamSpec | 
| #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec))) | 
Retrive the GType name of this pspec.
| pspec : | a valid GParamSpec | 
| #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type) | 
Retrive the GType to intiialize a GValue for this parameter.
| pspec : | a valid GParamSpec | 
| struct GParamSpec
{
  GTypeInstance  g_type_instance;
  gchar         *name;
  GParamFlags    flags;
  GType		 value_type;
  GType		 owner_type;	/* class using this property */
  /*< private >*/
  gchar         *_nick;
  gchar         *_blurb;
  GData		*qdata;
  guint          ref_count;
  guint		 param_id;	/* sort-criteria */
}; | 
| 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 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); | 
Increment 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); | 
Decrement 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, eventhough no one has explicitely called g_param_spec_ref() on it yet. So the einital reference count is flagged as "floating", untill 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).
| pspec : | a valid GParamSpec | 
| void g_param_value_set_default (GParamSpec *pspec, GValue *value); | 
Set 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); | 
Check whether value contains the default value as specified in pspec.
| pspec : | a valid GParamSpec | 
| value : | a GValue of correct type for pspec | 
| Returns : | whether value contains the canonical defualt for this pspec | 
| gboolean g_param_value_validate (GParamSpec *pspec, GValue *value); | 
Ensure 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 value was necessary to ensure validity | 
| gboolean g_param_value_convert (GParamSpec *pspec, const GValue *src_value, GValue *dest_value, gboolean strict_validation); | 
This function 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 suceed 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 : | $TRUE requires dest_value to conform to pspec without modifications | 
| Returns : | TRUE if transformation and validation were successfull, FALSE otherwise and dest_value is left untouched. | 
| gint g_param_values_cmp (GParamSpec *pspec, const GValue *value1, const GValue *value2); | 
Compare 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 | 
| G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec); | 
| pspec : | |
| Returns : | 
 | 
| G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec); | 
| pspec : | |
| Returns : | 
 | 
| G_CONST_RETURN gchar* g_param_spec_get_blurb (GParamSpec *pspec); | 
| pspec : | |
| Returns : | 
 | 
| gpointer g_param_spec_get_qdata (GParamSpec *pspec, GQuark quark); | 
| pspec : | |
| quark : | |
| Returns : | 
 | 
| void g_param_spec_set_qdata (GParamSpec *pspec, GQuark quark, gpointer data); | 
| pspec : | |
| quark : | |
| data : | 
 | 
| void g_param_spec_set_qdata_full (GParamSpec *pspec, GQuark quark, gpointer data, GDestroyNotify destroy); | 
| pspec : | |
| quark : | |
| data : | |
| destroy : | 
 | 
| gpointer g_param_spec_steal_qdata (GParamSpec *pspec, GQuark quark); | 
| pspec : | |
| quark : | |
| Returns : | 
 | 
| gpointer g_param_spec_internal (GType param_type, const gchar *name, const gchar *nick, const gchar *blurb, GParamFlags flags); | 
| param_type : | |
| name : | |
| nick : | |
| blurb : | |
| flags : | |
| Returns : | 
 | 
| 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);
}; | 
| GType g_param_type_register_static (const gchar *name, const GParamSpecTypeInfo *pspec_info); | 
| name : | |
| pspec_info : | |
| Returns : | 
 | 
| GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing); | 
| type_prefixing : | |
| Returns : | 
 | 
| void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type); | 
| pool : | |
| pspec : | |
| owner_type : | 
 | 
| void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec); | 
| pool : | |
| pspec : | 
 | 
| GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, const gchar *param_name, GType owner_type, gboolean walk_ancestors); | 
| pool : | |
| param_name : | |
| owner_type : | |
| walk_ancestors : | |
| Returns : | 
| GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, GType owner_type, guint *n_pspecs_p); | 
| pool : | |
| owner_type : | |
| n_pspecs_p : | |
| Returns : | 
 | 
| GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, GType owner_type); | 
| pool : | |
| owner_type : | |
| Returns : | 
 |