Wiki
Задать вопрос на форуме...

prev

up

home

gtk+ reference manual

next

top  |  description  |  object hierarchy  |  known derived interfaces  |  properties  |  signals

gtkobject

gtkobject — базовый класс иерархии типов gtk+

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

#include <gtk/gtk.h>


            gtkobject;
#define     gtk_object_type                 (object)
#define     gtk_object_type_name            (object)
enum        gtkobjectflags;
#define     gtk_object_flags                (obj)
#define     gtk_object_floating             (obj)
enum        gtkargflags;

gtkobject*  gtk_object_new                  (gtktype type,
                                             const gchar *first_property_name,
                                             ...);
void        gtk_object_sink                 (gtkobject *object);

gtkobject*  gtk_object_ref                  (gtkobject *object);
void        gtk_object_unref                (gtkobject *object);
void        gtk_object_weakref              (gtkobject *object,
                                             gtkdestroynotify notify,
                                             gpointer data);
void        gtk_object_weakunref            (gtkobject *object,
                                             gtkdestroynotify notify,
                                             gpointer data);
void        gtk_object_destroy              (gtkobject *object);
void        gtk_object_get                  (gtkobject *object,
                                             const gchar *first_property_name,
                                             ...);
void        gtk_object_set                  (gtkobject *object,
                                             const gchar *first_property_name,
                                             ...);
void        gtk_object_set_data             (gtkobject *object,
                                             const gchar *key,
                                             gpointer data);
void        gtk_object_set_data_full        (gtkobject *object,
                                             const gchar *key,
                                             gpointer data,
                                             gtkdestroynotify destroy);
void        gtk_object_remove_data          (gtkobject *object,
                                             const gchar *key);

gpointer    gtk_object_get_data             (gtkobject *object,
                                             const gchar *key);
void        gtk_object_remove_no_notify     (gtkobject *object,
                                             const gchar *key);
void        gtk_object_set_user_data        (gtkobject *object,
                                             gpointer data);

gpointer    gtk_object_get_user_data        (gtkobject *object);
void        gtk_object_add_arg_type         (const gchar *arg_name,
                                             gtktype arg_type,
                                             guint arg_flags,
                                             guint arg_id);
void        gtk_object_set_data_by_id       (gtkobject *object,
                                             gquark data_id,
                                             gpointer data);
void        gtk_object_set_data_by_id_full  (gtkobject *object,
                                             gquark data_id,
                                             gpointer data,
                                             gtkdestroynotify destroy);

gpointer    gtk_object_get_data_by_id       (gtkobject *object,
                                             gquark data_id);
void        gtk_object_remove_data_by_id    (gtkobject *object,
                                             gquark data_id);
void        gtk_object_remove_no_notify_by_id

                                            (gtkobject *object,
                                             gquark key_id);
#define     gtk_object_data_try_key
#define     gtk_object_data_force_id

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

  gobject
   +----ginitiallyunowned
         +----gtkobject
               +----gtkwidget
               +----gtkadjustment

               +----gtkcellrenderer
               +----gtkfilefilter
               +----gtkitemfactory
               +----gtktooltips
               +----gtktreeviewcolumn

               +----gtkrecentfilter

известные производные интерфейсы

gtkobject требует gtkrecentchooser.

свойства

  "user-data"            gpointer              : read / write

сигналы

"destroy"   void        user_function      (gtkobject *object,
                                            gpointer   user_data)      : cleanup / no recursion / no hooks

описание

gtkobject это базовый класс для всех виджетов, а также объектов таких как gtkadjustment. gtkobject предшественник gobject; не виджеты происходящие из gtkobject вместо gobject необходимы для обратной совместимости.

gtkobjects создаётся с "плавающим" подсчетом ссылок. это означает, что начальная ссылка не принадлежит никому. вызов g_object_unref() для вновь созданного gtkobject некорректен, сначала должна удаляться плавающая ссылка. это может сделать кто угодно в любое время, вызвав g_object_ref_sink() для преобразования плавающей ссылки в обычную. g_object_ref_sink() возвращает новую ссылку если объект уже не имеет плавающей ссылки.

когда вы добавляете виджет в его родительский контейнер, родительский контейнер выполняет следующее: 

  g_object_ref_sink (g_object (child_widget));

