1 /* GObject - GLib Type, Object, Parameter and Signal Library

     2  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.

     3  * Portions copyright (c) 2006-2009 Nokia Corporation.  All rights reserved.

     4  * This library is free software; you can redistribute it and/or

     5  * modify it under the terms of the GNU Lesser General Public

     6  * License as published by the Free Software Foundation; either

     7  * version 2 of the License, or (at your option) any later version.

     8  *

     9  * This library is distributed in the hope that it will be useful,

    10  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU

    12  * Lesser General Public License for more details.

    13  *

    14  * You should have received a copy of the GNU Lesser General

    15  * Public License along with this library; if not, write to the

    16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,

    17  * Boston, MA 02111-1307, USA.

    18  */

    19 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)

    20 #error "Only <glib-object.h> can be included directly."

    21 #endif

    22 

    23 #ifndef __G_ENUMS_H__

    24 #define __G_ENUMS_H__

    25 

    26 #include <gobject/gtype.h>

    27 

    28 G_BEGIN_DECLS

    29 

    30 /* --- type macros --- */

    31 /**

    32  * G_TYPE_IS_ENUM:

    33  * @type: a #GType ID.

    34  * 

    35  * Checks whether @type "is a" %G_TYPE_ENUM.

    36  *

    37  * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.

    38  */

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

    40 /**

    41  * G_ENUM_CLASS:

    42  * @class: a valid #GEnumClass

    43  * 

    44  * Casts a derived #GEnumClass structure into a #GEnumClass structure.

    45  */

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

    47 /**

    48  * G_IS_ENUM_CLASS:

    49  * @class: a #GEnumClass

    50  * 

    51  * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM

    52  * or derived.

    53  */

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

    55 /**

    56  * G_ENUM_CLASS_TYPE:

    57  * @class: a #GEnumClass

    58  * 

    59  * Get the type identifier from a given #GEnumClass structure.

    60  *

    61  * Returns: the #GType

    62  */

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

    64 /**

    65  * G_ENUM_CLASS_TYPE_NAME:

    66  * @class: a #GEnumClass

    67  * 

    68  * Get the static type name from a given #GEnumClass structure.

    69  *

    70  * Returns: the type name.

    71  */

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

    73 

    74 

    75 /**

    76  * G_TYPE_IS_FLAGS:

    77  * @type: a #GType ID.

    78  *

    79  * Checks whether @type "is a" %G_TYPE_FLAGS. 

    80  *

    81  * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.

    82  */

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

    84 /**

    85  * G_FLAGS_CLASS:

    86  * @class: a valid #GFlagsClass

    87  * 

    88  * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.

    89  */

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

    91 /**

    92  * G_IS_FLAGS_CLASS:

    93  * @class: a #GFlagsClass

    94  * 

    95  * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS

    96  * or derived.

    97  */

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

    99 /**

   100  * G_FLAGS_CLASS_TYPE:

   101  * @class: a #GFlagsClass

   102  * 

   103  * Get the type identifier from a given #GFlagsClass structure.

   104  *

   105  * Returns: the #GType

   106  */

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

   108 /**

   109  * G_FLAGS_CLASS_TYPE_NAME:

   110  * @class: a #GFlagsClass

   111  * 

   112  * Get the static type name from a given #GFlagsClass structure.

   113  *

   114  * Returns: the type name.

   115  */

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

   117 

   118 

   119 /**

   120  * G_VALUE_HOLDS_ENUM:

   121  * @value: a valid #GValue structure

   122  * 

   123  * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.

   124  * 

   125  * Returns: %TRUE on success.

   126  */

   127 #define G_VALUE_HOLDS_ENUM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))

   128 /**

   129  * G_VALUE_HOLDS_FLAGS:

   130  * @value: a valid #GValue structure

   131  * 

   132  * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.

   133  * 

   134  * Returns: %TRUE on success.

   135  */

   136 #define G_VALUE_HOLDS_FLAGS(value)     (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))

   137 

   138 

   139 /* --- enum/flag values & classes --- */

   140 typedef struct _GEnumClass  GEnumClass;

   141 typedef struct _GFlagsClass GFlagsClass;

   142 typedef struct _GEnumValue  GEnumValue;

   143 typedef struct _GFlagsValue GFlagsValue;

   144 

   145 /**

   146  * GEnumClass:

   147  * @g_type_class: the parent class

   148  * @minimum: the smallest possible value.

   149  * @maximum: the largest possible value.

   150  * @n_values: the number of possible values.

   151  * @values: an array of #GEnumValue structs describing the 

   152  *  individual values.

   153  * 

   154  * The class of an enumeration type holds information about its 

   155  * possible values.

   156  */

   157 struct	_GEnumClass

   158 {

   159   GTypeClass  g_type_class;

   160 

   161   /*< public >*/  

   162   gint	      minimum;

   163   gint	      maximum;

   164   guint	      n_values;

   165   GEnumValue *values;

   166 };

   167 /**

   168  * GFlagsClass:

   169  * @g_type_class: the parent class

   170  * @mask: a mask covering all possible values.

   171  * @n_values: the number of possible values.

   172  * @values: an array of #GFlagsValue structs describing the 

   173  *  individual values.

   174  * 

   175  * The class of a flags type holds information about its 

   176  * possible values.

   177  */

   178 struct	_GFlagsClass

   179 {

   180   GTypeClass   g_type_class;

   181   

   182   /*< public >*/  

   183   guint	       mask;

   184   guint	       n_values;

   185   GFlagsValue *values;

   186 };

   187 /**

   188  * GEnumValue:

   189  * @value: the enum value

   190  * @value_name: the name of the value

   191  * @value_nick: the nickname of the value

   192  * 

   193  * A structure which contains a single enum value, its name, and its

   194  * nickname.

   195  */

   196 struct _GEnumValue

   197 {

   198   gint	 value;

   199   const gchar *value_name;

   200   const gchar *value_nick;

   201 };

   202 /**

   203  * GFlagsValue:

   204  * @value: the flags value

   205  * @value_name: the name of the value

   206  * @value_nick: the nickname of the value

   207  * 

   208  * A structure which contains a single flags value, its name, and its

   209  * nickname.

   210  */

   211 struct _GFlagsValue

   212 {

   213   guint	 value;

   214   const gchar *value_name;

   215   const gchar *value_nick;

   216 };

   217 

   218 

   219 /* --- prototypes --- */

   220 IMPORT_C GEnumValue*	g_enum_get_value		(GEnumClass	*enum_class,

   221 						 gint		 value);

   222 IMPORT_C GEnumValue*	g_enum_get_value_by_name	(GEnumClass	*enum_class,

   223 						 const gchar	*name);

   224 IMPORT_C GEnumValue*	g_enum_get_value_by_nick	(GEnumClass	*enum_class,

   225 						 const gchar	*nick);

   226 IMPORT_C GFlagsValue*	g_flags_get_first_value		(GFlagsClass	*flags_class,

   227 						 guint		 value);

   228 IMPORT_C GFlagsValue*	g_flags_get_value_by_name	(GFlagsClass	*flags_class,

   229 						 const gchar	*name);

   230 IMPORT_C GFlagsValue*	g_flags_get_value_by_nick	(GFlagsClass	*flags_class,

   231 						 const gchar	*nick);

   232 IMPORT_C void            g_value_set_enum        	(GValue         *value,

   233 						 gint            v_enum);

   234 IMPORT_C gint            g_value_get_enum        	(const GValue   *value);

   235 IMPORT_C void            g_value_set_flags       	(GValue         *value,

   236 						 guint           v_flags);

   237 IMPORT_C guint           g_value_get_flags       	(const GValue   *value);

   238 

   239 

   240 

   241 /* --- registration functions --- */

   242 /* const_static_values is a NULL terminated array of enum/flags

   243  * values that is taken over!

   244  */

   245 IMPORT_C GType	g_enum_register_static	   (const gchar	      *name,

   246 				    const GEnumValue  *const_static_values);

   247 IMPORT_C GType	g_flags_register_static	   (const gchar	      *name,

   248 				    const GFlagsValue *const_static_values);

   249 /* functions to complete the type information

   250  * for enums/flags implemented by plugins

   251  */

   252 IMPORT_C void	g_enum_complete_type_info  (GType	       g_enum_type,

   253 				    GTypeInfo	      *info,

   254 				    const GEnumValue  *const_values);

   255 IMPORT_C void	g_flags_complete_type_info (GType	       g_flags_type,

   256 				    GTypeInfo	      *info,

   257 				    const GFlagsValue *const_values);

   258 

   259 G_END_DECLS

   260 

   261 #endif /* __G_ENUMS_H__ */