GObject.Object

g GObject.Object 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 new (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)
  handler_block (handler_id: int) -> None
  handler_unblock (handler_id)
  is_floating ()
  notify (property_name)
  notify_by_pspec (pspec)
  ref ()
  ref_sink ()
  replace_data (key, oldval, newval, destroy, old_destroy)
  replace_qdata (quark, oldval, newval, destroy, old_destroy)
  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 been changed.

Fields

Name Type Access Description
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:
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:

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

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.

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 new(object_type, parameters)[source]
Parameters:
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.

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

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.

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.

New in version 2.10.

replace_data(key, oldval, newval, destroy, old_destroy)[source]
Parameters:
Returns:

True if the existing value for key was replaced by newval, False otherwise.

Return type:

bool

Compares the user data for the key key on self with oldval, and if they are the same, replaces oldval with newval.

This is like a typical atomic compare-and-exchange operation, for user data on an object.

If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in old_destroy). Its up to the caller to free this as he wishes, which may or may not include using old_destroy as sometimes replacement should not destroy the object in the normal way.

New in version 2.34.

replace_qdata(quark, oldval, newval, destroy, old_destroy)[source]
Parameters:
Returns:

True if the existing value for quark was replaced by newval, False otherwise.

Return type:

bool

Compares the user data for the key quark on self with oldval, and if they are the same, replaces oldval with newval.

This is like a typical atomic compare-and-exchange operation, for user data on an object.

If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in old_destroy). Its up to the caller to free this as he wishes, which may or may not include using old_destroy as sometimes replacement should not destroy the object in the normal way.

New in version 2.34.

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.

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");
  // retrive 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:
do_dispose() virtual
do_finalize() virtual
do_get_property(property_id, value, pspec) virtual
Parameters:
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:

Signal Details

GObject.Object.signals.notify(object, pspec)
Signal Name:

notify

Flags:

RUN_FIRST, NO_RECURSE, DETAILED, ACTION, NO_HOOKS

Parameters:

The notify signal is emitted on an object when one of its properties has been changed. Note that getting this signal doesn’t guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value.

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 [canonical-parameter-name]’ parameter names as detail strings for the notify signal.