Name

Enums and Flags — Enumeration and flags types.

Library

gobject.lib

Synopsis

#include <glib-object.h>

GEnumClass;
GFlagsClass;
#define     G_ENUM_CLASS_TYPE               (class)
#define     G_ENUM_CLASS_TYPE_NAME          (class)
#define     G_TYPE_IS_ENUM                  (type)
#define     G_ENUM_CLASS                    (class)
#define     G_IS_ENUM_CLASS                 (class)
#define     G_TYPE_IS_FLAGS                 (type)
#define     G_FLAGS_CLASS                   (class)
#define     G_IS_FLAGS_CLASS                (class)
#define     G_FLAGS_CLASS_TYPE              (class)
#define     G_FLAGS_CLASS_TYPE_NAME         (class)
            GEnumValue;
            GFlagsValue;
GEnumValue* g_enum_get_value                (GEnumClass *enum_class, gint value);
GEnumValue* g_enum_get_value_by_name        (GEnumClass *enum_class, const gchar *name);
GEnumValue* g_enum_get_value_by_nick        (GEnumClass *enum_class, const gchar *nick);
GFlagsValue* g_flags_get_first_value        (GFlagsClass *flags_class, guint value);
GFlagsValue* g_flags_get_value_by_name      (GFlagsClass *flags_class, const gchar *name);
GFlagsValue* g_flags_get_value_by_nick      (GFlagsClass *flags_class, const gchar *nick);
GType       g_enum_register_static          (const gchar *name, const GEnumValue *const_static_values);
GType       g_flags_register_static         (const gchar *name, const GFlagsValue *const_static_values);
void        g_enum_complete_type_info       (GType g_enum_type, GTypeInfo *info, const GEnumValue *const_values);
void        g_flags_complete_type_info      (GType g_flags_type, GTypeInfo *info, const GFlagsValue *const_values);

Detailed Description

The GLib type system provides fundamental types for enumeration and flags types. (Flags types are like enumerations,
but allow their values to be combined by bitwise or).  A registered enumeration or flags type associates a name and a nickname with each allowed value, and the methods g_enum_get_value_by_name(), g_enum_get_value_by_nick(), g_flags_get_value_by_name() and g_flags_get_value_by_nick() can look up values by their name or nickname. When an enumeration or flags type is registered with the GLib type system, it can be used as value type for object properties, using g_param_spec_enum() or g_param_spec_flags().

GObject ships with a utility called glib-mkenums that can construct suitable type registration functions from C enumeration definitions.

Details

GEnumClass 

typedef struct {
  GTypeClass  g_type_class;

  gint	      minimum;
  gint	      maximum;
  guint	      n_values;
  GEnumValue *values;
} GEnumClass;

The class of an enumeration type holds information about its possible values.

GTypeClass g_type_class; the parent class
gint minimum; the smallest possible value.
gint maximum; the largest possible value.
guint n_values; the number of possible values.
GEnumValue *values; an array of GEnumValue structs describing the individual values.

GFlagsClass 

typedef struct {
  GTypeClass   g_type_class;
  
  guint	 mask;
  guint	 n_values;
  GFlagsValue *values;
} GFlagsClass;

The class of a flags type holds information about its possible values.

GTypeClass g_type_class; the parent class
guint mask; a mask covering all possible values.
guint n_values; the number of possible values.
GFlagsValue *values; an array of GFlagsValue structs describing the individual values.

G_ENUM_CLASS_TYPE() 

#define G_ENUM_CLASS_TYPE(class)       (G_TYPE_FROM_CLASS (class))

Returns the type identifier from a given GEnumClass structure.

class : a GEnumClass

G_ENUM_CLASS_TYPE_NAME() 

#define G_ENUM_CLASS_TYPE_NAME(class)  (g_type_name (G_ENUM_CLASS_TYPE (class)))

Returns the static type name from a given GEnumClass structure.

class : a GEnumClass

G_TYPE_IS_ENUM() 

#define G_TYPE_IS_ENUM(type)	       (G_TYPE_FUNDAMENTAL (type) == G_TYPE_ENUM)

Returns whether type "is a" G_TYPE_ENUM.

type : a GType ID.

G_ENUM_CLASS() 

#define G_ENUM_CLASS(class)	       (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_ENUM, GEnumClass))

Casts a derived GEnumClass structure into a GEnumClass structure.

class : a valid GEnumClass

G_IS_ENUM_CLASS() 

#define G_IS_ENUM_CLASS(class)	       (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_ENUM))

Checks whether class "is a" valid GEnumClass structure of type G_TYPE_ENUM or derived.

class : a GEnumClass

G_TYPE_IS_FLAGS() 

#define G_TYPE_IS_FLAGS(type)	       (G_TYPE_FUNDAMENTAL (type) == G_TYPE_FLAGS)

Returns whether type "is a" G_TYPE_FLAGS.

type : a GType ID.

G_FLAGS_CLASS() 

#define G_FLAGS_CLASS(class)	       (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_FLAGS, GFlagsClass))

Casts a derived GFlagsClass structure into a GFlagsClass structure.

class : a valid GFlagsClass

G_IS_FLAGS_CLASS() 

#define G_IS_FLAGS_CLASS(class)        (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_FLAGS))

