Skip to content

GObject.Value

record (struct)

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 Value.init on it.

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

Methods

copy

def copy(self, dest_value: Value) -> None

Copies the value of src_value into dest_value.

Parameters:

  • dest_value — an initialized Value structure of the same type as src_value

dup_object

def dup_object(self) -> Object | None

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

dup_string

def dup_string(self) -> str | None

Get a copy the contents of a G_TYPE_STRING Value.

dup_variant

def dup_variant(self) -> GLib.Variant | None

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

fits_pointer

def fits_pointer(self) -> 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

def get_boolean(self) -> bool

Get the contents of a G_TYPE_BOOLEAN Value.

get_boxed

def get_boxed(self) -> int | None

Get the contents of a G_TYPE_BOXED derived Value.

get_char

def get_char(self) -> int

:::warning Deprecated since 2.32 This API is deprecated. :::

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

Get the contents of a G_TYPE_CHAR Value.

get_double

def get_double(self) -> float

Get the contents of a G_TYPE_DOUBLE Value.

get_enum

def get_enum(self) -> int

Get the contents of a G_TYPE_ENUM Value.

get_flags

def get_flags(self) -> int

Get the contents of a G_TYPE_FLAGS Value.

get_float

def get_float(self) -> float

Get the contents of a G_TYPE_FLOAT Value.

get_gtype

def get_gtype(self) -> type | Type

Get the contents of a G_TYPE_GTYPE Value.

get_int

def get_int(self) -> int

Get the contents of a G_TYPE_INT Value.

get_int64

def get_int64(self) -> int

Get the contents of a G_TYPE_INT64 Value.

get_long

def get_long(self) -> int

Get the contents of a G_TYPE_LONG Value.

get_object

def get_object(self) -> Object | None

Get the contents of a G_TYPE_OBJECT derived Value.

get_param

def get_param(self) -> ParamSpec

Get the contents of a G_TYPE_PARAM Value.

get_pointer

def get_pointer(self) -> int | None

Get the contents of a pointer Value.

get_schar

def get_schar(self) -> int

Get the contents of a G_TYPE_CHAR Value.

get_string

def get_string(self) -> str | None

Get the contents of a G_TYPE_STRING Value.

get_uchar

def get_uchar(self) -> int

Get the contents of a G_TYPE_UCHAR Value.

get_uint

def get_uint(self) -> int

Get the contents of a G_TYPE_UINT Value.

get_uint64

def get_uint64(self) -> int

Get the contents of a G_TYPE_UINT64 Value.

get_ulong

def get_ulong(self) -> int

Get the contents of a G_TYPE_ULONG Value.

get_variant

def get_variant(self) -> GLib.Variant | None

Get the contents of a variant Value.

init

def init(self, g_type: type | Type) -> 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

def init_from_instance(self, instance: TypeInstance) -> None

Initializes and sets value from an instantiatable type.

This calls the 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 GObject.Type (such as a parent class type), you need to manually call Value.init and Value.set_instance.

Parameters:

  • instance — the instance

peek_pointer

def peek_pointer(self) -> int | None

Returns the value contents as a pointer.

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

This is an internal function introduced mainly for C marshallers.

reset

def reset(self) -> Value

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

set_boolean

def set_boolean(self, v_boolean: bool) -> None

Set the contents of a G_TYPE_BOOLEAN Value to v_boolean.

Parameters:

  • v_boolean — boolean value to be set

set_boxed

def set_boxed(self, v_boxed: int | None = ...) -> None

Set the contents of a G_TYPE_BOXED derived Value to v_boxed.

Parameters:

  • v_boxed — caller-owned boxed object to be duplicated for the Value

set_boxed_take_ownership

def set_boxed_take_ownership(self, v_boxed: int | None = ...) -> None

:::warning Deprecated since 2.4 This API is deprecated. :::

This is an internal function introduced mainly for C marshallers.

Parameters:

  • v_boxed — duplicated unowned boxed value to be set

set_char

def set_char(self, v_char: int) -> None

:::warning Deprecated since 2.32 This API is deprecated. :::

Set the contents of a G_TYPE_CHAR Value to v_char.

Parameters:

  • v_char — character value to be set

set_double

def set_double(self, v_double: float) -> None

Set the contents of a G_TYPE_DOUBLE Value to v_double.

Parameters:

  • v_double — double value to be set

set_enum

def set_enum(self, v_enum: int) -> None

Set the contents of a G_TYPE_ENUM Value to v_enum.

Parameters:

  • v_enum — enum value to be set

set_flags

def set_flags(self, v_flags: int) -> None

Set the contents of a G_TYPE_FLAGS Value to v_flags.

Parameters:

  • v_flags — flags value to be set

set_float

