Object#

class Object(**properties: Any)#

Subclasses: Binding, BindingGroup, InitiallyUnowned, SignalGroup, TypeModule

The base object type.

GObject is the fundamental type providing the common attributes and methods for all object types in GTK, Pango and other libraries based on GObject. The GObject class provides methods for object construction and destruction, property access methods, and signal support. Signals are described in detail [here][gobject-Signals].

For a tutorial on implementing a new GObject class, see How to define and implement a new GObject. For a list of naming conventions for GObjects and their methods, see the GType conventions. For the high-level concepts behind GObject, read Instantiatable classed types: Objects.

Since GLib 2.72, all GObjects are guaranteed to be aligned to at least the alignment of the largest basic GLib type (typically this is guint64 or gdouble). If you need larger alignment for an element in a GObject, you should allocate it on the heap (aligned), or arrange for your GObject to be appropriately padded. This guarantee applies to the GObject (or derived) struct, the GObjectClass (or derived) struct, and any private data allocated by G_ADD_PRIVATE().

Methods#

class Object
bind_property(source_property: str, target: Object, target_property: str, flags: BindingFlags | None = 0, transform_to: Callable[[Binding, Any, Any], Any] | None = None, transform_from: Callable[[Binding, Any, Any], Any] | None = None, user_data: Any = None) → Binding#

Creates a binding between a property on the source object and a property on the target object.

Parameters:

  • source_prop – The property name on the source object

  • target – The target object

  • target_prop – The property name on the target

  • flags – Optional flags to pass to the binding. Defaults to GObject.BindingFlags.DEFAULT

  • transform_to – Optional transformation function from the source to the target. The second argument of the callable is the source value. The third argument is the user data. This function should return the value to be set on the target, with the right type.

  • transform_from – Optional transformation function from the target to the source The second argument of the callable is the target value. The third argument is the user data. This function should return the value to be set on the source, with the right type.

  • user_data – Optional user data, provided as third argument to the transformation functions.

Returns:

A new Binding object, representing the binding.

Added in version 2.26.

chain(*params) → object | None#

Calls the original class closure of a signal.

This function should only be called from an overridden class closure.

Parameters:

params – The argument list of the signal emission.

Returns:

Return value of the signal handler.

connect(detailed_signal: str, handler: Callable[[Object, ...], Any], *args: Any) → int#

The connect() method adds a function or method (handler) to the end of the list of signal handlers for the named detailed_signal but before the default class signal handler. An optional set of parameters may be specified after the handler parameter. These will all be passed to the signal handler when invoked.

For example if a function handler was connected to a signal using:

handler_id = object.connect("signal_name", handler, arg1, arg2, arg3)

The handler should be defined as:

def handler(object, arg1, arg2, arg3):

A method handler connected to a signal using:

handler_id = object.connect("signal_name", self.handler, arg1, arg2)

requires an additional argument when defined:

def handler(self, object, arg1, arg2)

A TypeError exception is raised if detailed_signal identifies a signal name that is not associated with the object.

Parameters:

  • detailed_signal – A signal name.

  • handler – Callback to invoke if the signal is emitted. The callback signature needs to match the signature of the signal.

  • args – Additional arguments to pass to the callback.

connect_after(detailed_signal: str, handler: Callable[[Object, ...], Any], *args: Any) → int#

The connect_after() method is similar to the connect() method except that the handler is added to the signal handler list after the default class signal handler. Otherwise the details of handler definition and invocation are the same.

Parameters:

  • detailed_signal – A signal name.

  • handler – Callback to invoke if the signal is emitted. The callback signature needs to match the signature of the signal.

  • args – Additional arguments to pass to the callback.

connect_data(detailed_signal, handler, *data, connect_flags=0)#

Connect a callback to the given signal with optional user data.

Parameters:

  • detailed_signal (str) – A detailed signal to connect to.

  • handler (callable) – Callback handler to connect to the signal.

  • *data –

    Variable data which is passed through to the signal handler.

  • connect_flags (GObject.ConnectFlags) – Flags used for connection options.

Returns:

A signal id which can be used with disconnect.

connect_object(detailed_signal: str, handler: Callable[[Object, ...], Any], object: Object, *args: Any) → int#

The connect_after() method is similar to the connect() method except that it takes an additional object as argument. The object is weakly referenced and the signal is automatically disconnected when the object is finalized.

Parameters:

  • detailed_signal

  • handler

  • object

  • args

connect_object_after(detailed_signal: str, handler: Callable[[Object, Any], Any], object: Object, *args: Any) → int#

The connect_object_after() method is similar to the connect_object() method except that the handler is added to the signal handler list after the default class signal handler. Otherwise the details of handler definition and invocation are the same.

Parameters:

  • detailed_signal

  • handler

  • object

  • args

disconnect(handler_id: int) → None#

A convenience function to disconnect multiple signals at once.

The signal specs expected by this function have the form “any_signal”, which means to disconnect any signal with matching callback and data, or “any_signal::signal_name”, which only disconnects the signal named “signal_name”.

Parameters:

handler_id

disconnect_by_func(func: Callable[[Object, ...], Any]) → None#

Disconnect a function (callable) from any signal.

Parameters:

func

do_dispose()#
emit(signal_name: str, *args) → None#
Parameters:

  • signal_name

  • args

emit_stop_by_name(detailed_signal)#

Deprecated, please use stop_emission_by_name.

