GObject.Object¶

Subclasses:	`GObject.Binding`, `GObject.InitiallyUnowned`, `GObject.TypeModule`

Methods¶

Structs:	GObject.ObjectClass (5)

class	`compat_control` (what, data)
class	`find_property` (property_name)
class	`install_properties` (pspecs)
class	`install_property` (property_id, pspec)
class	`interface_find_property` (g_iface, property_name)
class	`interface_install_property` (g_iface, pspec)
class	`interface_list_properties` (g_iface)
class	`list_properties` ()
class	`newv` (object_type, parameters)
class	`override_property` (property_id, name)
	`bind_property` (source_property, target, target_property, flags)
	`bind_property_full` (source_property, target, target_property, flags, transform_to, transform_from)
	`connect` (detailed_signal: str, handler: function, *args) -> handler_id: int
	`connect_after` (detailed_signal: str, handler: function, *args) -> handler_id: int
	`disconnect` (id_)
	`emit` (signal_name: str, *args) -> None
	`force_floating` ()
	`freeze_notify` () -> None
	`get_data` (key)
	`get_property` (property_name: str) -> object
	`get_qdata` (quark)
	`getv` (names, values)
	`handler_block` (handler_id: int) -> None
	`handler_unblock` (handler_id)
	`is_floating` ()
	`notify` (property_name)
	`notify_by_pspec` (pspec)
	`ref` ()
	`ref_sink` ()
	`run_dispose` ()
	`set_data` (key, data)
	`set_property` (property_name: str, value: object)
	`steal_data` (key)
	`steal_qdata` (quark)
	`thaw_notify` () -> None
	`unref` ()
	`watch_closure` (closure)

Virtual Methods¶

	`do_constructed` ()
	`do_dispatch_properties_changed` (n_pspecs, pspecs)
	`do_dispose` ()
	`do_finalize` ()
	`do_get_property` (property_id, value, pspec)
	`do_notify` (pspec)
	`do_set_property` (property_id, value, pspec)

Properties¶

None

Signals¶

Name	Short Description
`notify`	The notify signal is emitted on an object when one of its properties has its value set through `GObject.Object.set_property`(), g_object_set(), et al.

Fields¶

Name	Type	Access
g_type_instance	`GObject.TypeInstance`	r
qdata	`GLib.Data`	r
ref_count	`int`	r

Class Details¶

class GObject.Object(**kwargs)¶

Abstract:	No
Structure:	`GObject.ObjectClass`

All the fields in the GObject.Object structure are private to the GObject.Object implementation and should never be accessed directly.

classmethod compat_control(what, data)[source]¶

Parameters:	what (`int`) – data (`object` or `None`) –
Return type:	`int`

classmethod find_property(property_name)¶

Parameters:	property_name (`str`) – the name of the property to look up
Returns:	the `GObject.ParamSpec` for the property, or `None` if the class doesn’t have a property of that name
Return type:	`GObject.ParamSpec`

Looks up the GObject.ParamSpec for a property of a class.

classmethod install_properties(pspecs)¶

Parameters:	pspecs ([`GObject.ParamSpec`]) – the `GObject.ParamSpecs` array defining the new properties

Installs new properties from an array of GObject.ParamSpecs.

All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads.

The property id of each property is the index of each GObject.ParamSpec in the pspecs array.

The property id of 0 is treated specially by GObject.Object and it should not be used to store a GObject.ParamSpec.

This function should be used if you plan to use a static array of GObject.ParamSpecs and GObject.Object.notify_by_pspec(). For instance, this class initialization:

enum {
  PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
};

static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };

static void
my_object_class_init (MyObjectClass *klass)
{
  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);

  obj_properties[PROP_FOO] =
    g_param_spec_int ("foo", "Foo", "Foo",
                      -1, G_MAXINT,
                      0,
                      G_PARAM_READWRITE);

  obj_properties[PROP_BAR] =
    g_param_spec_string ("bar", "Bar", "Bar",
                         NULL,
                         G_PARAM_READWRITE);

  gobject_class->set_property = my_object_set_property;
  gobject_class->get_property = my_object_get_property;
  g_object_class_install_properties (gobject_class,
                                     N_PROPERTIES,
                                     obj_properties);
}

allows calling GObject.Object.notify_by_pspec() to notify of property changes:

void
my_object_set_foo (MyObject *self, gint foo)
{
  if (self->foo != foo)
    {
      self->foo = foo;
      g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]);
    }
 }

New in version 2.26.

