GObject.Object

g GObject.Object 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

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

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.Object. The GObject class provides methods for object construction and destruction, property access methods, and signal support. Signals are described in detail here.

For a tutorial on implementing a new GObject class, see How to define and implement a new GObject. For a list of naming conventions for GObjects and their methods, see the GType conventions. For the high-level concepts behind GObject.Object, 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 G_ADD_PRIVATE().

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:

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", NULL, NULL,
                      -1, G_MAXINT,
                      0,
                      G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);

  obj_properties[PROP_BAR] =
    g_param_spec_string ("bar", NULL, NULL,
                         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:

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:

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

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

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", NULL, NULL,
                                           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()[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

the constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. constructed implementors should chain up to the constructed call of their parent class to allow it to complete its initialisation.

do_dispatch_properties_changed(n_pspecs, pspecs) virtual
Parameters:

emits property change notification for a bunch of properties. Overriding dispatch_properties_changed should be rarely needed.

do_dispose() virtual

the dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, dispose should chain up to the dispose method of the parent class.

do_finalize() virtual

instance finalization function, should finish the finalization of the instance begun in dispose and chain up to the finalize method of the parent class.

do_get_property(property_id, value, pspec) virtual
Parameters:

the generic getter for all properties of this type. Should be overridden for every type with properties.

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:

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.

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