Enumeration and Flag Types: GObject Reference Manual

Enumeration and Flag Types

Enumeration and Flag Types — Enumeration and flags types

Functions

#define	G_ENUM_CLASS_TYPE()
#define	G_ENUM_CLASS_TYPE_NAME()
#define	G_TYPE_IS_ENUM()
#define	G_ENUM_CLASS()
#define	G_IS_ENUM_CLASS()
#define	G_TYPE_IS_FLAGS()
#define	G_FLAGS_CLASS()
#define	G_IS_FLAGS_CLASS()
#define	G_FLAGS_CLASS_TYPE()
#define	G_FLAGS_CLASS_TYPE_NAME()
GEnumValue *	g_enum_get_value ()
GEnumValue *	g_enum_get_value_by_name ()
GEnumValue *	g_enum_get_value_by_nick ()
gchar *	g_enum_to_string ()
GFlagsValue *	g_flags_get_first_value ()
GFlagsValue *	g_flags_get_value_by_name ()
GFlagsValue *	g_flags_get_value_by_nick ()
gchar *	g_flags_to_string ()
GType	g_enum_register_static ()
GType	g_flags_register_static ()
void	g_enum_complete_type_info ()
void	g_flags_complete_type_info ()

Types and Values

struct	GEnumClass
struct	GFlagsClass
struct	GEnumValue
struct	GFlagsValue

Includes

#include <glib-object.h>

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.

Example of how to get a string representation of an enum value:

GEnumClass *enum_class;
GEnumValue *enum_value;

enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM);
enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO);

g_print ("Name: %s\n", enum_value->value_name);

g_type_class_unref (enum_class);

Functions

G_ENUM_CLASS_TYPE()

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

Get the type identifier from a given GEnumClass structure.

Parameters

class

a GEnumClass

Returns

the GType

G_ENUM_CLASS_TYPE_NAME()

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

Get the static type name from a given GEnumClass structure.

Parameters

class

a GEnumClass

Returns

the type name.

G_TYPE_IS_ENUM()

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

Checks whether type "is a" G_TYPE_ENUM.

Parameters

type

a GType ID.

Returns

TRUE if type "is a" G_TYPE_ENUM.

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.

Parameters

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.

Parameters

class

a GEnumClass

G_TYPE_IS_FLAGS()

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

Checks whether type "is a" G_TYPE_FLAGS.

Parameters

type

a GType ID.

Returns

TRUE if type "is a" G_TYPE_FLAGS.

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.

Parameters

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.

Parameters

class

a GFlagsClass

G_FLAGS_CLASS_TYPE()

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

Get the type identifier from a given GFlagsClass structure.

Parameters

class

a GFlagsClass

Returns

the GType

G_FLAGS_CLASS_TYPE_NAME()

#define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))

Get the static type name from a given GFlagsClass structure.

Parameters

class

a GFlagsClass

Returns

the type name.

g_enum_get_value ()

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

Returns the GEnumValue for a value.

Parameters

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.

[transfer none][nullable]

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.

Parameters

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.

[transfer none][nullable]

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.

Parameters

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.

[transfer none][nullable]

g_enum_to_string ()

gchar *
g_enum_to_string (GType g_enum_type,
                  gint value);

Pretty-prints value in the form of the enum’s name.

This is intended to be used for debugging purposes. The format of the output may change in the future.

Parameters

g_enum_type	the type identifier of a GEnumClass type
value	the value

Returns

a newly-allocated text string.

[transfer full]

Since: 2.54

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 .

Parameters

flags_class	a GFlagsClass
value	the value

Returns

the first GFlagsValue which is set in value , or NULL if none is set.

[transfer none][nullable]

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.

Parameters

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.

[transfer none][nullable]

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.

Parameters

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.

[transfer none][nullable]

g_flags_to_string ()

gchar *
g_flags_to_string (GType flags_type,
                   guint value);

Pretty-prints value in the form of the flag names separated by | and sorted. Any extra bits will be shown at the end as a hexadecimal number.

This is intended to be used for debugging purposes. The format of the output may change in the future.

Parameters

flags_type	the type identifier of a GFlagsClass type
value	the value

Returns

a newly-allocated text string.

[transfer full]

Since: 2.54

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

Parameters

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. GObject keeps a reference to the data, so it cannot be stack-allocated.

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

Parameters

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. GObject keeps a reference to the data, so it cannot be stack-allocated.

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

Parameters

g_enum_type	the type identifier of the type being completed
info	the GTypeInfo struct to be filled in.	[out callee-allocates]
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_enum_complete_type_info() above.

Parameters

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

Types and Values

struct GEnumClass

struct GEnumClass {
  GTypeClass  g_type_class;

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

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

Members

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.

struct GFlagsClass

struct GFlagsClass {
  GTypeClass   g_type_class;

  guint	       mask;
  guint	       n_values;
  GFlagsValue *values;
};

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

Members

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.

struct GEnumValue

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

A structure which contains a single enum value, its name, and its nickname.

Members

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

struct GFlagsValue

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

A structure which contains a single flags value, its name, and its nickname.

Members

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