GObject.Object¶

Subclasses: GObject.Binding, GObject.BindingGroup, GObject.InitiallyUnowned, GObject.SignalGroup, 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

The base object type.

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

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

classmethod compat_control(what, data)¶

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:

typedef enum {
  PROP_FOO = 1,
  PROP_BAR,
  N_PROPERTIES
} MyObjectProperty;

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 | G_PARAM_STATIC_STRINGS);

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

  gobject_class->set_property = my_object_set_property;
  gobject_class->get_property = my_object_get_property;
  g_object_class_install_properties (gobject_class,
                                     G_N_ELEMENTS (obj_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)¶

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)¶

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)¶

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)¶

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)¶

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.

Removing the binding by calling GObject.Object.unref() on it must only be done if the binding, self and target are only used from a single thread and it is clear that both self and target outlive the binding. Especially it is not safe to rely on this if the binding, self or target can be finalized from different threads. Keep another reference to the binding and use GObject.Binding.unbind() instead to be on the safe side.

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)¶

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¶

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_)¶

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()¶: 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¶

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)¶

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¶: Retrieves a property value.

get_qdata(quark)¶

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)¶

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()¶

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)¶

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)¶

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

typedef enum
{
  PROP_FOO = 1,
  PROP_LAST
} MyObjectProperty;

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_PARAM_STATIC_STRINGS);
  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()¶

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()¶

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()¶

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)¶

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)¶: Set property property_name to value.

steal_data(key)¶

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)¶

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¶

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()¶

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)¶

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.