это значит что контейнер теперь владеет ссылкой на дочерний виджет и дочерний виджет имеет плавающую ссылку.

цель плавающей ссылки заключается в том, чтобы поддержать существование виджета до добавления его в родительский контейнер: 

   button = gtk_button_new ();
   /* кнопка имеет одну плавающую ссылку для своего существования */
   gtk_container_add (gtk_container (container), button);
   /* кнопка имеет одну не плавающую ссылку которой владеет контейнер */

gtkwindow – особый случай, потому что gtk+ самостоятельно будет ссылаться и/или снимать ссылку на него при создании. таким образом, после вызова gtk_window_new(), gtkwindow будет иметь одну ссылку которой владеет gtk+, а не плавающую ссылку.

ещё один фактор входит в соблюдение правил: сигнал "destroy", издаваемый с помощью gtk_object_destroy(). сигнал "destroy" запрашивает весь код имея ссылку объекта для освобождения ссылки. таким образом, например, если вы вызовите gtk_object_destroy() на gtkwindow, gtk+ освободит ссылки которыми он владеет; если вы вызовите gtk_object_destroy() на gtkbutton, то кнопка будет удалена из родительского контейнера а родительский контейнер будет освобожден от ссылки на кнопку. поскольку ссылка освобождена, вызов gtk_object_destroy() должен освободить всю память связанную с объектом, за исключением ошибочного кода который не в состоянии освободить собственные ссылки в ответ на сигнал "destroy". освобождение памяти (упоминается как finalization) происходит только если количество ссылок равно нулю.

некоторые простые правила для обработки gtkobject:

  • никогда не вызывайте g_object_unref(), если предварительно не вызвали g_object_ref(), даже если вы создали gtkobject. (помните: это не правильно для gobject; для gobject, создатель объекта владеет ссылкой.)

  • вызывайте gtk_object_destroy() для избавления от большинства объектов в большинстве случаев. в частности, виджеты практически всегда разрушаются подобным способом.

  • из-за плавающего счета ссылок, вы не должны беспокоиться о счете ссылок для виджетов и окон верхнего уровня, если вы не вызовите g_object_ref() самостоятельно.

детали

gtkobject

typedef struct _gtkobject gtkobject;

непосредственно сам объект. для доступа к нему используйте макрос.

gtk_object_type()

#define gtk_object_type(object)           (g_type_from_instance (object))

определяет тип объекта.

object :

gtkobject.

gtk_object_type_name()

#define gtk_object_type_name(object)      (g_type_name (gtk_object_type (object)))

определяет типовое имя объекта.

object :

gtkobject.

enum gtkobjectflags

typedef enum
{
  gtk_in_destruction    = 1 << 0, /* used internally during dispose */
#if !defined (gtk_disable_deprecated) || defined (gtk_compilation)
  gtk_floating          = 1 << 1,
#endif
  gtk_reserved_1        = 1 << 2,
  gtk_reserved_2        = 1 << 3
} gtkobjectflags;

сообщает о состоянии объекта.

gtk_in_destruction

объект в текущий момент находится в состоянии разрушения. это используется внутренне gtk+ для предотвращения повторных вызовов разрушения.

gtk_reserved_2

зарезервировано для использования в будущем.

gtk_object_flags()

#define gtk_object_flags(obj)             (gtk_object (obj)->flags)

определяет gtkobjectflags для объекта, не обращаясь к его членам.

obj :

объект из которого возвращаются флажки.

gtk_object_floating()

#define gtk_object_floating(obj)          (g_object_is_floating (obj))

внимание

gtk_object_floating устарела и не должна использоваться во вновь создаваемом коде.

возвращает true если объект всё ещё имеет плавающие ссылки. смотрите краткий обзор gtkobject.

obj :

объект для проверки.

enum gtkargflags

typedef enum
{
  gtk_arg_readable       = g_param_readable,
  gtk_arg_writable       = g_param_writable,
  gtk_arg_construct      = g_param_construct,
  gtk_arg_construct_only = g_param_construct_only,
  gtk_arg_child_arg      = 1 << 4
} gtkargflags;

внимание

