epoc32/include/stdapis/glib-2.0/gobject/gparam.h
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
equal deleted inserted replaced
1:666f914201fb 2:2fe1408b6811
     1 gparam.h
     1 /* GObject - GLib Type, Object, Parameter and Signal Library
       
     2  * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
       
     3  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
       
     4  *
       
     5  * This library is free software; you can redistribute it and/or
       
     6  * modify it under the terms of the GNU Lesser General Public
       
     7  * License as published by the Free Software Foundation; either
       
     8  * version 2 of the License, or (at your option) any later version.
       
     9  *
       
    10  * This library is distributed in the hope that it will be useful,
       
    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
       
    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
       
    13  * Lesser General Public License for more details.
       
    14  *
       
    15  * You should have received a copy of the GNU Lesser General
       
    16  * Public License along with this library; if not, write to the
       
    17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
       
    18  * Boston, MA 02111-1307, USA.
       
    19  *
       
    20  * gparam.h: GParamSpec base class implementation
       
    21  */
       
    22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
       
    23 #error "Only <glib-object.h> can be included directly."
       
    24 #endif
       
    25 
       
    26 #ifndef __G_PARAM_H__
       
    27 #define __G_PARAM_H__
       
    28 
       
    29 #include <_ansi.h>
       
    30 #include	<gobject/gvalue.h>
       
    31 
       
    32 G_BEGIN_DECLS
       
    33 
       
    34 /* --- standard type macros --- */
       
    35 #define G_TYPE_IS_PARAM(type)		(G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
       
    36 #define G_PARAM_SPEC(pspec)		(G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
       
    37 #define G_IS_PARAM_SPEC(pspec)		(G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
       
    38 #define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
       
    39 #define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
       
    40 #define G_PARAM_SPEC_GET_CLASS(pspec)	(G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
       
    41 
       
    42 
       
    43 /* --- convenience macros --- */
       
    44 #define G_PARAM_SPEC_TYPE(pspec)	(G_TYPE_FROM_INSTANCE (pspec))
       
    45 #define G_PARAM_SPEC_TYPE_NAME(pspec)	(g_type_name (G_PARAM_SPEC_TYPE (pspec)))
       
    46 #define	G_PARAM_SPEC_VALUE_TYPE(pspec)	(G_PARAM_SPEC (pspec)->value_type)
       
    47 #define G_VALUE_HOLDS_PARAM(value)	(G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
       
    48        
       
    49 
       
    50 /* --- flags --- */
       
    51 typedef enum
       
    52 {
       
    53   G_PARAM_READABLE            = 1 << 0,
       
    54   G_PARAM_WRITABLE            = 1 << 1,
       
    55   G_PARAM_CONSTRUCT	      = 1 << 2,
       
    56   G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
       
    57   G_PARAM_LAX_VALIDATION      = 1 << 4,
       
    58   G_PARAM_STATIC_NAME	      = 1 << 5,
       
    59 #ifndef G_DISABLE_DEPRECATED
       
    60   G_PARAM_PRIVATE	      = G_PARAM_STATIC_NAME,
       
    61 #endif
       
    62   G_PARAM_STATIC_NICK	      = 1 << 6,
       
    63   G_PARAM_STATIC_BLURB	      = 1 << 7
       
    64 } GParamFlags;
       
    65 #define	G_PARAM_READWRITE	(G_PARAM_READABLE | G_PARAM_WRITABLE)
       
    66 #define	G_PARAM_MASK		(0x000000ff)
       
    67 /* bits in the range 0xffffff00 are reserved for 3rd party usage */
       
    68 #define	G_PARAM_USER_SHIFT	(8)
       
    69 
       
    70 
       
    71 /* --- typedefs & structures --- */
       
    72 typedef struct _GParamSpec      GParamSpec;
       
    73 typedef struct _GParamSpecClass GParamSpecClass;
       
    74 typedef struct _GParameter	GParameter;
       
    75 typedef struct _GParamSpecPool  GParamSpecPool;
       
    76 struct _GParamSpec
       
    77 {
       
    78   GTypeInstance  g_type_instance;
       
    79 
       
    80   gchar         *name;
       
    81   GParamFlags    flags;
       
    82   GType		 value_type;
       
    83   GType		 owner_type;	/* class or interface using this property */
       
    84 
       
    85   /*< private >*/
       
    86   gchar         *_nick;
       
    87   gchar         *_blurb;
       
    88   GData		*qdata;
       
    89   guint          ref_count;
       
    90   guint		 param_id;	/* sort-criteria */
       
    91 };
       
    92 struct _GParamSpecClass
       
    93 {
       
    94   GTypeClass      g_type_class;
       
    95 
       
    96   GType		  value_type;
       
    97 
       
    98   void	        (*finalize)		(GParamSpec   *pspec);
       
    99 
       
   100   /* GParam methods */
       
   101   void          (*value_set_default)    (GParamSpec   *pspec,
       
   102 					 GValue       *value);
       
   103   gboolean      (*value_validate)       (GParamSpec   *pspec,
       
   104 					 GValue       *value);
       
   105   gint          (*values_cmp)           (GParamSpec   *pspec,
       
   106 					 const GValue *value1,
       
   107 					 const GValue *value2);
       
   108   /*< private >*/
       
   109   gpointer	  dummy[4];
       
   110 };
       
   111 struct _GParameter /* auxillary structure for _setv() variants */
       
   112 {
       
   113   const gchar *name;
       
   114   GValue       value;
       
   115 };
       
   116 
       
   117 
       
   118 /* --- prototypes --- */
       
   119 IMPORT_C GParamSpec*	g_param_spec_ref		(GParamSpec    *pspec);
       
   120 IMPORT_C void		g_param_spec_unref		(GParamSpec    *pspec);
       
   121 IMPORT_C void		g_param_spec_sink		(GParamSpec    *pspec);
       
   122 IMPORT_C GParamSpec*	g_param_spec_ref_sink   	(GParamSpec    *pspec);
       
   123 IMPORT_C gpointer        g_param_spec_get_qdata		(GParamSpec    *pspec,
       
   124 						 GQuark         quark);
       
   125 IMPORT_C void            g_param_spec_set_qdata		(GParamSpec    *pspec,
       
   126 						 GQuark         quark,
       
   127 						 gpointer       data);
       
   128 IMPORT_C void            g_param_spec_set_qdata_full	(GParamSpec    *pspec,
       
   129 						 GQuark         quark,
       
   130 						 gpointer       data,
       
   131 						 GDestroyNotify destroy);
       
   132 IMPORT_C gpointer        g_param_spec_steal_qdata	(GParamSpec    *pspec,
       
   133 						 GQuark         quark);
       
   134 IMPORT_C GParamSpec*     g_param_spec_get_redirect_target (GParamSpec   *pspec);
       
   135 
       
   136 IMPORT_C void		g_param_value_set_default	(GParamSpec    *pspec,
       
   137 						 GValue	       *value);
       
   138 IMPORT_C gboolean	g_param_value_defaults		(GParamSpec    *pspec,
       
   139 						 GValue	       *value);
       
   140 IMPORT_C gboolean	g_param_value_validate		(GParamSpec    *pspec,
       
   141 						 GValue	       *value);
       
   142 IMPORT_C gboolean	g_param_value_convert		(GParamSpec    *pspec,
       
   143 						 const GValue  *src_value,
       
   144 						 GValue	       *dest_value,
       
   145 						 gboolean	strict_validation);
       
   146 IMPORT_C gint		g_param_values_cmp		(GParamSpec    *pspec,
       
   147 						 const GValue  *value1,
       
   148 						 const GValue  *value2);
       
   149 IMPORT_C G_CONST_RETURN gchar*	g_param_spec_get_name	(GParamSpec    *pspec);
       
   150 IMPORT_C G_CONST_RETURN gchar*	g_param_spec_get_nick	(GParamSpec    *pspec);
       
   151 IMPORT_C G_CONST_RETURN gchar*	g_param_spec_get_blurb	(GParamSpec    *pspec);
       
   152 IMPORT_C void            g_value_set_param               (GValue	       *value,
       
   153 						 GParamSpec    *param);
       
   154 IMPORT_C GParamSpec*     g_value_get_param               (const GValue  *value);
       
   155 IMPORT_C GParamSpec*     g_value_dup_param               (const GValue  *value);
       
   156 
       
   157 
       
   158 IMPORT_C void           g_value_take_param               (GValue        *value,
       
   159 					         GParamSpec    *param);
       
   160 #ifndef G_DISABLE_DEPRECATED
       
   161 IMPORT_C void           g_value_set_param_take_ownership (GValue        *value,
       
   162 					         GParamSpec    *param);
       
   163 #endif
       
   164 
       
   165 /* --- convenience functions --- */
       
   166 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
       
   167 struct _GParamSpecTypeInfo
       
   168 {
       
   169   /* type system portion */
       
   170   guint16         instance_size;                               /* obligatory */
       
   171   guint16         n_preallocs;                                 /* optional */
       
   172   void		(*instance_init)	(GParamSpec   *pspec); /* optional */
       
   173 
       
   174   /* class portion */
       
   175   GType           value_type;				       /* obligatory */
       
   176   void          (*finalize)             (GParamSpec   *pspec); /* optional */
       
   177   void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
       
   178 					 GValue       *value);
       
   179   gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
       
   180 					 GValue       *value);
       
   181   gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
       
   182 					 const GValue *value1,
       
   183 					 const GValue *value2);
       
   184 };
       
   185 IMPORT_C GType	g_param_type_register_static	(const gchar		  *name,
       
   186 					 const GParamSpecTypeInfo *pspec_info);
       
   187 
       
   188 /* For registering builting types */
       
   189 GType  _g_param_type_register_static_constant (const gchar              *name,
       
   190 					       const GParamSpecTypeInfo *pspec_info,
       
   191 					       GType                     opt_type);
       
   192 
       
   193 
       
   194 /* --- protected --- */
       
   195 IMPORT_C gpointer	g_param_spec_internal		(GType	        param_type,
       
   196 						 const gchar   *name,
       
   197 						 const gchar   *nick,
       
   198 						 const gchar   *blurb,
       
   199 						 GParamFlags    flags);
       
   200 IMPORT_C GParamSpecPool* g_param_spec_pool_new		(gboolean	type_prefixing);
       
   201 IMPORT_C void		g_param_spec_pool_insert	(GParamSpecPool	*pool,
       
   202 						 GParamSpec	*pspec,
       
   203 						 GType		 owner_type);
       
   204 IMPORT_C void		g_param_spec_pool_remove	(GParamSpecPool	*pool,
       
   205 						 GParamSpec	*pspec);
       
   206 IMPORT_C GParamSpec*	g_param_spec_pool_lookup	(GParamSpecPool	*pool,
       
   207 						 const gchar	*param_name,
       
   208 						 GType		 owner_type,
       
   209 						 gboolean	 walk_ancestors);
       
   210 IMPORT_C GList*		g_param_spec_pool_list_owned	(GParamSpecPool	*pool,
       
   211 						 GType		 owner_type);
       
   212 IMPORT_C GParamSpec**	g_param_spec_pool_list		(GParamSpecPool	*pool,
       
   213 						 GType		 owner_type,
       
   214 						 guint		*n_pspecs_p);
       
   215 
       
   216 
       
   217 
       
   218 /* contracts:
       
   219  *
       
   220  * gboolean value_validate (GParamSpec *pspec,
       
   221  *                          GValue     *value):
       
   222  *	modify value contents in the least destructive way, so
       
   223  *	that it complies with pspec's requirements (i.e.
       
   224  *	according to minimum/maximum ranges etc...). return
       
   225  *	whether modification was necessary.
       
   226  *
       
   227  * gint values_cmp (GParamSpec   *pspec,
       
   228  *                  const GValue *value1,
       
   229  *                  const GValue *value2):
       
   230  *	return value1 - value2, i.e. (-1) if value1 < value2,
       
   231  *	(+1) if value1 > value2, and (0) otherwise (equality)
       
   232  */
       
   233 
       
   234 G_END_DECLS
       
   235 
       
   236 #endif /* __G_PARAM_H__ */