GObject.Object¶
- Subclasses
GObject.Binding
,GObject.BindingGroup
,GObject.InitiallyUnowned
,GObject.SignalGroup
,GObject.TypeModule
Methods¶
- Structs
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
|
|
|
|
|
|
|
|
|
|
|
Properties¶
None
Signals¶
Name |
Short Description |
---|---|
The notify signal is emitted on an object when one of its properties has its value set through |
Fields¶
Name |
Type |
Access |
Description |
---|---|---|---|
g_type_instance |
r |
||
qdata |
r |
||
ref_count |
r |
Class Details¶
- class GObject.Object(**kwargs)¶
- Abstract
No
- Structure
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 orfloat
). If you need larger alignment for an element in aGObject.Object
, you should allocate it on the heap (aligned), or arrange for yourGObject.Object
to be appropriately padded. This guarantee applies to theGObject.Object
(or derived) struct, theGObject.ObjectClass
(or derived) struct, and any private data allocated by G_ADD_PRIVATE().- classmethod compat_control(what, data)¶
- classmethod find_property(property_name)¶
- Parameters
property_name (
str
) – the name of the property to look up- Returns
the
GObject.ParamSpec
for the property, orNone
if the class doesn’t have a property of that name- Return type
Looks up the
GObject.ParamSpec
for a property of a class.
- classmethod install_properties(pspecs)¶
- Parameters
pspecs ([
GObject.ParamSpec
]) – theGObject.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 aGObject.ParamSpec
.This function should be used if you plan to use a static array of
GObject.ParamSpecs
andGObject.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 propertypspec (
GObject.ParamSpec
) – theGObject.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 interfaceproperty_name (
str
) – name of a property to look up.
- Returns
the
GObject.ParamSpec
for the property of the interface with the name property_name, orNone
if no such property exists.- Return type
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 fromGObject.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
) – theGObject.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 createdGObject.ParamSpec
, but normallyGObject.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 withGLib.free
() when you are done with it.- Return type
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
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 theGObject.Object
subtype to instantiateparameters ([
GObject.Parameter
]) – an array ofGObject.Parameter
- Returns
a new instance of object_type
- Return type
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
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 asGObject.ObjectClass.find_property
() orGObject.ObjectClass.list_properties
() will return the overridden property. However, in one case, the construct_properties argument of the constructor virtual function, theGObject.ParamSpecOverride
is passed instead, so that the param_id field of theGObject.ParamSpec
will be correct. For virtually all uses, this makes no difference. If you need to get the overridden property, you can callGObject.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 bindtarget (
GObject.Object
) – the targetGObject.Object
target_property (
str
) – the property on target to bindflags (
GObject.BindingFlags
) – flags to pass toGObject.Binding
- Returns
the
GObject.Binding
instance representing the binding between the twoGObject.Object
instances. The binding is released whenever theGObject.Binding
reference count reaches zero.- Return type
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 actionGObject.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 returnedGObject.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 useGObject.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 bindtarget (
GObject.Object
) – the targetGObject.Object
target_property (
str
) – the property on target to bindflags (
GObject.BindingFlags
) – flags to pass toGObject.Binding
transform_to (
GObject.Closure
) – aGObject.Closure
wrapping the transformation function from the self to the target, orNone
to use the defaulttransform_from (
GObject.Closure
) – aGObject.Closure
wrapping the transformation function from the target to the self, orNone
to use the default
- Returns
the
GObject.Binding
instance representing the binding between the twoGObject.Object
instances. The binding is released whenever theGObject.Binding
reference count reaches zero.- Return type
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
(), usingGObject.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: allGObject.InitiallyUnowneds
are created with a floating reference which usually just needs to be sunken by callingGObject.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 thatthaw_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
Gets a named field from the objects table of associations (see
GObject.Object.set_data
()).
- get_qdata(quark)¶
- Parameters
quark (
int
) – A #GQuark, naming the user data pointer- Returns
The user data pointer set, or
None
- Return type
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 getvalues ([
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 callhandler_unblock()
implicitly at the end of the block:with an_object.handler_block(handler_id): # Do your work here ...
- 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) whenGObject.Object.thaw_notify
() is called.
- notify_by_pspec(pspec)¶
- Parameters
pspec (
GObject.ParamSpec
) – theGObject.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 usingGObject.Object.notify_by_pspec
() instead, is to store theGObject.ParamSpec
used withGObject.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
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
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)¶
-
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.
- steal_data(key)¶
- Parameters
key (
str
) – name of the key- Returns
the data if found, or
None
if no such data exists.- Return type
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
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 ofGObject.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 usefreeze_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 toNone
rather than retain a dangling pointer to a potentially invalidGObject.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
() andGObject.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) whenGObject.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
- Parameters
object (
GObject.Object
) – The object which received the signalpspec (
GObject.ParamSpec
) – theGObject.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 withGObject.ParamFlags.EXPLICIT_NOTIFY
, then any call toGObject.Object.set_property
() results in::notify
being emitted, even if the new value is the same as the old. If they did passGObject.ParamFlags.EXPLICIT_NOTIFY
, then this signal is emitted only when they explicitly callGObject.Object.notify
() orGObject.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.