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