gobject/gboxed.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 2000-2001 Red Hat, Inc.
   3  *
   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_BOXED_H__
  24 #define __G_BOXED_H__
  25
  26 #include        <gobject/gtype.h>
  27
  28 G_BEGIN_DECLS
  29
  30 /* --- type macros --- */
  31 #define G_TYPE_IS_BOXED(type)      (G_TYPE_FUNDAMENTAL (type) == G_TYPE_BOXED)
  32 /**
  33  * G_VALUE_HOLDS_BOXED:
  34  * @value: a valid #GValue structure
  35  *
  36  * Checks whether the given #GValue can hold values derived
  37  * from type %G_TYPE_BOXED.
  38  *
  39  * Returns: %TRUE on success.
  40  */
  41 #define G_VALUE_HOLDS_BOXED(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOXED))
  42
  43
  44 /* --- typedefs --- */
  45 /**
  46  * GBoxedCopyFunc:
  47  * @boxed: The boxed structure to be copied.
  48  *
  49  * This function is provided by the user and should produce a copy
  50  * of the passed in boxed structure.
  51  *
  52  * Returns: The newly created copy of the boxed structure.
  53  */
  54 typedef gpointer (*GBoxedCopyFunc) (gpointer boxed);
  55
  56 /**
  57  * GBoxedFreeFunc:
  58  * @boxed: The boxed structure to be freed.
  59  *
  60  * This function is provided by the user and should free the boxed
  61  * structure passed.
  62  */
  63 typedef void (*GBoxedFreeFunc) (gpointer boxed);
  64
  65
  66 /* --- prototypes --- */
  67 gpointer g_boxed_copy                     (GType boxed_type,
  68                                            gconstpointer  src_boxed);
  69 void     g_boxed_free                     (GType          boxed_type,
  70                                            gpointer       boxed);
  71 void     g_value_set_boxed                (GValue        *value,
  72                                            gconstpointer  v_boxed);
  73 void     g_value_set_static_boxed         (GValue        *value,
  74                                            gconstpointer  v_boxed);
  75 void     g_value_take_boxed               (GValue        *value,
  76                                            gconstpointer  v_boxed);
  77 #ifndef G_DISABLE_DEPRECATED
  78 void     g_value_set_boxed_take_ownership (GValue        *value,
  79                                            gconstpointer  v_boxed);
  80 #endif
  81 gpointer g_value_get_boxed                (const GValue  *value);
  82 gpointer g_value_dup_boxed                (const GValue  *value);
  83
  84
  85 /* --- convenience --- */
  86 GType    g_boxed_type_register_static     (const gchar   *name,
  87                                            GBoxedCopyFunc boxed_copy,
  88                                            GBoxedFreeFunc boxed_free);
  89
  90
  91 /* --- GLib boxed types --- */
  92 /**
  93  * G_TYPE_CLOSURE:
  94  *
  95  * The #GType for #GClosure.
  96  */
  97 #define G_TYPE_CLOSURE (g_closure_get_type ())
  98
  99 /**
 100  * G_TYPE_VALUE:
 101  *
 102  * The type ID of the "GValue" type which is a boxed type,
 103  * used to pass around pointers to GValues.
 104  */
 105 #define G_TYPE_VALUE (g_value_get_type ())
 106
 107 /**
 108  * G_TYPE_VALUE_ARRAY:
 109  *
 110  * The type ID of the "GValueArray" type which is a boxed type,
 111  * used to pass around pointers to GValueArrays.
 112  */
 113 #define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())
 114
 115 /**
 116  * G_TYPE_DATE:
 117  *
 118  * The #GType for #GDate.
 119  */
 120 #define G_TYPE_DATE (g_date_get_type ())
 121
 122 /**
 123  * G_TYPE_STRV:
 124  *
 125  * The #GType for a boxed type holding a %NULL-terminated array of strings.
 126  *
 127  * The code fragments in the following example show the use of a property of
 128  * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
 129  * and g_object_get().
 130  *
 131  * |[
 132  * g_object_class_install_property (object_class,
 133  *                                  PROP_AUTHORS,
 134  *                                  g_param_spec_boxed ("authors",
 135  *                                                      _("Authors"),
 136  *                                                      _("List of authors"),
 137  *                                                      G_TYPE_STRV,
 138  *                                                      G_PARAM_READWRITE));
 139  *
 140  * gchar *authors[] = { "Owen", "Tim", NULL };
 141  * g_object_set (obj, "authors", authors, NULL);
 142  *
 143  * gchar *writers[];
 144  * g_object_get (obj, "authors", &writers, NULL);
 145  * /&ast; do something with writers &ast;/
 146  * g_strfreev (writers);
 147  * ]|
 148  *
 149  * Since: 2.4
 150  */
 151 #define G_TYPE_STRV (g_strv_get_type ())
 152
 153 /**
 154  * G_TYPE_GSTRING:
 155  *
 156  * The #GType for #GString.
 157  */
 158 #define G_TYPE_GSTRING (g_gstring_get_type ())
 159
 160 /**
 161  * G_TYPE_HASH_TABLE:
 162  *
 163  * The #GType for a boxed type holding a #GHashTable reference.
 164  *
 165  * Since: 2.10
 166  */
 167 #define G_TYPE_HASH_TABLE (g_hash_table_get_type ())
 168
 169 /**
 170  * G_TYPE_REGEX:
 171  *
 172  * The #GType for a boxed type holding a #GRegex reference.
 173  *
 174  * Since: 2.14
 175  */
 176 #define G_TYPE_REGEX (g_regex_get_type ())
 177
 178 /**
 179  * G_TYPE_ARRAY:
 180  *
 181  * The #GType for a boxed type holding a #GArray reference.
 182  *
 183  * Since: 2.22
 184  */
 185 #define G_TYPE_ARRAY (g_array_get_type ())
 186
 187 /**
 188  * G_TYPE_BYTE_ARRAY:
 189  *
 190  * The #GType for a boxed type holding a #GByteArray reference.
 191  *
 192  * Since: 2.22
 193  */
 194 #define G_TYPE_BYTE_ARRAY (g_byte_array_get_type ())
 195
 196 /**
 197  * G_TYPE_PTR_ARRAY:
 198  *
 199  * The #GType for a boxed type holding a #GPtrArray reference.
 200  *
 201  * Since: 2.22
 202  */
 203 #define G_TYPE_PTR_ARRAY (g_ptr_array_get_type ())
 204
 205 /**
 206  * G_TYPE_VARIANT_TYPE:
 207  *
 208  * The #GType for a boxed type holding a #GVariantType.
 209  *
 210  * Since: 2.24
 211  */
 212 #define G_TYPE_VARIANT_TYPE (g_variant_type_get_gtype ())
 213
 214 /**
 215  * G_TYPE_ERROR:
 216  *
 217  * The #GType for a boxed type holding a #GError.
 218  *
 219  * Since: 2.26
 220  */
 221 #define G_TYPE_ERROR (g_error_get_type ())
 222
 223 /**
 224  * G_TYPE_DATE_TIME:
 225  *
 226  * The #GType for a boxed type holding a #GDateTime.
 227  *
 228  * Since: 2.26
 229  */
 230 #define G_TYPE_DATE_TIME (g_date_time_get_type ())
 231
 232 GType   g_closure_get_type       (void) G_GNUC_CONST;
 233 GType   g_value_get_type         (void) G_GNUC_CONST;
 234 GType   g_value_array_get_type   (void) G_GNUC_CONST;
 235 GType   g_date_get_type          (void) G_GNUC_CONST;
 236 GType   g_strv_get_type          (void) G_GNUC_CONST;
 237 GType   g_gstring_get_type       (void) G_GNUC_CONST;
 238 GType   g_hash_table_get_type    (void) G_GNUC_CONST;
 239 GType   g_array_get_type         (void) G_GNUC_CONST;
 240 GType   g_byte_array_get_type    (void) G_GNUC_CONST;
 241 GType   g_ptr_array_get_type     (void) G_GNUC_CONST;
 242 GType   g_variant_type_get_gtype (void) G_GNUC_CONST;
 243 GType   g_regex_get_type         (void) G_GNUC_CONST;
 244 GType   g_error_get_type         (void) G_GNUC_CONST;
 245 GType   g_date_time_get_type     (void) G_GNUC_CONST;
 246
 247 #ifndef G_DISABLE_DEPRECATED
 248 GType   g_variant_get_gtype      (void) G_GNUC_CONST;
 249 #endif
 250
 251 /**
 252  * GStrv:
 253  *
 254  * A C representable type name for #G_TYPE_STRV.
 255  */
 256 typedef gchar** GStrv;
 257
 258 G_END_DECLS
 259
 260 #endif  /* __G_BOXED_H__ */