Class

GObjectObject

Description [src]

class GObject.Object : GObject.TypeInstance
{
  /* No available fields */
}

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

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, read Instantiatable classed types: Objects.

Since GLib 2.72, all GObjects 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().

Descendants

Constructors

g_object_new

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

g_object_new_valist

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

g_object_new_with_properties

Creates a new instance of a GObject subtype and sets its properties using the provided arrays. Both arrays must have exactly n_properties elements, and the names and values correspond by index.

since: 2.54

g_object_newv

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

deprecated: 2.54

Functions

g_object_compat_control

No description available.

g_object_interface_find_property

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

since: 2.4

g_object_interface_install_property

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

since: 2.4

g_object_interface_list_properties

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

since: 2.4

Instance methods

g_object_add_toggle_ref

Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.

since: 2.8

g_object_add_weak_pointer

Adds a weak reference from weak_pointer to object to indicate that the pointer located at weak_pointer_location is only valid during the lifetime of object. When the object is finalized, weak_pointer will be set to NULL.

g_object_bind_property

Creates a binding between source_property on source and target_property on target.

since: 2.26

g_object_bind_property_full

Complete version of g_object_bind_property().

since: 2.26

g_object_bind_property_with_closures

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

since: 2.26

g_object_connect

A convenience function to connect multiple signals at once.

g_object_disconnect

A convenience function to disconnect multiple signals at once.

g_object_dup_data

This is a variant of g_object_get_data() which returns a ‘duplicate’ of the value. dup_func defines the meaning of ‘duplicate’ in this context, it could e.g. take a reference on a ref-counted object.

since: 2.34

g_object_dup_qdata

This is a variant of g_object_get_qdata() which returns a ‘duplicate’ of the value. dup_func defines the meaning of ‘duplicate’ in this context, it could e.g. take a reference on a ref-counted object.

since: 2.34

g_object_force_floating

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

since: 2.10

g_object_freeze_notify

Increases the freeze count on object. If the freeze count is non-zero, the emission of “notify” signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one GObject::notify signal is emitted for each property modified while the object is frozen.

g_object_get

Gets properties of an object.

g_object_get_data

Gets a named field from the objects table of associations (see g_object_set_data()).

g_object_get_property

Gets a property of an object.

g_object_get_qdata

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

g_object_get_valist

Gets properties of an object.

g_object_getv

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

since: 2.54

g_object_is_floating

Checks whether object has a [floating][floating-ref] reference.

since: 2.10

g_object_notify

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

g_object_notify_by_pspec

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

since: 2.26

g_object_ref

Increases the reference count of object.

g_object_ref_sink

Increase the reference count of object, and possibly remove the [floating][floating-ref] reference, if object has a floating reference.

since: 2.10

g_object_remove_toggle_ref

Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one.

since: 2.8

g_object_remove_weak_pointer

Removes a weak reference from object that was previously added using g_object_add_weak_pointer(). The weak_pointer_location has to match the one used with g_object_add_weak_pointer().

g_object_replace_data

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

since: 2.34

g_object_replace_qdata

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

since: 2.34

g_object_run_dispose

Releases all references to other objects. This can be used to break reference cycles.

g_object_set

Sets properties on an object.

g_object_set_data

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

g_object_set_data_full

Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed.

g_object_set_property

Sets a property on an object.

g_object_set_qdata

This sets an opaque, named pointer on an object. The name is specified through a GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the object with g_object_get_qdata() until the object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using NULL as pointer essentially removes the data stored.

g_object_set_qdata_full

This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with data as argument when the object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same quark.

g_object_set_valist

Sets properties on an object.

g_object_setv

Sets n_properties properties for an object. Properties to be set will be taken from values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

since: 2.54

g_object_steal_data

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

g_object_steal_qdata

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

g_object_take_ref

If object is floating, sink it. Otherwise, do nothing.

since: 2.70

g_object_thaw_notify

Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued “notify” signals are emitted.

g_object_unref

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

g_object_watch_closure

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 g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.

g_object_weak_ref

Adds a weak reference callback to an object. Weak references are used for notification when an object is disposed. They are called “weak references” because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive).

g_object_weak_unref

Removes a weak reference callback to an object.

Signals

GObject.Object::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Class structure

struct GObjectObjectClass {
  GTypeClass g_type_class;
  GObject* (* constructor) (
    GType type,
    guint n_construct_properties,
    GObjectConstructParam* construct_properties
  );
  void (* set_property) (
    GObject* object,
    guint property_id,
    const GValue* value,
    GParamSpec* pspec
  );
  void (* get_property) (
    GObject* object,
    guint property_id,
    GValue* value,
    GParamSpec* pspec
  );
  void (* dispose) (
    GObject* object
  );
  void (* finalize) (
    GObject* object
  );
  void (* dispatch_properties_changed) (
    GObject* object,
    guint n_pspecs,
    GParamSpec** pspecs
  );
  void (* notify) (
    GObject* object,
    GParamSpec* pspec
  );
  void (* constructed) (
    GObject* object
  );
  
}

The class structure for the GObject type.

// Example of implementing a singleton using a constructor.
static MySingleton *the_singleton = NULL;

static GObject*
my_singleton_constructor (GType                  type,
                          guint                  n_construct_params,
                          GObjectConstructParam *construct_params)
{
  GObject *object;
  
  if (!the_singleton)
    {
      object = G_OBJECT_CLASS (parent_class)->constructor (type,
                                                           n_construct_params,
                                                           construct_params);
      the_singleton = MY_SINGLETON (object);
    }
  else
    object = g_object_ref (G_OBJECT (the_singleton));

  return object;
}

Class members

g_type_class: GTypeClass: The parent class.
constructor: GObject* (* constructor) ( GType type, guint n_construct_properties, GObjectConstructParam* construct_properties ): The constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a constructor implementation must do is chain up to the constructor of the parent class. Overriding constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons.
set_property: void (* set_property) ( GObject* object, guint property_id, const GValue* value, GParamSpec* pspec ): 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.
get_property: void (* get_property) ( GObject* object, guint property_id, GValue* value, GParamSpec* pspec ): The generic getter for all properties of this type. Should be overridden for every type with properties.
dispose: void (* dispose) ( GObject* object ): 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.
finalize: void (* finalize) ( GObject* object ): Instance finalization function, should finish the finalization of the instance begun in dispose and chain up to the finalize method of the parent class.
dispatch_properties_changed: void (* dispatch_properties_changed) ( GObject* object, guint n_pspecs, GParamSpec** pspecs ): Emits property change notification for a bunch of properties. Overriding dispatch_properties_changed should be rarely needed.
notify: void (* notify) ( GObject* object, GParamSpec* pspec ): The class closure for the notify signal.
constructed: void (* constructed) ( GObject* object ): 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.

Virtual methods

GObject.ObjectClass.constructed

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.

GObject.ObjectClass.dispatch_properties_changed

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

GObject.ObjectClass.dispose

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.

GObject.ObjectClass.finalize

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

GObject.ObjectClass.get_property

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

GObject.ObjectClass.notify

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

GObject.ObjectClass.set_property

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.

Class methods

g_object_class_find_property

Looks up the GParamSpec for a property of a class.

g_object_class_install_properties

Installs new properties from an array of GParamSpecs.

since: 2.26

g_object_class_install_property

Installs a new property.

g_object_class_list_properties

Get an array of GParamSpec* for all properties of a class.

g_object_class_override_property

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

since: 2.4