GObject.Value¶

Fields¶

Name	Type	Access	Description
data	[`GObject._Value__data__union`]	r/w
g_type	`GObject.GType`	r

Methods¶

class	`type_compatible` (src_type, dest_type)
class	`type_transformable` (src_type, dest_type)
	`copy` (dest_value)
	`dup_object` ()
	`dup_string` ()
	`dup_variant` ()
	`fits_pointer` ()
	`get_boolean` ()
	`get_boxed` ()
	`get_char` ()
	`get_double` ()
	`get_enum` ()
	`get_flags` ()
	`get_float` ()
	`get_gtype` ()
	`get_int` ()
	`get_int64` ()
	`get_long` ()
	`get_object` ()
	`get_param` ()
	`get_pointer` ()
	`get_schar` ()
	`get_string` ()
	`get_uchar` ()
	`get_uint` ()
	`get_uint64` ()
	`get_ulong` ()
	`get_value` ()
	`get_variant` ()
	`init` (g_type)
	`init_from_instance` (instance)
	`peek_pointer` ()
	`reset` ()
	`set_boolean` (v_boolean)
	`set_boxed` (v_boxed)
	`set_boxed_take_ownership` (v_boxed)
	`set_char` (v_char)
	`set_double` (v_double)
	`set_enum` (v_enum)
	`set_flags` (v_flags)
	`set_float` (v_float)
	`set_gtype` (v_gtype)
	`set_instance` (instance)
	`set_int` (v_int)
	`set_int64` (v_int64)
	`set_interned_string` (v_string)
	`set_long` (v_long)
	`set_object` (v_object)
	`set_param` (param)
	`set_pointer` (v_pointer)
	`set_schar` (v_char)
	`set_static_boxed` (v_boxed)
	`set_static_string` (v_string)
	`set_string` (v_string)
	`set_string_take_ownership` (v_string)
	`set_uchar` (v_uchar)
	`set_uint` (v_uint)
	`set_uint64` (v_uint64)
	`set_ulong` (v_ulong)
	`set_value` (py_value)
	`set_variant` (variant)
	`steal_string` ()
	`take_boxed` (v_boxed)
	`take_string` (v_string)
	`take_variant` (variant)
	`transform` (dest_value)
	`unset` ()

Details¶

class GObject.Value(value_type=None, py_value=None)¶

An opaque structure used to hold different types of values.

Before it can be used, a GValue has to be initialized to a specific type by calling [method`GObject`.Value.init] on it.

Many types which are stored within a GValue need to allocate data on the heap, so [method`GObject`.Value.unset] must always be called on a GValue to free any such data once you’re finished with the GValue, even if the GValue itself is stored on the stack.

The data within the structure has protected scope: it is accessible only to functions within a [struct`GObject`.TypeValueTable] structure, or implementations of the g_value_*() API. That is, code which implements new fundamental types.

GValue users cannot 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 [func`GObject`.VALUE_TYPE] macro and related macros.

classmethod type_compatible(src_type, dest_type)[source]¶

Parameters:

src_type (GObject.GType) – source type to be copied
dest_type (GObject.GType) – destination type for copying

Returns:

true if the copy is possible; false otherwise

Return type:

bool

Checks whether a [method`GObject`.Value.copy] is able to copy values of type src_type into values of type dest_type.

classmethod type_transformable(src_type, dest_type)[source]¶

Parameters:

src_type (GObject.GType) – source type
dest_type (GObject.GType) – target type

Returns:

true if the transformation is possible; false otherwise

Return type:

bool

Checks whether [method`GObject`.Value.transform] is able to transform values of type src_type into values of type dest_type.

Note that for the types to be transformable, they must be compatible or a transformation function must be registered using [func`GObject`.Value.register_transform_func].

copy(dest_value)[source]¶

Parameters:: dest_value (GObject.Value) – an initialized [struct`GObject`.Value] structure of the same type as self

Copies the value of self into dest_value.

dup_object()[source]¶

Returns:: object content of self, should be unreferenced when no longer needed.
Return type:: GObject.Object or None

Get the contents of a GObject.TYPE_OBJECT derived GObject.Value, increasing its reference count. If the contents of the GObject.Value are None, then None will be returned.

dup_string()[source]¶

Returns:: a newly allocated copy of the string content of self
Return type:: str or None

Get a copy the contents of a GObject.TYPE_STRING GObject.Value.

dup_variant()[source]¶

Returns:: variant contents of self (may be None); should be unreffed using GLib.Variant.unref() when no longer needed
Return type:: GLib.Variant or None

