:right-sidebar: True Object =================================================================== .. currentmodule:: gi.repository.GObject .. class:: Object(**properties: ~typing.Any) :no-contents-entry: Subclasses: :class:`~gi.repository.GObject.Binding`, :class:`~gi.repository.GObject.BindingGroup`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.SignalGroup`, :class:`~gi.repository.GObject.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](tutorial.html#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 ``GObject``'s 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 ``:func:`~gi.repository.GObject.ADD_PRIVATE```. Methods ------- .. rst-class:: interim-class .. class:: Object :no-index: .. method:: bind_property(source_property: str, target: ~gi.repository.GObject.Object, target_property: str, flags: ~gi.repository.GObject.BindingFlags | None = 0, transform_to: ~typing.Callable[[~gi.repository.GObject.Binding, ~typing.Any, ~typing.Any], ~typing.Any] | None = None, transform_from: ~typing.Callable[[~gi.repository.GObject.Binding, ~typing.Any, ~typing.Any], ~typing.Any] | None = None, user_data: ~typing.Any = None) -> ~gi.repository.GObject.Binding Creates a binding between a property on the source object and a property on the target object. :param source_prop: The property name on the source object :param target: The target object :param target_prop: The property name on the target :param flags: Optional flags to pass to the binding. Defaults to :ref:`GObject.BindingFlags.DEFAULT` :param 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. :param 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. :param user_data: Optional user data, provided as third argument to the transformation functions. :returns: A new :obj:`~gi.repository.GObject.Binding` object, representing the binding. .. versionadded:: 2.26 .. method:: chain(*params) -> object | None Calls the original class closure of a signal. This function should only be called from an overridden class closure. :param params: The argument list of the signal emission. :returns: Return value of the signal handler. .. method:: connect(detailed_signal: str, handler: ~typing.Callable[[~gi.repository.GObject.Object, ...], ~typing.Any], *args: ~typing.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: .. code:: python handler_id = object.connect("signal_name", handler, arg1, arg2, arg3) The handler should be defined as: .. code:: python def handler(object, arg1, arg2, arg3): A method handler connected to a signal using: .. code:: python handler_id = object.connect("signal_name", self.handler, arg1, arg2) requires an additional argument when defined: .. code:: python def handler(self, object, arg1, arg2) A :ref:`TypeError` exception is raised if ``detailed_signal`` identifies a signal name that is not associated with the object. :param detailed_signal: A signal name. :param handler: Callback to invoke if the signal is emitted. The callback signature needs to match the signature of the signal. :param args: Additional arguments to pass to the callback. .. method:: connect_after(detailed_signal: str, handler: ~typing.Callable[[~gi.repository.GObject.Object, ...], ~typing.Any], *args: ~typing.Any) -> int The ``connect_after()`` method is similar to the :meth:`~gi.repository.GObject.Object.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. :param detailed_signal: A signal name. :param handler: Callback to invoke if the signal is emitted. The callback signature needs to match the signature of the signal. :param args: Additional arguments to pass to the callback. .. method:: connect_data(detailed_signal, handler, *data, **kwargs) Connect a callback to the given signal with optional user data. :param str detailed_signal: A detailed signal to connect to. :param callable handler: Callback handler to connect to the signal. :param *data: Variable data which is passed through to the signal handler. :param GObject.ConnectFlags connect_flags: Flags used for connection options. :returns: A signal id which can be used with disconnect. .. method:: connect_object(detailed_signal: str, handler: ~typing.Callable[[~gi.repository.GObject.Object, ...], ~typing.Any], object: ~gi.repository.GObject.Object, *args: ~typing.Any) -> int The ``connect_after()`` method is similar to the :meth:`~gi.repository.GObject.Object.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. :param detailed_signal: :param handler: :param object: :param args: .. method:: connect_object_after(detailed_signal: str, handler: ~typing.Callable[[~gi.repository.GObject.Object, ~typing.Any], ~typing.Any], object: ~gi.repository.GObject.Object, *args: ~typing.Any) -> int The ``connect_object_after()`` method is similar to the :meth:`~gi.repository.GObject.Object.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. :param detailed_signal: :param handler: :param object: :param args: .. method:: disconnect(instance: ~gi.repository.GObject.Object, 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". :param instance: :param handler_id: .. method:: disconnect_by_func(func: ~typing.Callable[[~gi.repository.GObject.Object, ...], ~typing.Any]) -> None Disconnect a function (callable) from any signal. :param func: .. method:: emit(signal_name: str, *args) -> None :param signal_name: :param args: .. method:: emit_stop_by_name(detailed_signal) Deprecated, please use stop_emission_by_name. :param detailed_signal: .. classmethod:: find_property(*args, **kwargs) Find the :obj:`~gi.repository.GObject.ParamSpec` with the given name for an interface. Generally, the interface vtable passed in as ``g_iface`` will be the default vtable from :func:`~gi.repository.GObject.type_default_interface_ref`, or, if you know the interface has already been loaded, :func:`~gi.repository.GObject.type_default_interface_peek`. .. versionadded:: 2.4 :param args: :param kwargs: .. method:: 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. .. code-block:: python with obj.freeze_notify(): pass .. method:: get_properties(*prop_names: str) -> tuple[~typing.Any, ...] :param prop_names: .. method:: get_property(prop_name: str) -> ~typing.Any Gets a property of an object. The ``value`` can be: - an empty :obj:`~gi.repository.GObject.Value` initialized by ``%G_VALUE_INIT``, which will be automatically initialized with the expected type of the property (since GLib 2.60) - a :obj:`~gi.repository.GObject.Value` initialized with the expected type of the property - a :obj:`~gi.repository.GObject.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 :func:`~gi.repository.GObject.Value.unset`. Note that :func:`~gi.repository.GObject.Object.get_property` is really intended for language bindings, :func:`~gi.repository.GObject.Object.get` is much more convenient for C programming. :param prop_name: .. method:: getv(names: ~typing.Sequence[str], values: ~typing.Sequence[~typing.Any]) -> 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. .. versionadded:: 2.54 :param names: the names of each property to get :param values: the values of each property to get .. method:: handler_block(handler_id) Blocks the signal handler from being invoked until handler_unblock() is called. :param GObject.Object obj: Object instance to block handlers for. :param int handler_id: Id of signal to block. :returns: A context manager which optionally can be used to automatically unblock the handler: .. code-block:: python with GObject.signal_handler_block(obj, id): pass .. method:: handler_block_by_func(func: ~typing.Callable[[~gi.repository.GObject.Object, ...], ...]) -> int :param func: .. method:: handler_disconnect(instance: ~gi.repository.GObject.Object, handler_id: int) -> None :param instance: :param handler_id: .. method:: handler_is_connected(instance: ~gi.repository.GObject.Object, handler_id: int) -> bool :param instance: :param handler_id: .. method:: handler_unblock(instance: ~gi.repository.GObject.Object, handler_id: int) -> None :param instance: :param handler_id: .. method:: handler_unblock_by_func(func: ~typing.Callable[[~gi.repository.GObject.Object, ...], ...]) -> int :param func: .. classmethod:: install_properties(*args, **kwargs) :param args: :param kwargs: .. classmethod:: install_property(*args, **kwargs) 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 :obj:`~gi.repository.GObject.ParamSpec`, but normally :func:`~gi.repository.GObject.ObjectClass.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 :obj:`~gi.repository.GObject.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. .. versionadded:: 2.4 :param args: :param kwargs: .. method:: is_floating() -> bool Checks whether ``object`` has a [floating][floating-ref] reference. .. versionadded:: 2.10 .. classmethod:: list_properties(*args, **kwargs) Lists the properties of an interface.Generally, the interface vtable passed in as ``g_iface`` will be the default vtable from :func:`~gi.repository.GObject.type_default_interface_ref`, or, if you know the interface has already been loaded, :func:`~gi.repository.GObject.type_default_interface_peek`. .. versionadded:: 2.4 :param args: :param kwargs: .. method:: 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 :func:`~gi.repository.GObject.Object.notify_by_pspec` instead. Note that emission of the notify signal may be blocked with :func:`~gi.repository.GObject.Object.freeze_notify`. In this case, the signal emissions are queued and will be emitted (in reverse order) when :func:`~gi.repository.GObject.Object.thaw_notify` is called. :param property_name: the name of a property installed on the class of ``object``. .. classmethod:: override_property(*args, **kwargs) :param args: :param kwargs: .. method:: 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. .. method:: set_properties(**props) -> None :param props: .. method:: set_property(prop_name: str, prop_value: ~typing.Any) -> None Sets a property on an object. :param prop_name: :param prop_value: .. method:: stop_emission(detailed_signal) Deprecated, please use stop_emission_by_name. :param detailed_signal: .. method:: stop_emission_by_name(instance: ~gi.repository.GObject.Object, detailed_signal: str) -> None :param instance: :param detailed_signal: .. method:: thaw_notify() -> None Reverts the effect of a previous call to :func:`~gi.repository.GObject.Object.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 :obj:`~gi.repository.GObject.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 ------- .. rst-class:: interim-class .. class:: Object.signals :no-index: .. method:: notify(pspec: ~gi.repository.GObject.ParamSpec) -> None The notify signal is emitted on an object when one of its properties has its value set through :func:`~gi.repository.GObject.Object.set_property`, :func:`~gi.repository.GObject.Object.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 :const:`~gi.repository.GObject.ParamFlags.EXPLICIT_NOTIFY`, then any call to :func:`~gi.repository.GObject.Object.set_property` results in ::notify being emitted, even if the new value is the same as the old. If they did pass :const:`~gi.repository.GObject.ParamFlags.EXPLICIT_NOTIFY`, then this signal is emitted only when they explicitly call :func:`~gi.repository.GObject.Object.notify` or :func:`~gi.repository.GObject.Object.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 :func:`~gi.repository.GObject.signal_connect` call, like this: .. code-block:: C :dedent: 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:`~gi.repository.GObject.ParamSpec#parameter-names` as detail strings for the notify signal. :param pspec: the :obj:`~gi.repository.GObject.ParamSpec` of the property which changed. Virtual Methods --------------- .. rst-class:: interim-class .. class:: Object :no-index: .. method:: do_dispatch_properties_changed(n_pspecs: int, pspecs: ~gi.repository.GObject.ParamSpec) -> None The type of the None singleton. :param n_pspecs: :param pspecs: .. method:: do_dispose() -> None The type of the None singleton. .. method:: do_get_property(property_id: int, value: ~typing.Any, pspec: ~gi.repository.GObject.ParamSpec) -> None the generic getter for all properties of this type. Should be overridden for every type with properties. :param property_id: :param value: :param pspec: .. method:: do_notify(pspec: ~gi.repository.GObject.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 :func:`~gi.repository.GObject.Object.notify_by_pspec` instead. Note that emission of the notify signal may be blocked with :func:`~gi.repository.GObject.Object.freeze_notify`. In this case, the signal emissions are queued and will be emitted (in reverse order) when :func:`~gi.repository.GObject.Object.thaw_notify` is called. :param pspec: .. method:: do_set_property(property_id: int, value: ~typing.Any, pspec: ~gi.repository.GObject.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. :param property_id: :param value: :param pspec: Fields ------ .. rst-class:: interim-class .. class:: Object :no-index: .. attribute:: g_type_instance .. attribute:: qdata .. attribute:: ref_count