## GObject

GObject — The base object type

## Synopsis

    #include <gobject.h>

    struct      GObject;
    struct      GObjectClass;
    void        (*GObjectGetPropertyFunc)       (GObject *object,
                                                 guint property_id,
                                                 GValue *value,
                                                 GParamSpec *pspec);
    void        (*GObjectSetPropertyFunc)       (GObject *object,
                                                 guint property_id,
                                                 const GValue *value,
                                                 GParamSpec *pspec);
    void        (*GObjectFinalizeFunc)          (GObject *object);
    #define     G_TYPE_IS_OBJECT                (type)
    #define     G_OBJECT                        (object)
    #define     G_IS_OBJECT                     (object)
    #define     G_OBJECT_CLASS                  (class)
    #define     G_IS_OBJECT_CLASS               (class)
    #define     G_OBJECT_GET_CLASS              (object)
    #define     G_OBJECT_TYPE                   (object)
    #define     G_OBJECT_TYPE_NAME              (object)
    #define     G_OBJECT_CLASS_TYPE             (class)
    #define     G_OBJECT_CLASS_NAME             (class)
    void        g_object_class_install_property (GObjectClass *oclass,
                                                 guint property_id,
                                                 GParamSpec *pspec);
    GParamSpec* g_object_class_find_property    (GObjectClass *oclass,
                                                 const gchar *property_name);
    GParamSpec** g_object_class_list_properties (GObjectClass *oclass,
                                                 guint *n_properties);
    gpointer    g_object_new                    (GType object_type,
                                                 const gchar *first_property_name,
                                                 ...);
    gpointer    g_object_newv                   (GType object_type,
                                                 guint n_parameters,
                                                 GParameter *parameters);
    struct      GParameter;
    gpointer    g_object_ref                    (gpointer object);
    void        g_object_unref                  (gpointer object);
    void        (*GWeakNotify)                  (gpointer data,
                                                 GObject *where_the_object_was);
    void        g_object_weak_ref               (GObject *object,
                                                 GWeakNotify notify,
                                                 gpointer data);
    void        g_object_weak_unref             (GObject *object,
                                                 GWeakNotify notify,
                                                 gpointer data);
    void        g_object_add_weak_pointer       (GObject *object,
                                                 gpointer *weak_pointer_location);
    void        g_object_remove_weak_pointer    (GObject *object,
                                                 gpointer *weak_pointer_location);
    gpointer    g_object_connect                (gpointer object,
                                                 const gchar *signal_spec,
                                                 ...);
    void        g_object_disconnect             (gpointer object,
                                                 const gchar *signal_spec,
                                                 ...);
    void        g_object_set                    (gpointer object,
                                                 const gchar *first_property_name,
                                                 ...);
    void        g_object_get                    (gpointer object,
                                                 const gchar *first_property_name,
                                                 ...);
    void        g_object_notify                 (GObject *object,
                                                 const gchar *property_name);
    void        g_object_freeze_notify          (GObject *object);
    void        g_object_thaw_notify            (GObject *object);
    gpointer    g_object_get_data               (GObject *object,
                                                 const gchar *key);
    void        g_object_set_data               (GObject *object,
                                                 const gchar *key,
                                                 gpointer data);
    void        g_object_set_data_full          (GObject *object,
                                                 const gchar *key,
                                                 gpointer data,
                                                 GDestroyNotify destroy);
    gpointer    g_object_steal_data             (GObject *object,
                                                 const gchar *key);
    gpointer    g_object_get_qdata              (GObject *object,
                                                 GQuark quark);
    void        g_object_set_qdata              (GObject *object,
                                                 GQuark quark,
                                                 gpointer data);
    void        g_object_set_qdata_full         (GObject *object,
                                                 GQuark quark,
                                                 gpointer data,
                                                 GDestroyNotify destroy);
    gpointer    g_object_steal_qdata            (GObject *object,
                                                 GQuark quark);
    void        g_object_set_property           (GObject *object,
                                                 const gchar *property_name,
                                                 const GValue *value);
    void        g_object_get_property           (GObject *object,
                                                 const gchar *property_name,
                                                 GValue *value);
    GObject*    g_object_new_valist             (GType object_type,
                                                 const gchar *first_property_name,
                                                 va_list var_args);
    void        g_object_set_valist             (GObject *object,
                                                 const gchar *first_property_name,
                                                 va_list var_args);
    void        g_object_get_valist             (GObject *object,
                                                 const gchar *first_property_name,
                                                 va_list var_args);
    void        g_object_watch_closure          (GObject *object,
                                                 GClosure *closure);
    void        g_object_run_dispose            (GObject *object);
    #define     G_OBJECT_WARN_INVALID_PSPEC     (object, pname, property_id, pspec)
    #define     G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec)

