GObject

GObject — Базовый тип объекта

Краткое описание



#include <glib-object.h>


                    GObject;
                    GObjectClass;
                    GObjectConstructParam;
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);
void                g_object_class_override_property    (GObjectClass *oclass,
                                                         guint property_id,
                                                         const gchar *name);
void                g_object_interface_install_property (gpointer g_iface,
                                                         GParamSpec *pspec);
GParamSpec*         g_object_interface_find_property    (gpointer g_iface,
                                                         const gchar *property_name);
GParamSpec**        g_object_interface_list_properties  (gpointer g_iface,
                                                         guint *n_properties_p);
gpointer            g_object_new                        (GType object_type,
                                                         const gchar *first_property_name,
                                                         ...);
gpointer            g_object_newv                       (GType object_type,
                                                         guint n_parameters,
                                                         GParameter *parameters);
                    GParameter;
gpointer            g_object_ref                        (gpointer object);
void                g_object_unref                      (gpointer object);
gpointer            g_object_ref_sink                   (gpointer object);
typedef             GInitiallyUnowned;
typedef             GInitiallyUnownedClass;
#define             G_TYPE_INITIALLY_UNOWNED
gboolean            g_object_is_floating                (gpointer object);
void                g_object_force_floating             (GObject *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);
void                (*GToggleNotify)                    (gpointer data,
                                                         GObject *object,
                                                         gboolean is_last_ref);
void                g_object_add_toggle_ref             (GObject *object,
                                                         GToggleNotify notify,
                                                         gpointer data);
void                g_object_remove_toggle_ref          (GObject *object,
                                                         GToggleNotify notify,
                                                         gpointer data);
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_PROPERTY_ID   (object, property_id, pspec)

Иерархия объектов



  GObject
   +----GTypeModule

Сигналы



  "notify"                                         : Run First / No Recursion / Has Details / Action / No Hooks

Описание

GObject является базовым типом обеспечивающим основные атрибуты и методы для всех объектных типов в GTK+, Pango и других библиотеках основанных на GObject. Класс GObject обеспечивает методы для конструирования и уничтожения объектов, методы доступа к свойству и поддержку сигналов. Сигналы подробно описаны в Сигналы (3).

GInitiallyUnowned наследует GObject. Единственное различие между ними заключается в том что начальная ссылка GInitiallyUnowned помечается как плавающая ссылка. Это значит что ни какой частью кода ни кто не "владеет". Основная мотивация обеспечения плавающих ссылок - удобство C. В частности, это позволяет писать код как:

Пример 1.


  container = create_container();
  container_add_child (container, create_child());

Если container_add_child() выполнит g_object_ref_sink() для помещённого child, ссылка на вновь созданный child не будет плавающей. Без плавающей ссылки, container_add_child() может создать ссылку на новый child только с помощью g_object_ref(), поэтому реализовать этот код без плавающей ссылки нужно было бы так:

Пример 2.


  Child *child;
  container = create_container();
  child = create_child();
  container_add_child (container, child);
  g_object_unref (child);

Плавающие ссылки могут быть преобразованы в обычные ссылки вызовом g_object_ref_sink(). Для объектов которые уже не имеют плавающих ссылок, g_object_ref_sink() эквивалентна g_object_ref() и возвращает новую ссылку. Так как плавающие ссылки в основном полезны только для удобства C, языковые привязки которые обеспечивают автоматизированные ссылки и монопольно обслуживают память (вроде умных указателей или "сборщики мусора") поэтому не нуждаются во вставке плавающих ссылок в их API.

Некоторые реализации объекта могут нуждаться в сохранении плавающего состояния объекта в определённых частях кода (например GtkMenu), для этого может использоваться следующее:

Пример 3.


  /* сохраняем плавающее состояние */
  gboolean was_floating = g_object_is_floating (object);
  g_object_ref_sink (object);
  /* скрытая часть кода */
  ...;
  /* восстановление плавающего состояния */
  if (was_floating)
    g_object_force_floating (object);
  g_obejct_unref (object); /* освобождение предварительно полученной ссылки */

Детали

GObject

typedef struct _GObject GObject;

Все поля в структуре GObject являются закрытыми для реализации GObject и не должны использоваться непосредственно.

GObjectClass

typedef struct {
  GTypeClass   g_type_class;

  /* seldomly overidden */
  GObject*   (*constructor)     (GType                  type,
                                 guint                  n_construct_properties,
                                 GObjectConstructParam *construct_properties);
  /* overridable methods */
  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);
  /* seldomly overidden */
  void       (*dispatch_properties_changed) (GObject      *object,
					     guint	   n_pspecs,
					     GParamSpec  **pspecs);
  /* signals */
  void	     (*notify)			(GObject	*object,
					 GParamSpec	*pspec);

  /* called when done constructing */
  void	     (*constructed)		(GObject	*object);
} GObjectClass;

