mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-22 08:58:54 +02:00
Migrating docs.
* docs/reference/gobject/tmpl/generic_values.sgml: * gobject/gboxed.h: * gobject/gtype.h: * gobject/gvalue.c: * gobject/gvalue.h: * gobject/gvaluetypes.c: Migrating docs. svn path=/trunk/; revision=7071
This commit is contained in:
@@ -1,263 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
Generic Values
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
A polymorphic type that can hold values of any other type
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
The #GValue structure is basically a variable container that consists
|
||||
of a type identifier and a specific value of that type.
|
||||
The type identifier within a #GValue structure always determines the
|
||||
type of the associated value.
|
||||
To create a undefined #GValue structure, simply create a zero-filled
|
||||
#GValue structure. To initialize the #GValue, use the g_value_init()
|
||||
function. A #GValue cannot be used until it is initialized.
|
||||
The basic type operations (such as freeing and copying) are determined
|
||||
by the #GTypeValueTable associated with the type ID stored in the #GValue.
|
||||
Other #GValue operations (such as converting values between types) are
|
||||
provided by this interface.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
The fundamental types which all support #GValue operations and thus
|
||||
can be used as a type initializer for g_value_init() are defined by
|
||||
a separate interface. See the <link
|
||||
linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values
|
||||
API</link> for details.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### MACRO G_VALUE_HOLDS ##### -->
|
||||
<para>
|
||||
Returns %TRUE if @value holds (or contains) a value of @type.
|
||||
This macro will also check for @value != %NULL and issue a
|
||||
warning if the check fails.
|
||||
</para>
|
||||
|
||||
@value: A #GValue structure.
|
||||
@type: A #GType value.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_VALUE_TYPE ##### -->
|
||||
<para>
|
||||
Returns the type identifier of @value.
|
||||
</para>
|
||||
|
||||
@value: A #GValue structure.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_VALUE_TYPE_NAME ##### -->
|
||||
<para>
|
||||
Returns the type name of @value.
|
||||
</para>
|
||||
|
||||
@value: A #GValue structure.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_TYPE_IS_VALUE ##### -->
|
||||
<para>
|
||||
Return whether the passed in type ID can be used for g_value_init().
|
||||
That is, this macro checks whether this type provides an implementation
|
||||
of the #GTypeValueTable functions required for a type to create a #GValue of.
|
||||
</para>
|
||||
|
||||
@type: A #GType value.
|
||||
@Returns: Whether @type is suitable as a #GValue type.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_TYPE_IS_VALUE_ABSTRACT ##### -->
|
||||
<para>
|
||||
Returns %TRUE if @type is an abstract value type. An abstract value type
|
||||
introduces a value table, but can't be used for g_value_init() and is normally
|
||||
used as an abstract base type for derived value types.
|
||||
</para>
|
||||
|
||||
@type: A #GType value.
|
||||
|
||||
|
||||
<!-- ##### MACRO G_IS_VALUE ##### -->
|
||||
<para>
|
||||
Returns %TRUE if @value is a valid and initialized #GValue structure.
|
||||
</para>
|
||||
|
||||
@value: A #GValue structure.
|
||||
|
||||
|
||||
<!-- ##### STRUCT GValue ##### -->
|
||||
<para>
|
||||
An opaque structure used to hold different types of values.
|
||||
The data within the structure has protected scope: it is accessible only
|
||||
to functions within a #GTypeValueTable structure, or implementations of
|
||||
the g_value_*() API. That is, code portions which implement new fundamental
|
||||
types.
|
||||
#GValue users can not make any assumptions about how data is stored
|
||||
within the 2 element @data union, and the @g_type member should
|
||||
only be accessed through the G_VALUE_TYPE() macro.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### MACRO G_TYPE_VALUE ##### -->
|
||||
<para>
|
||||
Returns the type ID of the "GValue" type which is a boxed type,
|
||||
used to pass around pointers to GValues.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO G_TYPE_VALUE_ARRAY ##### -->
|
||||
<para>
|
||||
Returns the type ID of the "GValueArray" type which is a boxed type,
|
||||
used to pass around pointers to GValueArrays.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_init ##### -->
|
||||
<para>
|
||||
Initializes @value with the default value of @type.
|
||||
</para>
|
||||
|
||||
@value: A zero-filled (uninitialized) #GValue structure.
|
||||
@g_type: Type the #GValue should hold values of.
|
||||
@Returns: the #GValue structure that has been passed in
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_copy ##### -->
|
||||
<para>
|
||||
Copies the value of @src_value into @dest_value.
|
||||
</para>
|
||||
|
||||
@src_value: An initialized #GValue structure.
|
||||
@dest_value: An initialized #GValue structure of the same type as @src_value.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_reset ##### -->
|
||||
<para>
|
||||
Clears the current value in @value and resets it to the default value
|
||||
(as if the value had just been initialized).
|
||||
</para>
|
||||
|
||||
@value: An initialized #GValue structure.
|
||||
@Returns: the #GValue structure that has been passed in
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_unset ##### -->
|
||||
<para>
|
||||
Clears the current value in @value and "unsets" the type,
|
||||
this releases all resources associated with this GValue.
|
||||
An unset value is the same as an uninitialized (zero-filled)
|
||||
#GValue structure.
|
||||
</para>
|
||||
|
||||
@value: An initialized #GValue structure.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_set_instance ##### -->
|
||||
<para>
|
||||
Sets @value from an instantiatable type via the
|
||||
value_table's collect_value() function.
|
||||
</para>
|
||||
|
||||
@value: An initialized #GValue structure.
|
||||
@instance: the instance
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_fits_pointer ##### -->
|
||||
<para>
|
||||
Determines if @value will fit inside the size of a pointer value.
|
||||
This is an internal function introduced mainly for C marshallers.
|
||||
</para>
|
||||
|
||||
@value: An initialized #GValue structure.
|
||||
@Returns: %TRUE if @value will fit inside a pointer value.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_peek_pointer ##### -->
|
||||
<para>
|
||||
Return the value contents as pointer. This function asserts that
|
||||
g_value_fits_pointer() returned %TRUE for the passed in value.
|
||||
This is an internal function introduced mainly for C marshallers.
|
||||
</para>
|
||||
|
||||
@value: An initialized #GValue structure.
|
||||
@Returns: %TRUE if @value will fit inside a pointer value.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_type_compatible ##### -->
|
||||
<para>
|
||||
Returns whether a #GValue of type @src_type can be copied into
|
||||
a #GValue of type @dest_type.
|
||||
</para>
|
||||
|
||||
@src_type: source type to be copied.
|
||||
@dest_type: destination type for copying.
|
||||
@Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_type_transformable ##### -->
|
||||
<para>
|
||||
Check whether g_value_transform() is able to transform values
|
||||
of type @src_type into values of type @dest_type.
|
||||
</para>
|
||||
|
||||
@src_type: Source type.
|
||||
@dest_type: Target type.
|
||||
@Returns: %TRUE if the transformation is possible, %FALSE otherwise.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_transform ##### -->
|
||||
<para>
|
||||
Tries to cast the contents of @src_value into a type appropriate
|
||||
to store in @dest_value, e.g. to transform a %G_TYPE_INT value
|
||||
into a %G_TYPE_FLOAT value. Performing transformations between
|
||||
value types might incur precision lossage. Especially
|
||||
transformations into strings might reveal seemingly arbitrary
|
||||
results and shouldn't be relied upon for production code (such
|
||||
as rcfile value or object property serialization).
|
||||
</para>
|
||||
|
||||
@src_value: Source value.
|
||||
@dest_value: Target value.
|
||||
@Returns: Whether a transformation rule was found and could be applied.
|
||||
Upon failing transformations, @dest_value is left untouched.
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GValueTransform ##### -->
|
||||
<para>
|
||||
The type of value transformation functions which can be registered with
|
||||
g_value_register_transform_func().
|
||||
</para>
|
||||
|
||||
@src_value: Source value.
|
||||
@dest_value: Target value.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_register_transform_func ##### -->
|
||||
<para>
|
||||
Registers a value transformation function for use in g_value_transform().
|
||||
A previously registered transformation function for @src_type and @dest_type
|
||||
will be replaced.
|
||||
</para>
|
||||
|
||||
@src_type: Source type.
|
||||
@dest_type: Target type.
|
||||
@transform_func: a function which transforms values of type @src_type
|
||||
into value of type @dest_type
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_strdup_value_contents ##### -->
|
||||
<para>
|
||||
Return a newly allocated string, which describes the contents of a #GValue.
|
||||
The main purpose of this function is to describe #GValue contents for
|
||||
debugging output, the way in which the contents are described may change
|
||||
between different GLib versions.
|
||||
</para>
|
||||
|
||||
@value: #GValue which contents are to be described.
|
||||
@Returns: Newly allocated string.
|
||||
|
||||
|
Reference in New Issue
Block a user