## Description

## Details

### struct GObject

    struct GObject {

      GTypeInstance g_type_instance;

    };

All the fields in the GObject structure are private to the GObject implementation and should never be accessed directly.

### struct GObjectClass

    struct GObjectClass {

      GTypeClass   g_type_class;

    };

### GObjectGetPropertyFunc ()

    void        (*GObjectGetPropertyFunc)       (GObject *object,
                                                 guint property_id,
                                                 GValue *value,
                                                 GParamSpec *pspec);

`object` : |
`property_id` : |
`value` : |
`pspec` : |

### GObjectSetPropertyFunc ()

    void        (*GObjectSetPropertyFunc)       (GObject *object,
                                                 guint property_id,
                                                 const GValue *value,
                                                 GParamSpec *pspec);

`object` : |
`property_id` : |
`value` : |
`pspec` : |

### GObjectFinalizeFunc ()

    void        (*GObjectFinalizeFunc)          (GObject *object);

`object` : |

### G_TYPE_IS_OBJECT()

    #define G_TYPE_IS_OBJECT(type)      (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT)

Return a boolean value of `FALSE` or `TRUE` indicating whether the passed in type id is a `G_TYPE_OBJECT` or derived from it.

`type` : | Type id to check for is a `G_TYPE_OBJECT` relationship.
Returns : | `FALSE` or `TRUE`, indicating whether `type` is a `G_TYPE_OBJECT`.

### G_OBJECT()

    #define G_OBJECT(object)            (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject))

Cast a GObject or derived pointer into a (GObject*) pointer. Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts.

`object` : | Object which is subject to casting.

### G_IS_OBJECT()

    #define G_IS_OBJECT(object)         (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT))

Check whether a valid GTypeInstance pointer is of type `G_TYPE_OBJECT`.

`object` : | Instance to check for being a `G_TYPE_OBJECT`.

### G_OBJECT_CLASS()

    #define G_OBJECT_CLASS(class)       (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass))

`class` : |

### G_IS_OBJECT_CLASS()

    #define G_IS_OBJECT_CLASS(class)    (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT))

`class` : |

### G_OBJECT_GET_CLASS()

    #define G_OBJECT_GET_CLASS(object)  (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass))

`object` : |

### G_OBJECT_TYPE()

    #define G_OBJECT_TYPE(object)       (G_TYPE_FROM_INSTANCE (object))

Return the type id of an object.

`object` : | Object to return the type id for.
Returns : | Type id of `object`.

### G_OBJECT_TYPE_NAME()

    #define G_OBJECT_TYPE_NAME(object)  (g_type_name (G_OBJECT_TYPE (object)))

`object` : |

### G_OBJECT_CLASS_TYPE()

    #define G_OBJECT_CLASS_TYPE(class)  (G_TYPE_FROM_CLASS (class))

`class` : |

### G_OBJECT_CLASS_NAME()

    #define G_OBJECT_CLASS_NAME(class)  (g_type_name (G_OBJECT_CLASS_TYPE (class)))

`class` : |

### g_object_class_install_property ()

    void        g_object_class_install_property (GObjectClass *oclass,
                                                 guint property_id,
                                                 GParamSpec *pspec);

