docs/reference/gobject/tmpl/generic_values.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Generic Values
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A polymorphic type that can hold values of any other type.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GValue structure is basically a variable container that consists
  10 of a type identifier and a specific value of that type.
  11 The type identifier within a #GValue structure always determines the
  12 type of the associated value.
  13 To create a undefined #GValue structure, simply create a zero-filled
  14 #GValue structure. To initialize the #GValue, use the g_value_init()
  15 function. A #GValue cannot be used until it is initialized.
  16 The basic type operations (such as freeing and copying) are determined
  17 by the #GTypeValueTable associated with the type ID stored in the #GValue.
  18 Other #GValue operations (such as converting values between types) are
  19 provided by this interface.
  20 </para>
  21
  22 <!-- ##### SECTION See_Also ##### -->
  23 <para>
  24 The fundamental types which all support #GValue operations and thus
  25 can be used as a type initializer for g_value_init() are defined by
  26 a separate interface.  See the Standard Values API for details.
  27 </para>
  28
  29 <!-- ##### MACRO G_VALUE_HOLDS ##### -->
  30 <para>
  31 Returns #TRUE if @value holds (or contains) a value of @type.
  32 This macro will also check for @value != #NULL and issue a
  33 warning if the check fails.
  34 </para>
  35
  36 @value:
  37 @type:
  38
  39
  40 <!-- ##### MACRO G_VALUE_TYPE ##### -->
  41 <para>
  42 Returns the type identifier of @value.
  43 </para>
  44
  45 @value: A #GValue structure.
  46
  47
  48 <!-- ##### MACRO G_VALUE_TYPE_NAME ##### -->
  49 <para>
  50 Returns the type name of @value.
  51 </para>
  52
  53 @value: A #GValue structure.
  54
  55
  56 <!-- ##### MACRO G_TYPE_IS_VALUE ##### -->
  57 <para>
  58 Return whether the passed in type ID can be used for g_value_init().
  59 That is, this macro checks whether this type provides an implementation
  60 of the #GTypeValueTable functions required for a type to create a #GValue of.
  61 </para>
  62
  63 @type:    A #GType value.
  64 @Returns: Whether @type is suitable as a #GValue type.
  65
  66
  67 <!-- ##### MACRO G_TYPE_IS_VALUE_ABSTRACT ##### -->
  68 <para>
  69
  70 </para>
  71
  72 @type:
  73
  74
  75 <!-- ##### MACRO G_IS_VALUE ##### -->
  76 <para>
  77 Returns #TRUE if @value is a valid and initialized #GValue structure.
  78 </para>
  79
  80 @value: A #GValue structure.
  81
  82
  83 <!-- ##### USER_FUNCTION GValueExchange ##### -->
  84 <para>
  85
  86 </para>
  87
  88 @value1:
  89 @value2:
  90
  91
  92 <!-- ##### STRUCT GValue ##### -->
  93 <para>
  94 A mostly opaque structure used to hold a #GValue object.  Mostly because
  95 the data within the structure has protected scope: it is accessible only
  96 to functions within a #GTypeValueTable structure, or implementations of
  97 the g_value_*() API.
  98 </para>
  99
 100
 101 <!-- ##### MACRO G_TYPE_VALUE ##### -->
 102 <para>
 103
 104 </para>
 105
 106
 107
 108 <!-- ##### MACRO G_TYPE_VALUE_ARRAY ##### -->
 109 <para>
 110
 111 </para>
 112
 113
 114
 115 <!-- ##### FUNCTION g_value_init ##### -->
 116 <para>
 117 Initializes @value with the default value of @type.
 118 </para>
 119
 120 @value:                 A zero-filled (uninitialized) #GValue structure.
 121 @g_type:        Type the #GValue should hold values of.
 122 @Returns:
 123
 124
 125 <!-- ##### FUNCTION g_value_copy ##### -->
 126 <para>
 127 Copies the value of @src_value into @dest_value.
 128 </para>
 129
 130 @src_value:     An initialized #GValue structure.
 131 @dest_value:    An initialized #GValue structure of the same type as @src_value.
 132
 133
 134 <!-- ##### FUNCTION g_value_reset ##### -->
 135 <para>
 136 Clears the current value in @value and resets it to the default value
 137 (as if the value had just been initialized).
 138 </para>
 139
 140 @value:         An initialized #GValue structure.
 141 @Returns:
 142
 143
 144 <!-- ##### FUNCTION g_value_unset ##### -->
 145 <para>
 146 Clears the current value in @value and "unsets" the type,
 147 this releases all resources associated with this GValue.
 148 An unset value is the same as an uninitialized (zero-filled)
 149 #GValue structure.
 150 </para>
 151
 152 @value:         An initialized #GValue structure.
 153
 154
 155 <!-- ##### FUNCTION g_value_fits_pointer ##### -->
 156 <para>
 157 Determines if @value will fit inside the size of a pointer value.
 158 This is an internal function introduced mainly for C marshallers.
 159 </para>
 160
 161 @value:                 An initialized #GValue structure.
 162 @Returns:       #TRUE if @value will fit inside a pointer value.
 163
 164
 165 <!-- ##### FUNCTION g_value_peek_pointer ##### -->
 166 <para>
 167 Return the value contents as pointer. This function asserts that
 168 g_value_fits_pointer() returned #TRUE for the passed in value.
 169 This is an internal function introduced mainly for C marshallers.
 170 </para>
 171
 172 @value:                 An initialized #GValue structure.
 173 @Returns:       #TRUE if @value will fit inside a pointer value.
 174
 175
 176 <!-- ##### FUNCTION g_value_type_compatible ##### -->
 177 <para>
 178
 179 </para>
 180
 181 @src_type:
 182 @dest_type:
 183 @Returns:
 184
 185
 186 <!-- ##### FUNCTION g_value_type_transformable ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @src_type:
 192 @dest_type:
 193 @Returns:
 194
 195
 196 <!-- ##### FUNCTION g_value_transform ##### -->
 197 <para>
 198
 199 </para>
 200
 201 @src_value:
 202 @dest_value:
 203 @Returns:
 204
 205
 206 <!-- ##### USER_FUNCTION GValueTransform ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @src_value:
 212 @dest_value:
 213
 214
 215 <!-- ##### FUNCTION g_value_register_transform_func ##### -->
 216 <para>
 217
 218 </para>
 219
 220 @src_type:
 221 @dest_type:
 222 @transform_func:
 223
 224
 225 <!-- ##### FUNCTION g_strdup_value_contents ##### -->
 226 <para>
 227
 228 </para>
 229
 230 @value:
 231 @Returns:
 232
 233