mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-05 08:56:16 +01:00
728ab5ff7e
2005-05-02 Matthias Clasen <mclasen@redhat.com> * gobject/tmpl/signals.sgml: * gobject/tmpl/generic_values.sgml: * gobject/tmpl/gtype.sgml: * gobject/tmpl/value_arrays.sgml: * gobject/tmpl/param_value_types.sgml: * gobject/tmpl/gtypemodule.sgml: * gobject/tmpl/enumerations_flags.sgml: Small additions.
252 lines
7.3 KiB
Plaintext
252 lines
7.3 KiB
Plaintext
<!-- ##### 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 Standard Values API 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 #GValue.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_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 apropriate
|
|
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 incour 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.
|
|
|
|
|