GObject Reference Manual
<<< Previous PageHomeUpNext Page >>>

GParamSpec

Name

GParamSpec -- Meta data object for parameter specifications.

Synopsis


#include <gobject.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)
struct      GParamSpec;
struct      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);
G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec);
G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec);
G_CONST_RETURN 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);
gpointer    g_param_spec_internal           (GType param_type,
                                             const gchar *name,
                                             const gchar *nick,
                                             const gchar *blurb,
                                             GParamFlags flags);
struct      GParamSpecTypeInfo;
GType       g_param_type_register_static    (const gchar *name,
                                             const GParamSpecTypeInfo *pspec_info);
struct      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);

Description

GParamSpec is an object structure that encapsulates the meta data required to specify parameters, such as e.g. GObject properties.

Details

G_TYPE_IS_PARAM()

#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

G_PARAM_SPEC()

#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

G_IS_PARAM_SPEC()

#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 :a GParamSpec

G_PARAM_SPEC_CLASS()

#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

G_IS_PARAM_SPEC_CLASS()

#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 :a GParamSpecClass

G_PARAM_SPEC_GET_CLASS()

#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

G_PARAM_SPEC_TYPE()

#define G_PARAM_SPEC_TYPE(pspec)	(G_TYPE_FROM_INSTANCE (pspec))

Retrive the GType of this pspec.

pspec :a valid GParamSpec

G_PARAM_SPEC_TYPE_NAME()

#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

G_PARAM_SPEC_VALUE_TYPE()

#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

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_instanceprivate 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

struct GParamSpecClass

struct GParamSpecClass;

enum GParamFlags

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_ONLYthe parameter will only be set upon object construction
G_PARAM_LAX_VALIDATIONupon parameter conversion (see g_param_value_convert()) strict validation is not required
G_PARAM_PRIVATE 

G_PARAM_READWRITE

#define	G_PARAM_READWRITE	(G_PARAM_READABLE | G_PARAM_WRITABLE)

GParamFlags value alias for G_PARAM_READABLE | G_PARAM_WRITABLE.

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.

g_param_spec_ref ()

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

g_param_spec_unref ()

void        g_param_spec_unref              (GParamSpec *pspec);

Decrement the reference count of a pspec.

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, 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

g_param_value_set_default ()

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

g_param_value_defaults ()

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

g_param_value_validate ()

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

g_param_value_convert ()

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.

g_param_values_cmp ()

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

G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec);

pspec : 
Returns : 

g_param_spec_get_nick ()

G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec);

pspec : 
Returns : 

g_param_spec_get_blurb ()

G_CONST_RETURN gchar* g_param_spec_get_blurb
                                            (GParamSpec *pspec);

pspec : 
Returns : 

g_param_spec_get_qdata ()

gpointer    g_param_spec_get_qdata          (GParamSpec *pspec,
                                             GQuark quark);

pspec : 
quark : 
Returns : 

g_param_spec_set_qdata ()

void        g_param_spec_set_qdata          (GParamSpec *pspec,
                                             GQuark quark,
                                             gpointer data);

pspec : 
quark : 
data : 

g_param_spec_set_qdata_full ()

void        g_param_spec_set_qdata_full     (GParamSpec *pspec,
                                             GQuark quark,
                                             gpointer data,
                                             GDestroyNotify destroy);

pspec : 
quark : 
data : 
destroy : 

g_param_spec_steal_qdata ()

gpointer    g_param_spec_steal_qdata        (GParamSpec *pspec,
                                             GQuark quark);

pspec : 
quark : 
Returns : 

g_param_spec_internal ()

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

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

g_param_type_register_static ()

GType       g_param_type_register_static    (const gchar *name,
                                             const GParamSpecTypeInfo *pspec_info);

name : 
pspec_info : 
Returns : 

struct GParamSpecPool

struct GParamSpecPool;

g_param_spec_pool_new ()

GParamSpecPool* g_param_spec_pool_new       (gboolean type_prefixing);

type_prefixing : 
Returns : 

g_param_spec_pool_insert ()

void        g_param_spec_pool_insert        (GParamSpecPool *pool,
                                             GParamSpec *pspec,
                                             GType owner_type);

pool : 
pspec : 
owner_type : 

g_param_spec_pool_remove ()

void        g_param_spec_pool_remove        (GParamSpecPool *pool,
                                             GParamSpec *pspec);

pool : 
pspec : 

g_param_spec_pool_lookup ()

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 : 

g_param_spec_pool_list ()

GParamSpec** g_param_spec_pool_list         (GParamSpecPool *pool,
                                             GType owner_type,
                                             guint *n_pspecs_p);

pool : 
owner_type : 
n_pspecs_p : 
Returns : 

g_param_spec_pool_list_owned ()

GList*      g_param_spec_pool_list_owned    (GParamSpecPool *pool,
                                             GType owner_type);

pool : 
owner_type : 
Returns : 

See Also

g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func()



<<< Previous PageHomeUpNext Page >>>
Varargs Value CollectionSignals