Get the contents of a variant GObject.Value, increasing its refcount. The returned GLib.Variant is never floating.

New in version 2.26.

fits_pointer()[source]¶

Returns:: true if self will fit inside a pointer value; false otherwise
Return type:: bool

Determines if self will fit inside the size of a pointer value.

This is an internal function introduced mainly for C marshallers.

get_boolean()[source]¶

Returns:: boolean contents of self
Return type:: bool

Get the contents of a GObject.TYPE_BOOLEAN GObject.Value.

get_boxed()[source]¶

Returns:: boxed contents of self
Return type:: object or None

Get the contents of a GObject.TYPE_BOXED derived GObject.Value.

get_char()[source]¶

Returns:: character contents of self
Return type:: int

Do not use this function; it is broken on platforms where the str type is unsigned, such as ARM and PowerPC. See GObject.Value.get_schar().

Get the contents of a GObject.TYPE_CHAR GObject.Value.

Deprecated since version 2.32: This function’s return type is broken, see GObject.Value.get_schar()

get_double()[source]¶

Returns:: double contents of self
Return type:: float

Get the contents of a GObject.TYPE_DOUBLE GObject.Value.

get_enum()[source]¶

Returns:: enum contents of self
Return type:: int

Get the contents of a GObject.TYPE_ENUM GObject.Value.

get_flags()[source]¶

Returns:: flags contents of self
Return type:: int

Get the contents of a GObject.TYPE_FLAGS GObject.Value.

get_float()[source]¶

Returns:: float contents of self
Return type:: float

Get the contents of a GObject.TYPE_FLOAT GObject.Value.

get_gtype()[source]¶

Returns:: the GObject.GType stored in self
Return type:: GObject.GType

Get the contents of a GObject.TYPE_GTYPE GObject.Value.

New in version 2.12.

get_int()[source]¶

Returns:: integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_INT GObject.Value.

get_int64()[source]¶

Returns:: 64bit integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_INT64 GObject.Value.

get_long()[source]¶

Returns:: long integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_LONG GObject.Value.

get_object()[source]¶

Returns:: object contents of self
Return type:: GObject.Object or None

Get the contents of a GObject.TYPE_OBJECT derived GObject.Value.

get_param()[source]¶

Returns:: GObject.ParamSpec content of self
Return type:: GObject.ParamSpec

Get the contents of a GObject.TYPE_PARAM GObject.Value.

get_pointer()[source]¶

Returns:: pointer contents of self
Return type:: object or None

Get the contents of a pointer GObject.Value.

get_schar()[source]¶

Returns:: signed 8 bit integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_CHAR GObject.Value.

New in version 2.32.

get_string()[source]¶

Returns:: string content of self
Return type:: str or None

Get the contents of a GObject.TYPE_STRING GObject.Value.

get_uchar()[source]¶

Returns:: unsigned character contents of self
Return type:: int

Get the contents of a GObject.TYPE_UCHAR GObject.Value.

get_uint()[source]¶

Returns:: unsigned integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_UINT GObject.Value.

get_uint64()[source]¶

Returns:: unsigned 64bit integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_UINT64 GObject.Value.

get_ulong()[source]¶

Returns:: unsigned long integer contents of self
Return type:: int

Get the contents of a GObject.TYPE_ULONG GObject.Value.

get_value()¶: The type of the None singleton.

get_variant()[source]¶

Returns:: variant contents of self (may be None)
Return type:: GLib.Variant or None

Get the contents of a variant GObject.Value.

New in version 2.26.

init(g_type)[source]¶

Parameters:: g_type (GObject.GType) – type the [struct`GObject`.Value] should hold values of
Returns:: the [struct`GObject`.Value] structure that has been passed in
Return type:: GObject.Value

Initializes self to store values of the given type, and sets its value to the default for type.

This must be called before any other methods on a [struct`GObject`.Value], so the value knows what type it’s meant to store.

```c GObject.Value value = G_VALUE_INIT;

GObject.Value.init (&value, SOME_G_TYPE); … GObject.Value.unset (&value); ```

init_from_instance(instance)[source]¶

Parameters:: instance (GObject.TypeInstance) – the instance

Initializes and sets self from an instantiatable type.

This calls the [callback`GObject`.TypeValueCollectFunc] function for the type the [struct`GObject`.Value] contains.

Note: The self will be initialised with the exact type of instance. If you wish to set the self’s type to a different [type`GObject`.Type] (such as a parent class type), you need to manually call [method`GObject`.Value.init] and [method`GObject`.Value.set_instance].

New in version 2.42.