gtkargflags устарела и не должна использоваться во вновь создаваемом коде. в будущем используйте вместо неё gparamspec

возможные флажки указывающие какие аргументы должны быть обработаны.

gtk_arg_readable

читабельный. (то есть может выполняться запрос)

gtk_arg_writable

записываемый. (то есть может устанавливаться)

gtk_arg_construct

нуждается в конструкции.

gtk_arg_construct_only

нуждается в конструкции (и создаётся один раз во время создания объекта) и по другому не может быть установлен. следовательно этот флажок не допускает gtk_arg_writable, и избыточен для gtk_arg_construct.

gtk_arg_child_arg

тип параметра применяемый к каждому дочернему элементу. используется для gtkcontainer.

gtk_object_new ()

gtkobject*  gtk_object_new                  (gtktype type,
                                             const gchar *first_property_name,
                                             ...);

внимание

gtk_object_new устарела и не должна использоваться во вновь создаваемом коде. используйте вместо неё g_object_new().

создаёт объект определяя его аргументы, перечисленные в вызове функции.

type :

тип идентифицирующий этот объект. возвращённый gtk_type_unique() (хотя для объектного свойства записи это должно быть доступно через макрос gtk_type_foo.)

first_property_name :

имя первого свойства для установки при конструировании объекта.

... :

значение первого аргумента, далее любое количество пар имя/значение-аргумента, заканчивается null.

возвращает :

новый gtkobject.

gtk_object_sink ()

void        gtk_object_sink                 (gtkobject *object);

внимание

gtk_object_sink устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_ref_sink().

удаляет плавающую ссылку из gtkobject, если есть; иначе ничего не делает. смотрите краткое описание gtkobject.

object :

объект для снятия плавающей ссылки.

gtk_object_ref ()

gtkobject*  gtk_object_ref                  (gtkobject *object);

внимание

gtk_object_ref устарела и не должна использоваться во вновь создаваемом коде. используйте вместо неё g_object_ref().

увеличивает количество плавающих ссылок объекта.

object :

объект для ссылки.

возвращает :

object.

gtk_object_unref ()

void        gtk_object_unref                (gtkobject *object);

внимание

gtk_object_unref устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_unref().

уменьшает количество ссылок на объект. когда количество ссылок доходит до 0, объект удаляется (то есть память освобождается).

object :

объект для уменьшения ссылок.

gtk_object_weakref ()

void        gtk_object_weakref              (gtkobject *object,
                                             gtkdestroynotify notify,
                                             gpointer data);

внимание

gtk_object_weakref устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_weak_ref().

добавляет слабую ссылку для объекта. слабая ссылка используется как уведомление о завершении цикла существования объекта. их называют "weak references", потому что они позволяют удерживать указатель на объект без вызова g_object_ref() (g_object_ref() добавляет жесткую ссылку, то есть, заставляет объект существовать).

object :

объект для слабой ссылки.

notify :

callback-функция вызываемая перед освобождением объекта.

data :

дополнительные данные для помещения в уведомление (notify).

gtk_object_weakunref ()

void        gtk_object_weakunref            (gtkobject *object,
                                             gtkdestroynotify notify,
                                             gpointer data);

внимание

gtk_object_weakunref устарела и не должна использоваться во вновь создаваемом коде. используйте вместо неё g_object_weak_unref().

удаляет слабые ссылки для объекта.

object :

объект слабые ссылки на который удаляются.

notify :

callback-функция для поиска.

data :

данные для поиска.

gtk_object_destroy ()

void        gtk_object_destroy              (gtkobject *object);

издаёт сигнал "destroy" уведомляющий что все ссылки на объект gtkobject освобождаются. смотрите краткое описание.

память для самого объекта не будет освобождена до тех пор, пока количество ссылок не достигнет 0; gtk_object_destroy() просто освобождает ссылки, она не создаёт пустого объекта.

object :

объект для удаления ссылок.

gtk_object_get ()

void        gtk_object_get                  (gtkobject *object,
                                             const gchar *first_property_name,
                                             ...);

внимание

gtk_object_get устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_get().

определяет свойства объекта.

object :

gtkobject.

first_property_name :

имя первого свойства для определения значения.

... :