Структура класса для типа GObject.

Пример 4. Реализация единицы множества используя конструктор


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;
}

GTypeClass `g_type_class`;	родительский класс
`constructor` ()	функция `constructor` вызывается с помощью `g_object_new()` для завершения инициализации объекта после установки всех свойств конструирования. Первое что должна сделать функция `constructor` - реализовать цепочку к `constructor` родительского класса. Отмена `constructor` редко необходима, например для обработки свойств конструирования, или для реализации единицы подмножества (singletons).
`set_property` ()	основной установщик для всех свойств этого типа. Должен быть переназначен для каждого типа со свойствами. Реализация `set_property` не должна явно издавать уведомление об изменении свойства, это обрабатывается системой типов.
`get_property` ()	основной получатель для всех свойств этого типа. Должен быть переназначен для каждого типа со свойствами.
`dispose` ()	функция `dispose` сбрасывает все ссылки на другие объекты, но сохраняет экземпляр нетронутым, так чтобы вызванный метод клиента остался роботающим. Это может быть выполнено множество раз (due to reference loops). Перед возвратом, `dispose` должна привязаться к `dispose` методу родительского класса.
`finalize` ()	функция инициализации экземпляра, должна завершать финализацию экземпляра начатую в `dispose` и привязаться к методу `finalize` родительского класса.
`dispatch_properties_changed` ()	издаёт уведомление изменения свойства для связки свойств. Переназначение `dispatch_properties_changed` должно быть редко необходимо.
`notify` ()	классовое замыкание для уведомляющего сигнала
`constructed` ()	функция `constructed` вызывается с помощью `g_object_new()` как завершающий шаг процесса создания объекта. В точке вызова, все свойства конструкции уже установлены на объект. Цель этого вызова позволить учесть шаги инициализации объекта которые выполняются только после установки свойств конструкции. Реализованные `constructed` должны привязываться к вызову `constructed` их родительского класса что позволяет завершить их инициализацию.

GObjectConstructParam

typedef struct {
  GParamSpec *pspec;
  GValue     *value;
} GObjectConstructParam;

Вспомогательная структура GObjectConstructParam используется для расположения GParamSpec/ GValue пар в constructor принадлежащем GObjectClass.

GParamSpec *`pspec`;	GParamSpec параметр конструктора
GValue *`value`;	Значение для параметра конструктора

GObjectGetPropertyFunc ()

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

Тип функции get_property в GObjectClass.

`object` :	a GObject
`property_id` :	числовой id под которым было зарегистрировано свойство с помощью `g_object_class_install_property()`.
`value` :	GValue возвращаемого значения свойства
`pspec` :	GParamSpec описание свойства

GObjectSetPropertyFunc ()

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

Тип функции set_property в GObjectClass.

`object` :	GObject
`property_id` :	числовой id под которым было зарегистрировано свойство с помощью `g_object_class_install_property()`.
`value` :	новое значение свойства
`pspec` :	GParamSpec описание свойства

GObjectFinalizeFunc ()

void (*GObjectFinalizeFunc) (GObject *object);

Тип функции finalize в GObjectClass.

object : финализируемый GObject

G_TYPE_IS_OBJECT()

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

Возвращает логическое значение FALSE или TRUE указывающее соответствует ли помещённый типовой id G_TYPE_OBJECT или происходит из него.

`type` :	Типовой id для проверки отношения к `G_TYPE_OBJECT`.
Возвращает :	`FALSE` или `TRUE`, указывая соответствует ли `type` объекту `G_TYPE_OBJECT`.

G_OBJECT()

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

Приводит GObject или полученный указатель к указателю (GObject*). В зависимости от текущего уровня отладки, эта функция может вызвать определённые динамические проверки чтобы идентифицировать недопустимые приведения типов.

object : Объект который необходимо преобразовать.

G_IS_OBJECT()

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

Проверяет допустимость указателя GTypeInstance типа G_TYPE_OBJECT.

object : Экземпляр для проверки соответствия типу G_TYPE_OBJECT.

G_OBJECT_CLASS()

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

Приводит полученную структуру GObjectClass к структуре GObjectClass.

class : допустимая GObjectClass

G_IS_OBJECT_CLASS()

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

Проверяет является ли class "is a" допустимой структурой GObjectClass типа G_TYPE_OBJECT или производной.

