Value

class Value(value_type: GType | None = None, py_value: Any | None = None) → 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 init on it.

Many types which are stored within a GValue need to allocate data on the heap, so 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 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 VALUE_TYPE macro and related macros.

Methods

class Value

dup_object() → Object | None

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

dup_string() → str | None

Get a copy the contents of a str Value.

dup_variant() → Variant | None

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

Added in version 2.26.

fits_pointer() → bool

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

This is an internal function introduced mainly for C marshallers.

get_boolean() → bool

Get the contents of a bool Value.

get_boxed() → GBoxed

Get the contents of a Boxed derived Value.

get_char() → int

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

Get the contents of a int Value.

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

get_double() → float

Get the contents of a float Value.

get_enum() → int

Get the contents of a Enum Value.

get_flags() → int

Get the contents of a Flags Value.

get_float() → float

Get the contents of a float Value.

get_gtype() → GType

Get the contents of a GType Value.

Added in version 2.12.

get_int() → int

Get the contents of a int Value.

get_int64() → int

Get the contents of a int Value.

get_long() → int

Get the contents of a int Value.

get_object() → Object | None

Get the contents of a object derived Value.

get_param() → ParamSpec

Get the contents of a ParamSpec Value.

get_pointer() → Any | None

Get the contents of a pointer Value.

get_schar() → int

Get the contents of a int Value.

Added in version 2.32.

get_string() → str | None

Get the contents of a str Value.

get_uchar() → int

Get the contents of a unsigned int Value.

get_uint() → int

Get the contents of a unsigned int Value.

get_uint64() → int

Get the contents of a unsigned int Value.

get_ulong() → int

Get the contents of a unsigned int Value.

get_value() → Any

get_variant() → Variant | None

Get the contents of a variant Value.

Added in version 2.26.

init(g_type: GType) → Value

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

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

GValue value = G_VALUE_INIT;

g_value_init (&value, SOME_G_TYPE);
…
g_value_unset (&value);

Parameters:

g_type – type the Value should hold values of

init_from_instance(instance: TypeInstance) → None

Initializes and sets value from an instantiatable type.

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

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

Added in version 2.42.

Parameters:

instance – the instance

peek_pointer() → Any | None

Returns the value contents as a pointer.

This function asserts that fits_pointer returned true for the passed in value.

This is an internal function introduced mainly for C marshallers.

reset() → Value

Clears the current value in value and resets it to the initial value (as if the value had just been initialized using init).

set_boolean(v_boolean: bool) → None

Set the contents of a bool Value to v_boolean.

Parameters:

v_boolean – boolean value to be set

set_boxed(boxed: GBoxed)

Set the contents of a Boxed derived Value to v_boxed.

Parameters:

boxed

set_boxed_take_ownership(v_boxed: Any = None) → None

This is an internal function introduced mainly for C marshallers.

Deprecated since version 2.4: Use take_boxed() instead.

Parameters:

v_boxed – duplicated unowned boxed value to be set

set_char(v_char: int) → None

Set the contents of a int Value to v_char.

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

Parameters:

v_char – character value to be set

set_double(v_double: float) → None

Set the contents of a float Value to v_double.

Parameters:

v_double – double value to be set

set_enum(v_enum: int) → None

Set the contents of a Enum Value to v_enum.

Parameters:

v_enum – enum value to be set

set_flags(v_flags: int) → None

Set the contents of a Flags Value to v_flags.

Parameters:

v_flags – flags value to be set

set_float(v_float: float) → None

Set the contents of a float Value to v_float.

Parameters:

v_float – float value to be set

set_gtype(v_gtype: GType) → None

Set the contents of a GType Value to v_gtype.

Added in version 2.12.

Parameters:

v_gtype – Type to be set

set_instance(instance: Any = None) → None

Sets value from an instantiatable type.

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

Parameters:

instance – the instance

set_int(v_int: int) → None

Set the contents of a int Value to v_int.

Parameters:

v_int – integer value to be set

set_int64(v_int64: int) → None

Set the contents of a int Value to v_int64.

Parameters:

v_int64 – 64bit integer value to be set

set_interned_string(v_string: str | None = None) → None

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

Added in version 2.66.

Parameters:

v_string – static string to be set

set_long(v_long: int) → None

Set the contents of a int Value to v_long.

Parameters:

v_long – long integer value to be set

set_object(v_object: Object | None = None) → None

Set the contents of a object derived Value to v_object.

set_object() increases the reference count of v_object (the 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 Value because you no longer need it), use take_object() instead.

It is important that your 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 Value still exists).

Parameters:

v_object – object value to be set

set_param(param: ParamSpec | None = None) → None

Set the contents of a ParamSpec Value to param.

Parameters:

param – the ParamSpec to be set

set_pointer(v_pointer: Any = None) → None

Set the contents of a pointer Value to v_pointer.

Parameters:

v_pointer – pointer value to be set

set_schar(v_char: int) → None

Set the contents of a int Value to v_char.

Added in version 2.32.

Parameters:

v_char – signed 8 bit integer to be set

set_static_boxed(v_boxed: Any = None) → None

Set the contents of a Boxed derived Value to v_boxed.

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

Parameters:

v_boxed – static boxed value to be set

set_static_string(v_string: str | None = None) → None

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

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

Parameters:

v_string – static string to be set

set_string(v_string: str | None = None) → None

Set the contents of a str Value to a copy of v_string.

Parameters:

v_string – caller-owned string to be duplicated for the Value

set_string_take_ownership(v_string: str | None = None) → None

This is an internal function introduced mainly for C marshallers.

Deprecated since version 2.4: Use take_string() instead.

Parameters:

v_string – duplicated unowned string to be set

set_uchar(v_uchar: int) → None

Set the contents of a unsigned int Value to v_uchar.

Parameters:

v_uchar – unsigned character value to be set

set_uint(v_uint: int) → None

Set the contents of a unsigned int Value to v_uint.

Parameters:

v_uint – unsigned integer value to be set

set_uint64(v_uint64: int) → None

Set the contents of a unsigned int Value to v_uint64.

Parameters:

v_uint64 – unsigned 64bit integer value to be set

set_ulong(v_ulong: int) → None

Set the contents of a unsigned int Value to v_ulong.

Parameters:

v_ulong – unsigned long integer value to be set

set_value(py_value: Any) → None

Parameters:

py_value

set_variant(variant: Variant | None = None) → None

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

Added in version 2.26.

Parameters:

variant – a Variant, or None

take_boxed(v_boxed: Any = None) → None

Sets the contents of a Boxed derived 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.

Added in version 2.4.

Parameters:

v_boxed – duplicated unowned boxed value to be set

take_string(v_string: str | None = None) → None

Sets the contents of a str Value to v_string.

Added in version 2.4.

Parameters:

v_string – string to take ownership of

take_variant(variant: Variant | None = None) → None

Set the contents of a variant 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 Value to hold its own reference to variant, use set_variant() instead.

This is an internal function introduced mainly for C marshallers.

Added in version 2.26.

Parameters:

variant – a Variant, or None

transform(dest_value: Value) → bool

Tries to cast the contents of src_value 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.

Parameters:

dest_value – target value

classmethod type_compatible(src_type: GType, dest_type: GType) → bool

Checks whether a copy is able to copy values of type src_type into values of type dest_type.

Parameters:

• src_type – source type to be copied

• dest_type – destination type for copying

classmethod type_transformable(src_type: GType, dest_type: GType) → bool

Checks whether 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 register_transform_func.

Parameters:

• src_type – source type

• dest_type – target type

unset() → None

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

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

Fields

class Value

data

g_type