Functions

add_emission_hook(type: Object, name: str, callback: Callable[[...], None], *args: Any) → None

Parameters:

type
name
callback
args

boxed_free(boxed_type: type, boxed: None) → None

Free the boxed structure boxed which is of type boxed_type.

Parameters:

boxed_type – The type of boxed.
boxed – The boxed structure to be freed.

boxed_type_register_static(name: str, boxed_copy: Callable[[None], None], boxed_free: Callable[[None], None]) → type

This function creates a new Boxed derived type id for a new boxed type with name name.

Boxed type handling functions have to be provided to copy and free opaque boxed structures of this type.

For the general case, it is recommended to use DEFINE_BOXED_TYPE() instead of calling boxed_type_register_static() directly. The macro will create the appropriate *_get_type() function for the boxed type.

Parameters:

name – Name of the new boxed type.
boxed_copy – Boxed structure copy function.
boxed_free – Boxed structure free function.

Returns:

New Boxed derived type id for name.

cclosure_marshal_BOOLEAN__BOXED_BOXED(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_BOOLEAN__FLAGS(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_STRING__OBJECT_POINTER(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__BOOLEAN(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__BOXED(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__CHAR(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__DOUBLE(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__ENUM(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__FLAGS(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__FLOAT(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__INT(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__LONG(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__OBJECT(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__PARAM(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__POINTER(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__STRING(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__UCHAR(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__UINT(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__UINT_POINTER(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__ULONG(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__VARIANT(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_VOID__VOID(closure: Callable[[...], Any], return_value: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_value
n_param_values
param_values
invocation_hint
marshal_data

cclosure_marshal_generic(closure: Callable[[...], Any], return_gvalue: Any, n_param_values: int, param_values: Any, invocation_hint: None, marshal_data: None) → None

Parameters:

closure
return_gvalue
n_param_values
param_values
invocation_hint
marshal_data

child_watch_add(*args, **kwargs)

Deprecated since version PyGObject-3.16.0: GObject.child_watch_add is deprecated; use GLib.child_watch_add instead

Parameters:

args
kwargs

clear_signal_handler(handler_id_ptr: int, instance: Object) → None

Disconnects a handler from instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler_id_ptr is then set to zero, which is never a valid handler ID value (see signal_connect()).

If the handler ID is 0 then this function does nothing.

There is also a macro version of this function so that the code will be inlined.

Added in version 2.62.

Parameters:

handler_id_ptr – A pointer to a handler ID (of type gulong) of the handler to be disconnected.
instance – The instance to remove the signal handler from. This pointer may be None or invalid, if the handler ID is zero.

enum_complete_type_info(g_enum_type: type, const_values: EnumValue) → TypeInfo

This function is meant to be called from the complete_type_info function of a TypePlugin implementation, as in the following example:

static void
my_enum_complete_type_info (GTypePlugin     *plugin,
                            GType            g_type,
                            GTypeInfo       *info,
                            GTypeValueTable *value_table)
{
  static const GEnumValue values[] = {
    { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
    { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
    { 0, NULL, NULL }
  };

  g_enum_complete_type_info (type, info, values);
}

Parameters:

g_enum_type – the type identifier of the type being completed
const_values – An array of EnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0.

enum_get_value(enum_class: EnumClass, value: int) → EnumValue | None

Returns the EnumValue for a value.

Parameters:

enum_class – a EnumClass
value – the value to look up

Returns:

the EnumValue for value, or None if value is not a member of the enumeration

enum_get_value_by_name(enum_class: EnumClass, name: str) → EnumValue | None

Looks up a EnumValue by name.

Parameters:

enum_class – a EnumClass
name – the name to look up

Returns:

the EnumValue with name name, or None if the enumeration doesn’t have a member with that name

enum_get_value_by_nick(enum_class: EnumClass, nick: str) → EnumValue | None

Looks up a EnumValue by nickname.

Parameters:

enum_class – a EnumClass
nick – the nickname to look up

Returns:

the EnumValue with nickname nick, or None if the enumeration doesn’t have a member with that nickname

enum_register_static(name: str, const_static_values: EnumValue) → type

Registers a new static enumeration type with the name name.

It is normally more convenient to let [glib-mkenums][glib-mkenums], generate a my_enum_get_type() function from a usual C enumeration definition than to write one yourself using enum_register_static().

Parameters:

name – A nul-terminated string used as the name of the new type.
const_static_values – An array of EnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated.

Returns:

The new type identifier.

enum_to_string(g_enum_type: type, value: int) → str

Pretty-prints value in the form of the enum’s name.

This is intended to be used for debugging purposes. The format of the output may change in the future.

Added in version 2.54.

Parameters:

g_enum_type – the type identifier of a EnumClass type
value – the value

Returns:

a newly-allocated text string

filename_display_basename(filename: str) → str

Deprecated since version PyGObject-3.16.0: GObject.filename_display_basename is deprecated; use GLib.filename_display_basename instead

Parameters:: filename

filename_display_name(filename: str) → str

Deprecated since version PyGObject-3.16.0: GObject.filename_display_name is deprecated; use GLib.filename_display_name instead

Parameters:: filename

filename_from_utf8(utf8string, len=-1)

Deprecated since version PyGObject-3.16.0: GObject.filename_from_utf8 is deprecated; use GLib.filename_from_utf8 instead

Parameters:

utf8string
len

flags_complete_type_info(g_flags_type: type, const_values: FlagsValue) → TypeInfo

This function is meant to be called from the complete_type_info() function of a TypePlugin implementation, see the example for enum_complete_type_info() above.

Parameters:

g_flags_type – the type identifier of the type being completed
const_values – An array of FlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0.

flags_get_first_value(flags_class: FlagsClass, value: int) → FlagsValue | None

Returns the first FlagsValue which is set in value.

Parameters:

flags_class – a FlagsClass
value – the value

Returns:

the first FlagsValue which is set in value, or None if none is set

flags_get_value_by_name(flags_class: FlagsClass, name: str) → FlagsValue | None

Looks up a FlagsValue by name.

Parameters:

flags_class – a FlagsClass
name – the name to look up

Returns:

the FlagsValue with name name, or None if there is no flag with that name

flags_get_value_by_nick(flags_class: FlagsClass, nick: str) → FlagsValue | None

Looks up a FlagsValue by nickname.

Parameters:

flags_class – a FlagsClass
nick – the nickname to look up

Returns:

the FlagsValue with nickname nick, or None if there is no flag with that nickname

flags_register_static(name: str, const_static_values: FlagsValue) → type

Registers a new static flags type with the name name.

It is normally more convenient to let [glib-mkenums][glib-mkenums] generate a my_flags_get_type() function from a usual C enumeration definition than to write one yourself using flags_register_static().

Parameters:

name – A nul-terminated string used as the name of the new type.
const_static_values – An array of FlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated.

Returns:

The new type identifier.

flags_to_string(flags_type: type, value: int) → str

Pretty-prints value in the form of the flag names separated by ` | ` and sorted. Any extra bits will be shown at the end as a hexadecimal number.

This is intended to be used for debugging purposes. The format of the output may change in the future.

Added in version 2.54.

Parameters:

flags_type – the type identifier of a FlagsClass type
value – the value

Returns:

a newly-allocated text string

get_application_name() → str | None: Deprecated since version PyGObject-3.16.0: GObject.get_application_name is deprecated; use GLib.get_application_name instead

get_current_time(): Deprecated since version PyGObject-3.16.0: GObject.get_current_time is deprecated; use GLib.get_current_time instead

get_prgname() → str | None: Deprecated since version PyGObject-3.16.0: GObject.get_prgname is deprecated; use GLib.get_prgname instead

gtype_get_type() → type

idle_add(function, *user_data, **kwargs)

Deprecated since version PyGObject-3.16.0: GObject.idle_add is deprecated; use GLib.idle_add instead

Parameters:

function
user_data
kwargs

io_add_watch(*args, **kwargs)

Deprecated since version PyGObject-3.16.0: GObject.io_add_watch is deprecated; use GLib.io_add_watch instead

Parameters:

args
kwargs

list_properties() → list[ParamSpec]

main_context_default() → MainContext: Deprecated since version PyGObject-3.16.0: GObject.main_context_default is deprecated; use GLib.main_context_default instead

main_depth() → int: Deprecated since version PyGObject-3.16.0: GObject.main_depth is deprecated; use GLib.main_depth instead

markup_escape_text(text, length=-1)

Deprecated since version PyGObject-3.16.0: GObject.markup_escape_text is deprecated; use GLib.markup_escape_text instead

Parameters:

text
length

new(gtype: GType) → None

Parameters:: gtype

param_spec_boolean(name: str, nick: str | None, blurb: str | None, default_value: bool, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecBoolean instance specifying a bool property. In many cases, it may be more appropriate to use an enum with param_spec_enum(), both to improve code clarity by using explicitly named values, and to allow for more values to be added in future without breaking API.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_boxed(name: str, nick: str | None, blurb: str | None, boxed_type: type, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecBoxed instance specifying a Boxed derived property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
boxed_type – Boxed derived type of this property
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_char(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecChar instance specifying a int property.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_double(name: str, nick: str | None, blurb: str | None, minimum: float, maximum: float, default_value: float, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecDouble instance specifying a float property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_enum(name: str, nick: str | None, blurb: str | None, enum_type: type, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecEnum instance specifying a Enum property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
enum_type – a Type derived from Enum
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_flags(name: str, nick: str | None, blurb: str | None, flags_type: type, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecFlags instance specifying a Flags property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
flags_type – a Type derived from Flags
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_float(name: str, nick: str | None, blurb: str | None, minimum: float, maximum: float, default_value: float, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecFloat instance specifying a float property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_gtype(name: str, nick: str | None, blurb: str | None, is_a_type: type, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecGType instance specifying a GType property.

See internal() for details on property names.

Added in version 2.10.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
is_a_type – a Type whose subtypes are allowed as values of the property (use ``%G_TYPE_NONE`` for any type)
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_int(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecInt instance specifying a int property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_int64(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecInt64 instance specifying a int property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_long(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecLong instance specifying a int property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_object(name: str, nick: str | None, blurb: str | None, object_type: type, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecBoxed instance specifying a object derived property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
object_type – object derived type of this property
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_param(name: str, nick: str | None, blurb: str | None, param_type: type, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecParam instance specifying a ParamSpec property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
param_type – a Type derived from ParamSpec
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_pointer(name: str, nick: str | None, blurb: str | None, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecPointer instance specifying a pointer property. Where possible, it is better to use param_spec_object() or param_spec_boxed() to expose memory management information.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_string(name: str, nick: str | None, blurb: str | None, default_value: str | None, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecString instance.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_uchar(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecUChar instance specifying a unsigned int property.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_uint(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecUInt instance specifying a unsigned int property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_uint64(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecUInt64 instance specifying a unsigned int property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_ulong(name: str, nick: str | None, blurb: str | None, minimum: int, maximum: int, default_value: int, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecULong instance specifying a unsigned int property.

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
minimum – minimum value for the property specified
maximum – maximum value for the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_unichar(name: str, nick: str | None, blurb: str | None, default_value: str, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecUnichar instance specifying a unsigned int property. Value structures for this property can be accessed with set_uint() and get_uint().

See internal() for details on property names.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
default_value – default value for the property specified
flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_variant(name: str, nick: str | None, blurb: str | None, type: VariantType, default_value: Variant | None, flags: ParamFlags) → ParamSpec

Creates a new GParamSpecVariant instance specifying a Variant property.

If default_value is floating, it is consumed.

See internal() for details on property names.

Added in version 2.26.

Parameters:

name – canonical name of the property specified
nick – nick name for the property specified
blurb – description of the property specified
type – a VariantType
default_value – a Variant of type type to use as the default value, or None
flags – flags for the property specified

Returns:

the newly created ParamSpec

param_type_register_static(name: str, pspec_info: ParamSpecTypeInfo) → type

Registers name as the name of a new static type derived from ParamSpec.

The type system uses the information contained in the ParamSpecTypeInfo structure pointed to by info to manage the ParamSpec type and its instances.

Parameters:

name – 0-terminated string used as the name of the new ParamSpec type.
pspec_info – The ParamSpecTypeInfo for this ParamSpec type.

Returns:

The new type identifier.

param_value_convert(pspec: ParamSpec, src_value: Any, dest_value: Any, strict_validation: bool) → bool

Transforms src_value into dest_value if possible, and then validates dest_value, in order for it to conform to pspec. If strict_validation is True this function will only succeed if the transformed dest_value complied to pspec without modifications.

See also type_transformable(), transform() and param_value_validate().

Parameters:

pspec – a valid ParamSpec
src_value – source Value
dest_value – destination Value of correct type for pspec
strict_validation – True requires dest_value to conform to pspec without modifications

Returns:

True if transformation and validation were successful, False otherwise and dest_value is left untouched.

param_value_defaults(pspec: ParamSpec, value: Any) → bool

Checks whether value contains the default value as specified in pspec.

Parameters:

pspec – a valid ParamSpec
value – a Value of correct type for pspec

Returns:

whether value contains the canonical default for this pspec

param_value_is_valid(pspec: ParamSpec, value: Any) → bool

Return whether the contents of value comply with the specifications set out by pspec.

Added in version 2.74.

Parameters:

pspec – a valid ParamSpec
value – a Value of correct type for pspec

Returns:

whether the contents of value comply with the specifications set out by pspec.

param_value_set_default(pspec: ParamSpec, value: Any) → None

Sets value to its default value as specified in pspec.

Parameters:

pspec – a valid ParamSpec
value – a Value of correct type for pspec; since 2.64, you can also pass an empty Value, initialized with ``%G_VALUE_INIT``

param_value_validate(pspec: ParamSpec, value: Any) → bool

Ensures that the contents of value comply with the specifications set out by pspec. For example, a GParamSpecInt might require that integers stored in value may not be smaller than -42 and not be greater than +42. If value contains an integer outside of this range, it is modified accordingly, so the resulting value will fit into the range -42 .. +42.

Parameters:

pspec – a valid ParamSpec
value – a Value of correct type for pspec

Returns:

whether modifying value was necessary to ensure validity

param_values_cmp(pspec: ParamSpec, value1: Any, value2: Any) → int

Compares value1 with value2 according to pspec, and return -1, 0 or +1, if value1 is found to be less than, equal to or greater than value2, respectively.

Parameters:

pspec – a valid ParamSpec
value1 – a Value of correct type for pspec
value2 – a Value of correct type for pspec

Returns:

-1, 0 or +1, for a less than, equal to or greater than result

pointer_type_register_static(name: str) → type

Creates a new %G_TYPE_POINTER derived type id for a new pointer type with name name.

Parameters:: name – the name of the new pointer type.
Returns:: a new %G_TYPE_POINTER derived type id for name.

remove_emission_hook(obj, detailed_signal, hook_id)

Parameters:

obj
detailed_signal
hook_id

set_application_name(application_name: str) → None

Deprecated since version PyGObject-3.16.0: GObject.set_application_name is deprecated; use GLib.set_application_name instead

Parameters:: application_name

set_prgname(prgname: str) → None

Deprecated since version PyGObject-3.16.0: GObject.set_prgname is deprecated; use GLib.set_prgname instead

Parameters:: prgname

signal_accumulator_first_wins(ihint, return_accu, handler_return, user_data=None)

A predefined SignalAccumulator for signals intended to be used as a hook for application code to provide a particular value. Usually only one such value is desired and multiple handlers for the same signal don’t make much sense (except for the case of the default handler defined in the class structure, in which case you will usually want the signal connection to override the class handler).

This accumulator will use the return value from the first signal handler that is run as the return value for the signal and not run any further handlers (ie: the first handler “wins”).

Added in version 2.28.

Parameters:

ihint – standard SignalAccumulator parameter
return_accu – standard SignalAccumulator parameter
handler_return – standard SignalAccumulator parameter
user_data

Returns:

standard SignalAccumulator result

signal_accumulator_true_handled(ihint, return_accu, handler_return, user_data=None)

A predefined SignalAccumulator for signals that return a boolean values. The behavior that this accumulator gives is that a return of True stops the signal emission: no further callbacks will be invoked, while a return of False allows the emission to continue. The idea here is that a True return indicates that the callback handled the signal, and no further handling is needed.

Added in version 2.4.

Parameters:

ihint – standard SignalAccumulator parameter
return_accu – standard SignalAccumulator parameter
handler_return – standard SignalAccumulator parameter
user_data

Returns:

standard SignalAccumulator result

signal_add_emission_hook(signal_id: int, detail: int, hook_func: Callable[[...], bool], *hook_data: Any) → int

Adds an emission hook for a signal, which will get called for any emission of that signal, independent of the instance. This is possible only for signals which don’t have NO_HOOKS flag set.

Parameters:

signal_id – the signal identifier, as returned by signal_lookup().
detail – the detail on which to call the hook.
hook_func – a SignalEmissionHook function.
hook_data – user data for hook_func.

Returns:

the hook id, for later use with signal_remove_emission_hook().

signal_chain_from_overridden(instance_and_params: Sequence[Any], return_value: Any) → None

Calls the original class closure of a signal. This function should only be called from an overridden class closure; see signal_override_class_closure() and signal_override_class_handler().

Parameters:

instance_and_params – the argument list of the signal emission. The first element in the array is a Value for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal.
return_value – Location for the return value.

signal_connect_closure(instance: Object, detailed_signal: str, closure: Callable[[...], Any], after: bool) → int

Connects a closure to a signal for a particular object.

If closure is a floating reference (see sink()), this function takes ownership of closure.

This function cannot fail. If the given signal doesn’t exist, a critical warning is emitted.

Parameters:

instance – the instance to connect to.
detailed_signal – a string of the form “signal-name::detail”.
closure – the closure to connect.
after – whether the handler should be called before or after the default handler of the signal.

Returns:

the handler ID (always greater than 0)

signal_connect_closure_by_id(instance: Object, signal_id: int, detail: int, closure: Callable[[...], Any], after: bool) → int

Connects a closure to a signal for a particular object.

If closure is a floating reference (see sink()), this function takes ownership of closure.

This function cannot fail. If the given signal doesn’t exist, a critical warning is emitted.

Parameters:

instance – the instance to connect to.
signal_id – the id of the signal.
detail – the detail.
closure – the closure to connect.
after – whether the handler should be called before or after the default handler of the signal.

Returns:

the handler ID (always greater than 0)

signal_emitv(instance_and_params: Sequence[Any], signal_id: int, detail: int) → Any

Emits a signal. Signal emission is done synchronously. The method will only return control after all handlers are called or signal emission was stopped.

Note that signal_emitv() doesn’t change return_value if no handlers are connected, in contrast to signal_emit() and signal_emit_valist().

Parameters:

instance_and_params – argument list for the signal emission. The first element in the array is a Value for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal.
signal_id – the signal id
detail – the detail

signal_get_invocation_hint(instance: Object) → SignalInvocationHint | None

Returns the invocation hint of the innermost signal emission of instance.

Parameters:: instance – the instance to query
Returns:: the invocation hint of the innermost signal emission, or None if not found.

signal_handler_block(obj, handler_id)

Blocks the signal handler from being invoked until handler_unblock() is called.

Parameters:

obj (GObject.Object) – Object instance to block handlers for.
handler_id (int) – Id of signal to block.

Returns:

A context manager which optionally can be used to automatically unblock the handler:

with GObject.signal_handler_block(obj, id):
    pass

signal_handler_disconnect(instance: Object, handler_id: int) → None

Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler_id becomes invalid and may be reused.

The handler_id has to be a valid signal handler id, connected to a signal of instance.

Parameters:

instance – The instance to remove the signal handler from.
handler_id – Handler id of the handler to be disconnected.

signal_handler_find(instance: Object, mask: SignalMatchType, signal_id: int, detail: int, closure: Callable[[...], Any] | None, func: None, data: None) → int

Finds the first signal handler that matches certain selection criteria. The criteria mask is passed as an OR-ed combination of SignalMatchType flags, and the criteria values are passed as arguments. The match mask has to be non-0 for successful matches. If no handler was found, 0 is returned.

Parameters:

instance – The instance owning the signal handler to be found.
mask – Mask indicating which of signal_id, detail, closure, func and/or data the handler has to match.
signal_id – Signal the handler has to be connected to.
detail – Signal detail the handler has to be connected to.
closure – The closure the handler will invoke.
func – The C closure callback of the handler (useless for non-C closures).
data – The closure data of the handler’s closure.

Returns:

A valid non-0 signal handler id for a successful match.

signal_handler_is_connected(instance: Object, handler_id: int) → bool

Returns whether handler_id is the ID of a handler connected to instance.

Parameters:

instance – The instance where a signal handler is sought.
handler_id – the handler ID.

Returns:

whether handler_id identifies a handler connected to instance.

signal_handler_unblock(instance: Object, handler_id: int) → None

Undoes the effect of a previous signal_handler_block() call. A blocked handler is skipped during signal emissions and will not be invoked, unblocking it (for exactly the amount of times it has been blocked before) reverts its “blocked” state, so the handler will be recognized by the signal system and is called upon future or currently ongoing signal emissions (since the order in which handlers are called during signal emissions is deterministic, whether the unblocked handler in question is called as part of a currently ongoing emission depends on how far that emission has proceeded yet).

The handler_id has to be a valid id of a signal handler that is connected to a signal of instance and is currently blocked.

Parameters:

instance – The instance to unblock the signal handler of.
handler_id – Handler id of the handler to be unblocked.

signal_handlers_block_matched(instance: Object, mask: SignalMatchType, signal_id: int, detail: int, closure: Callable[[...], Any] | None, func: None, data: None) → int

Blocks all handlers on an instance that match a certain selection criteria.

The criteria mask is passed as a combination of SignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all flags set in mask to be blocked (i.e. the match is conjunctive).

Passing at least one of the ID, CLOSURE, FUNC or DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of blocked handlers otherwise.

Support for ID was added in GLib 2.78.

Parameters:

instance – The instance to block handlers from.
mask – Mask indicating which of signal_id, detail, closure, func and/or data the handlers have to match.
signal_id – Signal the handlers have to be connected to.
detail – Signal detail the handlers have to be connected to.
closure – The closure the handlers will invoke.
func – The C closure callback of the handlers (useless for non-C closures).
data – The closure data of the handlers’ closures.

Returns:

The number of handlers that matched.

signal_handlers_destroy(instance: Object) → None

Destroy all signal handlers of a type instance. This function is an implementation detail of the Object dispose implementation, and should not be used outside of the type system.

Parameters:: instance – The instance whose signal handlers are destroyed

signal_handlers_disconnect_matched(instance: Object, mask: SignalMatchType, signal_id: int, detail: int, closure: Callable[[...], Any] | None, func: None, data: None) → int

Disconnects all handlers on an instance that match a certain selection criteria.

The criteria mask is passed as a combination of SignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all flags set in mask to be disconnected (i.e. the match is conjunctive).

Passing at least one of the ID, CLOSURE, FUNC or DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of disconnected handlers otherwise.

Support for ID was added in GLib 2.78.

Parameters:

instance – The instance to remove handlers from.
mask – Mask indicating which of signal_id, detail, closure, func and/or data the handlers have to match.
signal_id – Signal the handlers have to be connected to.
detail – Signal detail the handlers have to be connected to.
closure – The closure the handlers will invoke.
func – The C closure callback of the handlers (useless for non-C closures).
data – The closure data of the handlers’ closures.

Returns:

The number of handlers that matched.

signal_handlers_unblock_matched(instance: Object, mask: SignalMatchType, signal_id: int, detail: int, closure: Callable[[...], Any] | None, func: None, data: None) → int

Unblocks all handlers on an instance that match a certain selection criteria.

The criteria mask is passed as a combination of SignalMatchType flags, and the criteria values are passed as arguments. A handler must match on all flags set in mask to be unblocked (i.e. the match is conjunctive).

Passing at least one of the ID, CLOSURE, FUNC or DATA match flags is required for successful matches. If no handlers were found, 0 is returned, the number of unblocked handlers otherwise. The match criteria should not apply to any handlers that are not currently blocked.

Support for ID was added in GLib 2.78.

Parameters:

instance – The instance to unblock handlers from.
mask – Mask indicating which of signal_id, detail, closure, func and/or data the handlers have to match.
signal_id – Signal the handlers have to be connected to.
detail – Signal detail the handlers have to be connected to.
closure – The closure the handlers will invoke.
func – The C closure callback of the handlers (useless for non-C closures).
data – The closure data of the handlers’ closures.

Returns:

The number of handlers that matched.

signal_has_handler_pending(instance: Object, signal_id: int, detail: int, may_be_blocked: bool) → bool

Returns whether there are any handlers connected to instance for the given signal id and detail.

If detail is 0 then it will only match handlers that were connected without detail. If detail is non-zero then it will match handlers connected both without detail and with the given detail. This is consistent with how a signal emitted with detail would be delivered to those handlers.

Since 2.46 this also checks for a non-default class closure being installed, as this is basically always what you want.

One example of when you might use this is when the arguments to the signal are difficult to compute. A class implementor may opt to not emit the signal if no one is attached anyway, thus saving the cost of building the arguments.

Parameters:

instance – the object whose signal handlers are sought.
signal_id – the signal id.
detail – the detail.
may_be_blocked – whether blocked handlers should count as match.

Returns:

True if a handler is connected to the signal, False otherwise.

signal_is_valid_name(name: str) → bool

Validate a signal name. This can be useful for dynamically-generated signals which need to be validated at run-time before actually trying to create them.

See [canonical parameter names][canonical-parameter-names] for details of the rules for valid names. The rules for signal names are the same as those for property names.

Added in version 2.66.

Parameters:: name – the canonical name of the signal
Returns:: True if name is a valid signal name, False otherwise.

signal_list_ids(type_)

Lists the signals by id that a certain instance or interface type created. Further information about the signals can be acquired through signal_query().

Parameters:: type
Returns:: Newly allocated array of signal IDs.

signal_list_names(type_)

Parameters:: type

signal_lookup(name, type_)

Given the name of the signal and the type of object it connects to, gets the signal’s identifying integer. Emitting the signal by number is somewhat faster than using the name each time.

Also tries the ancestors of the given type.

The type class passed as itype must already have been instantiated (for example, using ref()) for this function to work, as signals are always installed during class initialization.

See signal_new() for details on allowed signal names.

Parameters:

name – the signal’s name.
type

Returns:

the signal’s identifying number, or 0 if no signal was found.

signal_name(signal_id: int) → str | None

Given the signal’s identifier, finds its name.

Two different signals may have the same name, if they have differing types.

Parameters:: signal_id – the signal’s identifying number.
Returns:: the signal name, or None if the signal number was invalid.

signal_new(signal_name: str, itype: type[Object], signal_flags: SignalFlags, return_type: type, param_types: Sequence[GType]) → int

Creates a new signal. (This is usually done in the class initializer.)

A signal name consists of segments consisting of ASCII letters and digits, separated by either the - or _ character. The first character of a signal name must be a letter. Names which violate these rules lead to undefined behaviour. These are the same rules as for property naming (see internal()).

When registering a signal and looking up a signal, either separator can be used, but they cannot be mixed. Using - is considerably more efficient. Using _ is discouraged.

If 0 is used for class_offset subclasses cannot override the class handler in their class_init method by doing super_class->signal_handler = my_signal_handler. Instead they will have to use signal_override_class_handler().

If c_marshaller is None, marshal_generic() will be used as the marshaller for this signal. In some simple cases, signal_new() will use a more optimized c_marshaller and va_marshaller for the signal instead of marshal_generic().

If c_marshaller is non-None, you need to also specify a va_marshaller using signal_set_va_marshaller() or the generic va_marshaller will be used.

Parameters:

signal_name – the name for the signal
itype – the type this signal pertains to. It will also pertain to types which are derived from this type.
signal_flags – a combination of SignalFlags specifying detail of when the default handler is to be invoked. You should at least specify RUN_FIRST or RUN_LAST.
return_type – the type of return value, or ``%G_TYPE_NONE`` for a signal without a return value.
param_types

Returns:

the signal id

signal_newv(signal_name: str, itype: type, signal_flags: SignalFlags, class_closure: Callable[[...], Any] | None, accumulator: Callable[[...], bool] | None, c_marshaller: Callable[[Callable[[...], Any], Any | None, Sequence[Any], None, None], None] | None, return_type: type, param_types: Sequence[type] | None = None, *accu_data: Any) → int

Creates a new signal. (This is usually done in the class initializer.)

See signal_new() for details on allowed signal names.

If c_marshaller is None, marshal_generic() will be used as the marshaller for this signal.

Parameters:

signal_name – the name for the signal
itype – the type this signal pertains to. It will also pertain to types which are derived from this type
signal_flags – a combination of SignalFlags specifying detail of when the default handler is to be invoked. You should at least specify RUN_FIRST or RUN_LAST
class_closure – The closure to invoke on signal emission; may be None
accumulator – the accumulator for this signal; may be None
c_marshaller – the function to translate arrays of parameter values to signal emissions into C language callback invocations or None
return_type – the type of return value, or ``%G_TYPE_NONE`` for a signal without a return value
param_types – an array of types, one for each parameter (may be None if n_params is zero)
accu_data – user data for the accumulator

Returns:

the signal id

signal_override_class_closure(signal_id: int, instance_type: type, class_closure: Callable[[...], Any]) → None

Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of instance_type. instance_type must be derived from the type to which the signal belongs.

See signal_chain_from_overridden() and signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one.

Parameters:

signal_id – the signal id
instance_type – the instance type on which to override the class closure for the signal.
class_closure – the closure.

signal_override_class_handler(signal_name: str, instance_type: type, class_handler: Callable[[], None]) → None

Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of instance_type with callback class_handler. instance_type must be derived from the type to which the signal belongs.

See signal_chain_from_overridden() and signal_chain_from_overridden_handler() for how to chain up to the parent class closure from inside the overridden one.

Added in version 2.18.

Parameters:

signal_name – the name for the signal
instance_type – the instance type on which to override the class handler for the signal.
class_handler – the handler.

signal_parse_name(detailed_signal, itype, force_detail_quark)

Parse a detailed signal name into (signal_id, detail).

Parameters:: detailed_signal (str) – Signal name which can include detail. For example: “notify:prop_name”
Returns:: Tuple of (signal_id, detail)
Raises:: ValueError – If the given signal is unknown.

signal_query(id_or_name, type_=None)

Queries the signal system for in-depth information about a specific signal. This function will fill in a user-provided structure to hold signal-specific information. If an invalid signal id is passed in, the signal_id member of the SignalQuery is 0. All members filled into the SignalQuery structure should be considered constant and have to be left untouched.

Parameters:

id_or_name
type

signal_remove_emission_hook(signal_id: int, hook_id: int) → None

Deletes an emission hook.

Parameters:

signal_id – the id of the signal
hook_id – the id of the emission hook, as returned by signal_add_emission_hook()

signal_set_va_marshaller(signal_id: int, instance_type: type, va_marshaller: VaClosureMarshal) → None

Change the SignalCVaMarshaller used for a given signal. This is a specialised form of the marshaller that can often be used for the common case of a single connected signal handler and avoids the overhead of Value. Its use is optional.

Added in version 2.32.

Parameters:

signal_id – the signal id
instance_type – the instance type on which to set the marshaller.
va_marshaller – the marshaller to set.

signal_stop_emission(instance: Object, signal_id: int, detail: int) → None

Stops a signal’s current emission.

This will prevent the default method from running, if the signal was RUN_LAST and you connected normally (i.e. without the “after” flag).

Prints a warning if used on a signal which isn’t being emitted.

Parameters:

instance – the object whose signal handlers you wish to stop.
signal_id – the signal identifier, as returned by signal_lookup().
detail – the detail which the signal was emitted with.

signal_stop_emission_by_name(instance: Object, detailed_signal: str) → None

Stops a signal’s current emission.

This is just like signal_stop_emission() except it will look up the signal id for you.

Parameters:

instance – the object whose signal handlers you wish to stop.
detailed_signal – a string of the form “signal-name::detail”.

signal_type_cclosure_new(itype: type, struct_offset: int) → Callable[[...], Any]

Creates a new closure which invokes the function found at the offset struct_offset in the class structure of the interface or classed type identified by itype.

Parameters:

itype – the Type identifier of an interface or classed type
struct_offset – the offset of the member function of itype’s class structure which is to be invoked by the new closure

Returns:

a floating reference to a new GCClosure

source_remove(tag: int) → bool

Deprecated since version PyGObject-3.16.0: GObject.source_remove is deprecated; use GLib.source_remove instead

Parameters:: tag

source_set_closure(source: Source, closure: Callable[[...], Any]) → None

Set the callback for a source as a Closure.

If the source is not one of the standard GLib types, the closure_callback and closure_marshal fields of the SourceFuncs structure must have been filled in with pointers to appropriate functions.

Parameters:

source – the source
closure – a Closure

source_set_dummy_callback(source: Source) → None

Sets a dummy callback for source. The callback will do nothing, and if the source expects a gboolean return value, it will return True. (If the source expects any other type of return value, it will return a 0/None value; whatever init() initializes a Value to for that type.)

Parameters:: source – the source

spawn_async(argv: ~typing.Sequence[str], envp: ~typing.Sequence[str] | None = None, working_directory: str | None = None, flags: ~gi.repository.GLib.SpawnFlags = <flags 0 of type GLib.SpawnFlags>, child_setup: ~typing.Callable[[~typing.Any], None] | None = None, user_data: ~typing.Any = None, standard_input: bool = False, standard_output: bool = False, standard_error: bool = False) → tuple[Pid, int | None, int | None, int | None]

spawn_async(argv, envp=None, working_directory=None,: flags=0, child_setup=None, user_data=None, standard_input=None, standard_output=None, standard_error=None) -> (pid, stdin, stdout, stderr)

Execute a child program asynchronously within a glib.MainLoop() See the reference manual for a complete reference.

Deprecated since version PyGObject-3.16.0: GObject.spawn_async is deprecated; use GLib.spawn_async instead

Parameters:

argv
envp
working_directory
flags
child_setup
user_data
standard_input
standard_output
standard_error

strdup_value_contents(value: Any) → str

Return a newly allocated string, which describes the contents of a Value. The main purpose of this function is to describe Value contents for debugging output, the way in which the contents are described may change between different GLib versions.

Parameters:: value – Value which contents are to be described.
Returns:: Newly allocated string.

threads_init()

timeout_add(interval, function, *user_data, **kwargs)

Deprecated since version PyGObject-3.16.0: GObject.timeout_add is deprecated; use GLib.timeout_add instead

Parameters:

interval
function
user_data
kwargs

timeout_add_seconds(interval, function, *user_data, **kwargs)

Deprecated since version PyGObject-3.16.0: GObject.timeout_add_seconds is deprecated; use GLib.timeout_add_seconds instead

Parameters:

interval
function
user_data
kwargs

type_add_class_private(class_type: type, private_size: int) → None

Registers a private class structure for a classed type; when the class is allocated, the private structures for the class and all of its parent types are allocated sequentially in the same memory block as the public structures, and are zero-filled.

This function should be called in the type’s get_type() function after the type is registered. The private structure can be retrieved using the TYPE_CLASS_GET_PRIVATE() macro.

Added in version 2.24.

Parameters:

class_type – GType of a classed type
private_size – size of private structure

type_add_instance_private(class_type: type, private_size: int) → int

Parameters:

class_type
private_size

type_add_interface_dynamic(instance_type: type, interface_type: type, plugin: TypePlugin) → None

Adds interface_type to the dynamic instance_type. The information contained in the TypePlugin structure pointed to by plugin is used to manage the relationship.

Parameters:

instance_type – Type value of an instantiatable type
interface_type – Type value of an interface type
plugin – TypePlugin structure to retrieve the InterfaceInfo from

type_add_interface_static(instance_type: type, interface_type: type, info: InterfaceInfo) → None

Adds interface_type to the static instance_type. The information contained in the InterfaceInfo structure pointed to by info is used to manage the relationship.

Parameters:

instance_type – Type value of an instantiatable type
interface_type – Type value of an interface type
info – InterfaceInfo structure for this (instance_type, interface_type) combination

type_check_class_is_a(g_class: TypeClass, is_a_type: type) → bool

Parameters:

g_class
is_a_type

type_check_instance(instance: TypeInstance) → bool

Private helper function to aid implementation of the TYPE_CHECK_INSTANCE() macro.

Parameters:: instance – a valid TypeInstance structure
Returns:: True if instance is valid, False otherwise

type_check_instance_is_a(instance: TypeInstance, iface_type: type) → bool

Parameters:

instance
iface_type

type_check_instance_is_fundamentally_a(instance: TypeInstance, fundamental_type: type) → bool

Parameters:

instance
fundamental_type

type_check_is_value_type(type: type) → bool

Parameters:: type

type_check_value(value: Any) → bool

Parameters:: value

type_check_value_holds(value: Any, type: type) → bool

Parameters:

value
type

type_children(type: type) → list[type]

Return a newly allocated and 0-terminated array of type IDs, listing the child types of type.

Parameters:: type – the parent type
Returns:: Newly allocated and 0-terminated array of child types, free with free()

type_class_adjust_private_offset(g_class: None, private_size_or_offset: int) → None

Parameters:

g_class
private_size_or_offset

type_class_peek(type: type) → TypeClass

Parameters:: type

type_class_peek_static(type: type) → TypeClass

Parameters:: type

type_default_interface_peek(g_type: type) → TypeInterface

If the interface type g_type is currently in use, returns its default interface vtable.

Added in version 2.4.

Parameters:: g_type – an interface type
Returns:: the default vtable for the interface, or None if the type is not currently in use

type_depth(type: type) → int

Returns the length of the ancestry of the passed in type. This includes the type itself, so that e.g. a fundamental type has depth 1.

Parameters:: type – a Type
Returns:: the depth of type

type_ensure(type: type) → None

Ensures that the indicated type has been registered with the type system, and its _class_init() method has been run.

In theory, simply calling the type’s _get_type() method (or using the corresponding macro) is supposed take care of this. However, _get_type() methods are often marked %G_GNUC_CONST for performance reasons, even though this is technically incorrect (since %G_GNUC_CONST requires that the function not have side effects, which _get_type() methods do on the first call). As a result, if you write a bare call to a _get_type() macro, it may get optimized out by the compiler. Using type_ensure() guarantees that the type’s _get_type() method is called.

Added in version 2.34.

Parameters:: type – a Type

type_free_instance(instance: TypeInstance) → None

Frees an instance of a type, returning it to the instance pool for the type, if there is one.

Like type_create_instance(), this function is reserved for implementors of fundamental types.

Parameters:: instance – an instance of a type

type_from_name(name)

Look up the type ID from a given type name, returning 0 if no type has been registered under this name (this is the preferred method to find out by name whether a specific type has been registered yet).

Parameters:: name – type name to look up
Returns:: corresponding type ID or 0

type_fundamental(type_id: type) → type

Internal function, used to extract the fundamental type ID portion. Use TYPE_FUNDAMENTAL() instead.

Parameters:: type_id – valid type ID
Returns:: fundamental type ID

type_fundamental_next() → type

Returns the next free fundamental type id which can be used to register a new fundamental type with type_register_fundamental(). The returned type ID represents the highest currently registered fundamental type identifier.

Returns:: the next available fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs

type_get_instance_count(type: type) → int

Returns the number of instances allocated of the particular type; this is only available if GLib is built with debugging support and the instance-count debug flag is set (by setting the GOBJECT_DEBUG variable to include instance-count).

Added in version 2.44.

Parameters:: type – a Type
Returns:: the number of instances allocated of the given type; if instance counts are not available, returns 0.

type_get_plugin(type: type) → TypePlugin

Returns the TypePlugin structure for type.

Parameters:: type – Type to retrieve the plugin for
Returns:: the corresponding plugin if type is a dynamic type, None otherwise

type_get_qdata(type: type, quark: int) → None

Obtains data which has previously been attached to type with type_set_qdata().

Note that this does not take subtyping into account; data attached to one type with type_set_qdata() cannot be retrieved from a subtype using type_get_qdata().

Parameters:

type – a Type
quark – a Quark id to identify the data

Returns:

the data, or None if no data was found

type_get_type_registration_serial() → int

Returns an opaque serial number that represents the state of the set of registered types. Any time a type is registered this serial changes, which means you can cache information based on type lookups (such as type_from_name()) and know if the cache is still valid at a later time by comparing the current serial with the one at the type lookup.

Added in version 2.36.

Returns:: An unsigned int, representing the state of type registrations

type_init() → None: This function used to initialise the type system. Since GLib 2.36, the type system is initialised automatically and this function does nothing.

Deprecated since version 2.36: the type system is now initialised automatically

type_init_with_debug_flags(debug_flags: TypeDebugFlags) → None

This function used to initialise the type system with debugging flags. Since GLib 2.36, the type system is initialised automatically and this function does nothing.

If you need to enable debugging features, use the GOBJECT_DEBUG environment variable.

Deprecated since version 2.36: the type system is now initialised automatically

Parameters:: debug_flags – bitwise combination of TypeDebugFlags values for debugging purposes

type_interface_add_prerequisite(interface_type: type, prerequisite_type: type) → None

Parameters:

interface_type
prerequisite_type

type_interface_get_plugin(instance_type: type, interface_type: type) → TypePlugin

Parameters:

instance_type
interface_type

type_interface_instantiatable_prerequisite(interface_type: type) → type

Parameters:: interface_type

type_interface_peek(instance_class: TypeClass, iface_type: type) → TypeInterface

Parameters:

instance_class
iface_type

type_interface_prerequisites(interface_type: type) → list[type]

Parameters:: interface_type

type_interfaces(type: type) → list[type]

Return a newly allocated and 0-terminated array of type IDs, listing the interface types that type conforms to.

Parameters:: type – the type to list interface types for
Returns:: Newly allocated and 0-terminated array of interface types, free with free()

type_is_a(type: type, is_a_type: type) → bool

If is_a_type is a derivable type, check whether type is a descendant of is_a_type. If is_a_type is an interface, check whether type conforms to it.

Parameters:

type – type to check ancestry for
is_a_type – possible ancestor of type or interface that type could conform to

Returns:

True if type is a is_a_type

type_name(type: type) → str | None

Get the unique name that is assigned to a type ID. Note that this function (like all other GType API) cannot cope with invalid type IDs. Invalid may be passed to this function, as may be any other validly registered type ID, but randomized type IDs should not be passed in and will most likely lead to a crash.

Parameters:: type – type to return name for
Returns:: static type name or None

type_name_from_class(g_class: TypeClass) → str

Parameters:: g_class

type_name_from_instance(instance: TypeInstance) → str

Parameters:: instance

type_next_base(leaf_type: type, root_type: type) → type

Given a leaf_type and a root_type which is contained in its ancestry, return the type that root_type is the immediate parent of. In other words, this function determines the type that is derived directly from root_type which is also a base class of leaf_type. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type.

Parameters:

leaf_type – descendant of root_type and the type to be returned
root_type – immediate parent of the returned type

Returns:

immediate child of root_type and ancestor of leaf_type

type_parent(type_)

Return the direct parent type of the passed in type. If the passed in type has no parent, i.e. is a fundamental type, 0 is returned.

Parameters:: type
Returns:: the parent type

type_qname(type: type) → int

Get the corresponding quark of the type IDs name.

Parameters:: type – type to return quark of type name for
Returns:: the type names quark or 0

type_query(type: type) → TypeQuery

Queries the type system for information about a specific type.

This function will fill in a user-provided structure to hold type-specific information. If an invalid Type is passed in, the type member of the TypeQuery is 0. All members filled into the TypeQuery structure should be considered constant and have to be left untouched.

Since GLib 2.78, this function allows queries on dynamic types. Previously it only supported static types.

Parameters:: type – Type of a static, classed type

type_register(type) → GType

Parameters:: type

type_register_dynamic(parent_type: type, type_name: str, plugin: TypePlugin, flags: TypeFlags) → type

Registers type_name as the name of a new dynamic type derived from parent_type. The type system uses the information contained in the TypePlugin structure pointed to by plugin to manage the type and its instances (if not abstract). The value of flags determines the nature (e.g. abstract or not) of the type.

Parameters:

parent_type – type from which this type will be derived
type_name – 0-terminated string used as the name of the new type
plugin – TypePlugin structure to retrieve the TypeInfo from
flags – bitwise combination of TypeFlags values

Returns:

the new type identifier or Invalid if registration failed

type_register_fundamental(type_id: type, type_name: str, info: TypeInfo, finfo: TypeFundamentalInfo, flags: TypeFlags) → type

Registers type_id as the predefined identifier and type_name as the name of a fundamental type. If type_id is already registered, or a type named type_name is already registered, the behaviour is undefined. The type system uses the information contained in the TypeInfo structure pointed to by info and the TypeFundamentalInfo structure pointed to by finfo to manage the type and its instances. The value of flags determines additional characteristics of the fundamental type.

Parameters:

type_id – a predefined type identifier
type_name – 0-terminated string used as the name of the new type
info – TypeInfo structure for this type
finfo – TypeFundamentalInfo structure for this type
flags – bitwise combination of TypeFlags values

Returns:

the predefined type identifier

type_register_static(parent_type: type, type_name: str, info: TypeInfo, flags: TypeFlags) → type

Registers type_name as the name of a new static type derived from parent_type. The type system uses the information contained in the TypeInfo structure pointed to by info to manage the type and its instances (if not abstract). The value of flags determines the nature (e.g. abstract or not) of the type.

Parameters:

parent_type – type from which this type will be derived
type_name – 0-terminated string used as the name of the new type
info – TypeInfo structure for this type
flags – bitwise combination of TypeFlags values

Returns:

the new type identifier

type_set_qdata(type: type, quark: int, data: None) → None

Attaches arbitrary data to a type.

Parameters:

type – a Type
quark – a Quark id to identify the data
data – the data

type_test_flags(type: type, flags: int) → bool

Parameters:

type
flags

uri_list_extract_uris(uri_list: str) → list[str]

Deprecated since version PyGObject-3.16.0: GObject.uri_list_extract_uris is deprecated; use GLib.uri_list_extract_uris instead

Parameters:: uri_list

value_type_compatible(src_type: type, dest_type: type) → bool

Parameters:

src_type
dest_type

value_type_transformable(src_type: type, dest_type: type) → bool

Parameters:

src_type
dest_type

variant_get_gtype() → type