peek_pointer()[source]¶

Returns:: the value contents as a pointer
Return type:: object or None

Returns the value contents as a pointer.

This function asserts that [method`GObject`.Value.fits_pointer] returned true for the passed in value.

This is an internal function introduced mainly for C marshallers.

reset()[source]¶

Returns:: the [struct`GObject`.Value] structure that has been passed in
Return type:: GObject.Value

Clears the current value in self and resets it to the default value (as if the value had just been initialized using [method`GObject`.Value.init]).

set_boolean(v_boolean)[source]¶

Parameters:: v_boolean (bool) – boolean value to be set

Set the contents of a GObject.TYPE_BOOLEAN GObject.Value to v_boolean.

set_boxed(v_boxed)[source]¶

Parameters:: v_boxed (object or None) – caller-owned boxed object to be duplicated for the GObject.Value

Set the contents of a GObject.TYPE_BOXED derived GObject.Value to v_boxed.

set_boxed_take_ownership(v_boxed)[source]¶

Parameters:: v_boxed (object or None) – duplicated unowned boxed value to be set

This is an internal function introduced mainly for C marshallers.

Deprecated since version 2.4: Use GObject.Value.take_boxed() instead.

set_char(v_char)[source]¶

Parameters:: v_char (int) – character value to be set

Set the contents of a GObject.TYPE_CHAR GObject.Value to v_char.

Deprecated since version 2.32: This function’s input type is broken, see GObject.Value.set_schar()

set_double(v_double)[source]¶

Parameters:: v_double (float) – double value to be set

Set the contents of a GObject.TYPE_DOUBLE GObject.Value to v_double.

set_enum(v_enum)[source]¶

Parameters:: v_enum (int) – enum value to be set

Set the contents of a GObject.TYPE_ENUM GObject.Value to v_enum.

set_flags(v_flags)[source]¶

Parameters:: v_flags (int) – flags value to be set

Set the contents of a GObject.TYPE_FLAGS GObject.Value to v_flags.

set_float(v_float)[source]¶

Parameters:: v_float (float) – float value to be set

Set the contents of a GObject.TYPE_FLOAT GObject.Value to v_float.

set_gtype(v_gtype)[source]¶

Parameters:: v_gtype (GObject.GType) – GObject.GType to be set

Set the contents of a GObject.TYPE_GTYPE GObject.Value to v_gtype.

New in version 2.12.

set_instance(instance)[source]¶

Parameters:: instance (object or None) – the instance

Sets self from an instantiatable type.

This calls the [callback`GObject`.TypeValueCollectFunc] function for the type the [struct`GObject`.Value] contains.

set_int(v_int)[source]¶

Parameters:: v_int (int) – integer value to be set

Set the contents of a GObject.TYPE_INT GObject.Value to v_int.

set_int64(v_int64)[source]¶

Parameters:: v_int64 (int) – 64bit integer value to be set

Set the contents of a GObject.TYPE_INT64 GObject.Value to v_int64.

set_interned_string(v_string)[source]¶

Parameters:: v_string (str or None) – static string to be set

Set the contents of a GObject.TYPE_STRING GObject.Value to v_string. The string is assumed to be static and interned (canonical, for example from GLib.intern_string()), and is thus not duplicated when setting the GObject.Value.

New in version 2.66.

set_long(v_long)[source]¶

Parameters:: v_long (int) – long integer value to be set

Set the contents of a GObject.TYPE_LONG GObject.Value to v_long.

set_object(v_object)[source]¶

Parameters:: v_object (GObject.Object or None) – object value to be set

Set the contents of a GObject.TYPE_OBJECT derived GObject.Value to v_object.

GObject.Value.set_object() increases the reference count of v_object (the GObject.Value holds a reference to v_object). If you do not wish to increase the reference count of the object (i.e. you wish to pass your current reference to the GObject.Value because you no longer need it), use g_value_take_object() instead.

It is important that your GObject.Value holds a reference to v_object (either its own, or one it has taken) to ensure that the object won’t be destroyed while the GObject.Value still exists).

set_param(param)[source]¶

Parameters:: param (GObject.ParamSpec or None) – the GObject.ParamSpec to be set

Set the contents of a GObject.TYPE_PARAM GObject.Value to param.

set_pointer(v_pointer)[source]¶

Parameters:: v_pointer (object or None) – pointer value to be set

Set the contents of a pointer GObject.Value to v_pointer.

set_schar(v_char)[source]¶

Parameters:: v_char (int) – signed 8 bit integer to be set

Set the contents of a GObject.TYPE_CHAR GObject.Value to v_char.

