gparam.h

Go to the documentation of this file.
00001 /* GObject - GLib Type, Object, Parameter and Signal Library
00002  * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
00003  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Lesser General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Lesser General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Lesser General
00016  * Public License along with this library; if not, write to the
00017  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
00018  * Boston, MA 02111-1307, USA.
00019  *
00020  * gparam.h: GParamSpec base class implementation
00021  */
00022 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
00023 #error "Only <glib-object.h> can be included directly."
00024 #endif
00025 
00026 #ifndef __G_PARAM_H__
00027 #define __G_PARAM_H__
00028 
00029 #include <_ansi.h>
00030 #include        <gobject/gvalue.h>
00031 
00032 G_BEGIN_DECLS
00033 
00034 /* --- standard type macros --- */
00035 #define G_TYPE_IS_PARAM(type)           (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
00036 #define G_PARAM_SPEC(pspec)             (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
00037 #define G_IS_PARAM_SPEC(pspec)          (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
00038 #define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
00039 #define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
00040 #define G_PARAM_SPEC_GET_CLASS(pspec)   (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
00041 
00042 
00043 /* --- convenience macros --- */
00044 #define G_PARAM_SPEC_TYPE(pspec)        (G_TYPE_FROM_INSTANCE (pspec))
00045 #define G_PARAM_SPEC_TYPE_NAME(pspec)   (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
00046 #define G_PARAM_SPEC_VALUE_TYPE(pspec)  (G_PARAM_SPEC (pspec)->value_type)
00047 #define G_VALUE_HOLDS_PARAM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
00048        
00049 
00050 /* --- flags --- */
00051 typedef enum
00052 {
00053   G_PARAM_READABLE            = 1 << 0,
00054   G_PARAM_WRITABLE            = 1 << 1,
00055   G_PARAM_CONSTRUCT           = 1 << 2,
00056   G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
00057   G_PARAM_LAX_VALIDATION      = 1 << 4,
00058   G_PARAM_STATIC_NAME         = 1 << 5,
00059 #ifndef G_DISABLE_DEPRECATED
00060   G_PARAM_PRIVATE             = G_PARAM_STATIC_NAME,
00061 #endif
00062   G_PARAM_STATIC_NICK         = 1 << 6,
00063   G_PARAM_STATIC_BLURB        = 1 << 7
00064 } GParamFlags;
00065 #define G_PARAM_READWRITE       (G_PARAM_READABLE | G_PARAM_WRITABLE)
00066 #define G_PARAM_MASK            (0x000000ff)
00067 /* bits in the range 0xffffff00 are reserved for 3rd party usage */
00068 #define G_PARAM_USER_SHIFT      (8)
00069 
00070 
00071 /* --- typedefs & structures --- */
00072 typedef struct _GParamSpec      GParamSpec;
00073 typedef struct _GParamSpecClass GParamSpecClass;
00074 typedef struct _GParameter      GParameter;
00075 typedef struct _GParamSpecPool  GParamSpecPool;
00076 struct _GParamSpec
00077 {
00078   GTypeInstance  g_type_instance;
00079 
00080   gchar         *name;
00081   GParamFlags    flags;
00082   GType          value_type;
00083   GType          owner_type;    /* class or interface using this property */
00084 
00085   /*< private >*/
00086   gchar         *_nick;
00087   gchar         *_blurb;
00088   GData         *qdata;
00089   guint          ref_count;
00090   guint          param_id;      /* sort-criteria */
00091 };
00092 struct _GParamSpecClass
00093 {
00094   GTypeClass      g_type_class;
00095 
00096   GType           value_type;
00097 
00098   void          (*finalize)             (GParamSpec   *pspec);
00099 
00100   /* GParam methods */
00101   void          (*value_set_default)    (GParamSpec   *pspec,
00102                                          GValue       *value);
00103   gboolean      (*value_validate)       (GParamSpec   *pspec,
00104                                          GValue       *value);
00105   gint          (*values_cmp)           (GParamSpec   *pspec,
00106                                          const GValue *value1,
00107                                          const GValue *value2);
00108   /*< private >*/
00109   gpointer        dummy[4];
00110 };
00111 struct _GParameter /* auxillary structure for _setv() variants */
00112 {
00113   const gchar *name;
00114   GValue       value;
00115 };
00116 
00117 
00118 /* --- prototypes --- */
00119 IMPORT_C GParamSpec*    g_param_spec_ref                (GParamSpec    *pspec);
00120 IMPORT_C void           g_param_spec_unref              (GParamSpec    *pspec);
00121 IMPORT_C void           g_param_spec_sink               (GParamSpec    *pspec);
00122 IMPORT_C GParamSpec*    g_param_spec_ref_sink           (GParamSpec    *pspec);
00123 IMPORT_C gpointer        g_param_spec_get_qdata         (GParamSpec    *pspec,
00124                                                  GQuark         quark);
00125 IMPORT_C void            g_param_spec_set_qdata         (GParamSpec    *pspec,
00126                                                  GQuark         quark,
00127                                                  gpointer       data);
00128 IMPORT_C void            g_param_spec_set_qdata_full    (GParamSpec    *pspec,
00129                                                  GQuark         quark,
00130                                                  gpointer       data,
00131                                                  GDestroyNotify destroy);
00132 IMPORT_C gpointer        g_param_spec_steal_qdata       (GParamSpec    *pspec,
00133                                                  GQuark         quark);
00134 IMPORT_C GParamSpec*     g_param_spec_get_redirect_target (GParamSpec   *pspec);
00135 
00136 IMPORT_C void           g_param_value_set_default       (GParamSpec    *pspec,
00137                                                  GValue        *value);
00138 IMPORT_C gboolean       g_param_value_defaults          (GParamSpec    *pspec,
00139                                                  GValue        *value);
00140 IMPORT_C gboolean       g_param_value_validate          (GParamSpec    *pspec,
00141                                                  GValue        *value);
00142 IMPORT_C gboolean       g_param_value_convert           (GParamSpec    *pspec,
00143                                                  const GValue  *src_value,
00144                                                  GValue        *dest_value,
00145                                                  gboolean       strict_validation);
00146 IMPORT_C gint           g_param_values_cmp              (GParamSpec    *pspec,
00147                                                  const GValue  *value1,
00148                                                  const GValue  *value2);
00149 IMPORT_C G_CONST_RETURN gchar*  g_param_spec_get_name   (GParamSpec    *pspec);
00150 IMPORT_C G_CONST_RETURN gchar*  g_param_spec_get_nick   (GParamSpec    *pspec);
00151 IMPORT_C G_CONST_RETURN gchar*  g_param_spec_get_blurb  (GParamSpec    *pspec);
00152 IMPORT_C void            g_value_set_param               (GValue               *value,
00153                                                  GParamSpec    *param);
00154 IMPORT_C GParamSpec*     g_value_get_param               (const GValue  *value);
00155 IMPORT_C GParamSpec*     g_value_dup_param               (const GValue  *value);
00156 
00157 
00158 IMPORT_C void           g_value_take_param               (GValue        *value,
00159                                                  GParamSpec    *param);
00160 #ifndef G_DISABLE_DEPRECATED
00161 IMPORT_C void           g_value_set_param_take_ownership (GValue        *value,
00162                                                  GParamSpec    *param);
00163 #endif
00164 
00165 /* --- convenience functions --- */
00166 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
00167 struct _GParamSpecTypeInfo
00168 {
00169   /* type system portion */
00170   guint16         instance_size;                               /* obligatory */
00171   guint16         n_preallocs;                                 /* optional */
00172   void          (*instance_init)        (GParamSpec   *pspec); /* optional */
00173 
00174   /* class portion */
00175   GType           value_type;                                  /* obligatory */
00176   void          (*finalize)             (GParamSpec   *pspec); /* optional */
00177   void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
00178                                          GValue       *value);
00179   gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
00180                                          GValue       *value);
00181   gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
00182                                          const GValue *value1,
00183                                          const GValue *value2);
00184 };
00185 IMPORT_C GType  g_param_type_register_static    (const gchar              *name,
00186                                          const GParamSpecTypeInfo *pspec_info);
00187 
00188 /* For registering builting types */
00189 GType  _g_param_type_register_static_constant (const gchar              *name,
00190                                                const GParamSpecTypeInfo *pspec_info,
00191                                                GType                     opt_type);
00192 
00193 
00194 /* --- protected --- */
00195 IMPORT_C gpointer       g_param_spec_internal           (GType          param_type,
00196                                                  const gchar   *name,
00197                                                  const gchar   *nick,
00198                                                  const gchar   *blurb,
00199                                                  GParamFlags    flags);
00200 IMPORT_C GParamSpecPool* g_param_spec_pool_new          (gboolean       type_prefixing);
00201 IMPORT_C void           g_param_spec_pool_insert        (GParamSpecPool *pool,
00202                                                  GParamSpec     *pspec,
00203                                                  GType           owner_type);
00204 IMPORT_C void           g_param_spec_pool_remove        (GParamSpecPool *pool,
00205                                                  GParamSpec     *pspec);
00206 IMPORT_C GParamSpec*    g_param_spec_pool_lookup        (GParamSpecPool *pool,
00207                                                  const gchar    *param_name,
00208                                                  GType           owner_type,
00209                                                  gboolean        walk_ancestors);
00210 IMPORT_C GList*         g_param_spec_pool_list_owned    (GParamSpecPool *pool,
00211                                                  GType           owner_type);
00212 IMPORT_C GParamSpec**   g_param_spec_pool_list          (GParamSpecPool *pool,
00213                                                  GType           owner_type,
00214                                                  guint          *n_pspecs_p);
00215 
00216 
00217 
00218 /* contracts:
00219  *
00220  * gboolean value_validate (GParamSpec *pspec,
00221  *                          GValue     *value):
00222  *      modify value contents in the least destructive way, so
00223  *      that it complies with pspec's requirements (i.e.
00224  *      according to minimum/maximum ranges etc...). return
00225  *      whether modification was necessary.
00226  *
00227  * gint values_cmp (GParamSpec   *pspec,
00228  *                  const GValue *value1,
00229  *                  const GValue *value2):
00230  *      return value1 - value2, i.e. (-1) if value1 < value2,
00231  *      (+1) if value1 > value2, and (0) otherwise (equality)
00232  */
00233 
00234 G_END_DECLS
00235 
00236 #endif /* __G_PARAM_H__ */
Copyright © Nokia Corporation 2001-2008
Back to top