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.

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

GObject.Value 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 G_VALUE_TYPE() macro.

classmethod type_compatible(src_type, dest_type)

Parameters:

• src_type (GObject.GType) – source type to be copied.

• dest_type (GObject.GType) – destination type for copying.

Returns:

True if GObject.Value.copy() is possible with src_type and dest_type.

Return type:

bool

Returns whether a GObject.Value of type src_type can be copied into a GObject.Value of type dest_type.

classmethod type_transformable(src_type, dest_type)

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

Check whether 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.

copy(dest_value)

Parameters:

dest_value (GObject.Value) – An initialized GObject.Value structure of the same type as self.

Copies the value of self into dest_value.

dup_object()

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()

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()

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()

Returns:

True if self will fit inside a pointer value.

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()

Returns:

boolean contents of self

Return type:

bool

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

get_boxed()

Returns:

boxed contents of self

Return type:

object or None

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

get_char()

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()

Returns:

double contents of self

Return type:

float

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

get_enum()

Returns:

enum contents of self

Return type:

int

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

get_flags()

Returns:

flags contents of self

Return type:

int

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

get_float()

Returns:

float contents of self

Return type:

float

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

get_gtype()

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()

Returns:

integer contents of self

Return type:

int

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

get_int64()

Returns:

64bit integer contents of self

Return type:

int

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

get_long()

Returns:

long integer contents of self

Return type:

int

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

get_object()

Returns:

object contents of self

Return type:

GObject.Object or None

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

get_param()

Returns:

GObject.ParamSpec content of self

Return type:

GObject.ParamSpec

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

get_pointer()

Returns:

pointer contents of self

Return type:

object or None

Get the contents of a pointer GObject.Value.

get_schar()

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()

Returns:

string content of self

Return type:

str or None

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

get_uchar()

Returns:

unsigned character contents of self

Return type:

int

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

get_uint()

Returns:

unsigned integer contents of self

Return type:

int

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

get_uint64()

Returns:

unsigned 64bit integer contents of self

Return type:

int

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

get_ulong()

Returns:

unsigned long integer contents of self

Return type:

int

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

get_value()

get_variant()

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)

Parameters:

g_type (GObject.GType) – Type the GObject.Value should hold values of.

Returns:

the GObject.Value structure that has been passed in

Return type:

GObject.Value

Initializes self with the default value of type.

init_from_instance(instance)

Parameters:

instance (GObject.TypeInstance) – the instance

Initializes and sets self from an instantiatable type via the value_table’s collect_value() function.

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

New in version 2.42.

peek_pointer()

Returns:

the value contents as pointer

Return type:

object or None

Returns the value contents as pointer. This function asserts that GObject.Value.fits_pointer() returned True for the passed in value. This is an internal function introduced mainly for C marshallers.

reset()

Returns:

the 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).

set_boolean(v_boolean)

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)

Parameters:

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

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

set_boxed_take_ownership(v_boxed)

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)

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)

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)

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)

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)

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)

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)

Parameters:

instance (object or None) – the instance

Sets self from an instantiatable type via the value_table’s collect_value() function.

set_int(v_int)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

set_variant(variant)

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()

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)

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)

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)

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)

Parameters:

dest_value (GObject.Value) – Target value.

Returns:

Whether a transformation rule was found and could be applied. Upon failing transformations, dest_value is left untouched.

Return type:

bool

Tries to cast the contents of self into a type appropriate to store in dest_value, e.g. to transform a GObject.TYPE_INT value into a GObject.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).

unset()

Clears the current value in self (if any) and “unsets” the type, this releases all resources associated with this GObject.Value. An unset value is the same as an uninitialized (zero-filled) GObject.Value structure.