class : GObjectClass

G_OBJECT_GET_CLASS()

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

Возвращает классовую структуру связанную с экземпляром GObject.

object : экземпляр GObject.

G_OBJECT_TYPE()

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

Возвращает типовой id объекта.

`object` :	Объект для которого возвращается типовой id.
Возвращает :	Типовой id для `object`.

G_OBJECT_TYPE_NAME()

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

Возвращает имя объектного типа.

`object` :	Объект для которого возвращается типовое имя.
Возвращает :	Типовое имя `object`. Строкой владеет система типов и её не нужно освобождать.

G_OBJECT_CLASS_TYPE()

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

Возвращает типовой id сструктуры класса.

`class` :	допустимая GObjectClass
Возвращает :	Типовой id для `class`.

G_OBJECT_CLASS_NAME()

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

Возвращает имя классовой сструктуры типа.

`class` :	допустимая GObjectClass
Возвращает :	Типовое имя `class`. Строкой владеет система типов и она не должна освобождаться.

g_object_class_install_property ()

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

Устанавливает новое свойство. Это обычно делается в инициализации класса.

`oclass` :	GObjectClass
`property_id` :	id для нового свойства
`pspec` :	GParamSpec для нового свойства

g_object_class_find_property ()

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

Находит GParamSpec для свойства класса.

`oclass` :	GObjectClass
`property_name` :	искомое имя свойства
Возвращает :	GParamSpec для свойства, или `NULL` если класс не имеет свойства с таким именем

g_object_class_list_properties ()

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

Возвращает массив GParamSpec* для всех свойств класса.

`oclass` :	GObjectClass
`n_properties` :	расположение длины возвращаемого массива
Возвращает :	массив GParamSpec* который должен быть освобождён после использования

g_object_class_override_property ()

void                g_object_class_override_property    (GObjectClass *oclass,
                                                         guint property_id,
                                                         const gchar *name);

Регистрирует property_id как ссылку свойства с именем name в родительском классе или в интерфейсе реализуемом с помощью oclass. Это позволяет классу переназначать свойство реализации в родительском классе или обеспечить реализацию свойства из интерфейса.

Помните

Внутренне, переназначение реализуется созданием свойства типа GParamSpecOverride; обычно операции которые запрашивают свойства объектного класса, такие как g_object_class_find_property() или g_object_class_list_properties() вернут переназначенное свойство. Однако, в одном случае, construct_properties параметр виртуальной функции constructor, помещается вместо GParamSpecOverride, так чтобы поле param_id было заполнено правильным GParamSpec. Для виртуального использования это не имеет разницы. Если вам нужно получить переназначенное свойство, вы можете вызвать g_param_spec_get_redirect_target().

`oclass` :	GObjectClass
`property_id` :	новый ID свойства
`name` :	имя свойства зарегистрированное в родительском классе или в интерфейсе этого класса.

Начиная с версии 2.4

g_object_interface_install_property ()

void                g_object_interface_install_property (gpointer g_iface,
                                                         GParamSpec *pspec);

Добавляет свойство к интерфейсу; это полезно только для интерфейсов которые добавлены в GObject-производные типы. Добавление свойства в интерфейс заставляет все объекты класса иметь совместимые свойства с этим интерфейсом. Совместимые свойства могут быть вновь созданным GParamSpec, но обычно используется g_object_class_override_property() так чтобы объектный класс обеспечил реализацию и унаследовал описание свойства, значение по умолчанию, связь, и так далее из своего интерфейса.

Эта функция предназначается для вызова из значения по умолчанию vtable интерфейсной функции инициализации (член class_init в GTypeInfo.) Это нельзя вызвать после того как class_init вызвана для любой реализации объектных типов этого интерфейса.

`g_iface` :	любой vtable для интерфейса, или значение по умолчанию vtable для интерфейса.
`pspec` :	GParamSpec для нового свойства

Начиная с версии 2.4

g_object_interface_find_property ()

GParamSpec*         g_object_interface_find_property    (gpointer g_iface,
                                                         const gchar *property_name);

Находит GParamSpec с полученным именем для интерфейса. В основном, интерфейсный vtable помещённый как g_iface будет значением по умолчанию vtable из g_type_default_interface_ref(), или, если известно что интерфейс уже загружен, g_type_default_interface_peek().

`g_iface` :	любой интерфейсный vtable для интерфейса, или значение по умолчанию vtable для интерфейса
`property_name` :	имя искомого свойства
Возвращает :	GParamSpec для свойства интерфейса с именем `property_name`, или `NULL` если нет такого свойства.

