GObject.Object
Description: Reference for GObject.Object

### 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 `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()`.

#### Descendants

- GBinding
- GBindingGroup
- GInitiallyUnowned
- GSignalGroup
- GTypeModule

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