null-завершённый список возвращаемых имен пар.

gtk_object_set ()

void        gtk_object_set                  (gtkobject *object,
                                             const gchar *first_property_name,
                                             ...);

внимание

gtk_object_set устарела и не должна использоваться во вновь создаваемом коде. используйте вместо неё g_object_set().

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

void set_box_properties (gtkbox* box)
{
  gtk_object_set (gtk_object (box), "homogeneous", true,
                                    "spacing", 8,
                                    null);
}

object :

gtkobject.

first_property_name :

имя первого свойства для установки

... :

значение первого аргумента, далее опционально следует большое количество пар имя/значение, завершается null.

gtk_object_set_data ()

void        gtk_object_set_data             (gtkobject *object,
                                             const gchar *key,
                                             gpointer data);

внимание

gtk_object_set_data устарела и не должна использоваться во вновь создаваемом коде. вместо ней используйте g_object_set_data().

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

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

object :

объект содержащий ассоциации.

key :

имя ключа.

data :

данные связанные с ключом.

gtk_object_set_data_full ()

void        gtk_object_set_data_full        (gtkobject *object,
                                             const gchar *key,
                                             gpointer data,
                                             gtkdestroynotify destroy);

внимание

gtk_object_set_data_full устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_set_data_full().

тоже самое что gtk_object_set_data(), но добавляет уведомление при разрушении ассоциации, с помощью gtk_object_remove_data() или когда разрушается объект.

object :

объект содержащий ассоциации.

key :

имя ключа.

data :

данные связанные с ключом.

destroy :

функция вызываемая при уничтожении ассоциации.

gtk_object_remove_data ()

void        gtk_object_remove_data          (gtkobject *object,
                                             const gchar *key);

внимание

gtk_object_remove_data устарела и не должна использоваться во вновь создаваемом коде. используйте g_object_set_data() для установки данных объекта в null.

удаляет определённые данные из ассоциированных данных объекта (object_data). последующие вызовы gtk_object_get_data() вернут null.

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

object :

объект поддерживающий ассоциацию.

key :

имя ключа для ассоциации.

gtk_object_get_data ()

gpointer    gtk_object_get_data             (gtkobject *object,
                                             const gchar *key);

внимание

gtk_object_get_data устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_get_data().

определяет именованное поле из объектной таблицы ассоциаций (object_data).

object :

объект поддерживающий ассоциации.

key :

имя ключа для этой ассоциации.

возвращает :

данные если найдены, или null если нет таких данных.

gtk_object_remove_no_notify ()

void        gtk_object_remove_no_notify     (gtkobject *object,
                                             const gchar *key);

внимание

gtk_object_remove_no_notify устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_steal_data().

удаляет данные из ассоциаций объекта (object_data), не вызывает уничтожающий обработчик.

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

object :

объект поддерживающий ассоциации.

key :

имя ключа для ассоциации.

gtk_object_set_user_data ()

void        gtk_object_set_user_data        (gtkobject *object,
                                             gpointer data);

внимание

gtk_object_set_user_data устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_set_data().

ля удобства, каждый объект предлагает основной указатель пользовательских данных. эта функция устанавливает их.

object :

объект для установки пользовательских данных.

data :

новое значение пользовательских данных.

gtk_object_get_user_data ()

gpointer    gtk_object_get_user_data        (gtkobject *object);

внимание

gtk_object_get_user_data устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_get_data().

определяет указатель пользовательских данных.

этот указатель предназначен для удобства при написании вашего приложения.

object :

объект.

возвращает :

область пользовательских данных для объекта.

gtk_object_add_arg_type ()

void        gtk_object_add_arg_type         (const gchar *arg_name,
                                             gtktype arg_type,
                                             guint arg_flags,
                                             guint arg_id);

внимание

gtk_object_add_arg_type устарела и не должна использоваться во вновь создаваемом коде.

устарела, вместо неё используется система свойств gobject включая gparamspec. добавляет новый тип аргумента для объектного класса. обычно вызывается при регистрации нового типа объекта.

arg_name :

полностью квалифицированное имя объекта, например gtkobject::user_data.

arg_type :

тип аргумента.

arg_flags :