Начиная с версии 2.4

g_object_interface_list_properties ()

GParamSpec**        g_object_interface_list_properties  (gpointer g_iface,
                                                         guint *n_properties_p);

Списки свойств интерфейса. В основном, интерфейсный vtable помещаемый как g_iface будет значением по умолчанию vtable из g_type_default_interface_ref(), или, если известно что интерфейс уже загружен, g_type_default_interface_peek().

`g_iface` :	любой интерфейсный vtable для интерфейса, или значение по умолчанию vtable для интерфейса
`n_properties_p` :	расположение для хранения количества возвращённых свойств.
Возвращает :	указатель на массив указателей структур GParamSpec. Структурами владеет GLib, но массив должен быть освобождён с помощью `g_free()` когда он вам больше не нужен.

Начиная с версии 2.4

g_object_new ()

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

Создаёт новый экземпляр GObject подтипа (subtype) и устанавливает его свойства.

Конструкционные параметры (смотрите G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) которые определены не явно, устанавливаются в их значения по умолчанию.

`object_type` :	типовой id подтипа GObject для экземпляра
`first_property_name` :	имя первого свойства
`...` :	значение первого свойства, опционально следующие пары name/value, зтем `NULL`
Возвращает :	новый экземпляр `object_type`

g_object_newv ()

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

Создаёт новый экземпляр подтипа GObject и устанавливает его свойства.

Конструкционные параметры (смотрите G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) которые не были установлены явно, устанавливаются в их значения по умолчанию.

`object_type` :	типовой id подтипа GObject для экземпляра
`n_parameters` :	длина массива `parameters`
`parameters` :	массив GParameter
Возвращает :	новый экземпляр `object_type`

GParameter

typedef struct {
  const gchar *name;
  GValue       value;
} GParameter;

Вспомогательная структура GParameter используется для размещения параметных пар name/value в g_object_newv().

const gchar *`name`;	имя параметра
GValue `value`;	значение параметра

g_object_ref ()

gpointer g_object_ref (gpointer object);

Увеличивает количество ссылок object.

`object` :	GObject
Возвращает :	тот же `object`

g_object_unref ()

void g_object_unref (gpointer object);

Уменьшает количество ссылок object. Когда количество ссылок достигает 0, объект финализируется (то есть память связанная с этим объектом освобождается).

object : a GObject

g_object_ref_sink ()

gpointer g_object_ref_sink (gpointer object);

Увеличивает количество ссылок object, и возможно удаляет плавающую ссылку, если object имеет плавающую ссылку.

Другими словами, если объект плавающий, то этот вызов "принимает владение" плавающей ссылкой, преобразует её в обычную ссылку очищая плавающий флаг оставляя неизменным количество ссылок. Если объект не плавающий, то этот вызов добавляет обычную ссылку увеличивая количество ссылок на одну.

`object` :	GObject
Возвращает :	`object`

Начиная с версии 2.10

GInitiallyUnowned

typedef struct _GObject                  GInitiallyUnowned;

Все поля в структуре GInitiallyUnowned являются закрытыми для реализации GInitiallyUnowned и к ним нет непосредственного доступа.

GInitiallyUnownedClass

typedef struct _GObjectClass             GInitiallyUnownedClass;

Классовая структура для типа GInitiallyUnowned.

G_TYPE_INITIALLY_UNOWNED

#define G_TYPE_INITIALLY_UNOWNED	      (g_initially_unowned_get_type())

Тип для GInitiallyUnowned.

g_object_is_floating ()

gboolean g_object_is_floating (gpointer object);

Проверяет имеет ли object плавающую ссылку.

`object` :	GObject
Возвращает :	`TRUE` если `object` имеет плавающую ссылку

Начиная с версии 2.10

g_object_force_floating ()

void g_object_force_floating (GObject *object);

Эта функция предназначается для реализации GObject утвердить плавающую ссылку объекта. Выполнение этой операции требуется редко, все GInitiallyUnowned создаются с плавающими ссылками которые обычно должны просто обрабатываться вызовом g_object_ref_sink().

object : a GObject

Начиная с версии 2.10

GWeakNotify ()

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

Функция GWeakNotify может быть добавлена в объект как callback-функция которая вызывается когда объект финализирован. Так как объект уже финализирован когда вызывается GWeakNotify, вы ничего не можете делать с объектом, кроме как использовать его адрес как hash-index или нечто подобное.

`data` :	данные обеспечиваемые при установке слабых ссылок
`where_the_object_was` :	объект для финализации

g_object_weak_ref ()

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