Checks whether class "is a" valid GFlagsClass structure of type G_TYPE_FLAGS or derived.

class : a GFlagsClass

G_FLAGS_CLASS_TYPE() 

#define G_FLAGS_CLASS_TYPE(class)      (G_TYPE_FROM_CLASS (class))

Returns the type identifier from a given GFlagsClass structure.

class : a GFlagsClass

G_FLAGS_CLASS_TYPE_NAME() 

#define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_TYPE (class)))

Returns the static type name from a given GFlagsClass structure.

class : a GFlagsClass

GEnumValue 

typedef struct {
  gint	 value;
  gchar *value_name;
  gchar *value_nick;
} GEnumValue;

A structure which contains a single enum value, it's name, and it's nickname.

gint value; the enum value
gchar *value_name; the name of the value
gchar *value_nick; the nickname of the value

GFlagsValue 

typedef struct {
  guint	 value;
  gchar *value_name;
  gchar *value_nick;
} GFlagsValue;

A structure which contains a single flags value, it's name, and it's nickname.

guint value; the flags value
gchar *value_name; the name of the value
gchar *value_nick; the nickname of the value

g_enum_get_value () 

GEnumValue* g_enum_get_value                (GEnumClass *enum_class, gint value);

Returns the GEnumValue for a value.

enum_class : a GEnumClass
value : the value to look up
Returns : the GEnumValue for value, or NULL if value is not a member of the enumeration

g_enum_get_value_by_name () 

GEnumValue* g_enum_get_value_by_name        (GEnumClass *enum_class, const gchar *name);

Looks up a GEnumValue by name.

enum_class : a GEnumClass
name : the name to look up
Returns : the GEnumValue with name name, or NULL if the enumeration doesn' t have a member with that name

g_enum_get_value_by_nick () 

GEnumValue* g_enum_get_value_by_nick        (GEnumClass *enum_class, const gchar *nick);

Looks up a GEnumValue by nickname.

enum_class : a GEnumClass
nick : the nickname to look up
Returns : the GEnumValue with nickname nick, or NULL if the enumeration doesn' t have a member with that nickname

g_flags_get_first_value () 

GFlagsValue* g_flags_get_first_value        (GFlagsClass *flags_class, guint value);

Returns the first GFlagsValue which is set in value.

flags_class : a GFlagsClass
value : the value
Returns : the first GFlagsValue which is set in value, or NULL if none is set

g_flags_get_value_by_name () 

GFlagsValue* g_flags_get_value_by_name      (GFlagsClass *flags_class, const gchar *name);

Looks up a GFlagsValue by name.

flags_class : a GFlagsClass
name : the name to look up
Returns : the GFlagsValue with name name, or NULL if there is no flag with that name

g_flags_get_value_by_nick () 

GFlagsValue* g_flags_get_value_by_nick      (GFlagsClass *flags_class, const gchar *nick);

Looks up a GFlagsValue by nickname.

flags_class : a GFlagsClass
nick : the nickname to look up
Returns : the GFlagsValue with nickname nick, or NULL if there is no flag with that nickname

g_enum_register_static () 

GType       g_enum_register_static         (const gchar *name, const GEnumValue *const_static_values);

Registers a new static enumeration type with the name name.

It is normally more convenient to let glib-mkenums generate a my_enum_get_type() function from a usual C enumeration definition than to write one yourself using g_enum_register_static().

name : A nul-terminated string used as the name of the new type.
const_static_values : An array of GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0.
Returns : The new type identifier.

g_flags_register_static () 

GType       g_flags_register_static         (const gchar *name, const GFlagsValue *const_static_values);

Registers a new static flags type with the name name.

It is normally more convenient to let glib-mkenums generate a my_flags_get_type() function from a usual C enumeration definition than to write one yourself using g_flags_register_static().

name : A nul-terminated string used as the name of the new type.
const_static_values : An array of GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0.
Returns : The new type identifier.

g_enum_complete_type_info () 

void        g_enum_complete_type_info       (GType g_enum_type, GTypeInfo *info, const GEnumValue *const_values);

This function is meant to be called from the complete_type_info() function of a GTypePlugin implementation, as in the following example: 

static void
my_enum_complete_type_info (GTypePlugin  *plugin, GType  g_type, GTypeInfo  *info, GTypeValueTable *value_table)
{
  static const GEnumValue values[] = {
    { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
    { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
    { 0, NULL, NULL }
  };  
   
  g_enum_complete_type_info (type, info, values);  
}

g_enum_type : the type identifier of the type being completed
info : the GTypeInfo struct to be filled in
const_values : An array of GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0.

g_flags_complete_type_info () 

void        g_flags_complete_type_info      (GType g_flags_type, GTypeInfo *info, const GFlagsValue *const_values);

This function is meant to be called from the complete_type_info() function of a GTypePlugin implementation, see the example for g_enumeration_complete_type_info() above.

g_flags_type : the type identifier of the type being completed
info : the GTypeInfo struct to be filled in
const_values : An array of GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0.

See Also

GParamSpecEnum, GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags(), glib-mkenums.

Feedback

For additional information or queries on this page send feedback

© 2005-2007 Nokia

Top