поразрядное-или перечисления gtkargflags. (является ли аргумент settable или gettable, устанавливается ли при конструировании объекта.)

arg_id :

внутренний номер, передаётся в или из "set_arg" и "get_arg" обработчиков объекта.

gtk_object_set_data_by_id ()

void        gtk_object_set_data_by_id       (gtkobject *object,
                                             gquark data_id,
                                             gpointer data);

внимание

gtk_object_set_data_by_id устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_set_qdata().

то же, что и gtk_object_set_data(), но вместо строки принимает gquark, поэтому немного быстрее.

используйте gtk_object_data_try_key() и gtk_object_data_force_id() для определения id из строки.

object :

объект содержащий ассоциации.

data_id :

кварк (quark) ключа.

data :

данные ассоциированные с ключом.

gtk_object_set_data_by_id_full ()

void        gtk_object_set_data_by_id_full  (gtkobject *object,
                                             gquark data_id,
                                             gpointer data,
                                             gtkdestroynotify destroy);

внимание

gtk_object_set_data_by_id_full устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_set_qdata_full().

то же, что и gtk_object_set_data_full(), за исключение м использования gquark вместо строки, что немного быстрее.

используйте gtk_object_data_try_key() и gtk_object_data_force_id() для получения id из строки.

object :

объект содержащий ассоциации.

data_id :

кварк (quark) ключа.

data :

данные связанные с ключом.

destroy :

функция вызываемая при разрушении ассоциации.

gtk_object_get_data_by_id ()

gpointer    gtk_object_get_data_by_id       (gtkobject *object,
                                             gquark data_id);

внимание

gtk_object_get_data_by_id устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_get_qdata().

то же, что и gtk_object_get_data(), за исключением использования gquark вместо строки, что немного быстрее.

используйте gtk_object_data_try_key() и gtk_object_data_force_id() для получения id из строки.

object :

объект содержащий ассоциации.

data_id :

кварк (quark) ключа.

возвращает :

данные если найдены, или null если нет таких данных.

gtk_object_remove_data_by_id ()

void        gtk_object_remove_data_by_id    (gtkobject *object,
                                             gquark data_id);

внимание

gtk_object_remove_data_by_id устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_set_qdata() с null вместо данных.

тоже самое, что и gtk_object_remove_data(), за исключением использования gquark вместо строки, что немного быстрее.

удаляет определённые данные из ассоциированных данных объекта. последующие вызовы gtk_object_get_data() возвратят null.

используйте gtk_object_data_try_key() и gtk_object_data_force_id() для получения id из строки.

object :

объект содержащий ассоциации.

data_id :

кварк (quark) ключа.

gtk_object_remove_no_notify_by_id ()

void        gtk_object_remove_no_notify_by_id
                                            (gtkobject *object,
                                             gquark key_id);

внимание

gtk_object_remove_no_notify_by_id устарела и не должна использоваться во вновь создаваемом коде. вместо неё используйте g_object_steal_qdata().

тоже что и gtk_object_remove_no_notify(), за исключением использования gquark вместо строки, что немного быстрее.

используйте gtk_object_data_try_key() и gtk_object_data_force_id() для получения id из строки.

object :

объект содержащий ассоциации.

key_id :

кварк (quark) ключа.

gtk_object_data_try_key

#define gtk_object_data_try_key     g_quark_try_string

внимание

gtk_object_data_try_key устарела и не должна использоваться во вновь создаваемом коде.

устаревший макрос. игнорируйте его.

gtk_object_data_force_id

#define gtk_object_data_force_id    g_quark_from_string

внимание

gtk_object_data_force_id устарела и не должна использоваться во вновь создаваемом коде.

устаревший макрос. игнорируйте его.

детали свойств

свойство "user-data"

  "user-data"            gpointer              : read / write

анонимный указатель используемых данных (anonymous user data pointer).

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

сигнал "destroy"

void        user_function                  (gtkobject *object,
                                            gpointer   user_data)      : cleanup / no recursion / no hooks

сигнализирует об освобождении всех ссылок на gtkobject. может привести к уничтожению объекта если освободит все ссылки.

object :

объект получающий сигнал.

user_data :

данные используемые для установки при подключении обработчика сигнала.

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

gobject