Добавляет слабую ссылку callback-функции в объект. Слабые ссылки используются для уведомления при финализации объекта. Они называются "слабые ссылки" ("weak references") потому что позволяют вам безопасно удерживать указатель на объект без вызова g_object_ref() (g_object_ref() добавляет строгую ссылку, которая заставляет объект существовать).

`object` :	GObject для слабой ссылки
`notify` :	callback-функция вызываемая перед освобождением объекта
`data` :	дополнительные данные помещаемые в уведомление

g_object_weak_unref ()

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

Удаляет слабую ссылку callback-функции для объекта.

`object` :	GObject для удаления слабой ссылки
`notify` :	callback-функция для поиска
`data` :	данные для поиска

g_object_add_weak_pointer ()

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

Добавляет слабую ссылку из weak_pointer в object указывая что указатель расположенный в weak_pointer_location допустим только в течение жизненного цикла object. Когда object финализирован, weak_pointer будет установлен в NULL.

`object` :	Объект для слабой ссылки.
`weak_pointer_location` :	адрес указателя в памяти.

g_object_remove_weak_pointer ()

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

Удаляет слабую ссылку из object которая была предварительно добавлена используя g_object_add_weak_pointer(). weak_pointer_location должен соответствовать использованному с g_object_add_weak_pointer().

`object` :	Объект для слабой ссылки.
`weak_pointer_location` :	адрес указателя в памяти.

GToggleNotify ()

void                (*GToggleNotify)                    (gpointer data,
                                                         GObject *object,
                                                         gboolean is_last_ref);

Callback-функция используемая для уведомления о переключении состояния ссылки. Смотрите g_object_add_toggle_ref().

`data` :	Callback-данные помещаемые в `g_object_add_toggle_ref()`
`object` :	Объект для которого вызвана `g_object_add_toggle_ref()`.
`is_last_ref` :	`TRUE` если переключаемая ссылка последняя ссылка на объект. `FALSE` если переключаемая ссылка была последней ссылкой а теперь есть другая ссылка.

g_object_add_toggle_ref ()

void                g_object_add_toggle_ref             (GObject *object,
                                                         GToggleNotify notify,
                                                         gpointer data);

Увеличивает счётчик ссылок объекта на одну и устанавливает callback-функцию вызываемую когда все ссылки на объект будут сброшены, или когда это уже последняя ссылка на объект и другая ссылка установлена.

Эти функциональные возможности предназначены для привязки object к объекту посреднику управляемому другим менеджером памяти. Это выполняется двумя парами ссылок: строгая ссылка добавляется g_object_add_toggle_ref() а противоположная в объект посредник который является либо строгой ссылкой либо слабой ссылкой.

Установка заключается в том что когда нет других ссылок на object, только слабая ссылка размещается в обратном направлении из object в объект посредник, но когда есть другие ссылки размещённые в object, строгая ссылка удерживается. Callback-функция notify вызывается когда ссылка из object в объекте посреднике должна быть переключена из строгой в слабую (is_last_ref true) или из слабой в строгую (is_last_ref false).

Так как (обычная) ссылка должна содержаться в объекте перед вызовом g_object_toggle_ref(), начальное состояние обратной ссылки всегда строгое (strong).

Множество переключаемых ссылок могут быть добавлены в тот же gobject, однако если множество переключаемых ссылок на объект, то не будет уведомления пока все не будут удалены. Поэтому, вы должны использовать переключающую ссылку если есть важное состояние в объекте посреднике.

`object` :	GObject
`notify` :	функция вызываемая когда ссылка является последней ссылкой на объект, или больше не последняя ссылка на объект.
`data` :	данные помещаемые в `notify`

Начиная с версии 2.8

g_object_remove_toggle_ref ()

void                g_object_remove_toggle_ref          (GObject *object,
                                                         GToggleNotify notify,
                                                         gpointer data);

Удаляет ссылку добавленную с помощью g_object_add_toggle_ref(). Количество ссылок на объект уменьшается на одну.

`object` :	GObject
`notify` :	функция вызываемая когда ссылка является последней ссылкой на объект, или когда она больше не является последней ссылкой на объект.
`data` :	данные помещаемые в `notify`

Начиная с версии 2.8

g_object_connect ()

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

Удобная функция для подключения множество сигналов сразу.

Спецификации сигналов ожидаемых этой функцией имеет форму "modifier::signal_name", где modifier может быть одним из следующего:

signal	эквивалент `g_signal_connect_data (...)`
object_signal, object-signal	эквивалент `g_signal_connect_object (...)`
swapped_signal, swapped-signal	эквивалент `g_signal_connect_data (..., G_CONNECT_SWAPPED)`
swapped_object_signal, swapped-object-signal	эквивалент `g_signal_connect_object (..., G_CONNECT_SWAPPED)`
signal_after, signal-after	эквивалент `g_signal_connect_data (..., G_CONNECT_AFTER)`
object_signal_after, object-signal-after	эквивалент `g_signal_connect_object (..., G_CONNECT_AFTER)`
swapped_signal_after, swapped-signal-after	эквивалент `g_signal_connect_data (..., G_CONNECT_SWAPPED \| G_CONNECT_AFTER)`
swapped_object_signal_after, swapped-object-signal-after	эквивалент `g_signal_connect_object (..., G_CONNECT_SWAPPED \| G_CONNECT_AFTER)`


  menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
						   "type", GTK_WINDOW_POPUP,
						   "child", menu,
						   NULL),
				     "signal::event", gtk_menu_window_event, menu,
				     "signal::size_request", gtk_menu_window_size_request, menu,
				     "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
				     NULL);

`object` :	GObject
`signal_spec` :	спецификация первого сигнала
`...` :	GCallback-функция для первого сигнала, зтем данные для первого сигнала, зтем опционально следующие spec/callback/data, завершается `NULL`
Возвращает :	`object`

g_object_disconnect ()

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

Удобная функция для отключения множества сигналов сразу.

Спецификация сигналов ожидаемых этой функцией имеет форму "any_signal", которая означает отключение любых сигналов с соответствующими callback-функциями и данными, или "any_signal::signal_name", которая отключает только сигнал с именем "signal_name".

`object` :	GObject
`signal_spec` :	спецификация для первого сигнала
`...` :	GCallback-функция для первого сигнала, зтем данные для первого сигнала, зтем опционально остальные spec/callback/data, завершается `NULL`

g_object_set ()

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

Устанавливает свойства на объект.

`object` :	GObject
`first_property_name` :	имя первого устанавливаемого свойства
`...` :	значение для первого свойства, зтем опционально следующие name/value pairs, завершается `NULL`

g_object_get ()

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

Получает свойства объекта.

В основном, копия делается содержимого свойства и вызывающий функцию отвечает за освобождение памяти так как это делается для типа, например вызовом g_free() или g_object_unref().

Пример 5. Использование g_object_get()

Пример использования g_object_get() для получения содержимого трёх свойств - одного типа G_TYPE_INT, одного типа G_TYPE_STRING и одного типа ""


 gint intval;
 gchar *strval;
 GObject *objval; 
 
 g_object_get (my_object,
               "intproperty", &intval,
               "strproperty", &strval,
               "objproperty", &objval,
               NULL);

 /* Do something with intval, strval, objval */
 
 g_free (strval);
 g_object_unref (objval);

`object` :	GObject
`first_property_name` :	имя первого свойства для получения
`...` :	возвращаемое расположение для первого свойства, зтем опционально следующие пары name/return, завершается `NULL`

g_object_notify ()

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

Издаёт сигнал "notify" для свойства property_name в object.

`object` :	GObject
`property_name` :	имя свойства установленное в класс `object`.

g_object_freeze_notify ()

void g_object_freeze_notify (GObject *object);

Останавливает эмиссию сигнала "notify" в object. Сигналы ставятся в очередь пока g_object_thaw_notify() не вызвана для object.

Это необходимо для аксессоров которые изменяют множество свойств, для предотвращения уведомления в течение модификации объекта.

object : GObject

g_object_thaw_notify ()

void g_object_thaw_notify (GObject *object);

Обратный эффект от предыдущего вызова g_object_freeze_notify(). Это заставит все сигналы "notify" поставленные в очередь издаться на object.

object : GObject

g_object_get_data ()

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

Получает именованное поле из таблицы объектов ассоциации (смотрите g_object_set_data()).

`object` :	GObject содержащий ассоциации
`key` :	имя ключа для этой ассоциации
Возвращает :	данные если найдены, или `NULL` если нет существующих данных.

g_object_set_data ()

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

Каждый объект поддерживает таблицу ассоциаций от строк до указателей. Эта функция позволяет вам установить ассоциацию.

Если объект уже содержит ассоциацию с таким именем, старая ассоциация будет уничтожена.

`object` :	GObject содержащий ассоциации.
`key` :	имя ключа
`data` :	данные связанные с этим ключом

g_object_set_data_full ()

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

Как g_object_set_data() кроме того добавляет уведомление о том когда ассоциация уничтожена, или установлена в другое значение или когда объект уничтожен.

Помните что destroy callback-функция не вызывается если data это NULL.