classmethod install_property(property_id, pspec)¶

Parameters:	property_id (`int`) – the id for the new property pspec (`GObject.ParamSpec`) – the `GObject.ParamSpec` for the new property

Installs a new property.

All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads.

Note that it is possible to redefine a property in a derived class, by installing a property with the same name. This can be useful at times, e.g. to change the range of allowed values or the default value.

classmethod interface_find_property(g_iface, property_name)[source]¶

Parameters:	g_iface (`GObject.TypeInterface`) – any interface vtable for the interface, or the default vtable for the interface property_name (`str`) – name of a property to look up.
Returns:	the `GObject.ParamSpec` for the property of the interface with the name property_name, or `None` if no such property exists.
Return type:	`GObject.ParamSpec`

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

New in version 2.4.

classmethod interface_install_property(g_iface, pspec)[source]¶

Parameters:	g_iface (`GObject.TypeInterface`) – any interface vtable for the interface, or the default vtable for the interface. pspec (`GObject.ParamSpec`) – the `GObject.ParamSpec` for the new property

Add a property to an interface; this is only useful for interfaces that are added to GObject.Object-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 GObject.ParamSpec, but normally 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 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.

New in version 2.4.

classmethod interface_list_properties(g_iface)[source]¶

Parameters:	g_iface (`GObject.TypeInterface`) – any interface vtable for the interface, or the default vtable for the interface
Returns:	a pointer to an array of pointers to `GObject.ParamSpec` structures. The paramspecs are owned by GLib, but the array should be freed with `GLib.free`() when you are done with it.
Return type:	[`GObject.ParamSpec`]

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

New in version 2.4.

classmethod list_properties()¶

Returns:	an array of `GObject.ParamSpec` which should be freed after use
Return type:	[`GObject.ParamSpec`]

Get an array of GObject.ParamSpec for all properties of a class.

classmethod newv(object_type, parameters)[source]¶

Parameters:	object_type (`GObject.GType`) – the type id of the `GObject.Object` subtype to instantiate parameters ([`GObject.Parameter`]) – an array of `GObject.Parameter`
Returns:	a new instance of object_type
Return type:	`GObject.Object`

Creates a new instance of a GObject.Object subtype and sets its properties.

