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)

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

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.