`object` :	GObject содержащий ассоциации
`key` :	имя ключа
`data` :	данные связанные с ключом
`destroy` :	функция вызываемая при уничтожении ассоциации

g_object_steal_data ()

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

Удаляет определённую величину из объектных данных ассоциаций, без вызова обработчика уничтожения ассоциаций.

`object` :	GObject содержащий ассоциации
`key` :	имя ключа
Возвращает :	данные если найдены, или `NULL` если такие данные не существуют.

g_object_get_qdata ()

gpointer            g_object_get_qdata                  (GObject *object,
                                                         GQuark quark);

Эта функция получает назад пользовательские указатели данных сохранённые через g_object_set_qdata().

`object` :	GObject для получения сохраненных указателей пользовательских данных
`quark` :	GQuark, именующий указатель пользовательских данных
Возвращает :	Набор указателей пользовательских данных, или `NULL`

g_object_set_qdata ()

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

Устанавливает непрозрачный именованный указатель в объект. Имя определяется через GQuark (находится например через g_quark_from_static_string()), и указатель может быть получен обратно из object с помощью g_object_get_qdata() пока object не финализирован. Предварительная установка набора указателей пользовательских данных, переписывает (освобождает) старый набор указателей, используя NULL поскольку указатель по существу удаляет сохранённые данные.

`object` :	GObject для хранения набора пользовательских указателей данных
`quark` :	GQuark, именованный указатель пользовательских данных
`data` :	Непрозрачный указатель пользовательских данных

g_object_set_qdata_full ()

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

Эта функция работает так же как g_object_set_qdata(), но в дополнение, может быть определена функция void (*destroy) (gpointer) которая вызывается с data в качестве аргумента при финализации object, или данные переписываются вызовом g_object_set_qdata() с таким же quark.

`object` :	GObject для хранения указателя набора пользовательских данных
`quark` :	GQuark, именованный указатель пользовательских данных
`data` :	Непрозрачный указатель пользовательских данных
`destroy` :	Функция вызываемая с `data` как аргумент, когда `data` нужно освободить

g_object_steal_qdata ()

gpointer            g_object_steal_qdata                (GObject *object,
                                                         GQuark quark);

Эта функция получает назад указатели пользовательских данных сохранённые через g_object_set_qdata() и удаляет data из объекта без вызова функции destroy() (если они были установлены). Обычно, вызов этой функции запросит только обновление указателей пользовательских данных с уведомлением разрушения, например:


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);
}

Использование g_object_get_qdata() в примере выше, вместо g_object_steal_qdata() отменило бы установку функции уничтожения, и поэтому часть списка строк освобождается через g_object_set_qdata_full().

`object` :	GObject для получения сохранённого указателя пользовательских данных
`quark` :	GQuark, именованный указатель пользовательских данных
Возвращает :	Установленный указатель пользовательских данных, или `NULL`

g_object_set_property ()

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

Устанавливает свойство для объекта.

`object` :	GObject
`property_name` :	имя устанавливаемого свойства
`value` :	значение

g_object_get_property ()

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

Получает свойство объекта.

В основном, делается копия содержимого свойства и вызывающий должен отвечать за освобождение памяти с помощью вызова g_value_unset().

Помните что g_object_get_property() фактически предназначен для языковых привязок, g_object_get() намного удобнее для C программирования.

`object` :	GObject
`property_name` :	имя получаемого свойства
`value` :	расположение возвращаемого значения свойства

g_object_new_valist ()

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

Создаёт новый экземпляр подтипа GObject и устанавливает его свойства.

Параметры конструкции (смотрите G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) которые явно не определены устанавливаются в значение по умолчанию.

`object_type` :	типовой id подтипа GObject для инстанциирования
`first_property_name` :	имя первого свойства
`var_args` :	значение первого свойства, зтем опционально следующие пары name/value, завершает `NULL`
Возвращает :	новый экземпляр `object_type`

g_object_set_valist ()

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

Устанавливает свойства объекта.

`object` :	GObject
`first_property_name` :	имя первого свойства для установки
`var_args` :	значение первого свойства, fзтем опционально следующие пары name/value, завершает `NULL`

g_object_get_valist ()

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

Получает свойства объекта.

В основном, создаётся копия содержимого свойства и вызывающий отвечает за освобождение памяти так как это делается для типа, например вызовом g_free() или g_object_unref().

Смотрите g_object_get().

`object` :	GObject
`first_property_name` :	имя первого свойства для получения
`var_args` :	расположение возвращаемого первого свойства, зтем опционально следующие пары name/return, завершает `NULL`