Construction parameters (see GObject.ParamFlags.CONSTRUCT, GObject.ParamFlags.CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.

Deprecated since version 2.54: Use g_object_new_with_properties() instead. deprecated. See GObject.Parameter for more information.

classmethod override_property(property_id, name)¶

Parameters:	property_id (`int`) – the new property ID name (`str`) – the name of a property registered in a parent class or in an interface of this class.

Registers property_id as referring to a property with the name name in a parent class or in an interface implemented by self. This allows this class to “override” a property implementation in a parent class or to provide the implementation of a property from an interface.

Internally, overriding is implemented by creating a property of type GObject.ParamSpecOverride; generally operations that query the properties of the object class, such as GObject.ObjectClass.find_property() or GObject.ObjectClass.list_properties() will return the overridden property. However, in one case, the construct_properties argument of the constructor virtual function, the GObject.ParamSpecOverride is passed instead, so that the param_id field of the GObject.ParamSpec will be correct. For virtually all uses, this makes no difference. If you need to get the overridden property, you can call GObject.ParamSpec.get_redirect_target().

New in version 2.4.

bind_property(source_property, target, target_property, flags)[source]¶

Parameters:	source_property (`str`) – the property on self to bind target (`GObject.Object`) – the target `GObject.Object` target_property (`str`) – the property on target to bind flags (`GObject.BindingFlags`) – flags to pass to `GObject.Binding`
Returns:	the `GObject.Binding` instance representing the binding between the two `GObject.Object` instances. The binding is released whenever the `GObject.Binding` reference count reaches zero.
Return type:	`GObject.Binding`

Creates a binding between source_property on self and target_property on target. Whenever the source_property is changed the target_property is updated using the same value. For instance:

g_object_bind_property (action, "active", widget, "sensitive", 0);

Will result in the “sensitive” property of the widget GObject.Object instance to be updated with the same value of the “active” property of the action GObject.Object instance.

If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on self will be updated as well.

The binding will automatically be removed when either the self or the target instances are finalized. To remove the binding without affecting the self and the target you can just call GObject.Object.unref() on the returned GObject.Binding instance.

A GObject.Object can have multiple bindings.

New in version 2.26.

bind_property_full(source_property, target, target_property, flags, transform_to, transform_from)[source]¶

Parameters:	source_property (`str`) – the property on self to bind target (`GObject.Object`) – the target `GObject.Object` target_property (`str`) – the property on target to bind flags (`GObject.BindingFlags`) – flags to pass to `GObject.Binding` transform_to (`GObject.Closure`) – a `GObject.Closure` wrapping the transformation function from the self to the target, or `None` to use the default transform_from (`GObject.Closure`) – a `GObject.Closure` wrapping the transformation function from the target to the self, or `None` to use the default
Returns:	the `GObject.Binding` instance representing the binding between the two `GObject.Object` instances. The binding is released whenever the `GObject.Binding` reference count reaches zero.
Return type:	`GObject.Binding`

Creates a binding between source_property on self and target_property on target, allowing you to set the transformation functions to be used by the binding.

This function is the language bindings friendly version of GObject.Object.bind_property_full(), using GObject.Closures instead of function pointers.

New in version 2.26.

connect(detailed_signal: str, handler: function, *args) → handler_id: int[source]¶

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.

connect_after(detailed_signal: str, handler: function, *args) → handler_id: 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.

disconnect(id_)[source]¶

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”.

emit(signal_name: str, *args) → None¶

Emit signal signal_name. Signal arguments must follow, e.g. if your signal is of type (int,), it must be emitted with:

self.emit(signal_name, 42)

force_floating()[source]¶: This function is intended for GObject.Object implementations to re-enforce a floating object reference. Doing this is seldom required: all GObject.InitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling GObject.Object.ref_sink().

New in version 2.10.

freeze_notify() → None[source]¶

This method freezes all the “notify::” signals (which are emitted when any property is changed) until the thaw_notify() method is called.

It recommended to use the with statement when calling freeze_notify(), that way it is ensured that thaw_notify() is called implicitly at the end of the block:

with an_object.freeze_notify():
    # Do your work here
    ...

get_data(key)[source]¶

Parameters:	key (`str`) – name of the key for that association
Returns:	the data if found, or `None` if no such data exists.
Return type:	`object` or `None`

Gets a named field from the objects table of associations (see GObject.Object.set_data()).

get_property(property_name: str) → object[source]¶: Retrieves a property value.

get_qdata(quark)[source]¶

Parameters:	quark (`int`) – A #GQuark, naming the user data pointer
Returns:	The user data pointer set, or `None`
Return type:	`object` or `None`

This function gets back user data pointers stored via g_object_set_qdata().

getv(names, values)[source]¶

Parameters:	names ([`str`]) – the names of each property to get values ([`GObject.Value`]) – the values of each property to get

Gets n_properties properties for an self. 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.

New in version 2.54.

handler_block(handler_id: int) → None¶

Blocks a handler of an instance so it will not be called during any signal emissions unless handler_unblock() is called for that handler_id. Thus “blocking” a signal handler means to temporarily deactivate it, a signal handler has to be unblocked exactly the same amount of times it has been blocked before to become active again.

It is recommended to use handler_block() in conjunction with the with statement which will call handler_unblock() implicitly at the end of the block:

with an_object.handler_block(handler_id):
    # Do your work here
    ...

handler_unblock(handler_id)¶

Parameters:	handler_id (`int`) –

is_floating()[source]¶

Returns:	`True` if self has a floating reference
Return type:	`bool`

Checks whether self has a floating reference.

New in version 2.10.

notify(property_name)[source]¶

Parameters:	property_name (`str`) – the name of a property installed on the class of self.

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

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

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

notify_by_pspec(pspec)[source]¶

Parameters:	pspec (`GObject.ParamSpec`) – the `GObject.ParamSpec` of a property installed on the class of self.

Emits a “notify” signal for the property specified by pspec on self.

This function omits the property name lookup, hence it is faster than GObject.Object.notify().

One way to avoid using GObject.Object.notify() from within the class that registered the properties, and using GObject.Object.notify_by_pspec() instead, is to store the GObject.ParamSpec used with GObject.ObjectClass.install_property() inside a static array, e.g.:

enum
{
  PROP_0,
  PROP_FOO,
  PROP_LAST
};

static GParamSpec *properties[PROP_LAST];

static void
my_object_class_init (MyObjectClass *klass)
{
  properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
                                           0, 100,
                                           50,
                                           G_PARAM_READWRITE);
  g_object_class_install_property (gobject_class,
                                   PROP_FOO,
                                   properties[PROP_FOO]);
}

and then notify a change on the “foo” property with:

g_object_notify_by_pspec (self, properties[PROP_FOO]);

New in version 2.26.

ref()[source]¶

Returns:	the same self
Return type:	`GObject.Object`

Increases the reference count of self.

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of self will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

ref_sink()[source]¶

Returns:	self
Return type:	`GObject.Object`

Increase the reference count of self, and possibly remove the floating reference, if self has a floating reference.

In other words, if the object is floating, then this call “assumes ownership” of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

Since GLib 2.56, the type of self will be propagated to the return type under the same conditions as for GObject.Object.ref().

New in version 2.10.

run_dispose()[source]¶

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_data(key, data)[source]¶

Parameters:	key (`str`) – name of the key data (`object` or `None`) – data to associate with that key

Each object carries around a table of associations from strings to pointers. This function lets you set an association.

If the object already had an association with that name, the old association will be destroyed.

Internally, the key is converted to a #GQuark using GLib.quark_from_string(). This means a copy of key is kept permanently (even after self has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the #GQuark storage growing unbounded.

set_property(property_name: str, value: object)[source]¶: Set property property_name to value.

steal_data(key)[source]¶

Parameters:	key (`str`) – name of the key
Returns:	the data if found, or `None` if no such data exists.
Return type:	`object` or `None`

Remove a specified datum from the object’s data associations, without invoking the association’s destroy handler.

steal_qdata(quark)[source]¶

Parameters:	quark (`int`) – A #GQuark, naming the user data pointer
Returns:	The user data pointer set, or `None`
Return type:	`object` or `None`

This function gets back user data pointers stored via g_object_set_qdata() and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example:

void
object_add_to_user_list (GObject     *object,
                         const gchar *new_string)
{
  // the quark, naming the object data
  GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
  // retrieve the old string list
  GList *list = g_object_steal_qdata (object, quark_string_list);

  // prepend new string
  list = g_list_prepend (list, g_strdup (new_string));
  // this changed 'list', so we need to set it again
  g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
  GList *node, *list = data;

  for (node = list; node; node = node->next)
    g_free (node->data);
  g_list_free (list);
}

Using GObject.Object.get_qdata() in the above example, instead of GObject.Object.steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

thaw_notify() → None[source]¶

Thaw all the “notify::” signals which were thawed by freeze_notify().

It is recommended to not call thaw_notify() explicitly but use freeze_notify() together with the with statement.

unref()[source]¶

Decreases the reference count of self. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

If the pointer to the GObject.Object may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to None rather than retain a dangling pointer to a potentially invalid GObject.Object instance. Use g_clear_object() for this.

watch_closure(closure)[source]¶

Parameters:	closure (`GObject.Closure`) – `GObject.Closure` to watch

This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling GObject.Closure.invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, GObject.Object.ref() and GObject.Object.unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on self during invocation of the closure. Usually, this function will be called on closures that use this self as closure data.

do_constructed() virtual¶

do_dispatch_properties_changed(n_pspecs, pspecs) virtual¶

Parameters:	n_pspecs (`int`) – pspecs (`GObject.ParamSpec`) –

do_dispose() virtual¶

do_finalize() virtual¶

do_get_property(property_id, value, pspec) virtual¶

Parameters:	property_id (`int`) – value (`GObject.Value`) – pspec (`GObject.ParamSpec`) –

do_notify(pspec) virtual¶

Parameters:	pspec (`GObject.ParamSpec`) –

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 GObject.Object.notify_by_pspec() instead.

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

do_set_property(property_id, value, pspec) virtual¶

Parameters:	property_id (`int`) – value (`GObject.Value`) – pspec (`GObject.ParamSpec`) –

Signal Details¶

GObject.Object.signals.notify(object, pspec)¶

Signal Name:	`notify`
Flags:	`RUN_FIRST`, `NO_RECURSE`, `DETAILED`, `ACTION`, `NO_HOOKS`
Parameters:	object (`GObject.Object`) – The object which received the signal pspec (`GObject.ParamSpec`) – the `GObject.ParamSpec` of the property which changed.

The notify signal is emitted on an object when one of its properties has its value set through GObject.Object.set_property(), g_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.Object class. If the implementor did not create the property with GObject.ParamFlags.EXPLICIT_NOTIFY, then any call to GObject.Object.set_property() results in ::notify being emitted, even if the new value is the same as the old. If they did pass GObject.ParamFlags.EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call GObject.Object.notify() or 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 g_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 as detail strings for the notify signal.