Parameters:

detailed_signal

classmethod find_property(property_name: str) → ParamSpec#

Find the ParamSpec with the given name for an interface. Generally, the interface vtable passed in as g_iface will be the default vtable from type_default_interface_ref(), or, if you know the interface has already been loaded, type_default_interface_peek().

Added in version 2.4.

Parameters:

property_name – name of a property to look up.

freeze_notify()#

Freezes the object’s property-changed notification queue.

Returns:

A context manager which optionally can be used to automatically thaw notifications.

This will freeze the object so that “notify” signals are blocked until the thaw_notify() method is called.

with obj.freeze_notify():
    pass
get_properties(*prop_names: str) → tuple[Any, ...]#
Parameters:

prop_names

get_property(prop_name: str) → Any#

Gets a property of an object.

The value can be:

  • an empty Value initialized by %G_VALUE_INIT, which will be

    automatically initialized with the expected type of the property (since GLib 2.60)

  • a Value initialized with the expected type of the property

  • a Value initialized with a type to which the expected type

    of the property can be transformed

In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling unset().

Note that get_property() is really intended for language bindings, get() is much more convenient for C programming.

Parameters:

prop_name

getv(names: list[str], values: list[Value]) → None#

Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

Added in version 2.54.

Parameters:

  • names – the names of each property to get

  • values – the values of each property to get

handler_block(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
handler_block_by_func(func: Callable[[Object, ...], ...]) → int#
Parameters:

func

handler_disconnect(handler_id: int) → None#
Parameters:

handler_id

handler_is_connected(handler_id: int) → bool#
Parameters:

handler_id

handler_unblock(handler_id: int) → None#
Parameters:

handler_id

handler_unblock_by_func(func: Callable[[Object, ...], ...]) → int#
Parameters:

func

classmethod install_properties(pspecs: list[ParamSpec]) → None#
Parameters:

pspecs

classmethod install_property(property_id: int, pspec: ParamSpec) → None#

Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created ParamSpec, but normally override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.

This function is meant to be called from the interface’s default vtable initialization function (the class_init member of TypeInfo.) It must not be called after after class_init has been called for any object types implementing this interface.

If pspec is a floating reference, it will be consumed.

Added in version 2.4.

Parameters:

  • property_id

  • pspec – the ParamSpec for the new property

is_floating() → bool#

Checks whether object has a [floating][floating-ref] reference.

Added in version 2.10.

classmethod list_properties() → list[ParamSpec]#

Lists the properties of an interface.Generally, the interface vtable passed in as g_iface will be the default vtable from type_default_interface_ref(), or, if you know the interface has already been loaded, type_default_interface_peek().

Added in version 2.4.

notify(property_name: str) → None#

Emits a “notify” signal for the property property_name on object.

When possible, eg. when signaling a property change from within the class that registered the property, you should use notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when thaw_notify() is called.

Parameters:

property_name – the name of a property installed on the class of object.

classmethod override_property(property_id: int, name: str) → None#
Parameters:

  • property_id

  • name

run_dispose() → None#

Releases all references to other objects. This can be used to break reference cycles.

This function should only be called from object system implementations.

set_properties(**props) → None#
Parameters:

props

set_property(prop_name: str, prop_value: Any) → None#

Sets a property on an object.

Parameters:

  • prop_name

  • prop_value

stop_emission(detailed_signal)#

Deprecated, please use stop_emission_by_name.

Parameters:

detailed_signal

stop_emission_by_name(detailed_signal: str) → None#
Parameters:

detailed_signal

thaw_notify() → None#

Reverts the effect of a previous call to freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued “notify” signals are emitted.

Duplicate notifications for each property are squashed so that at most one Object::notify signal is emitted for each property, in the reverse order in which they have been queued.

It is an error to call this function when the freeze count is zero.

Signals#

class Object.signals
notify(pspec: ParamSpec) → None#

The notify signal is emitted on an object when one of its properties has its value set through set_property(), set(), et al.

Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with EXPLICIT_NOTIFY, then any call to set_property() results in ::notify being emitted, even if the new value is the same as the old. If they did pass EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call notify() or notify_by_pspec(), and common practice is to do that only when the value has actually changed.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the signal_connect() call, like this:

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use [canonical parameter names]:obj:ParamSpec#parameter-names as detail strings for the notify signal.

Parameters:

pspec – the ParamSpec of the property which changed.

Virtual Methods#

class Object
do_dispatch_properties_changed(n_pspecs: int, pspecs: ParamSpec) → None#

The type of the None singleton.

Parameters:

  • n_pspecs

  • pspecs

do_dispose() → None#

The type of the None singleton.

do_get_property(property_id: int, value: Value, pspec: ParamSpec) → None#
the generic getter for all properties of this type. Should be

overridden for every type with properties.

Parameters:

  • property_id

  • value

  • pspec

do_notify(pspec: ParamSpec) → None#

Emits a “notify” signal for the property property_name on object.

When possible, eg. when signaling a property change from within the class that registered the property, you should use notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when thaw_notify() is called.

Parameters:

pspec

do_set_property(property_id: int, value: Value, pspec: ParamSpec) → None#
the generic setter for all properties of this type. Should be

overridden for every type with properties. If implementations of set_property don’t emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

Parameters:

  • property_id

  • value

  • pspec

Fields#

class Object
g_type_instance#
qdata#
ref_count#