Installs a new property. This is usually done in the class initializer.

`oclass` : | a GObjectClass
`property_id` : | the id for the new property
`pspec` : | the GParamSpec for the new property

### g_object_class_find_property ()

    GParamSpec* g_object_class_find_property    (GObjectClass *oclass,
                                                 const gchar *property_name);

`oclass` : |
`property_name` : |
Returns : |

### g_object_class_list_properties ()

    GParamSpec** g_object_class_list_properties (GObjectClass *oclass,
                                                 guint *n_properties);

`oclass` : |
`n_properties` : |
Returns : |

### g_object_new ()

    gpointer    g_object_new                    (GType object_type,
                                                 const gchar *first_property_name,
                                                 ...);

`object_type` : |
`first_property_name` : |
`...` : |
Returns : |

### g_object_newv ()

    gpointer    g_object_newv                   (GType object_type,
                                                 guint n_parameters,
                                                 GParameter *parameters);

`object_type` : |
`n_parameters` : |
`parameters` : |
Returns : |

### struct GParameter

    struct GParameter {

      const gchar *name;
      GValue       value;
    };

### g_object_ref ()

    gpointer    g_object_ref                    (gpointer object);

`object` : |
Returns : |

### g_object_unref ()

    void        g_object_unref                  (gpointer object);

`object` : |

### GWeakNotify ()

    void        (*GWeakNotify)                  (gpointer data,
                                                 GObject *where_the_object_was);

`data` : |
`where_the_object_was` : |

### g_object_weak_ref ()

    void        g_object_weak_ref               (GObject *object,
                                                 GWeakNotify notify,
                                                 gpointer data);

`object` : |
`notify` : |
`data` : |

### g_object_weak_unref ()

    void        g_object_weak_unref             (GObject *object,
                                                 GWeakNotify notify,
                                                 gpointer data);

`object` : |
`notify` : |
`data` : |

### g_object_add_weak_pointer ()

    void        g_object_add_weak_pointer       (GObject *object,
                                                 gpointer *weak_pointer_location);

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

`object` : | The object that should be weak referenced.
`weak_pointer_location` : | The memory address of a pointer.

### g_object_remove_weak_pointer ()

    void        g_object_remove_weak_pointer    (GObject *object,
                                                 gpointer *weak_pointer_location);

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

`object` : | The object that is weak referenced.
`weak_pointer_location` : | The memory address of a pointer.

### g_object_connect ()

    gpointer    g_object_connect                (gpointer object,
                                                 const gchar *signal_spec,
                                                 ...);

`object` : |
`signal_spec` : |
`...` : |
Returns : |

### g_object_disconnect ()

    void        g_object_disconnect             (gpointer object,
                                                 const gchar *signal_spec,
                                                 ...);

`object` : |
`signal_spec` : |
`...` : |

### g_object_set ()

    void        g_object_set                    (gpointer object,
                                                 const gchar *first_property_name,
                                                 ...);

`object` : |
`first_property_name` : |
`...` : |

### g_object_get ()

    void        g_object_get                    (gpointer object,
                                                 const gchar *first_property_name,
                                                 ...);

`object` : |
`first_property_name` : |
`...` : |

### g_object_notify ()

    void        g_object_notify                 (GObject *object,
                                                 const gchar *property_name);

Emits a "notify" signal for the property `property_name` on `object`.

`object` : | a GObject
`property_name` : | the name of a property installed on the class of `object`.

### g_object_freeze_notify ()

    void        g_object_freeze_notify          (GObject *object);

Stops emission of "notify" signals on `object`. The signals are queued until `g_object_thaw_notify()` is called on `object`.

`object` : | a GObject

### g_object_thaw_notify ()

    void        g_object_thaw_notify            (GObject *object);

Reverts the effect of a previous call to `g_object_freeze_notify()`. This causes all queued "notify" signals on `object` to be emitted.

`object` : | a GObject

### g_object_get_data ()

    gpointer    g_object_get_data               (GObject *object,
                                                 const gchar *key);