New in version 2.32.

set_static_boxed(v_boxed)[source]¶

Parameters:: v_boxed (object or None) – static boxed value to be set

Set the contents of a GObject.TYPE_BOXED derived GObject.Value to v_boxed.

The boxed value is assumed to be static, and is thus not duplicated when setting the GObject.Value.

set_static_string(v_string)[source]¶

Parameters:: v_string (str or None) – static string to be set

Set the contents of a GObject.TYPE_STRING GObject.Value to v_string. The string is assumed to be static, and is thus not duplicated when setting the GObject.Value.

If the the string is a canonical string, using GObject.Value.set_interned_string() is more appropriate.

set_string(v_string)[source]¶

Parameters:: v_string (str or None) – caller-owned string to be duplicated for the GObject.Value

Set the contents of a GObject.TYPE_STRING GObject.Value to a copy of v_string.

set_string_take_ownership(v_string)[source]¶

Parameters:: v_string (str or None) – duplicated unowned string to be set

This is an internal function introduced mainly for C marshallers.

Deprecated since version 2.4: Use GObject.Value.take_string() instead.

set_uchar(v_uchar)[source]¶

Parameters:: v_uchar (int) – unsigned character value to be set

Set the contents of a GObject.TYPE_UCHAR GObject.Value to v_uchar.

set_uint(v_uint)[source]¶

Parameters:: v_uint (int) – unsigned integer value to be set

Set the contents of a GObject.TYPE_UINT GObject.Value to v_uint.

set_uint64(v_uint64)[source]¶

Parameters:: v_uint64 (int) – unsigned 64bit integer value to be set

Set the contents of a GObject.TYPE_UINT64 GObject.Value to v_uint64.

set_ulong(v_ulong)[source]¶

Parameters:: v_ulong (int) – unsigned long integer value to be set

Set the contents of a GObject.TYPE_ULONG GObject.Value to v_ulong.

set_value(py_value)¶: The type of the None singleton.

set_variant(variant)[source]¶

Parameters:: variant (GLib.Variant or None) – a GLib.Variant, or None

Set the contents of a variant GObject.Value to variant. If the variant is floating, it is consumed.

New in version 2.26.

steal_string()[source]¶

Returns:: string content of self; Should be freed with GLib.free() when no longer needed.
Return type:: str or None

Steal ownership on contents of a GObject.TYPE_STRING GObject.Value. As a result of this operation the value’s contents will be reset to None.

The purpose of this call is to provide a way to avoid an extra copy when some object have been serialized into string through GObject.Value API.

NOTE: for safety and compatibility purposes, if GObject.Value contains static string, or an interned one, this function will return a copy of the string. Otherwise the transfer notation would be ambiguous.

New in version 2.80.

take_boxed(v_boxed)[source]¶

Parameters:: v_boxed (object or None) – duplicated unowned boxed value to be set

Sets the contents of a GObject.TYPE_BOXED derived GObject.Value to v_boxed and takes over the ownership of the caller’s reference to v_boxed; the caller doesn’t have to unref it any more.

New in version 2.4.

take_string(v_string)[source]¶

Parameters:: v_string (str or None) – string to take ownership of

Sets the contents of a GObject.TYPE_STRING GObject.Value to v_string.

New in version 2.4.

take_variant(variant)[source]¶

Parameters:: variant (GLib.Variant or None) – a GLib.Variant, or None

Set the contents of a variant GObject.Value to variant, and takes over the ownership of the caller’s reference to variant; the caller doesn’t have to unref it any more (i.e. the reference count of the variant is not increased).

If variant was floating then its floating reference is converted to a hard reference.

If you want the GObject.Value to hold its own reference to variant, use GObject.Value.set_variant() instead.

This is an internal function introduced mainly for C marshallers.

New in version 2.26.

transform(dest_value)[source]¶

Parameters:: dest_value (GObject.Value) – target value
Returns:: true on success; false otherwise
Return type:: bool

Tries to cast the contents of self into a type appropriate to store in dest_value.

If a transformation is not possible, dest_value is not modified.

For example, this could transform a G_TYPE_INT value into a G_TYPE_FLOAT value.

Performing transformations between value types might incur precision loss. Especially transformations into strings might reveal seemingly arbitrary results and the format of particular transformations to strings is not guaranteed over time.

unset()[source]¶

Clears the current value in self (if any) and ‘unsets’ the type.

This releases all resources associated with this [struct`GObject`.Value]. An unset value is the same as a cleared (zero-filled) [struct`GObject`.Value] structure set to G_VALUE_INIT.