def set_float(self, v_float: float) -> None

Set the contents of a G_TYPE_FLOAT Value to v_float.

Parameters:

  • v_float — float value to be set

set_gtype

def set_gtype(self, v_gtype: type | Type) -> None

Set the contents of a G_TYPE_GTYPE Value to v_gtype.

Parameters:

  • v_gtype — GType to be set

set_instance

def set_instance(self, instance: int | None = ...) -> None

Sets value from an instantiatable type.

This calls the TypeValueCollectFunc function for the type the Value contains.

Parameters:

  • instance — the instance

set_int

def set_int(self, v_int: int) -> None

Set the contents of a G_TYPE_INT Value to v_int.

Parameters:

  • v_int — integer value to be set

set_int64

def set_int64(self, v_int64: int) -> None

Set the contents of a G_TYPE_INT64 Value to v_int64.

Parameters:

  • v_int64 — 64bit integer value to be set

set_interned_string

def set_interned_string(self, v_string: str | None = ...) -> None

Set the contents of a G_TYPE_STRING 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 Value.

Parameters:

  • v_string — static string to be set

set_long

def set_long(self, v_long: int) -> None

Set the contents of a G_TYPE_LONG Value to v_long.

Parameters:

  • v_long — long integer value to be set

set_object

def set_object(self, v_object: Object | None = ...) -> None

Set the contents of a G_TYPE_OBJECT derived Value to v_object.

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

def set_param(self, param: ParamSpec | None = ...) -> None

Set the contents of a G_TYPE_PARAM Value to param.

Parameters:

set_pointer

def set_pointer(self, v_pointer: int | None = ...) -> None

Set the contents of a pointer Value to v_pointer.

Parameters:

  • v_pointer — pointer value to be set

set_schar

def set_schar(self, v_char: int) -> None

Set the contents of a G_TYPE_CHAR Value to v_char.

Parameters:

  • v_char — signed 8 bit integer to be set

set_static_boxed

def set_static_boxed(self, v_boxed: int | None = ...) -> None

Set the contents of a G_TYPE_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

def set_static_string(self, v_string: str | None = ...) -> None

Set the contents of a G_TYPE_STRING 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 Value.set_interned_string is more appropriate.

Parameters:

  • v_string — static string to be set

set_string

def set_string(self, v_string: str | None = ...) -> None

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

Parameters:

  • v_string — caller-owned string to be duplicated for the Value

set_string_take_ownership

def set_string_take_ownership(self, v_string: str | None = ...) -> None

:::warning Deprecated since 2.4 This API is deprecated. :::

This is an internal function introduced mainly for C marshallers.

Parameters:

  • v_string — duplicated unowned string to be set

set_uchar

def set_uchar(self, v_uchar: int) -> None

Set the contents of a G_TYPE_UCHAR Value to v_uchar.

Parameters:

  • v_uchar — unsigned character value to be set

set_uint

def set_uint(self, v_uint: int) -> None

Set the contents of a G_TYPE_UINT Value to v_uint.

Parameters:

  • v_uint — unsigned integer value to be set

set_uint64

def set_uint64(self, v_uint64: int) -> None

Set the contents of a G_TYPE_UINT64 Value to v_uint64.

Parameters:

  • v_uint64 — unsigned 64bit integer value to be set

set_ulong

def set_ulong(self, v_ulong: int) -> None

Set the contents of a G_TYPE_ULONG Value to v_ulong.

Parameters:

  • v_ulong — unsigned long integer value to be set

set_variant

def set_variant(self, variant: GLib.Variant | None = ...) -> None

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

Parameters:

steal_string

def steal_string(self) -> str | None

Steal ownership on contents of a G_TYPE_STRING 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 Value API.

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

take_boxed

def take_boxed(self, v_boxed: int | None = ...) -> None

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

Parameters:

  • v_boxed — duplicated unowned boxed value to be set

take_string

def take_string(self, v_string: str | None = ...) -> None

Sets the contents of a G_TYPE_STRING Value to v_string.

Parameters:

  • v_string — string to take ownership of

take_variant

def take_variant(self, variant: GLib.Variant | 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 Value.set_variant instead.

This is an internal function introduced mainly for C marshallers.

Parameters:

transform

def transform(self, 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

unset

def unset(self) -> 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.

Static functions

type_compatible

@staticmethod
def type_compatible(src_type: type | Type, dest_type: type | Type) -> bool

Checks whether a Value.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

type_transformable

@staticmethod
def type_transformable(src_type: type | Type, dest_type: type | Type) -> bool

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

Parameters:

  • src_type — source type
  • dest_type — target type

Properties

g_type

g_type: type | Type  # read/write

data

data: list[_Value__data__union]  # read/write