`object` : |
`key` : |
Returns : |

### g_object_set_data ()

    void        g_object_set_data               (GObject *object,
                                                 const gchar *key,
                                                 gpointer data);

`object` : |
`key` : |
`data` : |

### g_object_set_data_full ()

    void        g_object_set_data_full          (GObject *object,
                                                 const gchar *key,
                                                 gpointer data,
                                                 GDestroyNotify destroy);

`object` : |
`key` : |
`data` : |
`destroy` : |

### g_object_steal_data ()

    gpointer    g_object_steal_data             (GObject *object,
                                                 const gchar *key);

`object` : |
`key` : |
Returns : |

### g_object_get_qdata ()

    gpointer    g_object_get_qdata              (GObject *object,
                                                 GQuark quark);

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

`object` : | The GObject to get a stored user data pointer from
`quark` : | A GQuark, naming the user data pointer
Returns : | The user data pointer set, or `NULL`

### g_object_set_qdata ()

    void        g_object_set_qdata              (GObject *object,
                                                 GQuark quark,
                                                 gpointer data);

This sets an opaque, named pointer on an object. The name is specified through a GQuark (retrived 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.

`object` : | The GObject to set store a user data pointer
`quark` : | A GQuark, naming the user data pointer
`data` : | An opaque user data pointer

### g_object_set_qdata_full ()

    void        g_object_set_qdata_full         (GObject *object,
                                                 GQuark quark,
                                                 gpointer data,
                                                 GDestroyNotify destroy);

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

`object` : | The GObject to set store a user data pointer
`quark` : | A GQuark, naming the user data pointer
`data` : | An opaque user data pointer
`destroy` : | Function to invoke with `data` as argument, when `data` needs to be freed

### g_object_steal_qdata ()

    gpointer    g_object_steal_qdata            (GObject *object,
                                                 GQuark quark);

This function gets back user data pointers stored via `g_object_set_qdata()` and removes the `data` from object without invoking it's `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 `g_object_get_qdata()` in the above example, instead of `g_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()`.

`object` : | The GObject to get a stored user data pointer from
`quark` : | A GQuark, naming the user data pointer
Returns : | The user data pointer set, or `NULL`

### g_object_set_property ()

    void        g_object_set_property           (GObject *object,
                                                 const gchar *property_name,
                                                 const GValue *value);

`object` : |
`property_name` : |
`value` : |

### g_object_get_property ()

    void        g_object_get_property           (GObject *object,
                                                 const gchar *property_name,
                                                 GValue *value);

`object` : |
`property_name` : |
`value` : |

### g_object_new_valist ()

    GObject*    g_object_new_valist             (GType object_type,
                                                 const gchar *first_property_name,
                                                 va_list var_args);

`object_type` : |
`first_property_name` : |
`var_args` : |
Returns : |

### g_object_set_valist ()

    void        g_object_set_valist             (GObject *object,
                                                 const gchar *first_property_name,
                                                 va_list var_args);

`object` : |
`first_property_name` : |
`var_args` : |

### g_object_get_valist ()

    void        g_object_get_valist             (GObject *object,
                                                 const gchar *first_property_name,
                                                 va_list var_args);

`object` : |
`first_property_name` : |
`var_args` : |

### g_object_watch_closure ()

    void        g_object_watch_closure          (GObject *object,
                                                 GClosure *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 (non existing) 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.

`object` : | GObject restricting lifetime of `closure`
`closure` : | GClosure to watch

### g_object_run_dispose ()

    void        g_object_run_dispose            (GObject *object);

`object` : |

### G_OBJECT_WARN_INVALID_PSPEC()

    #define     G_OBJECT_WARN_INVALID_PSPEC(object, pname, property_id, pspec)

`object` : |
`pname` : |
`property_id` : |
`pspec` : |

### G_OBJECT_WARN_INVALID_PROPERTY_ID()

    #define     G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec)

`object` : |
`property_id` : |
`pspec` : |