g_object_watch_closure ()

void                g_object_watch_closure              (GObject *object,
                                                         GClosure *closure);

Эта функция по существу лимитирует время жизни closure до времени жизни объекта. Таким образом, когда объект финализирован, closure ликвидируется вызовом g_closure_invalidate(), чтобы предотвратить вызов замыкания с несуществующим объектом. Кроме того, g_object_ref() и g_object_unref() добавляются как защищённые маршаллеры closure, гарантируя что дополнительный счётчик ссылок содержит object в течение вызова closure. Обычно, эта функция вызывается в замыканиях которые используют этот object в качестве данных для замыкания.

`object` :	GObject ограничивающий жизненное время `closure`
`closure` :	GClosure для отслеживания

g_object_run_dispose ()

void g_object_run_dispose (GObject *object);

Высвобождает все ссылки на другие объекты. Это может быть использовано для прерывания циклов ссылки.

Помните

Эти функции должны вызываться только из системы реализации объекта.

object : GObject

G_OBJECT_WARN_INVALID_PROPERTY_ID()

#define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec)

Этот макрос должен использоваться для издания стандартного предупреждения о несуществующем свойстве в реализациях set_property() и get_property().

`object` :	GObject в котором были вызваны `set_property()` или `get_property()`
`property_id` :	числовой id свойства
`pspec` :	GParamSpec свойства

Детали сигналов

The `"notify"` signal

void                user_function                      (GObject    *gobject,
                                                        GParamSpec *arg1,
                                                        gpointer    user_data)      : Run First / No Recursion / Has Details / Action / No Hooks

Сигнал уведомления издаётся на объекте когда одно из его свойств изменяется. Помните что получение этого сигнала не гарантирует что значение свойства фактически изменилось, он может так же издаваться когда установщик свойства вызван для переустановки предыдущего значения.

Этот сигнал обычно используется для получения уведомления об изменении единственного свойства, определяя имя свойства как детальный параметр в вызове g_signal_connect(), например:


g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

Важно отметить что вы должны использовать canonical параметр называемый как детальная строка для сигнала уведомления.

`pspec` :	GParamSpec свойства которое изменяется
`gobject` :	объект который получает сигнал.
`user_data` :	пользовательские данные устанавливаемые при подключении обработчика сигнала.

			Справочное описание GObject
Top \| Описание \| Иерархия объектов \| Сигналы

GObject

Краткое описание

Иерархия объектов

Сигналы

Описание

Детали

GObject

GObjectClass

GObjectConstructParam

GObjectGetPropertyFunc ()

GObjectSetPropertyFunc ()

GObjectFinalizeFunc ()

G_TYPE_IS_OBJECT()

G_OBJECT()

G_IS_OBJECT()

G_OBJECT_CLASS()

G_IS_OBJECT_CLASS()

G_OBJECT_GET_CLASS()

G_OBJECT_TYPE()

G_OBJECT_TYPE_NAME()

G_OBJECT_CLASS_TYPE()

G_OBJECT_CLASS_NAME()

g_object_class_install_property ()

g_object_class_find_property ()

g_object_class_list_properties ()

g_object_class_override_property ()

Помните

g_object_interface_install_property ()

g_object_interface_find_property ()

g_object_interface_list_properties ()

g_object_new ()

g_object_newv ()

GParameter

g_object_ref ()

g_object_unref ()

g_object_ref_sink ()

GInitiallyUnowned

GInitiallyUnownedClass

G_TYPE_INITIALLY_UNOWNED

g_object_is_floating ()

g_object_force_floating ()

GWeakNotify ()

g_object_weak_ref ()

g_object_weak_unref ()

g_object_add_weak_pointer ()

g_object_remove_weak_pointer ()

GToggleNotify ()

g_object_add_toggle_ref ()

g_object_remove_toggle_ref ()

g_object_connect ()

g_object_disconnect ()

g_object_set ()

g_object_get ()

g_object_notify ()

g_object_freeze_notify ()

g_object_thaw_notify ()

g_object_get_data ()

g_object_set_data ()

g_object_set_data_full ()

g_object_steal_data ()

g_object_get_qdata ()

g_object_set_qdata ()

g_object_set_qdata_full ()

g_object_steal_qdata ()

g_object_set_property ()

g_object_get_property ()

g_object_new_valist ()

g_object_set_valist ()

g_object_get_valist ()

g_object_watch_closure ()

g_object_run_dispose ()

Помните

G_OBJECT_WARN_INVALID_PROPERTY_ID()

Детали сигналов

The "notify" signal

Смотрите также

The `"notify"` signal