Справочное описание GObject |
---|
Версия GLib 2.13.7
Замечания по поводу перевода присылать sergeyvp@gmail.com
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> GTypeModule; GTypeModuleClass; gboolean g_type_module_use (GTypeModule *module); void g_type_module_unuse (GTypeModule *module); void g_type_module_set_name (GTypeModule *module, const gchar *name); GType g_type_module_register_type (GTypeModule *module, GType parent_type, const gchar *type_name, const GTypeInfo *type_info, GTypeFlags flags); void g_type_module_add_interface (GTypeModule *module, GType instance_type, GType interface_type, const GInterfaceInfo *interface_info); GType g_type_module_register_enum (GTypeModule *module, const gchar *name, const GEnumValue *const _static_values); GType g_type_module_register_flags (GTypeModule *module, const gchar *name, const GFlagsValue *const _static_values); #define G_DEFINE_DYNAMIC_TYPE (TN, t_n, T_P) #define G_DEFINE_DYNAMIC_TYPE_EXTENDED (TypeName, type_name, TYPE_PARENT, flags, CODE)
GTypeModule обеспечивает простую реализацию интерфейса
GTypePlugin.
Моделью GTypeModule является динамически загружаемый модуль
который реализует некоторое количество реализаций типов и интерфейсов. Когда модуль загружен, происходит регистрация его типов и интерфейсов
используя g_type_module_register_type()
и
g_type_module_add_interface()
.
Пока экземпляры этих типов и интерфейсов используются, модуль остаётся загруженным.
Когда типы и интерфейсы больше не нужны, модуль может быть выгружен.
Если типы и интерфейсы потребовались снова, модуль перезагружается.
Помните что последний сброс ссылки не может произойти в коде модуля,
так как это привело бы к выгрузке кода вызываемой программой прежде чем
g_object_unref()
вернёт значение.
Отслеживание загружен модуль или нет выполняется счётчиком использования - начиная с нуля,
всегда когда счётчик больше нуля, модуль загружен. Счётчик использования внутренне поддерживается системой типов,
но так же может явно контролироваться с помощью
g_type_module_use()
и
g_type_module_unuse()
.
Обычно когда загружается модуль для первого типа,
g_type_module_use()
будет использована чтобы при загрузке могли инициализироваться его типы. Немного позже, когда модуль больше не должен быть загружен
кроме как для реализации типа который содержит, вызывается g_type_module_unuse()
.
GTypeModule фактически не обеспечивает ни загрузки ни выгрузки модуля. Для создания специфичного модуля вы должны унаследовать GTypeModule и реализовать загрузку и выгрузку функций в GTypeModuleClass.
typedef struct { gchar *name; } GTypeModule;
Члены сструктуры GTypeModule не имеют непосредственного доступа, исключая поле
name
.
gchar *name ; |
имя модуля |
typedef struct { GObjectClass parent_class; gboolean (* load) (GTypeModule *module); void (* unload) (GTypeModule *module); } GTypeModuleClass;
Для осуществления динамической загрузки типов основанных на
GTypeModule,
функции load
и unload
должны быть реализованы в GTypeModuleClass.
GObjectClass parent_class ; |
родительский класс |
load () |
загружает модуль и регистрирует один тип или больше используя
g_type_module_register_type() .
|
unload () |
выгружает модуль |
gboolean g_type_module_use (GTypeModule *module);
Увеличивает количество использований GTypeModule на единицу. Если количество использований перед этим было 0, модуль будет загружен.
module : |
GTypeModule |
Возвращает : |
FALSE
если необходимая загрузка модуля неудалась.
|
void g_type_module_unuse (GTypeModule *module);
Уменьшает количество использований GTypeModule на единицу. Если результатом уменьшения будет 0, модуль выгружается. (Однако, GTypeModule не будет освобождена, а регистрация типов связанных с GTypeModule не отменяется. Как только GTypeModule инициализирована, она будет существовать всегда).
module : |
GTypeModule |
void g_type_module_set_name (GTypeModule *module, const gchar *name);
Устанавливает имя для GTypeModule
module : |
GTypeModule. |
name : |
Удобное для чтения имя используемое в сообщениях об ошибках. |
GType g_type_module_register_type (GTypeModule *module, GType parent_type, const gchar *type_name, const GTypeInfo *type_info, GTypeFlags flags);
Находит или регистрирует тип который реализуется специфичным типовым модулем. Если тип с именем
type_name
был предварительно зарегистрирован, возвращается
GType идентифицирующий тип, иначе тип вновь регистрируется и
возвращается результирующий GType идентификатор.
Когда перерегистрируется тип (обычно потому что модуль выгружен а зтем загружен снова, и переинициализирован),
module
и parent_type
должны быть такими же как предыдущие.
Пока любые экземпляры типа существуют, модуль типа не будет выгружен.
module : |
GTypeModule |
parent_type : |
тип для родительского класса |
type_name : |
имя для типа |
type_info : |
структура типовой информации |
flags : |
поле флажков обеспечивающих детали о типе |
Возвращает : | новый или существующий ID типа |
void g_type_module_add_interface (GTypeModule *module, GType instance_type, GType interface_type, const GInterfaceInfo *interface_info);
Регистрирует дополнительный интерфейс для типа, у которого уже есть интерфейс в данном типовом модуле. Если интерфейс уже был зарегистрирован для типа в данном модуле, ничего не происходит.
Пока существуют любые интерфейсы типа, типовой модуль не будет выгружен.
module : |
GTypeModule |
instance_type : |
тип к которому добавляется интерфейс. |
interface_type : |
интерфейсный тип для добавления |
interface_info : |
структура типовой информации |
GType g_type_module_register_enum (GTypeModule *module, const gchar *name, const GEnumValue *const _static_values);
находит или регистрирует перечисление которое реализуется с помощью специфичного типового модуля.
Если тип с именем type_name
был предварительно зарегистрирован,
возвращается GType идентификатор для типа, иначе тип вновь
регистрируется и возвращается результирующий GType идентификатор.
Пока существуют любые экземпляры типа, типовой модуль не выгружается.
module : |
GTypeModule |
name : |
имя для типа |
_static_values : |
|
Возвращает : | новый или существующий ID типа |
Начиная с версии 2.6
GType g_type_module_register_flags (GTypeModule *module, const gchar *name, const GFlagsValue *const _static_values);
Находит или регистрирует флаги типа который реализован специфичным типовым модулем.
Если тип с именем type_name
был предварительно зарегистрирован,
возвращается GType идентификатор типа, иначе тип вновь
регистрируется и возвращается GType идентификатор.
Пока существует любой экземпляр типа, модуль не будет выгружен.
module : |
GTypeModule |
name : |
имя для типа |
_static_values : |
|
Возвращает : | новый или существующий ID типа |
Начиная с версии 2.6
#define G_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P) G_DEFINE_DYNAMIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
Удобный макрос для динамической реализации типа, который объявляет функцию инициализации класса, функцию инициализации экземпляра
(смотрите GTypeInfo для информации об этом)
и статичную переменную с именем t_n
_parent_class указывающим на родительский класс.
Кроме того, он определяет *
и статичную функцию
_get_type()
*
для использования в вашей
_register_type()
.
Смотрите module_init()
G_DEFINE_DYNAMIC_TYPE_EXTENDED()
для примера.
TN : |
Имя нового типа, в стиле CamelCase. |
t_n : |
Имя нового типа, в нижнем регистре со словами разделёнными символом '_'. |
T_P : |
GType родительского типа. |
Начиная с версии 2.14
#define G_DEFINE_DYNAMIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE)
Более общая версия G_DEFINE_DYNAMIC_TYPE()
которая
позволяет определять GTypeFlags и произвольный код.
G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, gtk_gadget, GTK_TYPE_THING, 0, G_IMPLEMENT_INTERFACE (TYPE_GIZMO, gtk_gadget_gizmo_init));разворачивается до
static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); static void gtk_gadget_class_finalize (GtkGadgetClass *klass); static gpointer gtk_gadget_parent_class = NULL; static GType gtk_gadget_type_id = 0; static void gtk_gadget_class_intern_init (gpointer klass) { gtk_gadget_parent_class = g_type_class_peek_parent (klass); gtk_gadget_class_init ((GtkGadgetClass*) klass); } GType gtk_gadget_get_type (void) { return gtk_gadget_type_id; } static void gtk_gadget_register_type (GTypeModule *type_module) { const GTypeInfo g_define_type_info = { sizeof (GtkGadgetClass), (GBaseInitFunc) NULL, (GBaseFinalizeFunc) NULL, (GClassInitFunc) gtk_gadget_class_intern_init, (GClassFinalizeFunc) gtk_gadget_class_finalize, NULL, /* class_data */ sizeof (GtkGadget), 0, /* n_preallocs */ (GInstanceInitFunc) gtk_gadget_init, NULL /* value_table */ }; gtk_gadget_type_id = g_type_module_register_type (type_module, GTK_TYPE_THING, GtkGadget, &g_define_type_info, (GTypeFlags) flags); { const GInterfaceInfo g_implement_interface_info = { (GInterfaceInitFunc) gtk_gadget_gizmo_init }; g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); } }
TypeName : |
Имя нового типа, в стиле CamelCase. |
type_name : |
Имя нового типа в нижнем регистре, со словами разделёнными символом '_'. |
TYPE_PARENT : |
GType родительского типа. |
flags : |
GTypeFlags помещаемые в
g_type_register_static()
|
CODE : |
Произвольный код вставляемый в функцию *_get_type() .
|
Начиная с версии 2.14
GTypePlugin | Интерфейс загрузчика абстрактного типа. |
GModule | Портируемый механизм для динамической загрузки модулей. |
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> GTypePlugin; GTypePluginClass; void (*GTypePluginUse) (GTypePlugin *plugin); void (*GTypePluginUnuse) (GTypePlugin *plugin); void (*GTypePluginCompleteTypeInfo) (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table); void (*GTypePluginCompleteInterfaceInfo) (GTypePlugin *plugin, GType instance_type, GType interface_type, GInterfaceInfo *info); void g_type_plugin_use (GTypePlugin *plugin); void g_type_plugin_unuse (GTypePlugin *plugin); void g_type_plugin_complete_type_info (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table); void g_type_plugin_complete_interface_info (GTypePlugin *plugin, GType instance_type, GType interface_type, GInterfaceInfo *info);
Система типов GObject поддерживает динамическую загрузку типов. Интерфейс GTypePlugin используется для обработки жизненного цикла динамически загружаемых типов. Это происходит следующим образом:
Сначала тип внедряется (обычно после загрузки модуля в первый раз, или вашим основным приложением,
которое знает какие модули внедряют какие типы), например:
new_type_id = g_type_register_dynamic (parent_type_id,
"TypeName",
new_type_plugin,
type_flags);
где new_type_plugin
это реализация интерфейса
GTypePlugin.
На реализованный тип создаётся ссылка, например через
g_type_class_ref()
или через
g_type_create_instance()
(вызывается функцией g_object_new()
)
или как описано выше выполняя наследование типа из new_type_id
.
Это заставит систему типов загрузить реализацию типа вызвав
g_type_plugin_use()
и
g_type_plugin_complete_type_info()
для
new_type_plugin
.
В некоторой точке реализация типа больше не требуется, например после
g_type_class_unref()
или
g_type_free_instance()
(вызывается когда количество ссылок экземпляра сброшено до нуля).
Это заставит систему типов сбросить информацию найденную с помощью
g_type_plugin_complete_type_info()
и зтем вызвать
g_type_plugin_unuse()
для
new_type_plugin
.
Цикл может повторятся от второго шага.
В основном вы должны реализовать GTypePlugin тип
который несёт use_count, как только use_count станет единицей, вы должны загрузить реализацию для успешной обработки наступающего вызова
g_type_plugin_complete_type_info()
.
Позже, возможно после последующих использованных/неиспользованных вызовов, как только use_count сброшен до 0, вы можете выгрузить реализацию
снова. Система типов гарантированно вызовет
g_type_plugin_use()
и
g_type_plugin_complete_type_info()
снова
когда тип потребуется опять.
GTypeModule это реализация GTypePlugin в которой уже реализованы большинство необходимого для фактической загрузки или выгрузки модуля. Это даже обрабатывает многократную регистрацию типов в модуле.
typedef struct _GTypePlugin GTypePlugin;
Декларация типа GTypePlugin используется как метка для объектов которые реализуют интерфейс GTypePlugin.
typedef struct { GTypePluginUse use_plugin; GTypePluginUnuse unuse_plugin; GTypePluginCompleteTypeInfo complete_type_info; GTypePluginCompleteInterfaceInfo complete_interface_info; } GTypePluginClass;
Интерфейс GTypePlugin используется системой типов для обработки жизненного цикла динамически загружаемых типов.
GTypePluginUse use_plugin ; |
Увеличивает количество используемых plugin. |
GTypePluginUnuse unuse_plugin ; |
Уменьшает количество используемых plugin. |
GTypePluginCompleteTypeInfo complete_type_info ; |
Заполняет сструктуры GTypeInfo и
GTypeValueTable для типа.
Сструктуры инициализируются с помощью memset(s, 0, sizeof (s)) перед вызовом этой функции.
|
GTypePluginCompleteInterfaceInfo complete_interface_info ; |
Заполняет недостающие части GInterfaceInfo
для интерфейса. Сструктуры инициализируются с помощью memset(s, 0, sizeof (s)) перед вызовом этой
функции.
|
void (*GTypePluginUse) (GTypePlugin *plugin);
Тип use_plugin
функции
GTypePluginClass, которая вызывается для увеличения
используемого количества plugin
.
plugin : |
GTypePlugin чьё используемое количество должно быть увеличено |
void (*GTypePluginUnuse) (GTypePlugin *plugin);
Тип unuse_plugin
функции GTypePluginClass.
plugin : |
GTypePlugin чьё используемое количество должно быть уменьшено |
void (*GTypePluginCompleteTypeInfo) (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table);
Тип complete_type_info
функции GTypePluginClass.
plugin : |
GTypePlugin |
g_type : |
GType чья информация заполнена |
info : |
GTypeInfo структура для заполнения |
value_table : |
GTypeValueTable для заполнения |
void (*GTypePluginCompleteInterfaceInfo) (GTypePlugin *plugin, GType instance_type, GType interface_type, GInterfaceInfo *info);
Тип complete_interface_info
функции GTypePluginClass.
plugin : |
GTypePlugin |
instance_type : |
GType инстанциируемого типа к которому добавляется интерфейс |
interface_type : |
GType интерфейса чья информация заполнена |
info : |
GInterfaceInfo для заполнения |
void g_type_plugin_use (GTypePlugin *plugin);
Вызывает use_plugin
функцию из
GTypePluginClass принадлежащей
plugin
.
Нет необходимости использовать эту функцию вне системы типов GObject непосредственно.
plugin : |
GTypePlugin |
void g_type_plugin_unuse (GTypePlugin *plugin);
Вызывает unuse_plugin
функцию из
GTypePluginClass принадлежащей
plugin
.
Нет необходимости использовать эту функцию вне системы типов GObject непосредственно.
plugin : |
a GTypePlugin |
void g_type_plugin_complete_type_info (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table);
Вызывает complete_type_info
функцию из
GTypePluginClass принадлежащей
plugin
.
Нет необходимости использовать эту функцию вне системы типов GObject непосредственно.
plugin : |
GTypePlugin |
g_type : |
GType чья информация заполняется |
info : |
GTypeInfo структура для заполнения |
value_table : |
GTypeValueTable для заполнения |
void g_type_plugin_complete_interface_info (GTypePlugin *plugin, GType instance_type, GType interface_type, GInterfaceInfo *info);
Вызывает complete_interface_info
функцию из
GTypePluginClass принадлежащей
plugin
.
Нет необходимости использовать эту функцию вне системы типов GObject непосредственно.
plugin : |
GTypePlugin |
instance_type : |
GType инстанциируемого типа к которому добавляется интерфейс |
interface_type : |
GType интерфейса чья информация заполняется |
info : |
GInterfaceInfo для заполнения |
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
GObject, and its lower-level type system, GType, are used by GTK+ and most GNOME libraries to provide:
object-oriented C-based APIs and
automatic transparent API bindings to other compiled or interpreted languages.
A lot of programmers are used to work with compiled-only or dynamically interpreted-only languages and do not understand the challenges associated with cross-language interoperability. This introduction tries to provide an insight into these challenges. describes briefly the solution choosen by GLib.
The following chapters go into greater detail into how GType and GObject work and how you can use them as a C programmer. It is useful to keep in mind that allowing access to C objects from other interpreted languages was one of the major design goals: this can often explain the sometimes rather convoluted APIs and features present in this library.
One could say (I have seen such definitions used in some textbooks on programming language theory) that a programming language is merely a way to create data types and manipulate them. Most languages provide a number of language-native types and a few primitives to create more complex types based on these primitive types.
In C, the language provides types such as char, long, pointer. During compilation of C code, the compiler maps these language types to the compiler's target architecture machine types. If you are using a C interpreter (I have never seen one myself but it is possible :), the interpreter (the program which interprets the source code and executes it) maps the language types to the machine types of the target machine at runtime, during the program execution (or just before execution if it uses a Just In Time compiler engine).
Perl and Python which are interpreted languages do not really provide type definitions similar to those used by C. Perl and Python programmers manipulate variables and the type of the variables is decided only upon the first assignment or upon the first use which forces a type on the variable. The interpreter also often provides a lot of automatic conversions from one type to the other. For example, in Perl, a variable which holds an integer can be automatically converted to a string given the required context:
my $tmp = 10; print "this is an integer converted to a string:" . $tmp . "\n";
Of course, it is also often possible to explicitely specify conversions when the default conversions provided by the language are not intuitive.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
C API определяет набор функций и глобальные переменные которые обычно экспортируются из бинарных. C функции имеют произвольное количество аргументов и одно возвращаемое значение. Каждая функция идентифицируется уникальным именем функции и набором C типов которые описывают аргументы функции и возвращаемое значение. Глобальные переменные экспортируемого API также идентифицируются их именем и типом.
Таким образом C API определяется набором имён с которыми связаны наборы типов. Если вам известны правила вызова функции и отображение C типов в машинные типы используемые на вашей платформе, вы можете транслировать имя каждой функции чтобы найти код связанный с этой функцией в распределённой памяти, а зтем создать правильный список аргументов для функции. Наконец, всё что вы должны сделать это переключить вызов целевой C функции со списком аргументов.
Для дальнейшего обсуждения, рассмотрим простую C функцию и связанный 32 bit x86 ассемблерный код сгенерированный gcc на моей linux машине:
static void function_foo (int foo) {} int main (int argc, char *argv[]) { function_foo (10); return 0; } push $0xa call 0x80482f4 <function_foo>
Ассемблерный код показанный выше достаточно прямолинейный: первая инструкция помещает
шестнадцатеричное значение 0xa (числовое значение 10) как 32 bit целочисленное в стек и вызывает
function_foo
. Как вы видите, вызов C функции осуществлён gcc непосредственным вызовом функции
(вероятно это самая быстрая из возможных реализаций).
Теперь, скажем нам нужно вызвать C функцию function_foo
из
программы написанной на языке python. Чтобы это сделать, интерпретатору python необходимо:
Найти расположение функции. Это вероятно означает поиск в бинарном коде сгенерированном C компилятором который экспортирован этой функцией.
Загрузка функции в исполняемую память.
Конвертация python параметров в C-совместимые параметры перед вызовом функции.
Вызов функции с соблюдением соглашения о вызовах
Конвертация возвращаемого значения C функции в python-совместимую переменную для возвращения её в python код.
Процессс описанный выше довольно сложен и есть много способов сделать его полностью автоматическим и прозрачным для C и Python программистов:
Первое решение заключается в ручном написании совмещающего кода, для каждой экспортируемой или импортируемой функции, который выполняет конвертацию параметров python в C и конвертацию возвращаемого значения C в python. Этот совмещающий код связывается с интерпретатором который позволяет программам вызывать python функции делегирующие работу в C функцию.
Другой, намного лучше, автоматически генерировать совмещающий код, для каждой экспортируемой или импортируемой функции, со специальным компилятором который читает оригинальную сигнатуру функции.
Решение используемое GLib заключается в применении GType библиотеки которая содержит во время выполнения описание всех объектов которыми манипулирует программист. Эта, так называемая библиотека динамического типа [1], используется специальным основным кодом совмещения для автоматической конвертации параметров функции и согласует вызов функции между разными областями исполнения.
Самое большое преимущество реализуемое GType в том, что код совмещения находящийся в границе области исполнения пишется один раз: схема ниже демонстрирует это более ясно.
В настоящее время, существует по крайней мере основной код совмещения для Python и Perl, который позволяет использовать
C объекты написанные с помощью GType непосредственно в Python или Perl, с минимальными доработками: нет необходимости генерировать
огромное количество кода совмещения вручную или автоматически.
Хотя цель была достаточно похвальной, главной задачей является в целом библиотека GType/GObject. C программисты вероятно будут озадачены сложностью особенностей демонстрируемых в следующих главах, если они забудут, что библиотека GType/GObject была разработана не только для объектно-ориентированных улучшений C прграммистам, но и для прозрачной крос-языковой функциональной совместимости.
[1] Есть многочисленные различные реализации систем динамических типов: все C++ компиляторы имеют такую систему, Java и .NET имеют её тоже. Система динамического типа позволяет вам получать информацию о каждом созданном динамическом объекте. Это может быть реализовано с помощью определённой для процесса базы данных: каждый новый объект создаёт регистры характеристик связанного с ним типа в системе. так же это может быть реализовано интерфейсом самоанализа. Общим пунктом между всеми этими разными системами типа и реализациями является то, что они позволяют вам делать запрос метаданных динамического объекта.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
A type, as manipulated by the Glib type system, is much more generic than what is usually understood as an Object type. It is best explained by looking at the structure and the functions used to register new types in the type system.
typedef struct _GTypeInfo GTypeInfo; struct _GTypeInfo { /* interface types, classed types, instantiated types */ guint16 class_size; GBaseInitFunc base_init; GBaseFinalizeFunc base_finalize; /* classed types, instantiated types */ GClassInitFunc class_init; GClassFinalizeFunc class_finalize; gconstpointer class_data; /* instantiated types */ guint16 instance_size; guint16 n_preallocs; GInstanceInitFunc instance_init; /* value handling */ const GTypeValueTable *value_table; }; GType g_type_register_static (GType parent_type, const gchar *type_name, const GTypeInfo *info, GTypeFlags flags); GType g_type_register_fundamental (GType type_id, const gchar *type_name, const GTypeInfo *info, const GTypeFundamentalInfo *finfo, GTypeFlags flags);
g_type_register_static
and
g_type_register_fundamental
are the C functions, defined in
gtype.h
and implemented in gtype.c
which you should use to register a new GType in the program's type system.
It is not likely you will ever need to use
g_type_register_fundamental
(you have to be Tim Janik
to do that) but in case you want to, the last chapter explains how to create
new fundamental types.
[2]
Fundamental types are top-level types which do not derive from any other type
while other non-fundamental types derive from other types.
Upon initialization by g_type_init
, the type system not
only initializes its internal data structures but it also registers a number of core
types: some of these are fundamental types. Others are types derived from these
fundamental types.
Fundamental and non-Fundamental types are defined by:
class size: the class_size field in GTypeInfo.
class initialization functions (C++ constructor): the base_init and class_init fields in GTypeInfo.
class destruction functions (C++ destructor): the base_finalize and class_finalize fields in GTypeInfo.
instance size (C++ parameter to new): the instance_size field in GTypeInfo.
instanciation policy (C++ type of new operator): the n_preallocs field in GTypeInfo.
copy functions (C++ copy operators): the value_table field in GTypeInfo.
type characteristic flags: GTypeFlags.
Fundamental types are also defined by a set of GTypeFundamentalFlags
which are stored in a GTypeFundamentalInfo.
Non-Fundamental types are furthermore defined by the type of their parent which is
passed as the parent_type parameter to g_type_register_static
and g_type_register_dynamic
.
The major common point between all glib types (fundamental and non-fundamental, classed and non-classed, instantiable and non-instantiable) is that they can all be manipulated through a single API to copy/assign them.
The GValue structure is used as an abstract container for all of these
types. Its simplistic API (defined in gobject/gvalue.h
) can be
used to invoke the value_table functions registered
during type registration: for example g_value_copy
copies the
content of a GValue to another GValue. This is similar
to a C++ assignment which invokes the C++ copy operator to modify the default
bit-by-bit copy semantics of C++/C structures/classes.
The following code shows how you can copy around a 64 bit integer, as well as a GObject
instance pointer (sample code for this is located in the source tarball for this document in
sample/gtype/test.c
):
static void test_int (void) { GValue a_value = {0, }; GValue b_value = {0, }; guint64 a, b; a = 0xdeadbeaf; g_value_init (&a_value, G_TYPE_UINT64); g_value_set_uint64 (&a_value, a); g_value_init (&b_value, G_TYPE_UINT64); g_value_copy (&a_value, &b_value); b = g_value_get_uint64 (&b_value); if (a == b) { g_print ("Yay !! 10 lines of code to copy around a uint64.\n"); } else { g_print ("Are you sure this is not a Z80 ?\n"); } } static void test_object (void) { GObject *obj; GValue obj_vala = {0, }; GValue obj_valb = {0, }; obj = g_object_new (MAMAN_BAR_TYPE, NULL); g_value_init (&obj_vala, MAMAN_BAR_TYPE); g_value_set_object (&obj_vala, obj); g_value_init (&obj_valb, G_TYPE_OBJECT); /* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference. This function thus calls g_object_ref. It is interesting to note that the assignment works here because MAMAN_BAR_TYPE is a G_TYPE_OBJECT. */ g_value_copy (&obj_vala, &obj_valb); g_object_unref (G_OBJECT (obj)); g_object_unref (G_OBJECT (obj)); }
The important point about the above code is that the exact semantic of the copy calls is undefined since they depend on the implementation of the copy function. Certain copy functions might decide to allocate a new chunk of memory and then to copy the data from the source to the destination. Others might want to simply increment the reference count of the instance and copy the reference to the new GValue.
The value_table used to specify these assignment functions is defined in
gtype.h
and is thoroughly described in the
API documentation provided with GObject (for once ;-) which is why we will
not detail its exact semantics.
typedef struct _GTypeValueTable GTypeValueTable; struct _GTypeValueTable { void (*value_init) (GValue *value); void (*value_free) (GValue *value); void (*value_copy) (const GValue *src_value, GValue *dest_value); /* varargs functionality (optional) */ gpointer (*value_peek_pointer) (const GValue *value); gchar *collect_format; gchar* (*collect_value) (GValue *value, guint n_collect_values, GTypeCValue *collect_values, guint collect_flags); gchar *lcopy_format; gchar* (*lcopy_value) (const GValue *value, guint n_collect_values, GTypeCValue *collect_values, guint collect_flags); };
Interestingly, it is also very unlikely you will ever need to specify a value_table during type registration because these value_tables are inherited from the parent types for non-fundamental types which means that unless you want to write a fundamental type (not a great idea !), you will not need to provide a new value_table since you will inherit the value_table structure from your parent type.
[2]
Please, note that there exist another registration function: the
g_type_register_dynamic
. We will not discuss this
function here since its use is very similar to the _static
version.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Для определения что интерфейс требует присутствия других интерфейсов при реализации, GObject вводит понятие предпосылки: возможность связать список необходимых как условие интерфейсов с интерфейсом. Например, если объект A хочет реализовать интерфейс I1, и если интерфейс I1 имеет предпосылку на интерфейс I2, A реализует оба интерфейса I1 и I2.
Механизм описанный выше на практике очень похож на Java, интерфейс I1 дополняется интерфейсом I2. Пример ниже показывает GObject эквивалент:
type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbar", &info, 0); /* Создаём интерфейс MamanIbar требующий интерфейс MamanIbaz. */ g_type_interface_add_prerequisite (type, MAMAN_TYPE_IBAZ);
Код показанный выше добавляет интерфейс MamanIbaz в список предпосылок MamanIbar в то время как код ниже показывает как реализовать оба интерфейса и зарегистрировать их реализацию:
static void ibar_do_another_action (MamanBar *self) { g_print ("Bar implementation of IBar interface Another Action: 0x%x.\n", self->instance_member); } static void ibar_interface_init (gpointer g_iface, gpointer iface_data) { MamanIbarInterface *iface = (MamanIbarInterface *)g_iface; iface->do_another_action = (void (*) (MamanIbar *self))ibar_do_another_action; } static void ibaz_do_action (MamanBar *self) { g_print ("Bar implementation of IBaz interface Action: 0x%x.\n", self->instance_member); } static void ibaz_interface_init (gpointer g_iface, gpointer iface_data) { MamanIbazInterface *iface = (MamanIbazInterface *)g_iface; iface->do_action = (void (*) (MamanIbaz *self))ibaz_do_action; } static void bar_instance_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = (MamanBar *)instance; self->instance_member = 0x666; } GType maman_bar_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBarClass), NULL, /* base_init */ NULL, /* base_finalize */ NULL, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBar), 0, /* n_preallocs */ bar_instance_init /* instance_init */ }; static const GInterfaceInfo ibar_info = { (GInterfaceInitFunc) ibar_interface_init, /* interface_init */ NULL, /* interface_finalize */ NULL /* interface_data */ }; static const GInterfaceInfo ibaz_info = { (GInterfaceInitFunc) ibaz_interface_init, /* interface_init */ NULL, /* interface_finalize */ NULL /* interface_data */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBarType", &info, 0); g_type_add_interface_static (type, MAMAN_TYPE_IBAZ, &ibaz_info); g_type_add_interface_static (type, MAMAN_TYPE_IBAR, &ibar_info); } return type; }
Важно обратить внимание что порядок, в котором реализованные интерфейсы добавляются к основному объекту, не случаен:
g_type_add_interface_static
должна быть вызвана сначала для интерфейсов которые не имеют никаких предпосылок а зтем для остальных.
Полный исходный код, показывающий как определить интерфейс MamanIbar который требует MamanIbaz и как реализовать
интерфейс MamanIbar, расположен в sample/interface/maman-ibar.{h|c}
и sample/interface/maman-bar.{h|c}
.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Сигналы GObject могут использоваться для обеспечения большей гибкости чем механизм уведомления об изменении файла рассмотренный в предыдущем примере. Одна из ключевых идей - сделать процесс записи данных в файл частью процесса эмиссии сигнала позволив пользователю получать уведомления либо перед либо после записи данных в файл.
Для интеграции процесса записи данных в файл с механизмом эмиссии сигнала, мы можем зарегистрировать классовое замыкание по умолчанию для этого сигнала которое будет вызываться в течение эмиссии сигнала, просто как любой другой подключаемый пользователем обработчик сигнала.
Первый шаг реализации этой идеи - изменить сигнатуру сигнала: мы должны разместить буфер для записи и его размер.
Для этого мы используем собственный маршаллер который будет сгенерирован с помощью специальной утилиты glib.
Таким образом создаём файл с именем marshall.list
который содержит следующую строку:
VOID:POINTER,UINT
и используем Makefile поставляемый в sample/signal/Makefile
для генерации файла с именем
maman-file-complex-marshall.c
. Этот C файл включаем в maman-file-complex.c
.
Как только маршаллер создан, мы регистрируем сигнал и его маршаллер в функции class_init объекта
MamanFileComplex (полный исходный код этого объекта включён в
sample/signal/maman-file-complex.{h|c}
):
GClosure *default_closure; GType param_types[2]; default_closure = g_cclosure_new (G_CALLBACK (default_write_signal_handler), (gpointer)0xdeadbeaf /* user_data */, NULL /* destroy_data */); param_types[0] = G_TYPE_POINTER; param_types[1] = G_TYPE_UINT; klass->write_signal_id = g_signal_newv ("write", G_TYPE_FROM_CLASS (g_class), G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS, default_closure /* class closure */, NULL /* accumulator */, NULL /* accu_data */, maman_file_complex_VOID__POINTER_UINT, G_TYPE_NONE /* return_type */, 2 /* n_params */, param_types /* param_types */);
Код показанный выше создаёт замыкание которое содержит код полной записи файла. Это замыкание регистрируется как значение по умолчанию class_closure вновь созданного сигнала.
Конечно, вы должны полностью реализовать код для замыкания по умолчанию, так как я создал только скелет:
static void default_write_signal_handler (GObject *obj, guint8 *buffer, guint size, gpointer user_data) { g_assert (user_data == (gpointer)0xdeadbeaf); /* Здесь мы вызываем реальную запись файла. */ g_print ("default signal handler: 0x%x %u\n", buffer, size); }
Наконец, код клиента должен вызвать функцию maman_file_complex_write
которая переключает
эмиссию сигнала:
void maman_file_complex_write (MamanFileComplex *self, guint8 *buffer, guint size) { /* trigger event */ g_signal_emit (self, MAMAN_FILE_COMPLEX_GET_CLASS (self)->write_signal_id, 0, /* details */ buffer, size); }
Клиентский код (представленный ниже и в sample/signal/test.c
) может теперь подключать обработчики сигнала
перед и после завершения записи файла: так как обработчик сигнала по умолчанию, который делает саму запись, выполняется в течение фазы
RUN_LAST эмиссии сигнала, он будет выполнен после всех обработчиков подключенных с помощью
g_signal_connect
и перед обработчиками подключенными с помощью
g_signal_connect_after
.
Если вы намерены написать GObject который издаёт сигналы, я рекомендовал бы вам создавать все ваши сигналы
с G_SIGNAL_RUN_LAST чтобы пользователи могли иметь максимальную гибкость при получении события.
Здесь мы объединили его с G_SIGNAL_NO_RECURSE и G_SIGNAL_NO_HOOKS чтобы гарантировать что пользователи не будут делать ничего
сверхъестественного с нашим GObject. Я строго советую вам делать тоже самое если вы действительно не знаете почему
(если бы вы знали внутреннюю работу GSignal вы бы это не читали).
static void complex_write_event_before (GObject *file, guint8 *buffer, guint size, gpointer user_data) { g_assert (user_data == NULL); g_print ("Complex Write event before: 0x%x, %u\n", buffer, size); } static void complex_write_event_after (GObject *file, guint8 *buffer, guint size, gpointer user_data) { g_assert (user_data == NULL); g_print ("Complex Write event after: 0x%x, %u\n", buffer, size); } static void test_file_complex (void) { guint8 buffer[100]; GObject *file; file = g_object_new (MAMAN_FILE_COMPLEX_TYPE, NULL); g_signal_connect (G_OBJECT (file), "write", (GCallback)complex_write_event_before, NULL); g_signal_connect_after (G_OBJECT (file), "write", (GCallback)complex_write_event_after, NULL); maman_file_complex_write (MAMAN_FILE_COMPLEX (file), buffer, 50); g_object_unref (G_OBJECT (file)); }
Код выше генерирует следующий вывод на моей машине:
Complex Write event before: 0xbfffe280, 50 default signal handler: 0xbfffe280 50 Complex Write event after: 0xbfffe280, 50
По многим историческим причинам связанным с тем что предок GObject используется для работы в GTK+ версий 1.x,
есть намного более простой[17]
способ создания сигнала с обработчиком по умолчанию, чем создавать замыкание вручную и использовать
g_signal_newv
.
Например, g_signal_new
может использоваться для создания
сигнала который использует обработчик по умолчанию сохранённый в структуре класса объекта. Конкретнее, структура класса содержит
указатель функции который доступен в течение эмиссии сигнала для вызова обработчика по умолчанию, а пользователь как ожидается
обеспечит для g_signal_new
смещение сначала классовой
сструктуры для указания функции.[18]
Следующий код показывает декларацию классовой сструктуры MamanFileSimple которая содержит указатель
write
функции.
struct _MamanFileSimpleClass { GObjectClass parent; guint write_signal_id; /* обработчик сигнала по умолчанию */ void (*write) (MamanFileSimple *self, guint8 *buffer, guint size); };
Указатель write
функции инициализированной в функции class_init объекта для
default_write_signal_handler
:
static void maman_file_simple_class_init (gpointer g_class, gpointer g_class_data) { GObjectClass *gobject_class = G_OBJECT_CLASS (g_class); MamanFileSimpleClass *klass = MAMAN_FILE_SIMPLE_CLASS (g_class); klass->write = default_write_signal_handler;
Наконец, сигнал создаётся с помощью g_signal_new
в той же функции class_init:
klass->write_signal_id = g_signal_new ("write", G_TYPE_FROM_CLASS (g_class), G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (MamanFileSimpleClass, write), NULL /* accumulator */, NULL /* accu_data */, maman_file_complex_VOID__POINTER_UINT, G_TYPE_NONE /* return_type */, 2 /* n_params */, G_TYPE_POINTER, G_TYPE_UINT);
Примечателен здесь 4-ый аргумент функции: он рассчитывается с помощью макроса G_STRUCT_OFFSET
указывая смещение члена write от начала классовой сструктуры
MamanFileSimpleClass.[19]
Не смотря на то, что полный код для этого обработчика по умолчанию выглядит меньше clutered как показано в
sample/signal/maman-file-simple.{h|c}
, он содержит много тонкостей.
Основная тонкость которую должен знать каждый - сигнатура обработчика по умолчанию созданного таким способом
не имеет аргумента user_data:
default_write_signal_handler
в
sample/signal/maman-file-complex.c
отличается от
sample/signal/maman-file-simple.c
.
Если вы не знаете какой метод использовать, я советовал бы вам второй который вызывает
g_signal_new
а не
g_signal_newv
:
он лучше для написания кода который похож на большую часть кода GTK+/GObject чем делать это собственным способом.
Однако теперь вы знаете как это сделать.
[17] Я лично думаю что этот метод ужасно запутанный: он добавляет новую неопределённость которая излишне усложняет код. Однако, раз этот метод широко используется во всём коде GTK+ и GObject, читатель должен об этом знать. Причина по которой этот метод используется в GTK+ связана с фактом что предок GObject не обеспечивал других способов создания сигналов с обработчиками по умолчанию. Некоторые люди пытались оправдать этот способ тем что он быстрее и лучше (У меня большие сомнения по поводу утверждения о быстроте. Честно говоря, и фраза о "лучше" тоже большая для меня загадка ;-). Я думаю что большинство копируют похожий код и не задумываются над этим. Вероятно лучше оставить эти специфичные пустяки в области хакерских легенд...
[18] Я хотел бы заметить что причина по которой обработчик сигнала по умолчанию везде именуется как class_closure заключается в том что фактически это действительно указатель функции хранящийся в классовой структуре.
[19] GSignal использует это смещение для создания специальной оболочки замыкания которая сначала получает целевой указатель функции перед её вызовом.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Теперь когда вы знаете как создавать сигналы которые пользователь может легко подключать в любой точке эмиссии сигнала благодаря
g_signal_connect
,
g_signal_connect_after
и G_SIGNAL_RUN_LAST,
пришло время изучить как ваши пользователи могут заморочить вас. Это интересно, чтобы знать как вы сами можете заморочить
других людей.
Что заставит вас чувствовать себя хорошо.
Пользователи могут:
остановить эмиссию сигнала в любое время
переписать обработчик по умолчанию для сигнала если он сохранён как функция указанная в структуре класса (которая является предпочтительным способом создания обработчика по умолчанию что обсуждалось в предыдущем разделе).
В обоих случаях настоящий программист должен быть осторожен на столько на сколько это возможно создавая код который отвергает факт что обработчик сигнала по умолчанию может не выполниться. Это очевидно не касается случая в примере используемом в предыдущем разделе, так как запись файла зависит от того выполнен или нет обработчик по умолчанию (однако, вашей целью может быть: позволить пользователю предотвратить запись файла если он хочет).
Если вы просто хотите остановить эмиссию сигнала из одной callback-функции подключенной вами,
вы можете вызвать g_signal_stop_by_name
. Это очень просто поэтому я не буду
описывать подробно.
Если по умолчанию обработчик сигнала является просто указателем классовой функции, возможно переписать его самостоятельно из типовой функции class_init которая унаследована у родителя. В этом случае, когда издаётся сигнал, родительский класс будет использовать функцию обеспеченную потомком как обработчик сигнала по умолчанию. Конечно, также возможно (и рекомендуется) соединять потомка с родительским обработчиком сигнала по умолчанию гарантируя целостность родительского объекта.
Перезапись классового метода и формирование цепочек было продемонстрировано в “Object methods” поэтому я не стану показывать здесь как это делается снова.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
В двух предыдущих разделах обсуждались детали Динамической системы типов Glib и её система управления сигналами. Библиотека GObject так же содержит реализацию основного базового типа называемого GObject.
GObject это базовый классифицируемый инстанциируемый тип. Он осуществляет:
Управление памятью с подсчётом ссылок
Создание/уничтожение интерфейсов
Основные свойства объекта с установкой/получением функциональных пар
Лёгкое использование сигналов
Все библиотеки GNOME которые используют систему типов GLib (такие как Gtk+ и GStreamer) наследуют GObject который важно изучить, чтобы понять детально как это работает.
Семейство функций g_object_new
могут использоваться для инстанциации любого GType который наследует основной тип GObject. Все эти функции проверяют класс
и экземпляр сструктуры на правильную инициализацию в системе типов glib и вызывают один за другим метод конструктора класса,
который используется для:
Распределение и очистка памяти с помощью
g_type_create_instance
,
Инициализацию экземпляра объекта с созданными свойствами.
Хотя можно устанавливать класс и члены объекта (кроме полей указывающих на родителей) в нули, некоторые считают хорошей практикой установку явных значений для них.
Объекты которые наследуют GObject позволяют переписывать этот метод создания класса: однако перед этим, они должны привязываться к их родительскому методу конструктора:
GObject* (*constructor) (GType type, guint n_construct_properties, GObjectConstructParam *construct_properties);
Например ниже показано как MamanBar перезаписывает родительский конструктор:
#define MAMAN_TYPE_BAR (maman_bar_get_type ()) #define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar)) #define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass)) #define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR)) #define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR)) #define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass)) typedef struct _MamanBar MamanBar; typedef struct _MamanBarClass MamanBarClass; struct _MamanBar { GObject parent; /* instance members */ }; struct _MamanBarClass { GObjectClass parent; /* class members */ }; /* used by MAMAN_TYPE_BAR */ GType maman_bar_get_type (void); static GObject * maman_bar_constructor (GType type, guint n_construct_properties, GObjectConstructParam *construct_properties) { GObject *obj; { /* Invoke parent constructor. */ MamanBarClass *klass; GObjectClass *parent_class; klass = MAMAN_BAR_CLASS (g_type_class_peek (MAMAN_TYPE_BAR)); parent_class = G_OBJECT_CLASS (g_type_class_peek_parent (klass)); obj = parent_class->constructor (type, n_construct_properties, construct_properties); } /* do stuff. */ return obj; } static void maman_bar_instance_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = (MamanBar *)instance; /* do stuff */ } static void maman_bar_class_init (gpointer g_class, gpointer g_class_data) { GObjectClass *gobject_class = G_OBJECT_CLASS (g_class); MamanBarClass *klass = MAMAN_BAR_CLASS (g_class); gobject_class->constructor = maman_bar_constructor; } GType maman_bar_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBarClass), NULL, /* base_init */ NULL, /* base_finalize */ maman_bar_class_init, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBar), 0, /* n_preallocs */ maman_bar_instance_init /* instance_init */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBarType", &info, 0); } return type; }
Если пользователь инстанциирует объект MamanBar с помощью:
MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
Если это первая инстанциация такого объекта, функция maman_b_class_init
будет вызвана после любой функции maman_b_base_class_init
.
Это позволит убедиться в том, что структура класса этого нового объекта правильно инициализирована.
Здесь maman_bar_class_init
как ожидается отменит объектные методы класса
и установит собственные. В примере выше, метод конструктора единственный отменённый метод:
он устанавливается в maman_bar_constructor
.
Как только g_object_new
получила ссылку на инициализированную структуру класса, она вызывает свой метод конструктора для создания экземпляра нового объекта.
Затем она просто отменяет maman_bar_class_init
в maman_bar_constructor
, вызывая её позже, потому что была реализована правильно,
она связывается со своим родительским конструктором. Проблема заключается в поиске родительского конструктора.
Метод (используемый в исходном коде GTK+) состоит в том, чтобы сохранить оригинальный конструктор в статической переменной
в maman_bar_class_init
и зтем многократно использовать её из
maman_bar_constructor
. Это вполне возможно и очень просто, но это не очень хороший метод,
предпочтительней использовать функции
g_type_class_peek
и
g_type_class_peek_parent
.
Наконец, попорядку, g_object_constructor
вызывается последней в цепочке.
Эта функция распределяет инстанциированный объектный буфер через
g_type_create_instance
это значит в этой точке вызывается функция instance_init если она зарегистрирована.
После выполнения instance_init, объект полностью инициализирован и должен быть готов ответить на любой пользовательский запрос.
Когда g_type_create_instance
выполнена, g_object_constructor
устанавливает свойства конструкции
(то есть: свойства полученные в g_object_new
)
и возвращается в пользовательский конструктор которому позволяет выполнить подходящую инициализацию экземпляра...
Процессс описанный выше может показаться немного сложным (он действительно усложнён по моему..) но он может быть
резюмирован таблицей ниже, которая описывает
g_object_new
и порядок её вызова.
Таблица 4. g_object_new
Время вызова | Вызываемая функция | Параметры функции | Ремарка |
---|---|---|---|
Первый вызов g_object_new для целевого типа |
функция base_init целевого типа | В дереве иерархии классов из базового типа в целевой тип. base_init вызывается один раз для каждой сструктуры класса. | У меня нет идей как это может использоваться. Если вы знаете хороший работающий пример как используется base_init класса, пожалуйста, сообщите мне. |
Функция class_init целевого типа | В структуре класса целевого типа | Здесь вы должны убедиться что инициализировали или отменили методы класса (то есть, указатели функций связанные с каждым методом класса) и создать сигналы и свойства связанные с вашим объектом. | |
Интерфейсная функция base_init | В интерфейсной vtable | ||
интерфейсная функция interface_init | В интерфейсной vtable | ||
Каждый вызов g_object_new для целевого типа |
Метод конструктора класса целевого типа: GObjectClass->constructor | В экземпляре объекта | Если вам нужно завершить инициализацию объекта после того как все свойства конструкции установлены, отмените метод конструктора и проверьте цепочку объектного родительского класса перед выполнением вашей собственной инициализации. Если сомневаетесь, не переписывайте метод конструктора. |
типовая функция instance_init | В дереве иерархии классов из базового типа в целевой тип. instance_init обеспечивается для каждого типа вызывая для каждого экземпляра сструктуры. | Обеспечьте функцию instance_init для инициализации вашего объекта перед установкой конструкционных свойств. Это предпочтительный способ инициализации экземпляра GObject. Эта функция эквивалентна конструкторам C++. |
Читатели могут быть смущены некоторым обстоятельством в порядке вызова функций:
в то время как, технически, метод классового конструктора вызывается перед
GType функцией instance_init (так как
g_type_create_instance
которая вызывает instance_init вызывается g_object_constructor
которая находится на верхнем уровне
классового метода конструктора и к которому привязываются пользователи), пользовательский код который выполняется в обеспеченном
пользователем конструкторе будет всегда выполняться после
GType функции instance_init, так как конструктор обеспеченный пользователем
должен (вы были предкпреждены) привязываться перед
выполнением чего-либо полезного.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Тип, которым манипулирует система типов Glib, намного более общий, чем тот который обычно подразумевается как объектный тип (Object type). Это лучше всего демонстрирует ниже показанная структура и функции используемые для регистрации типа в системе типов.
typedef struct _GTypeInfo GTypeInfo; struct _GTypeInfo { /* interface types, classed types, instantiated types */ guint16 class_size; GBaseInitFunc base_init; GBaseFinalizeFunc base_finalize; /* classed types, instantiated types */ GClassInitFunc class_init; GClassFinalizeFunc class_finalize; gconstpointer class_data; /* instantiated types */ guint16 instance_size; guint16 n_preallocs; GInstanceInitFunc instance_init; /* value handling */ const GTypeValueTable *value_table; }; GType g_type_register_static (GType parent_type, const gchar *type_name, const GTypeInfo *info, GTypeFlags flags); GType g_type_register_fundamental (GType type_id, const gchar *type_name, const GTypeInfo *info, const GTypeFundamentalInfo *finfo, GTypeFlags flags);
g_type_register_static
и
g_type_register_fundamental
являются C функциями, определёнными в gtype.h
и реализованными в gtype.c
которые вы должны использовать для регистрации новых GType
в программной системе типов.
Маловероятно что вам потребуется использовать
g_type_register_fundamental
(вы должны бить Tim Janik, чтобы делать это) но если вам это нужно, последний раздел разъясняет как создаются новые
базовые типы данных.
[2]
Базовые типы данных являются высшим уровнем типов которые не происходят от других типов
в то время как обычные типы происходят из других типов.
После инициализации g_type_init
,
система типов не только инициализирует внутренние сструктуры данных, но и регистрирует множество основных типов:
некоторые из них являются базовыми типами данных. Остальные являются типами полученными из этих базовых типов.
Базовые и небазовые типы данных определяют:
размер класса: поле class_size в GTypeInfo.
функции инициализации класса (C++ конструктор): поля base_init и class_init в GTypeInfo.
функции уничтожения класса (C++ деструктор): поля base_finalize и class_finalize в GTypeInfo.
размер экземпляра (C++ параметр нового): поле instance_size в GTypeInfo.
instanciation policy (C++ тип нового оператора): поле n_preallocs в GTypeInfo.
функции копирования (C++ операторы копирования): поле value_table в GTypeInfo.
флаги характеризующие тип: GTypeFlags.
Базовые типы данных определяются так же набором
GTypeFundamentalFlags
которые хранятся в GTypeFundamentalInfo.
Небазовые типы кроме всего прочего определяются их родителем, который помещается как параметр parent_type в
g_type_register_static
и g_type_register_dynamic
.
Основным обобщением между всеми glib типами (базовыми и небазовыми, классофицированными и неклассофицированными, instantiable и non-instantiable) является то, что ими можно манипулировать через единственный API для копирования и создания типов.
Структура GValue используется как абстрактный контейнер
для всех этих типов. Её упрощенный API (определён в gobject/gvalue.h
) может использоваться для
вызова value_table функций в течение регистрации типа: например
g_value_copy
для копирования содержимого
GValue в другой
GValue. Это подобно назначению в C++,
когда вызывается оператор копирования C++, чтобы по умолчанию побитно модифицировать копию семантики C++/C структур/классов.
Следующий код демонстрирует как можно копировать 64 битное целочисленное,
так же как экземпляр указателя GObject
(код этого примера находится в исходном пакете этой документации в sample/gtype/test.c
):
static void test_int (void) { GValue a_value = {0, }; GValue b_value = {0, }; guint64 a, b; a = 0xdeadbeaf; g_value_init (&a_value, G_TYPE_UINT64); g_value_set_uint64 (&a_value, a); g_value_init (&b_value, G_TYPE_UINT64); g_value_copy (&a_value, &b_value); b = g_value_get_uint64 (&b_value); if (a == b) { g_print ("Yay !! 10 lines of code to copy around a uint64.\n"); } else { g_print ("Are you sure this is not a Z80 ?\n"); } } static void test_object (void) { GObject *obj; GValue obj_vala = {0, }; GValue obj_valb = {0, }; obj = g_object_new (MAMAN_BAR_TYPE, NULL); g_value_init (&obj_vala, MAMAN_BAR_TYPE); g_value_set_object (&obj_vala, obj); g_value_init (&obj_valb, G_TYPE_OBJECT); /* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference. This function thus calls g_object_ref. It is interesting to note that the assignment works here because MAMAN_BAR_TYPE is a G_TYPE_OBJECT. */ g_value_copy (&obj_vala, &obj_valb); g_object_unref (G_OBJECT (obj)); g_object_unref (G_OBJECT (obj)); }
Важно в выше представленном коде то, что точная семантика вызова копирования не определена так как зависит от реализации функции копирования. Определённые функции копирования могут решить распределить новый участок памяти и зтем скопировать данные из источника в адресат. Другие могут просто увеличить количество ссылок на экземпляр и скопировать ссылку в новый GValue.
value_table определённый в gtype.h
используется
для определения этих функций и полностью описан в документации API поставляемой с
GObject (for once ;-) это объясняет почему мы не будем детализировать точную семантику.
typedef struct _GTypeValueTable GTypeValueTable; struct _GTypeValueTable { void (*value_init) (GValue *value); void (*value_free) (GValue *value); void (*value_copy) (const GValue *src_value, GValue *dest_value); /* varargs functionality (optional) */ gpointer (*value_peek_pointer) (const GValue *value); gchar *collect_format; gchar* (*collect_value) (GValue *value, guint n_collect_values, GTypeCValue *collect_values, guint collect_flags); gchar *lcopy_format; gchar* (*lcopy_value) (const GValue *value, guint n_collect_values, GTypeCValue *collect_values, guint collect_flags); };
Маловероятно что вы будете когда либо определять value_table в процессе регистрации типа потому что value_tables наследуется из родительского типа для небазовых типов, это значит что если вы хотите создать базовый тип (не очень хорошая идея!), вам не потребуется обеспечить новый value_table так как вы унаследуете структуру value_table из родителя вашего типа.
[2]
Пожалуйста помните что есть другие функции регистрации:
g_type_register_dynamic
.
Мы не будем обсуждать эту функцию здесь, так как её использование очень похоже на версию _static
.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
GObject, и её система типов низшего уровня GType, используются в GTK+ и в большинстве библиотек GNOME для обеспечения:
объектно-ориентированного C-based APIs и
автоматически прозрачных API bindings для других компилируемых или интерпретируемых языков.
Многие программисты используют для работы только компилируемые или только динамически интерпретируемые языки и не понимают вызовы связанные с разно-языковой совместимостью. Это введение является попыткой объяснить эти вызовы, кратко описывая выборочные решения GLib.
Следующие разделы лучше описывают то как работают GType и GObject, а так же как вы можете использовать их как C программист. Полезно помнить что доступность C объектов из других интерпретируемых языков было главной целью дизайна: это объясняет некоторую замысловатость API и усовершенствования представляемые этой библиотекой.
Можно сказать (я видел такие определения используются в некоторых учебниках по теории языков программирования), что язык программирования - это просто способ создания типов данных и манипулирования ими. Большинство языков обеспечивают множество родных языковых типов и несколько примитивов для создания более сложных типов на основе этих примитивных типов.
В C, язык обеспечивает такие типы как char, long, pointer. В процессе компилирования C кода, компилятор отображает эти языковые типы в скомпилированные целевые машинные типы. Если вы используете C интерпретатор (я никогда не видел этого сам, но это возможно :), интерпретатор (программа которая интерпретирует исходный текст и выполняет его) отображает языковые типы в машинные типы целевой архитектуры во время выполнения программы (или перед выполнением если это используется во время механизма компилирования).
Perl и Python, которые являются интерпретируемыми языками, на самом деле не обеспечивают определения типов подобно используемым в C. Perl и Python программисты манипулируют переменными и типами переменных только после первого назначения или после первого использования которое определяет тип переменной. Интерпретатор так же часто обеспечивает большинство автоматических преобразований из одного типа в другой. Например, в Perl, переменная которая содержит целочисленное может быть автоматически конвертирована в строку с данным контекстом:
my $tmp = 10; print "это целочисленное конвертированное в строку:" . $tmp . "\n";
Конечно, также часто возможно явное преобразование, когда преобразование по умолчанию обеспеченное языком не является интуитивно понятным.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Замыкания являются центром концепции асинхронных сигналов, которая широко используется повсюду в GTK+ и GNOME приложениях. Замыкание - основное представление callback-функций. Это небольшая структура содержащая дерево объектов:
указатель функции (непосредственно сама callback-функция), чей прототип похож на:
return_type function_callback (... , gpointer user_data);
Указатель user_data который помещается в callback-функцию при вызове замыкания
указатель функции который представляет деструктор замыкания: всякий раз когда количество ссылок замыкания достигает нуля, эта функция вызывается перед освобождением сструктуры замыкания.
Структура GClosure представляет основную функциональность всех замкнутых реализаций: существуют разные реализации Замыканий для каждого отдельного рабочего цикла который хочет использовать систему типов GObject. [8] Библиотека GObject обеспечивает простой тип GCClosure который является определением реализации замыканий используемый с C/C++ callback-функциями.
GClosure представляет простые сервисы:
Вызов (g_closure_invoke
): это то, для чего были
созданы замыкания: они скрывают детали callback-вызовов из callback-вызовов.
Уведомление: замыкания уведомляют об определённых событиях, таких как запрос замыкания, аннулирование замыкания
и финализация замыкания. Ожидающие сообщений могут быть зарегистрированы с помощью
g_closure_add_finalize_notifier
(уведомление финализации), g_closure_add_invalidate_notifier
(уведомление аннулирования) и
g_closure_add_marshal_guards
(уведемление запроса).
Существуют симметричные нерегистрационные функции для событий финализации и аннулирования
(g_closure_remove_finalize_notifier
и
g_closure_remove_invalidate_notifier
) но не для выполнения запроса.
[9]
Если вы используете C или C++ для подключения callback-функции к данному событию, то вы будете использовать либо просто
GCClosure
которая имеет довольно минимальный API, или ещё более простые функции
g_signal_connect
(которые будут продемонстрированы немного позже :).
GClosure* g_cclosure_new (GCallback callback_func, gpointer user_data, GClosureNotify destroy_data); GClosure* g_cclosure_new_swap (GCallback callback_func, gpointer user_data, GClosureNotify destroy_data); GClosure* g_signal_type_cclosure_new (GType itype, guint struct_offset);
g_cclosure_new
создаёт новое замыкание
которое может вызвать обеспеченную пользователем callback_func с обеспеченным пользователем user_data в качестве последнего параметра.
Когда замыкание финализируется (второй этап процесса уничтожения), оно вызовет функцию destroy_data если пользователь её
предоставил.
g_cclosure_new_swap
создаёт новое замыкание
которое может вызвать обеспеченную пользователем callback_func с обеспеченным пользователем user_data в качестве первого параметра
(а не последнего параметра как в g_cclosure_new
).
Когда замыкание финализируется (второй этап процесса уничтожения), оно вызовет функцию destroy_data если пользователь её
предоставил.
Как объяснялось выше, Замыкания скрывают подробности callback-вызовов. В C, callback-вызов такой же вызов функции: это просто вопрос создания правильного стека для вызова функции и выполнения трансляции команды вызова.
'C' маршаллеры замыканий преобразуют массив GValues, который представляет параметры целевой функции, в список параметров функций в C-стиле, вызывая предоставленную пользователем C функцию с этим списком параметров, получают возвращаемое значение функции, преобразуют его в GValue и возвращают это GValue в вызывающую программу.
Следующий код реализует простой маршаллер в C для C функции которая принимает целочисленное как первый параметр и ничего не возвращает.
g_cclosure_marshal_VOID__INT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data) { typedef void (*GMarshalFunc_VOID__INT) (gpointer data1, gint arg_1, gpointer data2); register GMarshalFunc_VOID__INT callback; register GCClosure *cc = (GCClosure*) closure; register gpointer data1, data2; g_return_if_fail (n_param_values == 2); data1 = g_value_peek_pointer (param_values + 0); data2 = closure->data; callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data : cc->callback); callback (data1, g_marshal_value_peek_int (param_values + 1), data2); }
Конечно, существуют другие виды маршаллеров. Например, James Henstridge
написал родной для Python маршаллер который используется всеми замыканиями языка python
(замыкания python используются python-based callback-функциями вызываемыми процессом запрса замыкания).
Этот python маршаллер преобразует введённый список GValue представляющий параметры функции в эквивалентную
структурную запись Python (вы можете посмотреть pyg_closure_marshal
в
pygtype.c
в модуле pygobject GNOME cvs server).
[8] На практике, Замыкания находятся в границах языкового окружения: если вы пишите код на python и один из ваших Python callback-вызовов получает сигнал одного из виджетов GTK+, код на C в GTK+ должен выполнить ваш код на Python. Замыкание вызывающее GTK+ object вызывает Python callback-вызов: он ведёт себя как обычный C object для GTK+ и как обычный Python object для python кода.
[9] Замыкания подсчитывают ссылки и уведомляют слушателя относительно своего уничтожения в два этапа: уведомление аннулирования вызывается перед уведомлением финализации.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
glib-genmarshalglib-genmarshal — Утилита генерирующая C код маршаллера для GLib замыканий |
glib-genmarshal
[options...] [files...]
glib-genmarshal это маленькая утилита которая генерирует C код маршаллеров для callback-функций GClosure механизма в библиотеке GObject входящей в состав GLib. Функции маршаллеры имеют стандартную сигнатуру, их помещают в вызов замыкания, массив структур значений содержит параметры callback-функций и структуру значения для возвращаемого значения callback-функции. Маршаллер отвечает за вызов соответствующего функционального C кода замыкания, со всеми параметрами в стеке, и накапливает возвращаемые значения.
glib-genmarshal принимает список маршаллеров для генерации ввода. Список маршаллеров читается либо из стандартного ввода либо из файлов помещаемых как дополнительный аргумент в командной строке.
--header |
Генерировать содержимое заголовочного файла маршаллера. |
--body |
Генерировать C код файла содержащего маршаллер. |
--prefix=string , --prefix string |
Определить префикс маршаллера. По умолчанию префикс |
--skip-source |
Пропустить исходное расположение замечаний в генерируемых комментариях. |
--nostdinc |
Не использовать стандартный маршаллер библиотеки GObject, и пропустить включённые директивы
|
--g-fatal-warnings |
Сделать предупреждения фатальными, то есть немедленно выходить из программы если получено предупреждение. |
-h , --help |
Напечатать краткое описание и выйти. |
-v , --version |
Напечатать версию и выйти. |
Списки маршаллеров обрабатываются построчно, строка может содержать комментарий в форме
# это комментарий
или спецификацию маршаллера в форме
RTYPE
:PTYPE
RTYPE
:PTYPE
,PTYPE
RTYPE
:PTYPE
,PTYPE
,PTYPE
(может присутствовать до 16 PTYPE
).
RTYPE
часть определяет возвращаемый тип callback-функции,
а PTYPE
отделённый справа двоеточием список параметров callback-функции,
за исключением первого и последнего параметра которые всегда являются указателями.
В настоящее время поддерживаются следующие типы:
VOID |
указывает что нет возвращаемого типа, или что отсутствуют дополнительные параметры.
Если |
BOOLEAN |
для логических типов (gboolean) |
CHAR |
для символьного типа со знаком (gchar) |
UCHAR |
для типа unsigned char (guchar) |
INT |
для типа signed integer (gint) |
UINT |
для типа unsigned integer (guint) |
LONG |
для типа signed long integer (glong) |
ULONG |
для типа unsigned long integer (gulong) |
INT64 |
для типа signed 64bit integer (gint64) |
UINT64 |
для типа unsigned 64bit integer (guint64) |
ENUM |
для перечислимого типа (gint) |
FLAGS |
для типа flag enumeration (guint) |
FLOAT |
для типа single-precision float (gfloat) |
DOUBLE |
для типа double-precision float (gdouble) |
STRING |
для строкового типа (gchar*) |
BOXED |
для типа boxed (анонимный но с подсчётом ссылок) (GBoxed*) |
PARAM |
для типа GParamSpec или производного (GParamSpec*) |
POINTER |
для типа anonymous pointer (gpointer) |
OBJECT |
для типа GObject или производного (GObject*) |
NONE |
устаревший псевдоним для |
BOOL |
устаревший псевдоним для |
Генерация маршаллеров для следующих callback-функций:
void foo (gpointer data1, gpointer data2); void bar (gpointer data1, gint param1, gpointer data2); gfloat baz (gpointer data1, gboolean param1, guchar param2, gpointer data2);
Список маршаллеров будет выглядеть так:
VOID:VOID VOID:INT FLOAT:BOOLEAN,UCHAR
Генерируемые маршаллеры имеют параметры закодированные в имени их функции. Для этого специфичного списка они будут
g_cclosure_marshal_VOID__VOID(), g_cclosure_marshal_VOID__INT(), g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
Они могут использоваться непосредственно для GClosures или будут помещены как GSignalCMarshaller c_marshaller параметр; после создания сигналов:
GClosure *cc_foo, *cc_bar, *cc_baz; cc_foo = g_cclosure_new (NULL, foo, NULL); g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID); cc_bar = g_cclosure_new (NULL, bar, NULL); g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT); cc_baz = g_cclosure_new (NULL, baz, NULL); g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
glib-genmarshal был написан Tim Janik
<timj@gtk.org>
.
Эту страницу руководства написал Tim Janik <timj@gtk.org>
.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
glib-mkenumsglib-mkenums — Утилита генерирующая описание перечислимых типов языка C |
glib-mkenums
[options...] [files...]
glib-mkenums это небольшой perl-скрипт анализирующий C код извлекая определения перечислений и создавая описания перечислений основываясь на текстовых шаблонах определённых пользователем. Чаще всего этот скрипт используется для производства C кода содержащего значения перечислений как строки, таким образом программы могут обеспечить строковые названия значений для самоанализа.
glib-mkenums принимает в качестве ввода список допустимых файлов с кодом на C. Опции определяют управление текстом вывода, определённые замены выполненные в текстовых шаблонах для ключевых слов окантовываются символами @.
--fhead text |
Выводить |
--fprod text |
Выводить |
--ftail text |
Выводить |
--eprod text |
Выводить |
--vhead text |
Выводить |
--vprod text |
Выводить |
--vtail text |
Выводить |
--comments text |
Шаблон для автоматической генерации комментариев, по умолчанию (для генерации C кода) это
|
--template file |
Читать шаблон из полученного файла. Шаблоны окантовываются в спецформат С комментариев /*** BEGIN section ***/ /*** END section ***/
где раздел (section) может быть |
--help |
Напечатать короткое описание и выйти. |
--version |
Напечатать версию и выйти. |
Определённые ключевые слова окантованные в символы @ будут заменены в итоговом тексте. Для демонстрации подстановки ключевых слов ниже, принят следующий пример перечисления:
typedef enum { PREFIX_THE_XVALUE = 1 << 3, PREFIX_ANOTHER_VALUE = 1 << 4 } PrefixTheXEnum;
@EnumName@ | Имя перечисления обрабатываемого в текущий момент, имена перечислений подразумевают правильное пространство имён и используют смешанный регистр для разделения слов в имени (например PrefixTheXEnum). |
@enum_name@ | Имя перечисления состоящее из слов в нижнем регистре разделённых символом подчеркивания (например prefix_the_xenum). |
@ENUMNAME@ | Имя перечисления состоящее из слов в верхнем регистре и разделённых символом подчеркивания (например PREFIX_THE_XENUM). |
@ENUMSHORT@ | Имя перечисления состоящее из слов в верхнем регистре и разделённых символом подчёркивания, с удалением префикса (например THE_XENUM). |
@VALUENAME@ | Названия значений перечислений обрабатываемых в текущий момент со словами в верхнем регистре разделёнными символом подчёркивания, это принятое буквальное обозначение значений перечисления в исходниках C (например PREFIX_THE_XVALUE). |
@valuenick@ | Псевдоним для значения перечисления обрабатываемого в данный момент, обычно генерируется пропуском основных префиксных слов всех значений текущего перечисления, слова в нижнем регистре и разделены знаком минус (например the-xvalue). |
@type@ | Заменяется либо "enum" либо "flags", в зависимости от того имеет ли значение перечисления определённые операторы побитного смещения или нет (например flags). |
@Type@ |
Тоже самое как |
@TYPE@ |
Тоже самое как |
@filename@ | Имя текущего обрабатываемого файла (например foo.h). |
Некоторые C комментарии обрабатываются по особенному в анализируемом определении перечисления,
Каждый комментарий начинается последовательностью трёх символов /*<
и заканчивается последовательностью трёх символов >*/
.
В определении перечисления, могут быть определены опции "skip" и "flags", указывающие что это
определение перечисления будет пропущено, или будет обработано как флаговое определение,
либо для определения основных префиксов пропускаемых во всех значениях для генерации псевдонимов значений,
соответственно. Опция "lowercase_name" может быть использована для определения разделителя слов используемого в
функциях *_get_type(). Например, /*< lowercase_name=gnome_vfs_uri_hide_options >*/.
В определении значения, могут поддерживаться опции "skip" и "nick". Первая послужит причиной для пропуска значения, а вторая может использоваться для автоматической генерации псевдонима. Например:
typedef enum /*< skip >*/ { PREFIX_FOO } PrefixThisEnumWillBeSkipped; typedef enum /*< flags,prefix=PREFIX >*/ { PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ PREFIX_THE_FIRST_VALUE, PREFIX_THE_SECOND_VALUE, PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/ } PrefixTheFlagsEnum;
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> gpointer (*GBoxedCopyFunc) (gpointer boxed); void (*GBoxedFreeFunc) (gpointer boxed); gpointer g_boxed_copy (GType boxed_type, gconstpointer src_boxed); void g_boxed_free (GType boxed_type, gpointer boxed); GType g_boxed_type_register_static (const gchar *name, GBoxedCopyFunc boxed_copy, GBoxedFreeFunc boxed_free); GType g_pointer_type_register_static (const gchar *name); #define G_TYPE_HASH_TABLE #define G_TYPE_DATE #define G_TYPE_GSTRING #define G_TYPE_STRV #define G_TYPE_REGEX typedef GStrv;
GBoxed это родной механизм упаковки для произвольных C структур. Единственная вещь которую нужно знать системе типов о структурах - как копировать и освобождать их, за тем они обрабатываются как непрозрачные участки памяти.
Упаковочные типы полезны для простых структур содержащих значения как прямоугольники или точки. Они так же могут быть использованы для упаковки структур определённых в библиотеках основанных не на GObject.
gpointer (*GBoxedCopyFunc) (gpointer boxed);
Эта функция обеспечивается пользователем и должна производить копию помещённой в контейнер сструктуры.
boxed : |
Упакованная структура для копирования. |
Возвращает : | Вновь созданная копия упакованной сструктуры. |
void (*GBoxedFreeFunc) (gpointer boxed);
Эта функция обеспечивается пользователем и должна освобождать структуру помещённую в контейнере.
boxed : |
Упакованная структура для освобождения. |
gpointer g_boxed_copy (GType boxed_type, gconstpointer src_boxed);
Обеспечивает копию упакованной сструктуры src_boxed
с типом boxed_type
.
boxed_type : |
Тип src_boxed .
|
src_boxed : |
Упакованная структура для копирования. |
Возвращает : | Вновь созданная копия упакованной сструктуры. |
void g_boxed_free (GType boxed_type, gpointer boxed);
Освобождает упакованную структуру boxed
с типом boxed_type
.
boxed_type : |
Тип boxed .
|
boxed : |
Упакованная структура для освобождения. |
GType g_boxed_type_register_static (const gchar *name, GBoxedCopyFunc boxed_copy, GBoxedFreeFunc boxed_free);
Эта функция создаёт новый G_TYPE_BOXED
производный типовой id для нового упаковочного типа с именем name
.
Упаковочный тип необходимо обеспечить функциями обработки для копирования и освобождения непрозрачных упакованных структур этого типа.
name : |
Имя нового упаковочного типа. |
boxed_copy : |
Функция копирования упакованной сструктуры. |
boxed_free : |
Функция освобождения упакованной сструктуры. |
Возвращает : | Новый произведённый G_TYPE_BOXED типовой id
для name .
|
GType g_pointer_type_register_static (const gchar *name);
Создаёт новый производный G_TYPE_POINTER
типовой id для нового типа указателя с именем name
.
name : |
имя нового типа указателя. |
Возвращает : | новый производный G_TYPE_POINTER
типовой id для name .
|
#define G_TYPE_HASH_TABLE (g_hash_table_get_type ())
GType упаковочного типа для содержания ссылки GHashTable.
Начиная с версии 2.10
#define G_TYPE_STRV (g_strv_get_type ())
GType для упаковочного типа содержащего
NULL
-завершённый массив строк.
Фрагменты кода в следующем примере демонстрируют использование типового свойства
G_TYPE_STRV с помощью
g_object_class_install_property()
, g_object_set()
и g_object_get()
.
g_object_class_install_property (object_class, PROP_AUTHORS, g_param_spec_boxed ("authors", _("Authors"), _("List of authors"), G_TYPE_STRV, G_PARAM_READWRITE)); gchar *authors[] = { "Owen", "Tim", NULL }; g_object_set (obj, "authors", authors, NULL); gchar *writers[]; g_object_get (obj, "authors", &writers, NULL); /* do something with writers */ g_strfreev (writers);
Начиная с версии 2.4
#define G_TYPE_REGEX (g_regex_get_type ())
GType упаковочного типа содержащий ссылку GRegex.
Начиная с версии 2.14
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> #define G_CLOSURE_NEEDS_MARSHAL (closure) #define G_CLOSURE_N_NOTIFIERS (cl) #define G_CCLOSURE_SWAP_DATA (cclosure) #define G_CALLBACK (f) void (*GCallback) (void); GClosure; #define G_TYPE_CLOSURE GCClosure; void (*GClosureMarshal) (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void (*GClosureNotify) (gpointer data, GClosure *closure); GClosure* g_cclosure_new (GCallback callback_func, gpointer user_data, GClosureNotify destroy_data); GClosure* g_cclosure_new_swap (GCallback callback_func, gpointer user_data, GClosureNotify destroy_data); GClosure* g_cclosure_new_object (GCallback callback_func, GObject *object); GClosure* g_cclosure_new_object_swap (GCallback callback_func, GObject *object); GClosure* g_closure_new_object (guint sizeof_closure, GObject *object); GClosure* g_closure_ref (GClosure *closure); void g_closure_sink (GClosure *closure); void g_closure_unref (GClosure *closure); void g_closure_invoke (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint); void g_closure_invalidate (GClosure *closure); void g_closure_add_finalize_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func); void g_closure_add_invalidate_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func); void g_closure_remove_finalize_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func); void g_closure_remove_invalidate_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func); GClosure* g_closure_new_simple (guint sizeof_closure, gpointer data); void g_closure_set_marshal (GClosure *closure, GClosureMarshal marshal); void g_closure_add_marshal_guards (GClosure *closure, gpointer pre_marshal_data, GClosureNotify pre_marshal_notify, gpointer post_marshal_data, GClosureNotify post_marshal_notify); void g_closure_set_meta_marshal (GClosure *closure, gpointer marshal_data, GClosureMarshal meta_marshal); void g_source_set_closure (GSource *source, GClosure *closure); #define G_TYPE_IO_CHANNEL #define G_TYPE_IO_CONDITION void g_cclosure_marshal_VOID__VOID (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__BOOLEAN (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__CHAR (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__UCHAR (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__INT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__UINT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__LONG (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__ULONG (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__ENUM (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__FLAGS (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__FLOAT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__DOUBLE (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__STRING (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__PARAM (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__BOXED (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__POINTER (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__OBJECT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_STRING__OBJECT_POINTER (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_VOID__UINT_POINTER (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); void g_cclosure_marshal_BOOLEAN__FLAGS (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data); #define g_cclosure_marshal_BOOL__FLAGS
GClosure представляет callback-функцию предоставляемую программистом. Это в общем включает функцию некоторого вида и маршаллер используемый для её вызова. Маршаллер конвертирует аргументы вызова из GValue в подходящую форму, выполняет callback-функцию с преобразованными аргументами, и преобразует возвращаемое значение обратно в GValue.
В случае C программ, замыкание обычно просто содержит указатель на функцию и может быть на данные аргумента, а маршаллер конвертирует между GValue и родными типами C. Библиотека GObject обеспечивает тип GCClosure для этой цели. Привязкам для других языков необходимы маршаллеры которые конвертируют между GValue и подходящими представлениями в рабочем цикле языка, чтобы использовать функции написанные на этом языке как callback-функции.
Внутри GObject, замыкания играют важную роль в реализации сигналов. Когда сигнал зарегистрирован,
аргумент c_marshaller
в
g_signal_new()
определяет C маршаллер по умолчанию
для любых замыканий которые подключаются к этому сигналу. GObject обеспечивает несколько C маршаллеров для этих целей,
смотрите g_cclosure_marshal_*() функции. Дополнительные C маршаллеры могут быть сгенерированы с помощью утилиты
glib-genmarshal. Замыкания могут явно подключаться к сигналам с помощью
g_signal_connect_closure()
, но обычно более
удобно позволить GObject создать замыкание автоматически используя одну из функций g_signal_connect_*() которые используют для этого
пары callback-функция/пользовательские данные.
Использование замыканий имеет множество преимуществ перед простой комбинацией callback-функция/указатель данных:
Замыкания позволяют вызывающему получать типы callback-параметров, что позволяет языковым привязкам не писать индивидуальный код совмещения (glue) для каждого callback-типа.
Подсчёт ссылок GClosure облегчает правильную обработку повторного использования; если callback-функция удалена во время вызова, замыкание и его параметры не будут освобождены до завершения вызова.
g_closure_invalidate()
и аннулирующие уведомления
позволяют callback-функциям автоматически удаляться когда объекты уничтожаются.
#define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL)
Возвращает TRUE
если маршаллер
GClosureMarshal ещё не установлен в
closure
.
Смотрите g_closure_set_marshal()
.
closure : |
GClosure |
#define G_CLOSURE_N_NOTIFIERS(cl)
Возвращает the total number of notifiers connected with the closure cl
.
The count includes the meta marshaller, the finalize and invalidate notifiers
and the marshal guards. Note that each guard counts as two notifiers.
See g_closure_set_meta_marshal()
, g_closure_add_finalize_notifier()
,
g_closure_add_invalidate_notifier()
and g_closure_add_marshal_guards()
.
cl : |
GClosure |
#define G_CCLOSURE_SWAP_DATA(cclosure) (((GClosure*) (closure))->derivative_flag)
Определяет должны ли пользовательские данные GCClosure
помещаться как первый параметр в callback-функцию.
Смотрите g_cclosure_new_swap()
.
cclosure : |
GCClosure |
#define G_CALLBACK(f) ((GCallback) (f))
Приводит указатель функции к типу GCallback.
f : |
указатель функции. |
void (*GCallback) (void);
Тип используемый для callback-функций в определениях структур и сигнатурах функций.
Это не означает что все callback-функции не должны принимать параметры и возвращать void.
Необходимая сигнатура callback-функции определяется контекстом в котором используется
(например сигнал к которому подключена). Используйте
G_CALLBACK()
для приведения callback-функции к типу
GCallback.
typedef struct { volatile guint in_marshal : 1; volatile guint is_invalid : 1; } GClosure;
GClosure представляет callback-функцию подходящую для программиста.
volatile guint in_marshal : 1; |
Указывает вызывается ли замыкание в текущий момент с помощью
g_closure_invoke()
|
volatile guint is_invalid : 1; |
Указывает аннулировано ли замыкание с помощью
g_closure_invalidate()
|
typedef struct { GClosure closure; gpointer callback; } GCClosure;
GCClosure это специализированная GClosure для C callback-функций.
void (*GClosureMarshal) (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Тип используемый для функций маршаллеров.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
GValue для хранения возвращаемого значения.
Может быть NULL если
callback-функция closure не возвращает значение.
|
n_param_values : |
длина массива param_values
|
param_values : |
массив GValue содержащих аргументы
для вызова callback-функции closure
|
invocation_hint : |
подсказка вызова получаемая как последний аргумент для
g_closure_invoke()
|
marshal_data : |
дополнительные данные определяемые при регистрации маршаллера,
смотрите g_closure_set_marshal() и
g_closure_set_meta_marshal()
|
void (*GClosureNotify) (gpointer data, GClosure *closure);
Тип используемый для разных callback-уведомлений которые могут быть зарегистрированы в замыкании.
data : |
данные определяемые при регистрации callback-уведомления |
closure : |
GClosure в которой издаётся уведомление |
GClosure* g_cclosure_new (GCallback callback_func, gpointer user_data, GClosureNotify destroy_data);
Создаёт новое замыкание которое вызывает callback_func
с
user_data
в качестве последнего параметра.
callback_func : |
вызываемая функция |
user_data : |
пользовательские данные помещаемые в callback_func
|
destroy_data : |
уничтожающее уведомление вызываемое когда user_data больше не используются
|
Возвращает : | новая GCClosure |
GClosure* g_cclosure_new_swap (GCallback callback_func, gpointer user_data, GClosureNotify destroy_data);
Создаёт новое замыкание которое вызывает callback_func
с
user_data
в качестве первого параметра.
callback_func : |
вызываемая функция |
user_data : |
пользовательские данные помещаемые в callback_func
|
destroy_data : |
уничтожающее уведомление вызываемое когда user_data больше не используются
|
Возвращает : | новая GCClosure |
GClosure* g_cclosure_new_object (GCallback callback_func, GObject *object);
Вариант g_cclosure_new()
который использует
object
как user_data
вызывает
g_object_watch_closure()
для
object
создавая замыкание. Эта функция полезна когда вам нужна callback-функция
тесно связанная с GObject,
и нужно чтобы callback-функция не запускалась после освобождения объекта.
GClosure* g_cclosure_new_object_swap (GCallback callback_func, GObject *object);
Вариант g_cclosure_new_swap()
который использует
object
как user_data
и вызывает
g_object_watch_closure()
для
object
создавая замыкание. Эта функция полезна когда вам нужна callback-функция тесно связанная с
GObject, и не нужно чтобы callback-функция вызывалась
после освобождения объекта.
GClosure* g_closure_new_object (guint sizeof_closure, GObject *object);
Вариант g_closure_new_simple()
которая сохраняет
object
в поле data
замыкания и вызывает
g_object_watch_closure()
для
object
при создании замыкания. Эта функция полезна главным образом при создании новых типов замыканий.
GClosure* g_closure_ref (GClosure *closure);
Увеличивает количество ссылок замыкания заставляя оставаться существующим в течение вызова содержащего указатель на неё.
closure : |
GClosure для увеличения количества ссылок |
Возвращает : | помещённое замыкание closure , для удобства
|
void g_closure_sink (GClosure *closure);
Принимает владение замыканием. Каждое замыкание инициализируется при создании в плавающее состояние,
это значит что инициализированным счётчиком ссылок никто не владеет.
g_closure_sink()
проверяет находится ли объект в плавающем
состоянии, и если это так, отменяет плавающее состояние и уменьшает количество ссылок. Если замыкание не плавающее,
g_closure_sink()
ничего не делает.
Причина существования плавающих состояний заключается в предотвращении громоздких последовательностей кода, например:
closure = g_cclosure_new (cb_func, cb_data); g_source_set_closure (source, closure); g_closure_unref (closure); /* XXX GObject на самом деле не нуждается в этом */
Поскольку g_source_set_closure()
(и подобные функции) будут владеть начальным счётчиком ссылок (если он не имеет владельца), мы можем написать следующее:
g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
Обычно эта функция используется вместе с g_closure_ref()
.
Например сохранение замыкания для более позднего уведомления выглядит так:
static GClosure *notify_closure = NULL; void foo_notify_set_closure (GClosure *closure) { if (notify_closure) g_closure_unref (notify_closure); notify_closure = closure; if (notify_closure) { g_closure_ref (notify_closure); g_closure_sink (notify_closure); } }
Поскольку g_closure_sink()
может уменьшить количество
ссылок замыкания (если она была вызвана для closure
) так же как
g_closure_unref()
, функция
g_closure_ref()
должна быть вызвана перед этой функцией.
closure : |
GClosure для уменьшения начального количества ссылок, если они всё ещё есть. |
void g_closure_unref (GClosure *closure);
Уменьшает количество ссылок замыкания после того как оно было увеличено подобным вызовом. Если нет других вызовов использующих замыкание, то замыкание будет уничтожено и освобождено.
closure : |
GClosure для уменьшения количества ссылок |
void g_closure_invoke (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint);
Вызывает замыкание, то есть выполняет вызов предоставляемый замыканием closure
.
closure : |
GClosure |
return_value : |
GValue для хранения возвращаемого значения.
Может быть NULL если
callback-функция closure не возвращает значение.
|
n_param_values : |
длина массива param_values
|
param_values : |
массив GValue содержащих аргументы
для вызова callback-функции closure
|
invocation_hint : |
зависящая от контекста подсказка вызова |
void g_closure_invalidate (GClosure *closure);
Устанавливает флаг в замыкание указывая что вызов невозможен, таким образом заставляет игнорировать любые последующие вызовы
g_closure_invoke()
в этом closure
. Кроме того, аннулирующее уведомление установленное в этом замыкании
будет вызвано в этой точке. Помните, если вы не удерживаете ссылку на замыкание самостоятельно, аннулирующее уведомление может
отменить ссылку на замыкание и таким образом уничтожить его, поэтому если вам нужен доступ к замыканию после вызова
g_closure_invalidate()
, убедитесь что вы
предварительно вызвали g_closure_ref()
.
Заметьте, g_closure_invalidate()
будет также вызвана когда количество ссылок замыкания сброшено в ноль (если оно не было аннулировано раньше).
closure : |
GClosure для аннулирования |
void g_closure_add_finalize_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
Регистрирует финализирующее уведомление которое вызывается когда количество ссылок
closure
достигает 0. Множество финализирующих уведомлений в единственном замыкании
вызываются в неопределённом порядке. Если единственный вызов
g_closure_unref()
приводит замыкание и к аннулированию и к
финализации, то уведомление аннулирования выполняется перед уведомлением финализации.
closure : |
GClosure |
notify_data : |
данные помещаемые в notify_func
|
notify_func : |
callback-функция для регистрации |
void g_closure_add_invalidate_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
Регистрирует уведомление аннулирования которое вызывается когда closure
аннулируется с помощью g_closure_invalidate()
.
Уведомления аннулирования вызываются перед уведомлениями финализации, в неопределённом порядке.
closure : |
GClosure |
notify_data : |
данные помещаемые в notify_func
|
notify_func : |
callback-функция для регистрации |
void g_closure_remove_finalize_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
Удаляет уведомление финализации.
Помните что уведомление удаляется автоматически после выполнения.
closure : |
GClosure |
notify_data : |
данные которые были помещены в
g_closure_add_finalize_notifier()
при регистрации notify_func
|
notify_func : |
callback-функция для удаления |
void g_closure_remove_invalidate_notifier (GClosure *closure, gpointer notify_data, GClosureNotify notify_func);
Удаляет аннулирующее уведомление.
Помните что уведомления автоматически удаляются после выполнения.
closure : |
GClosure |
notify_data : |
данные которые были помещены в
g_closure_add_invalidate_notifier()
при регистрации notify_func
|
notify_func : |
callback-функция для удаления |
GClosure* g_closure_new_simple (guint sizeof_closure, gpointer data);
Распределяет структуру с полученным размером и инициализирует начальную часть как GClosure. Эта функция в основном полезна при реализации новых типов замыканий.
typedef struct _MyClosure MyClosure; struct _MyClosure { GClosure closure; /* дополнительные данные расположены здесь */ }; static void my_closure_finalize (gpointer notify_data, GClosure *closure) { MyClosure *my_closure = (MyClosure *)closure; /* здесь освобождаем дополнительные данные */ } MyClosure *my_closure_new (gpointer data) { GClosure *closure; MyClosure *my_closure; closure = g_closure_new_simple (sizeof (MyClosure), data); my_closure = (MyClosure *) closure; /* здесь инициализируем дополнительные данные */ g_closure_add_finalize_notifier (closure, notify_data, my_closure_finalize); return my_closure; }
void g_closure_set_marshal (GClosure *closure, GClosureMarshal marshal);
Устанавливает маршаллер closure
. marshal_data
для
marshal
обеспечивает способ для мета-маршаллера обеспечивающего дополнительную информацию
для маршаллера. (Смотрите g_closure_set_meta_marshal()
). Для С маршаллеров предопределённых в GObject (функциями g_cclosure_marshal_*()), обеспечивается callback-функция для использования
вместо closure->callback
.
closure : |
GClosure |
marshal : |
функция GClosureMarshal |
void g_closure_add_marshal_guards (GClosure *closure, gpointer pre_marshal_data, GClosureNotify pre_marshal_notify, gpointer post_marshal_data, GClosureNotify post_marshal_notify);
Добавляет пары уведомлений которые получают вызов перед и после callback-функции замыкания, соответственно.
Это обычно используется для защиты дополнительных аргументов для продолжения callback-вызова.
Смотрите пример защиты маршаллера в g_object_watch_closure()
.
closure : |
GClosure |
pre_marshal_data : |
данные помещаемые в pre_marshal_notify
|
pre_marshal_notify : |
функция вызываемая перед callback-функцией замыкания |
post_marshal_data : |
данные помещаемые в post_marshal_notify
|
post_marshal_notify : |
функция вызываемая после callback-функции замыкания |
void g_closure_set_meta_marshal (GClosure *closure, gpointer marshal_data, GClosureMarshal meta_marshal);
Устанавливает мета-маршаллер для closure
.
Мета-маршаллер является оболочкой для closure->marshal
и изменяет способ вызова в той же манере.
В основном это используется для C callback-функций. Такие же маршаллеры (сгенирированные с помощью
glib-genmarshal) используются повсюду,
но способ которыми вы получаете callback-функции отличаются. В большинстве случаев вы используете
closure->callback
, но в некоторых случаях мы используем несколько другую методику поиска
callback-функций.
Например, классовое замыкание для сигналов
(смотрите g_signal_type_cclosure_new()
)
находит callback-функцию из фиксированного смещения в классовой структуре.
Мета-маршаллер отыскивает правильную callback-функцию и помещает её в маршаллер как аргумент
marshal_data
.
closure : |
GClosure |
marshal_data : |
зависимые от контекста данные помещаемые в meta_marshal
|
meta_marshal : |
функция GClosureMarshal |
void g_source_set_closure (GSource *source, GClosure *closure);
Устанавливает callback-функцию для источника подобного GClosure.
Если источник не относится к стандартным типам GLib, поля closure_callback
и closure_marshal
сструктуры
GSourceFuncs должны быть заполнены
указателями подходящих функций.
source : |
источник |
closure : |
GClosure |
#define G_TYPE_IO_CONDITION (g_io_condition_get_type ())
GType для GIOCondition.
void g_cclosure_marshal_VOID__VOID (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gpointer user_data)
.
closure : |
GClosure которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
1 |
param_values : |
массив GValue содержащих только экземпляр |
invocation_hint : |
подсказка вызова получаемая как последний аргумент
g_closure_invoke()
|
marshal_data : |
дополнительные данные определяемые при регистрации маршаллера |
void g_cclosure_marshal_VOID__BOOLEAN (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gboolean параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент для
g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__CHAR (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gchar arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляры и gchar параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент для
g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__UCHAR (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, guchar arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и guchar параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__INT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gint arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gint параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__UINT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, guint arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и guint параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__LONG (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, glong arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и glong параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__ULONG (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gulong arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gulong параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__ENUM (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gint arg1, gpointer user_data)
где gint параметр указывает тип перечисления..
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и перечислимый параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__FLAGS (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gint arg1, gpointer user_data)
где gint параметр указывает тип флагов.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и флаговый параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__FLOAT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gfloat параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__DOUBLE (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gdouble параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__STRING (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gchar* параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__PARAM (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и GParamSpec* параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__BOXED (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и GBoxed* параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__POINTER (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и gpointer параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__OBJECT (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и GObject* параметр |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_STRING__OBJECT_POINTER (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
3 |
param_values : |
массив GValue содержащих экземпляр, arg1 и arg2 |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_VOID__UINT_POINTER (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)
.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
игнорируется |
n_param_values : |
3 |
param_values : |
массив GValue содержащих экземпляр, arg1 и arg2 |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
void g_cclosure_marshal_BOOLEAN__FLAGS (GClosure *closure, GValue *return_value, guint n_param_values, const GValue *param_values, gpointer invocation_hint, gpointer marshal_data);
Маршаллер для GCClosure с callback-функцией типа
gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)
где gint параметр
указывает тип флагов.
closure : |
GClosure к которой принадлежит маршаллер |
return_value : |
GValue которая может хранить возвращаемое gboolean |
n_param_values : |
2 |
param_values : |
массив GValue содержащих экземпляр и arg1 |
invocation_hint : |
подсказка вызова полученная как последний аргумент
для g_closure_invoke()
|
marshal_data : |
дополнительные данные определённые при регистрации маршаллера |
#define g_cclosure_marshal_BOOL__FLAGS
Другое имя для g_cclosure_marshal_BOOLEAN__FLAGS()
.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> #define G_TYPE_IS_PARAM (type) #define G_PARAM_SPEC (pspec) #define G_IS_PARAM_SPEC (pspec) #define G_PARAM_SPEC_CLASS (pclass) #define G_IS_PARAM_SPEC_CLASS (pclass) #define G_PARAM_SPEC_GET_CLASS (pspec) #define G_PARAM_SPEC_TYPE (pspec) #define G_PARAM_SPEC_TYPE_NAME (pspec) #define G_PARAM_SPEC_VALUE_TYPE (pspec) GParamSpec; GParamSpecClass; enum GParamFlags; #define G_PARAM_READWRITE #define G_PARAM_STATIC_STRINGS #define G_PARAM_MASK #define G_PARAM_USER_SHIFT GParamSpec* g_param_spec_ref (GParamSpec *pspec); void g_param_spec_unref (GParamSpec *pspec); void g_param_spec_sink (GParamSpec *pspec); GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec); void g_param_value_set_default (GParamSpec *pspec, GValue *value); gboolean g_param_value_defaults (GParamSpec *pspec, GValue *value); gboolean g_param_value_validate (GParamSpec *pspec, GValue *value); gboolean g_param_value_convert (GParamSpec *pspec, const GValue *src_value, GValue *dest_value, gboolean strict_validation); gint g_param_values_cmp (GParamSpec *pspec, const GValue *value1, const GValue *value2); const gchar* g_param_spec_get_name (GParamSpec *pspec); const gchar* g_param_spec_get_nick (GParamSpec *pspec); const gchar* g_param_spec_get_blurb (GParamSpec *pspec); gpointer g_param_spec_get_qdata (GParamSpec *pspec, GQuark quark); void g_param_spec_set_qdata (GParamSpec *pspec, GQuark quark, gpointer data); void g_param_spec_set_qdata_full (GParamSpec *pspec, GQuark quark, gpointer data, GDestroyNotify destroy); gpointer g_param_spec_steal_qdata (GParamSpec *pspec, GQuark quark); GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec); gpointer g_param_spec_internal (GType param_type, const gchar *name, const gchar *nick, const gchar *blurb, GParamFlags flags); GParamSpecTypeInfo; GType g_param_type_register_static (const gchar *name, const GParamSpecTypeInfo *pspec_info); GParamSpecPool; GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing); void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type); void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec); GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, const gchar *param_name, GType owner_type, gboolean walk_ancestors); GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, GType owner_type, guint *n_pspecs_p); GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, GType owner_type);
GParamSpec is an object structure that encapsulates the metadata required to specify parameters, such as e.g. GObject properties.
Имя параметра должно начинаться с букв (a-z или A-Z). Последующие символы могут быть буквами, цифрами или символом '-'. Все другие символы заменяются символом '-' в процессе конструирования. Результат этого замещения называется каноническим именем параметра.
#define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
Определяет соответствует ли type
"is a" G_TYPE_PARAM
.
type : |
GType ID |
#define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
Преобразует производный объект GParamSpec (например тип GParamSpecInt) в объект GParamSpec.
pspec : |
допустимая структура GParamSpec |
#define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
Проверяет является ли pspec
"is a" допустимой структурой
GParamSpec типа
G_TYPE_PARAM
или производной.
pspec : |
GParamSpec |
#define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
Преобразует производную структуру GParamSpecClass в структуру GParamSpecClass.
pclass : |
допустимая структура GParamSpecClass |
#define G_IS_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
Проверяет является ли pclass
"is a" допустимой структурой
GParamSpecClass типа
G_TYPE_PARAM
или производной.
pclass : |
GParamSpecClass |
#define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
Находит GParamSpecClass из GParamSpec.
pspec : |
допустимая структура GParamSpec |
#define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec))
Находит GType этой pspec
.
pspec : |
допустимая структура GParamSpec |
#define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
Находит GType имя этой pspec
.
pspec : |
допустимая структура GParamSpec |
#define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type)
Находит GType для инициализации GValue этого параметра.
pspec : |
допустимая структура GParamSpec |
typedef struct { GTypeInstance g_type_instance; gchar *name; GParamFlags flags; GType value_type; GType owner_type; /* class or interface using this property */ } GParamSpec;
Все поля сструктуры GParamSpec закрыты и не должны использоваться непосредственно, за исключением следующих:
GTypeInstance
g_type_instance ; |
закрытая часть GTypeInstance |
gchar
*name ; |
имя этого параметра |
GParamFlags flags ; |
GParamFlags флаги для этого параметра |
GType value_type ; |
тип GValue для этого параметра |
GType owner_type ; |
тип GType который использует (вводит) этот параметр |
typedef struct { GTypeClass g_type_class; GType value_type; void (*finalize) (GParamSpec *pspec); /* GParam methods */ void (*value_set_default) (GParamSpec *pspec, GValue *value); gboolean (*value_validate) (GParamSpec *pspec, GValue *value); gint (*values_cmp) (GParamSpec *pspec, const GValue *value1, const GValue *value2); } GParamSpecClass;
Классовая структура для GParamSpec.
Обычно, классовая GParamSpec заполняется с помощью
g_param_type_register_static()
.
GTypeClass g_type_class ; |
родительский класс |
GType value_type ; |
тип GValue для этого параметра |
finalize () |
Функция финализации экземпляра (опционально), должна прикрепляться к методу родительского класса. |
value_set_default () |
Сбрасывает value в значение по умолчанию для этого типа
(рекомендуемое значение по умолчанию - g_value_reset() ),
смотрите g_param_value_set_default() .
|
value_validate () |
Гарантирует что содержимое value выполняет спецификацию
установленную этим типом (опционально), смотрите g_param_value_set_validate() .
|
values_cmp () |
Сравнивает value1 с value2 согласно этого типа
(рекомендуемое значение по умолчанию - memcmp() ),
смотрите g_param_values_cmp() .
|
typedef enum { G_PARAM_READABLE = 1 << 0, G_PARAM_WRITABLE = 1 << 1, G_PARAM_CONSTRUCT = 1 << 2, G_PARAM_CONSTRUCT_ONLY = 1 << 3, G_PARAM_LAX_VALIDATION = 1 << 4, G_PARAM_STATIC_NAME = 1 << 5, #ifndef G_DISABLE_DEPRECATED G_PARAM_PRIVATE = G_PARAM_STATIC_NAME, #endif G_PARAM_STATIC_NICK = 1 << 6, G_PARAM_STATIC_BLURB = 1 << 7 } GParamFlags;
Через значения GParamFlags, могут конфигурироваться определённые аспекты параметра.
G_PARAM_READABLE |
параметр можно прочесть |
G_PARAM_WRITABLE |
параметр можно записать |
G_PARAM_CONSTRUCT |
параметр будет установлен на конструкцию объекта |
G_PARAM_CONSTRUCT_ONLY |
параметр будет установлен только на конструкцию объекта |
G_PARAM_LAX_VALIDATION |
при преобразовании параметра не требуется строгая проверка правильности
(смотрите g_param_value_convert() )
|
G_PARAM_STATIC_NAME |
строка используемая как имя параметра при конструировании параметра гарантированно останется допустимой и неизменной в процессе жизненного цикла параметра. Начиная с версии 2.8 |
G_PARAM_PRIVATE |
|
G_PARAM_STATIC_NICK |
|
G_PARAM_STATIC_BLURB |
строка используемая как описание параметра при конструировании параметра гарантированно останется допустимой и неизменной в процессе жизненного цикла параметра. Начиная с версии 2.8 |
#define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE)
GParamFlags значение псевдонима для
G_PARAM_READABLE
| G_PARAM_WRITABLE
.
#define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)
GParamFlags значение псевдонима для G_PARAM_STATIC_NAME
| G_PARAM_STATIC_NICK
| G_PARAM_STATIC_BLURB
.
#define G_PARAM_MASK (0x000000ff)
Маска содержащая биты GParamSpec.flags которые зарезервированы для GLib.
#define G_PARAM_USER_SHIFT (8)
Минимальный сдвиг счетчика используемый для флагов определяемых пользователем, сохраняемых в GParamSpec.flags.
GParamSpec* g_param_spec_ref (GParamSpec *pspec);
Увеличивает количество ссылок pspec
.
pspec : |
допустимая структура GParamSpec |
Возвращает : | GParamSpec которая была помещена в эту функцию |
void g_param_spec_unref (GParamSpec *pspec);
Уменьшает количество ссылок pspec
.
pspec : |
допустимая структура GParamSpec |
void g_param_spec_sink (GParamSpec *pspec);
Инициализирует единицей счётчик ссылок вновь созданной GParamSpec,
даже если g_param_spec_ref()
не была вызвана явно.
Таким образом счётчик ссылок помечается как "плавающий" ("floating"), пока кто нибудь не вызовет
g_param_spec_ref (pspec); g_param_spec_sink (pspec);
в такой последовательности, переинициализировав счётчик ссылок
(таким образом счётчик ссылок pspec
остаётся равным 1, но больше не помечен как "плавающий").
pspec : |
допустимая структура GParamSpec |
GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec);
Удобная функция для создания ссылки и отмены плавающей GParamSpec.
pspec : |
допустимая структура GParamSpec |
Возвращает : | GParamSpec которая помещается в функцию |
Начиная с версии 2.10
void g_param_value_set_default (GParamSpec *pspec, GValue *value);
Устанавливает value
в значение по умолчанию как определено в
pspec
.
pspec : |
допустимая структура GParamSpec |
value : |
GValue правильного типа для
pspec
|
gboolean g_param_value_defaults (GParamSpec *pspec, GValue *value);
Проверяет содержит ли value
значение по умолчанию определённое в
pspec
.
pspec : |
допустимая структура GParamSpec |
value : |
GValue правильного типа для
pspec
|
Возвращает : | содержит ли value каноническое значение по умолчанию для этой
pspec
|
gboolean g_param_value_validate (GParamSpec *pspec, GValue *value);
Гарантирует что содержимое value
соответствует спецификации установленной с помощью
pspec
. Например, GParamSpecInt может потребовать чтобы целочисленные хранящиеся в value
были не меньше чем -42 и не больше чем +42. Если целочисленное содержимое value
выходит за этот
диапазон, оно соответственно изменяется, чтобы результирующее значение вписывалось в диапазон -42 .. +42.
pspec : |
допустимая структура GParamSpec |
value : |
GValue правильного типа для
pspec
|
Возвращает : | необходимо ли изменить value чтобы гарантировать его допустимость
|
gboolean g_param_value_convert (GParamSpec *pspec, const GValue *src_value, GValue *dest_value, gboolean strict_validation);
Преобразует src_value
в dest_value
если возможно,
а зтем утверждает dest_value
для соответствия pspec
.
Если strict_validation
это TRUE
, эта функция выполнится успешно только если преобразованный
dest_value
соответствует pspec
без изменений.
Смотрите также g_value_type_transformable()
, g_value_transform()
и
g_param_value_validate()
.
pspec : |
допустимая структура GParamSpec |
src_value : |
исходная GValue |
dest_value : |
целевая GValue правильного типа для
pspec
|
strict_validation : |
TRUE требует чтобы
dest_value соответствовало pspec без изменений
|
Возвращает : | TRUE
если преобразование и утверждение истинности полностью выполнены, иначе
FALSE и
dest_value остаётся нетронутым.
|
gint g_param_values_cmp (GParamSpec *pspec, const GValue *value1, const GValue *value2);
Сравнивает value1
с value2
согласно
pspec
, и возвращает -1, 0 или +1,
если value1
найдено но меньше, равно или больше чем value2
,
соответственно.
pspec : |
допустимая структура GParamSpec |
value1 : |
GValue правильного типа для
pspec
|
value2 : |
GValue правильного типа для
pspec
|
Возвращает : | -1, 0 или +1, для меньше, равно или больше чем результат |
const gchar* g_param_spec_get_name (GParamSpec *pspec);
Возвращает имя GParamSpec.
pspec : |
допустимая структура GParamSpec |
Возвращает : | имя pspec .
|
const gchar* g_param_spec_get_nick (GParamSpec *pspec);
Возвращает псевдоним GParamSpec.
pspec : |
допустимая структура GParamSpec |
Возвращает : | псевдоним pspec .
|
const gchar* g_param_spec_get_blurb (GParamSpec *pspec);
Возвращает короткое описание GParamSpec.
pspec : |
допустимая структура GParamSpec |
Возвращает : | короткое описание pspec .
|
gpointer g_param_spec_get_qdata (GParamSpec *pspec, GQuark quark);
Получает назад указатели пользовательских данных сохранённые через
g_param_spec_set_qdata()
.
pspec : |
допустимая структура GParamSpec |
quark : |
GQuark, именующий указатель пользовательских данных |
Возвращает : | установленный указатель пользовательских данных, или
NULL
|
void g_param_spec_set_qdata (GParamSpec *pspec, GQuark quark, gpointer data);
Устанавливает непрозрачный, именованный указатель в
GParamSpec. Имя определяется через
GQuark (найденный например через
g_quark_from_static_string()
),
а указатель может быть возвращён из pspec
с помощью
g_param_spec_get_qdata()
.
Устанавливаемый набор указателей пользовательских данных, переписывает (освобождает) старый набор указателей,
используя NULL
,
так как указатель фактически удаляет хранящиеся данные.
pspec : |
GParamSpec для хранения установленного указателя пользовательских данных |
quark : |
GQuark, именованный указатель пользовательских данных |
data : |
непрозрачный указатель пользовательских данных |
void g_param_spec_set_qdata_full (GParamSpec *pspec, GQuark quark, gpointer data, GDestroyNotify destroy);
Эта функция работает как g_param_spec_set_qdata()
,
но дополнительно, может быть определена функция void (*destroy) (gpointer)
которая вызывается с
data
в качестве аргумента при финализации pspec
,
или данные перезаписываются вызовом g_param_spec_set_qdata()
с тем же самым quark
.
pspec : |
GParamSpec для хранения установленного указателя пользовательских данных |
quark : |
GQuark, именующий указатель пользовательских данных |
data : |
непрозрачный указатель пользовательских данных |
destroy : |
функция вызываемая с data в качестве аргумента,
когда data необходимо освободить
|
gpointer g_param_spec_steal_qdata (GParamSpec *pspec, GQuark quark);
Получает обратно указатели пользовательских данных сохранённые через
g_param_spec_set_qdata()
и удаляет
data
из pspec
без вызова её destroy()
функции (если была установлена).
Обычно, вызов этой функции требуется только для обновления указателей пользовательских данных с уведомлением о разрушении.
pspec : |
GParamSpec для получения сохраненного указателя пользовательских данных |
quark : |
GQuark, именующий указатель пользовательских данных |
Возвращает : | установленный указатель пользовательских данных, или
NULL
|
GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec);
Если спецификация параметра перенаправила операции в другую спецификацию параметра (paramspec),
возвращается эта спецификация параметра. Перенаправление обычно используется для обеспечения новой реализации свойств в производном типе
сохраняя все свойства родительского типа. Перенаправление устанавливается созданием свойства типа
GParamSpecOverride.
Смотрите пример использования этой возможности в g_object_override_property()
.
pspec : |
GParamSpec |
Возвращает : | спецификация параметра в которую переадресованы операции, или
NULL если нет.
|
Начиная с версии 2.4
gpointer g_param_spec_internal (GType param_type, const gchar *name, const gchar *nick, const gchar *blurb, GParamFlags flags);
Создаёт новый экземпляр GParamSpec.
Имя свойства содержит ASCII буквы и цифры, разделённые символом '-' или '_'. Первый символ имени свойства должен быть буквой. Имена которые нарушают это правило приводят к неопределённому поведению.
При создании и поиске GParamSpec, каждый разделитель может быть использован, но они не могут быть смешаны. Использование '-' наиболее эффективно и фактически требуется когда имена свойств используются как детальные строки для сигналов.
param_type : |
GType для свойства; должна быть производной из G_TYPE_PARAM |
name : |
каноническое имя свойства |
nick : |
псевдоним свойства |
blurb : |
короткое описание свойства |
flags : |
комбинация GParamFlags |
Возвращает : | вновь распределённый экземпляр GParamSpec |
typedef struct { /* type system portion */ guint16 instance_size; /* obligatory */ guint16 n_preallocs; /* optional */ void (*instance_init) (GParamSpec *pspec); /* optional */ /* class portion */ GType value_type; /* obligatory */ void (*finalize) (GParamSpec *pspec); /* optional */ void (*value_set_default) (GParamSpec *pspec, /* recommended */ GValue *value); gboolean (*value_validate) (GParamSpec *pspec, /* optional */ GValue *value); gint (*values_cmp) (GParamSpec *pspec, /* recommended */ const GValue *value1, const GValue *value2); } GParamSpecTypeInfo;
Эта структура используется для обеспечения системы типов информацией требующейся для инициализации и уничтожения (финализации)
класса параметра и его экземпляра. Инициализированная структура помещается в
g_param_type_register_static()
система типов делает глубокую копию этой сструктуры, поэтому память не используется между вызовами
g_param_type_register_static()
.
guint16
instance_size ; |
Размер экземпляра сструктуры (объекта). |
guint16
n_preallocs ; |
До версии GLib 2.10, определял количество предварительно распределённых (кешированных) экземпляров для резервирования памяти (0 указывал на отсутствие кеша). Начиная с версии GLib 2.10, игнорируется, так как теперь экземпляры распределяются с помощью slice allocator. |
instance_init () |
Расположение функции инициализации экземпляра (опционально). |
GType value_type ; |
GType значение соответствующее этой GParamSpec |
finalize () |
Функция финализации экземпляра (опционально). |
value_set_default () |
Сбрасывает value в значение по умолчанию для pspec
(рекомендуемое значение по умолчанию - g_value_reset() ),
смотрите g_param_value_set_default() .
|
value_validate () |
Гарантирует что содержимое value соответствует спецификации
pspec (опционально), смотрите g_param_value_set_validate() .
|
values_cmp () |
Сравнивает value1 с value2
согласно pspec (рекомендуемое значение по умолчанию - memcmp() ),
смотрите g_param_values_cmp() .
|
GType g_param_type_register_static (const gchar *name, const GParamSpecTypeInfo *pspec_info);
Регистрирует name
как имя нового статичного типа унаследованного из
G_TYPE_PARAM.
Система типов использует информацию содержащуюся в структуре
GParamSpecTypeInfo указанной с помощью
info
для управления
GParamSpec и её экземплярами.
name : |
0-завершённая строка используемая как имя нового типа GParamSpec. |
pspec_info : |
GParamSpecTypeInfo для этого типа GParamSpec. |
Возвращает : | Новый идентификатор типа. |
typedef struct _GParamSpecPool GParamSpecPool;
GParamSpecPool содержащая накопленные GParamSpec быстрый доступ к которым может осуществляться по имени и владельцу. Реализованное свойство GObject система использует как пул для хранения свойств GParamSpecs всех типовых объектов.
GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing);
Создаёт новую GParamSpecPool.
Если type_prefixing
это
TRUE
, поиск во вновь созданном пуле
позволит определять владельца как отделённый двоеточием префикс имени свойства, например "GtkContainer:border-width".
Эта особенность устарела, поэтому вы должны всегда устанавливать type_prefixing
в значение
FALSE
.
type_prefixing : |
Поддерживает ли пул имена свойств с типовыми префиксами. |
Возвращает : | вновь распределённый GParamSpecPool. |
void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type);
Вставляет GParamSpec в пул.
pool : |
GParamSpecPool. |
pspec : |
вставляемая GParamSpec |
owner_type : |
GType идентифицирующий владельца
pspec
|
void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec);
Удаляет GParamSpec из пула.
pool : |
GParamSpecPool |
pspec : |
GParamSpec для удаления |
GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, const gchar *param_name, GType owner_type, gboolean walk_ancestors);
Ищет GParamSpec в пуле.
pool : |
GParamSpecPool |
param_name : |
имя для поиска |
owner_type : |
владелец для поиска |
walk_ancestors : |
Если TRUE ,
попробует искать GParamSpec с
param_name которая принадлежит предку owner_type .
|
Возвращает : | Найденная GParamSpec, или
NULL если соответствующая
GParamSpec не найдена.
|
GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, GType owner_type, guint *n_pspecs_p);
Получает массив всех GParamSpec принадлежащих
owner_type
в пуле.
pool : |
GParamSpecPool |
owner_type : |
владелец для поиска |
n_pspecs_p : |
расположение длины возвращаемого массива |
Возвращает : | вновь распределённый массив содержащий указатели на все
GParamSpec принадлежащие
owner_type в пуле
|
GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, GType owner_type);
Получает GList всех
GParamSpec принадлежащие
owner_type
в пуле.
pool : |
GParamSpecPool |
owner_type : |
владелец для поиска |
Возвращает : | GList всех
GParamSpec принадлежащие
owner_type в пуле GParamSpecs.
|
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> GEnumClass; GFlagsClass; #define G_ENUM_CLASS_TYPE (class) #define G_ENUM_CLASS_TYPE_NAME (class) #define G_TYPE_IS_ENUM (type) #define G_ENUM_CLASS (class) #define G_IS_ENUM_CLASS (class) #define G_TYPE_IS_FLAGS (type) #define G_FLAGS_CLASS (class) #define G_IS_FLAGS_CLASS (class) #define G_FLAGS_CLASS_TYPE (class) #define G_FLAGS_CLASS_TYPE_NAME (class) GEnumValue; GFlagsValue; GEnumValue* g_enum_get_value (GEnumClass *enum_class, gint value); GEnumValue* g_enum_get_value_by_name (GEnumClass *enum_class, const gchar *name); GEnumValue* g_enum_get_value_by_nick (GEnumClass *enum_class, const gchar *nick); GFlagsValue* g_flags_get_first_value (GFlagsClass *flags_class, guint value); GFlagsValue* g_flags_get_value_by_name (GFlagsClass *flags_class, const gchar *name); GFlagsValue* g_flags_get_value_by_nick (GFlagsClass *flags_class, const gchar *nick); GType g_enum_register_static (const gchar *name, const GEnumValue *const _static_values); GType g_flags_register_static (const gchar *name, const GFlagsValue *const _static_values); void g_enum_complete_type_info (GType g_enum_type, GTypeInfo *info, const GEnumValue *const _values); void g_flags_complete_type_info (GType g_flags_type, GTypeInfo *info, const GFlagsValue *const _values);
Система типов GLib обеспечивает базовые типы для перечислений и типовых флажков.
(Типовые флаги похожи на перечисления, но позволяют поразрядное комбинирование своих значений).
Регистрация перечисления или типовых флажков связывает имя и псевдоним с каждым возможным значением, а методы
g_enum_get_value_by_name()
,
g_enum_get_value_by_nick()
,
g_flags_get_value_by_name()
и g_flags_get_value_by_nick()
могут находить значение по их имени или псевдониму. Когда перечисление или типовые флаги зарегистрированы системой типов GLib,
они могут использоваться как типовое значение для свойств объекта, используя
g_param_spec_enum()
или
g_param_spec_flags()
.
GObject устанавливается с помощью утилиты называемой glib-mkenums которая может конструировать подходящий тип регистрационных функций из определённых C перечислений.
typedef struct { GTypeClass g_type_class; gint minimum; gint maximum; guint n_values; GEnumValue *values; } GEnumClass;
Класс типового перечисления содержит информацию о возможных значениях.
GTypeClass
g_type_class ; |
родительский класс |
gint
minimum ; |
минимально-возможное значение. |
gint
maximum ; |
максимально-возможное значение. |
guint
n_values ; |
количество возможных значений. |
GEnumValue *values ; |
массив структур GEnumValue описывающих индивидуальные значения. |
typedef struct { GTypeClass g_type_class; guint mask; guint n_values; GFlagsValue *values; } GFlagsClass;
Класс типовых флажков содержит информацию об их возможных значениях.
GTypeClass g_type_class ; |
родительский класс |
guint
mask ; |
маска покрывающая возможные значения. |
guint
n_values ; |
количество возможных значений. |
GFlagsValue *values ; |
массив структур GFlagsValue описывающих индивидуальные значения. |
#define G_ENUM_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
Возвращает идентификатор типа из полученной структуры GEnumClass.
class : |
GEnumClass |
#define G_ENUM_CLASS_TYPE_NAME(class) (g_type_name (G_ENUM_CLASS_TYPE (class)))
Возвращает статичное имя типа полученное из сструктуры GEnumClass.
class : |
GEnumClass |
#define G_TYPE_IS_ENUM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_ENUM)
Возвращает является ли type
"is a" G_TYPE_ENUM
.
type : |
GType ID. |
#define G_ENUM_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_ENUM, GEnumClass))
Приводит производную структуру GEnumClass в структуру GEnumClass.
class : |
допустимая GEnumClass |
#define G_IS_ENUM_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_ENUM))
Проверяет является ли class
"is a" допустимой структурой
GEnumClass типа
G_TYPE_ENUM
или производной.
class : |
GEnumClass |
#define G_TYPE_IS_FLAGS(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_FLAGS)
Возвращает является ли type
"is a" G_TYPE_FLAGS
.
type : |
GType ID. |
#define G_FLAGS_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_FLAGS, GFlagsClass))
Приводит производную структуру GFlagsClass в структуру GFlagsClass.
class : |
допустимая GFlagsClass |
#define G_IS_FLAGS_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_FLAGS))
Проверяет является ли class
"is a" допустимой структурой
GFlagsClass типа
G_TYPE_FLAGS
или производной.
class : |
GFlagsClass |
#define G_FLAGS_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
Возвращает идентификатор типа из полученной сструктуры GFlagsClass.
class : |
GFlagsClass |
#define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))
Возвращает статичное имя из полученной сструктуры GFlagsClass.
class : |
GFlagsClass |
typedef struct { gint value; const gchar *value_name; const gchar *value_nick; } GEnumValue;
Структура содержащая единственное значение перечисления, его имя, и его псевдоним.
typedef struct { guint value; const gchar *value_name; const gchar *value_nick; } GFlagsValue;
Структура содержащая единственное значение флажка, его имя, и его псевдоним.
GEnumValue* g_enum_get_value (GEnumClass *enum_class, gint value);
Возвращает GEnumValue для значения.
enum_class : |
GEnumClass |
value : |
значение для поиска |
Возвращает : | GEnumValue для
value , или
NULL если
value не член перечисления
|
GEnumValue* g_enum_get_value_by_name (GEnumClass *enum_class, const gchar *name);
Находит GEnumValue по имени.
enum_class : |
GEnumClass |
name : |
имя для поиска |
Возвращает : | GEnumValue с именем
name , или
NULL
если перечисление не имеет член с таким именем
|
GEnumValue* g_enum_get_value_by_nick (GEnumClass *enum_class, const gchar *nick);
Находит GEnumValue по псевдониму.
enum_class : |
GEnumClass |
nick : |
псевдоним для поиска |
Возвращает : | GEnumValue с псевдонимом
nick , или
NULL
если перечисление не имеет член с таким псевдонимом
|
GFlagsValue* g_flags_get_first_value (GFlagsClass *flags_class, guint value);
Возвращает первое GFlagsValue
которое устанавливается в value
.
flags_class : |
GFlagsClass |
value : |
значение |
Возвращает : | первое GFlagsValue
которое установлено в value , или
NULL если не установлено
|
GFlagsValue* g_flags_get_value_by_name (GFlagsClass *flags_class, const gchar *name);
Находит GFlagsValue по имени.
flags_class : |
GFlagsClass |
name : |
имя для поиска |
Возвращает : | GFlagsValue с именем
name , или
NULL если нет флага с таким именем
|
GFlagsValue* g_flags_get_value_by_nick (GFlagsClass *flags_class, const gchar *nick);
Находит GFlagsValue по псевдониму.
flags_class : |
GFlagsClass |
nick : |
псевдоним для поиска |
Возвращает : | GFlagsValue с псевдонимом
nick , или
NULL если нет флага стаким псевдонимом
|
GType g_enum_register_static (const gchar *name, const GEnumValue *const _static_values);
Регистрирует новый статичный тип перечисления с именем name
.
Обычно более удобно позволить glib-mkenums сгенирировать
функцию my_enum_get_type()
из обычного определения перечисления C, чем самостоятельно писать используя
g_enum_register_static()
.
name : |
Nul-завершённая строка используемая как имя нового типа. |
_static_values : |
|
Возвращает : | Идентификатор нового типа. |
GType g_flags_register_static (const gchar *name, const GFlagsValue *const _static_values);
Регистрирует новый статичный флаговый тип с именем name
.
Обычно более удобно позволить glib-mkenums сгенирировать
функцию my_flags_get_type()
из обычного определения перечисления C, чем самостоятельно писать используя
g_flags_register_static()
.
name : |
Nul-завершённая строка используемая как имя нового типа. |
_static_values : |
|
Возвращает : | Идентификатор нового типа. |
void g_enum_complete_type_info (GType g_enum_type, GTypeInfo *info, const GEnumValue *const _values);
Эта функция предназначена для вызова из функции complete_type_info()
реализации
GTypePlugin, как показано в следующем примере:
static void my_enum_complete_type_info (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table) { static const GEnumValue values[] = { { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, { 0, NULL, NULL } }; g_enum_complete_type_info (type, info, values); }
g_enum_type : |
типовой идентификатор заполняемого типа |
info : |
Структура GTypeInfo для заполнения |
_values : |
void g_flags_complete_type_info (GType g_flags_type, GTypeInfo *info, const GFlagsValue *const _values);
Эта функция предназначена для вызова из функции complete_type_info()
реализации
GTypePlugin, смотрите пример для
g_enumeration_complete_type_info()
выше.
g_flags_type : |
типовой идентификатор заполняемого типа |
info : |
Структура GTypeInfo для заполнения |
_values : |
GParamSpecEnum, GParamSpecFlags, g_param_spec_enum()
, g_param_spec_flags()
,
glib-mkenums
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> #define G_VALUE_HOLDS (value,type) #define G_VALUE_TYPE (value) #define G_VALUE_TYPE_NAME (value) #define G_TYPE_IS_VALUE (type) #define G_TYPE_IS_VALUE_ABSTRACT (type) #define G_IS_VALUE (value) GValue; #define G_TYPE_VALUE #define G_TYPE_VALUE_ARRAY GValue* g_value_init (GValue *value, GType g_type); void g_value_copy (const GValue *src_value, GValue *dest_value); GValue* g_value_reset (GValue *value); void g_value_unset (GValue *value); void g_value_set_instance (GValue *value, gpointer instance); gboolean g_value_fits_pointer (const GValue *value); gpointer g_value_peek_pointer (const GValue *value); gboolean g_value_type_compatible (GType src_type, GType dest_type); gboolean g_value_type_transformable (GType src_type, GType dest_type); gboolean g_value_transform (const GValue *src_value, GValue *dest_value); void (*GValueTransform) (const GValue *src_value, GValue *dest_value); void g_value_register_transform_func (GType src_type, GType dest_type, GValueTransform transform_func); gchar* g_strdup_value_contents (const GValue *value);
Структура GValue в общем переменная-контейнер которая содержит
идентификатор типа и определённое значение этого типа.
Идентификатор типа внутри сструктуры GValue
всегда определяет тип связанного с ним значения.
Для создания неопределённой сструктуры GValue,
просто создаётся структура GValue заполненная нулями.
Для инициализации GValue, используйте функцию
g_value_init()
.
GValue не может использоваться пока не инициализирована.
Основные типовые операции (такие как копирование и освобождение) определяются в
GTypeValueTable связанной с типовым ID
хранящемся в GValue.
Другие GValue операции
(такие как преобразование значений между типами) обеспечивает этот интерфейс.
#define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
Возвращает TRUE
если
value
содержит значение type
.
Этот макрос также проконтролирует
value
!= NULL
и выдаст предупреждение если проверка не удалась.
#define G_VALUE_TYPE(value) (((GValue*) (value))->g_type)
Возвращает идентификатор типа value
.
value : |
Структура GValue. |
#define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value)))
Возвращает типовое имя value
.
value : |
Структура GValue. |
#define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type))
Возвращает может ли помещенный типовой ID использоваться для
g_value_init()
.
Таким образом, этот макрос проверяет обеспечивает ли реализация функции
GTypeValueTable необходимые для создания типа
GValue.
#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
Возвращает TRUE
если
type
это абстрактное значение типа. Абстрактное значение типа входит в таблицу значений,
но не может использоваться для g_value_init()
и обычно используется как абстрактный базовый тип для производных типовых значений.
type : |
Значение GType. |
#define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value))
Возвращает TRUE
если
value
это допустимая и инициализированная структура
GValue.
value : |
Структура GValue. |
typedef struct { } GValue;
Не прозрачная структура для содержания разных типовых значений.
Данные в структуре являются закрытым контекстом: доступ к ним осуществляется только с помощью функций внутри сструктуры
GTypeValueTable, или реализуются g_value_*() API.
То есть части кода которые реализуют новые базовые типы.
Пользователи GValue не могут предполагать о том как данные
хранятся внутри 2 элементов объединения data
, а к члену
g_type
можно обращаться только через макрос
G_VALUE_TYPE()
.
#define G_TYPE_VALUE (g_value_get_type ())
Возвращает типовой ID типа "GValue" который является упаковочным типом, используемый для размещения указателей на GValues.
#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())
Возвращает типовой ID типа "GValueArray" который является упаковочным типом, используемый для размещения указателей на GValueArrays.
GValue* g_value_init (GValue *value, GType g_type);
Инициализирует value
которое по умолчанию является значением
type
.
void g_value_copy (const GValue *src_value, GValue *dest_value);
Копирует значение src_value
в dest_value
.
GValue* g_value_reset (GValue *value);
Очищает текущее значение в value
и сбрасывает его в значение по умолчанию
(как будто значение было только что инициализировано).
void g_value_unset (GValue *value);
Очищает текущее значение в value
и "отменяет установку" ("unsets") типа,
это высвобождает все ресурсы связанные с этой структурой GValue.
Сбросить значение тоже самое что заполненить нулями (zero-filled) структуру
GValue.
value : |
Инициализированная структура GValue. |
void g_value_set_instance (GValue *value, gpointer instance);
Устанавливает value
из инстанциируемого типа через
value_table's функцию collect_value()
.
value : |
Инициализированная структура GValue. |
instance : |
экземпляр |
gboolean g_value_fits_pointer (const GValue *value);
Определяет будет ли value
соответствовать размеру значения указателя.
Это внутренняя функция введённая главным образом для C маршаллеров.
gpointer g_value_peek_pointer (const GValue *value);
Возвращает содержимое значения как указатель. Эта функция утверждает что
g_value_fits_pointer()
возвратит TRUE
для помещённого значения.
Это внутренняя функция введённая главным образом для C маршаллеров.
gboolean g_value_type_compatible (GType src_type, GType dest_type);
Возвращает может ли GValue типа
src_type
быть скопирована в
GValue типа dest_type
.
src_type : |
исходный тип для копирования. |
dest_type : |
целевой тип для копирования. |
Возвращает : |
TRUE если
g_value_copy() возможно использовать с
src_type и dest_type .
|
gboolean g_value_type_transformable (GType src_type, GType dest_type);
Проверяет может ли g_value_transform()
преобразовать значения типа src_type
в значения типа
dest_type
.
gboolean g_value_transform (const GValue *src_value, GValue *dest_value);
Пробует преобразовать содержимое src_value
в тип подходящий для сохранения в
dest_value
, например преобразовать
значение G_TYPE_INT
в значение
G_TYPE_FLOAT
. Выполнение преобразования
между значениями типов может привести к серьёзной программной ошибке (lossage). Особенно преобразование в строки может привести к
непредсказуемым результатам на которые нельзя положиться в производственном коде
(такие как значение rcfile или преобразование в последовательную форму свойства объекта).
src_value : |
Исходное значение. |
dest_value : |
Целевое значение. |
Возвращает : | Найдено ли правило преобразование и может ли быть применено.
После неудачной попытки преобразования, dest_value остаётся нетронутым.
|
void (*GValueTransform) (const GValue *src_value, GValue *dest_value);
Функция преобразования типовых значений которая может быть зарегистрирована с помощью
g_value_register_transform_func()
.
src_value : |
Исходное значение. |
dest_value : |
Целевое значение. |
void g_value_register_transform_func (GType src_type, GType dest_type, GValueTransform transform_func);
Регистрирует функцию преобразования значений для использования в
g_value_transform()
.
Предварительно зарегистрированная функция для src_type
и
dest_type
будет заменена.
src_type : |
Исходное значение. |
dest_type : |
Целевое значение. |
transform_func : |
функция которая преобразует значение типа src_type
в значение типа dest_type
|
gchar* g_strdup_value_contents (const GValue *value);
Возвращает вновь рапределённую строку, которая описывает содержимое GValue. Основная цель этой функции состоит в том чтобы описать содержимое GValue для отладочного вывода, способ которым описывается содержимое может меняться в разных версиях GLib.
value : |
GValue контекст которой описывается. |
Возвращает : | Вновь распределённая строка. |
Базовые типы которые всегда поддерживают GValue операции и
поэтому могут использоваться как тип инициализации для
g_value_init()
определены отдельным интерфейсом.
Детали смотрите в Standard Values
API.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> GSignalInvocationHint; gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer data); typedef GSignalCMarshaller; gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint, guint n_param_values, const GValue *param_values, gpointer data); enum GSignalFlags; enum GSignalMatchType; GSignalQuery; #define G_SIGNAL_TYPE_STATIC_SCOPE #define G_SIGNAL_MATCH_MASK #define G_SIGNAL_FLAGS_MASK guint g_signal_new (const gchar *signal_name, GType itype, GSignalFlags signal_flags, guint class_offset, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, ...); guint g_signal_newv (const gchar *signal_name, GType itype, GSignalFlags signal_flags, GClosure *class_closure, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, GType *param_types); guint g_signal_new_valist (const gchar *signal_name, GType itype, GSignalFlags signal_flags, GClosure *class_closure, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, va_list args); void g_signal_query (guint signal_id, GSignalQuery *query); guint g_signal_lookup (const gchar *name, GType itype); const gchar* g_signal_name (guint signal_id); guint* g_signal_list_ids (GType itype, guint *n_ids); void g_signal_emit (gpointer instance, guint signal_id, GQuark detail, ...); void g_signal_emit_by_name (gpointer instance, const gchar *detailed_signal, ...); void g_signal_emitv (const GValue *instance_and_params, guint signal_id, GQuark detail, GValue *return_value); void g_signal_emit_valist (gpointer instance, guint signal_id, GQuark detail, va_list var_args); #define g_signal_connect (instance, detailed_signal, c_handler, data) #define g_signal_connect_after (instance, detailed_signal, c_handler, data) #define g_signal_connect_swapped (instance, detailed_signal, c_handler, data) gulong g_signal_connect_object (gpointer instance, const gchar *detailed_signal, GCallback c_handler, gpointer gobject, GConnectFlags connect_flags); enum GConnectFlags; gulong g_signal_connect_data (gpointer instance, const gchar *detailed_signal, GCallback c_handler, gpointer data, GClosureNotify destroy_data, GConnectFlags connect_flags); gulong g_signal_connect_closure (gpointer instance, const gchar *detailed_signal, GClosure *closure, gboolean after); gulong g_signal_connect_closure_by_id (gpointer instance, guint signal_id, GQuark detail, GClosure *closure, gboolean after); void g_signal_handler_block (gpointer instance, gulong handler_id); void g_signal_handler_unblock (gpointer instance, gulong handler_id); void g_signal_handler_disconnect (gpointer instance, gulong handler_id); gulong g_signal_handler_find (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data); guint g_signal_handlers_block_matched (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data); guint g_signal_handlers_unblock_matched (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data); guint g_signal_handlers_disconnect_matched (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data); gboolean g_signal_handler_is_connected (gpointer instance, gulong handler_id); #define g_signal_handlers_block_by_func (instance, func, data) #define g_signal_handlers_unblock_by_func (instance, func, data) #define g_signal_handlers_disconnect_by_func(instance, func, data) gboolean g_signal_has_handler_pending (gpointer instance, guint signal_id, GQuark detail, gboolean may_be_blocked); void g_signal_stop_emission (gpointer instance, guint signal_id, GQuark detail); void g_signal_stop_emission_by_name (gpointer instance, const gchar *detailed_signal); void g_signal_override_class_closure (guint signal_id, GType instance_type, GClosure *class_closure); void g_signal_chain_from_overridden (const GValue *instance_and_params, GValue *return_value); gulong g_signal_add_emission_hook (guint signal_id, GQuark detail, GSignalEmissionHook hook_func, gpointer hook_data, GDestroyNotify data_destroy); void g_signal_remove_emission_hook (guint signal_id, gulong hook_id); gboolean g_signal_parse_name (const gchar *detailed_signal, GType itype, guint *signal_id_p, GQuark *detail_p, gboolean force_detail_quark); GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance); GClosure* g_signal_type_cclosure_new (GType itype, guint struct_offset); gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy);
Основная концепция системы сигналов заключается в эмиссии сигнала. Сигналы вводятся в тип и идентифицируются через строки. Сигналы введённые в родительский тип также доступны и в производных типах, в основном они являются средством наследуемыйм через тип. Эмиссия сигнала главным образом вовлекает вызов определённого набора callback-функций точно определённым способом. Есть две основные категории таких вызовов, одна в объекте [12] и одна обеспечивается пользователем. Callback-функции в объекте чаще всего упоминаются как "обработчик метода объекта" ("object method handler") или "обработчик сигнала по умолчанию" ("default (signal) handler"), в то время как callback-функции обеспечиваемые пользователем обычно просто называются "обработчик сигнала" ("signal handler"). Обработчик метода объекта обеспечивается во время создания сигнала (чаще всего это происходит в конце создания объектного класса), в то время как обеспечиваемые пользователем обработчики часто подключаются и отключаются к/от определённого сигнала в определённых экземплярах объекта.
Эмиссия сигнала состоит из пяти стадий, если не останавливается преждевременно:
1 - Вызов обработчика объектного метода для сигналов
|
|
2 - Вызов обычного обеспечиваемого пользователем обработчика сигнала (после флага
|
|
3 - Вызов обработчика объектного метода для сигналов
|
|
4 - Вызов обеспечиваемых пользователем обработчиков, подключаемых после флага
|
|
5 - Вызов обработчика объектного метода для сигналов
|
Обеспечиваемые пользователем обработчики сигналов вызываются в том порядке в каком были подключены.
Все обработчики могут преждевременно остановить эмиссию сигнала, и любое количество обработчиков может быть подключено,
отключено, заблокировано или разблокировано в течение эмиссии сигнала. Есть определённые критерии для пропуска пользовательских
обработчиков в стадиях 2 и 4 эмиссии сигнала. Во первых, пользовательские обработчики могут быть
блокированы, блокированные обработчики пропускаются в течение вызова callback-функции,
для возвращения из "блокированного" состояния, обработчик должен получить разблокировку столько же раз сколько был заблокирован перед этим.
Во вторых, в эмиссию сигнала G_SIGNAL_DETAILED
,
дополнительный "детальный" ("detail") параметр помещаемый в
g_signal_emit()
должен соответствовать детальному параметру обработчика сигнала текущего субъекта вызова.
Спецификация не детального параметра для обработчика сигнала (исключая детальную часть спецификации сигнала на подключение)
служит в качестве шаблона соответствующего любому детальному параметру помещаемому в эмиссию сигнала.
typedef struct { guint signal_id; GQuark detail; GSignalFlags run_type; } GSignalInvocationHint;
Структура GSignalInvocationHint используется для помещения дополнительной информации в callback-функцию в течение эмиссии сигнала.
guint
signal_id ; |
Идентификатор сигнала вызывающего callback-функцию |
GQuark
detail ; |
Детальный параметр помещаемый в эту эмиссию |
GSignalFlags
run_type ; |
Текущая стадия эмиссии сигнала, это поле будет содержать одно из значений
G_SIGNAL_RUN_FIRST ,
G_SIGNAL_RUN_LAST или
G_SIGNAL_RUN_CLEANUP .
|
gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer data);
Сумматор сигнала - специальная callback-функция которая может использоваться для накопления возвращаемых переменных
разными callback-функциями которые вызываются в течение эмиссии сигнала. Сумматор сигнала определяется во время создания сигнала,
если он сброшен в NULL
,
накопление возвращаемых значений не выполняется. Возвращает значение возвращённое последней callback-функцией в эмиссии сигнала.
ihint : |
Подсказка вызова сигнала, смотрите GSignalInvocationHint. |
return_accu : |
Сумматор для накопления возвращаемых значений callback-функций, это возвращаемое значение текущей эмиссии сигнала. |
handler_return : |
GValue содержащая возвращаемое обработчиком сигнала значение. |
data : |
Данные для сallback-функции определённые при создании сигнала. |
Возвращает : | Должна ли функция сумматор возвращаемых значений прерывать эмиссию сигнала.
Возвращённое FALSE
означает прерывание эмиссии сигнала, а возвращённое
TRUE означает продолжение.
|
typedef GClosureMarshal GSignalCMarshaller;
Это сигнатура функций маршаллеров, требуемая для маршаллерных массивов значений параметра в эмиссиях сигнала внутри вызовов callback-функций языка С. Это просто псевдоним для GClosureMarshal так как механизм GClosure несёт ответственность за фактический вызов функции для системы сигналов.
gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint, guint n_param_values, const GValue *param_values, gpointer data);
Простой указатель функции которая вызывается когда издаётся сигнал. Это позволяет вам привязать обработчик прерываний к типовому сигналу, чтобы он стал прерыванием для всех эмиссий этого сигнала в любом объекте.
Вы не сможете привязать это к сигналу созданному с флагом G_SIGNAL_NO_HOOKS.
ihint : |
Подсказка вызова сигнала, смотрите GSignalInvocationHint. |
n_param_values : |
количество параметров для функции, включая экземпляр в котором был издан сигнал. |
param_values : |
экземпляр в котором был издан сигнал, зтем параметры эмиссии. |
data : |
пользовательские данные связанные с обработчиком прерывания. |
Возвращает : | необходимо ли оставаться подключённым. Если возвращается
FALSE ,
обработчик прерывания сигнала отключается (и уничтожается).
|
typedef enum { G_SIGNAL_RUN_FIRST = 1 << 0, G_SIGNAL_RUN_LAST = 1 << 1, G_SIGNAL_RUN_CLEANUP = 1 << 2, G_SIGNAL_NO_RECURSE = 1 << 3, G_SIGNAL_DETAILED = 1 << 4, G_SIGNAL_ACTION = 1 << 5, G_SIGNAL_NO_HOOKS = 1 << 6 } GSignalFlags;
Флаги используемые для определения поведения сигнала, полное описание как специальные флаги RUN управляют стадиями эмиссии сигнала.
G_SIGNAL_RUN_FIRST |
Вызывает обработчик объектного метода в первой стадии эмиссии. |
G_SIGNAL_RUN_LAST |
Вызывает обработчик объектного метода в третьей стадии эмиссии. |
G_SIGNAL_RUN_CLEANUP |
Вызывает обработчик объектного метода в последней стадии эмиссии. |
G_SIGNAL_NO_RECURSE |
Сигналы произведённые для объекта в текущей эмиссии для этого объекта не будут издаваться рекурсивно, но вместо этого заставят перезапустить первую эмиссию. |
G_SIGNAL_DETAILED |
Этот сигнал поддерживает "::detail" дополнение для имени сигнала при обработке соединения и эмиссии. |
G_SIGNAL_ACTION |
Сигналы действий это сигналы которые могут свободно издаваться в существующих объектах
из пользовательского кода через g_signal_emit()
и подобные ей функции, без необходимости внедрять дополнительный код который выполняет настройки объекта перед или после эмиссии.
Они могут также рассматриваться как методы объекта которые можно вызвать в основном с помощью постороннего кода (third-party code).
|
G_SIGNAL_NO_HOOKS |
Сигнал не поддерживает обработчики прерываний эмиссий. |
typedef enum { G_SIGNAL_MATCH_ID = 1 << 0, G_SIGNAL_MATCH_DETAIL = 1 << 1, G_SIGNAL_MATCH_CLOSURE = 1 << 2, G_SIGNAL_MATCH_FUNC = 1 << 3, G_SIGNAL_MATCH_DATA = 1 << 4, G_SIGNAL_MATCH_UNBLOCKED = 1 << 5 } GSignalMatchType;
Соответствующие типы определяющие соответствие сигналов с помощью
g_signal_handlers_block_matched()
,
g_signal_handlers_unblock_matched()
и
g_signal_handlers_disconnect_matched()
.
typedef struct { guint signal_id; const gchar *signal_name; GType itype; GSignalFlags signal_flags; GType return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ guint n_params; const GType *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ } GSignalQuery;
Структура содержащая подробную информацию для определённого сигнала. Она заполняется функцией
g_signal_query()
.
guint
signal_id ; |
Идентификатор сигнал сделавшего запрос, или 0 если сигнал сделавший запрос неизвестен. |
const gchar
*signal_name ; |
Имя сигнала. |
GType
itype ; |
Интерфейс/экземпляр типа который может издать этот сигнал. |
GSignalFlags
signal_flags ; |
Флаги сигнала помещённые в g_signal_new() .
|
GType
return_type ; |
Возвращаемый тип для пользовательской callback-функции. |
guint
n_params ; |
Количество параметров принимаемых пользовательской callback-функцией. |
const GType
*param_types ; |
Индивидуальный параметр типа для пользовательской callback-функции, помните что эффективная сигнатура callback-функции:
@return_type callback (gpointer data1, [param_types param_names,] gpointer data2); |
#define G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT)
Этот макрос помечает типовой параметр сигнала для которого система может предположить что экземпляр остаётся постоянным во всех эмиссиях сигнала в которых он используется. Это полезно только для беcсылочного подсчёта, копий типовых значений.
Чтобы пометить параметр таким способом, добавьте | G_SIGNAL_TYPE_STATIC_SCOPE
к соответствующему
параметру функции g_signal_new()
.
g_signal_new ("size_request", G_TYPE_FROM_CLASS (gobject_class), G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GtkWidgetClass, size_request), NULL, NULL, _gtk_marshal_VOID__BOXED, G_TYPE_NONE, 1, GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
guint g_signal_new (const gchar *signal_name, GType itype, GSignalFlags signal_flags, guint class_offset, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, ...);
Создаёт новый сигнал. (Это обычно выполняется в инициализаторе класса.)
Имя сигнала состоит из сегментов содержащих ASCII буквы и цифры, разделённые символом '-' или '_'. Первый символ имени сигнала должен быть буквой. Имена которые нарушают это правило приводят к непредсказуемому поведению системы GSignal.
Для регистрации и поиска сигнала, может быть использован любой разделитель, но они не должны перемешиваться.
signal_name : |
имя для сигнала |
itype : |
тип к которому принадлежит сигнал. Он также будет принадлежать к производному типу который унаследует этот тип. |
signal_flags : |
комбинация GSignalFlags определяющая детальный параметр
при вызове обработчика по умолчанию. Вы должны определить по крайней мере
G_SIGNAL_RUN_FIRST или
G_SIGNAL_RUN_LAST .
|
class_offset : |
Смещение указателя функции в классовой структуре для этого типа. В основном используется для вызова классового метода. Помещённый 0 не связывает классовый метод с этим сигналом. |
accumulator : |
сумматор для сигнала; может быть NULL .
|
accu_data : |
пользовательские данные для accumulator .
|
c_marshaller : |
функция для перевода массивов значений параметров в эмиссию сигнала внутри вызова callback-функции языка С. |
return_type : |
тип возвращаемого значения, или G_TYPE_NONE для сигнала без возвращаемого значения. |
n_params : |
Количество последующих типовых параметров. |
... : |
список типов, один для каждого параметра. |
Возвращает : | идентификатор сигнала |
guint g_signal_newv (const gchar *signal_name, GType itype, GSignalFlags signal_flags, GClosure *class_closure, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, GType *param_types);
Создаёт новый сигнал. (Это обычно выполняется в инициализаторе класса.)
Смотрите детали относительно имени сигнала в
g_signal_new()
.
signal_name : |
имя для сигнала |
itype : |
тип к которому принадлежит сигнал. Он будет также принадлежать производному типу который унаследует этот тип. |
signal_flags : |
комбинация GSignalFlags определяющая детальный параметр
когда вызывается обработчик по умолчанию. Вы должны по крайней мере определить
G_SIGNAL_RUN_FIRST или
G_SIGNAL_RUN_LAST .
|
class_closure : |
Замыкание вызываемое в эмиссии сигнала; может быть
NULL .
|
accumulator : |
сумматор для этого сигнала;
может быть NULL .
|
accu_data : |
пользовательские данные для accumulator .
|
c_marshaller : |
функция для перевода массивов значений параметров в эмиссию сигнала внутри вызова callback-функции языка С. |
return_type : |
тип возвращаемого значения, или G_TYPE_NONE для сигнала без возвращаемого значения. |
n_params : |
длина param_types .
|
param_types : |
массив типов, один для каждого параметра. |
Возвращает : | идентификатор сигнала |
guint g_signal_new_valist (const gchar *signal_name, GType itype, GSignalFlags signal_flags, GClosure *class_closure, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, va_list args);
Создаёт новый сигнал. (Это обычно выполняется в инициализаторе класса.)
Смотрите подробности относительно имени сигнала в g_signal_new()
.
signal_name : |
имя сигнала |
itype : |
тип которому принадлежит сигнал. Он также будет принадлежать производному типу который наследует этот тип. |
signal_flags : |
комбинация GSignalFlags
определяющая детальный параметр при вызове обработчика по умолчанию. Вы должны определить по крайней мере
G_SIGNAL_RUN_FIRST или
G_SIGNAL_RUN_LAST .
|
class_closure : |
Замыкание вызываемое в эмиссии сигнала; может быть
NULL .
|
accumulator : |
сумматор для этого сигнала; может быть
NULL .
|
accu_data : |
пользовательские данные для accumulator .
|
c_marshaller : |
функция для перевода массивов значений параметров в эмиссию сигнала внутри вызова callback-функции языка С. |
return_type : |
тип возвращаемого значения, или G_TYPE_NONE для сигнала без возвращаемого значения. |
n_params : |
количество типовых параметров в args .
|
args : |
va_list of GType, один для каждого параметра. |
Возвращает : | идентификатор параметра |
void g_signal_query (guint signal_id, GSignalQuery *query);
Запрашивает у системы сигналов подробную информацию для определённого сигнала. Эта функция заполняет определённую пользователем структуру
информацией для определённого сигнала. Если помещён несуществующий идентификатор сигнала,
signal_id
член GSignalQuery
равен 0. Все заполненные члены сструктуры GSignalQuery
должны рассматриваться как константы и должны оставаться нетронутыми.
signal_id : |
Идентификатор сигнала для которого запрашивается информация. |
query : |
Определённая пользователем структура которая заполняется константными значениями при успешном выполнении. |
guint g_signal_lookup (const gchar *name, GType itype);
Учитывая имя сигнала и тип подключенного к нему объекта, получает целочисленный идентификатор сигнала. Издание сигнала с помощью номера несколько быстрее чем каждый раз использовать имя.
Также проверяет предков полученного типа.
Смотрите подробности относительно имён сигналов в g_signal_new()
.
name : |
имя сигнала. |
itype : |
тип с которым оперирует данный сигнал. |
Возвращает : | номер который идентифицирует сигнал, или 0 если сигнал не найден. |
const gchar* g_signal_name (guint signal_id);
Находит идентификатор сигнала по его имени.
Два разных сигнала могут иметь одинаковое имя если они разных типов.
signal_id : |
номер идентифицирующий сигнал. |
Возвращает : | имя сигнала, или NULL
если номер сигнала был недопустимым.
|
guint* g_signal_list_ids (GType itype, guint *n_ids);
Создаёт список идентификаторов сигнала для определённого типового экземпляра или интерфейса.
Дальнейшая информация о сигналах может быть запрошена через
g_signal_query()
.
itype : |
Типовой экземпляр или интерфейс. |
n_ids : |
Расположение для хранения количества идентификаторов сигнала для itype .
|
Возвращает : | Вновь распределённый массив идентификаторов сигналов. |
void g_signal_emit (gpointer instance, guint signal_id, GQuark detail, ...);
Издаёт сигнал.
Помните что g_signal_emit()
сбрасывает возвращаемое значение в значение по умолчанию если нет подключенного обработчика,
в отличие от g_signal_emitv()
.
instance : |
экземпляр в котором издаётся сигнал. |
signal_id : |
идентификатор сигнала |
detail : |
детальный параметр |
... : |
параметры помещаемые в сигнал, следом расположение для возвращаемого значения. Если возвращаемый тип сигнала G_TYPE_NONE, расположение возвращаемого значения может быть опущено. |
void g_signal_emit_by_name (gpointer instance, const gchar *detailed_signal, ...);
Издаёт сигнал.
Помните что g_signal_emit_by_name()
сбрасывает возвращаемое значение в значение по умолчанию если нет подключенных обработчиков,
в отличие от g_signal_emitv()
.
instance : |
экземпляр в котором издаётся сигнал. |
detailed_signal : |
строка в форме "signal-name::detail". |
... : |
параметры помещаемые в сигнал, зтем расположение для возвращаемого значения. Если возвращаемый тип сигнала G_TYPE_NONE, расположение возвращаемого значения может быть опущено. |
void g_signal_emitv (const GValue *instance_and_params, guint signal_id, GQuark detail, GValue *return_value);
Издаёт сигнал.
Помните что g_signal_emitv()
не изменяет
return_value
если нет подключенных обработчиков, в отличие от
g_signal_emit()
и
g_signal_emit_valist()
.
instance_and_params : |
список параметров для эмиссии сигнала. Первый элемент в массиве это GValue для экземпляра в котором издаётся сигнал. Остальные - любые параметры помещаемые в сигнал. |
signal_id : |
идентификатор сигнала |
detail : |
детальный параметр |
return_value : |
Расположение для хранения возвращаемого значения эмиссии сигнала. |
void g_signal_emit_valist (gpointer instance, guint signal_id, GQuark detail, va_list var_args);
Издаёт сигнал.
Помните что g_signal_emit_valist()
сбрасывает возвращаемое значение в значение по умолчанию если нет подключенных обработчиков,
в отличие от g_signal_emitv()
.
instance : |
экземпляр в котором издаётся сигнал. |
signal_id : |
идентификатор сигнала |
detail : |
детальный параметр |
var_args : |
список параметров помещаемых в сигнал, зтем расположение для хранения возвращаемого значения. Если возвращаемый тип сигнала G_TYPE_NONE, расположение возвращаемого значения может быть опущено. |
#define g_signal_connect(instance, detailed_signal, c_handler, data)
Подключает GCallback функцию к сигналу определённого объекта.
Обработчик будет вызван перед вызовом обработчика по умолчанию для этого сигнала.
instance : |
экземпляр для подключения. |
detailed_signal : |
строка в форме "signal-name::detail". |
c_handler : |
GCallback для подключения. |
data : |
данные помещаемые в вызов c_handler .
|
Возвращает : | идентификатор обработчика |
#define g_signal_connect_after(instance, detailed_signal, c_handler, data)
Подключает GCallback функцию к сигналу определённого объекта.
Обработчик будет вызван после вызова обработчика по умолчанию для этого сигнала.
instance : |
экземпляр для подключения. |
detailed_signal : |
строка в форме "signal-name::detail". |
c_handler : |
GCallback для подключения. |
data : |
данные помещаемые в вызов c_handler .
|
Возвращает : | идентификатор обработчика |
#define g_signal_connect_swapped(instance, detailed_signal, c_handler, data)
Подключает функцию GCallback к сигналу определённого объекта.
Экземпляр в котором издаётся сигнал и data
будут меняться местами когда вызывается обработчик.
instance : |
экземпляр для подключения. |
detailed_signal : |
строка в форме "signal-name::detail". |
c_handler : |
GCallback для подключения. |
data : |
данные помещаемые в вызов c_handler .
|
Возвращает : | идентификатор обработчика |
gulong g_signal_connect_object (gpointer instance, const gchar *detailed_signal, GCallback c_handler, gpointer gobject, GConnectFlags connect_flags);
Подобна g_signal_connect_data()
,
использует замыкание которое гарантирует что gobject
будет существовать в течение вызова
c_handler
с помощью создания временной ссылки на gobject
.
Помните что есть ошибка в GObject которая делает эту функцию менее удобной чем может показаться.
Как только gobject
расположен, callback-функция больше не вызывается,
но обработчик сигнала в текущий момент не отключен. Если
instance
самостоятельно освободится в тоже самое время то это не имеет значения,
так как сигнал будет автоматически удалён, но если instance
сохранится,
то обработчик сигнала приведёт к утечке памяти. Вы не должны удалять сигнал самостоятельно потому что в будущих версиях
GObject, обработчик будет отключаться автоматически.
Возможное решение этой проблемы, способ который будет работать в будущих версиях GObject, проверять что обработчик сигнала остаётся подключённым перед его отключением:
if (g_signal_handler_is_connected (instance, id)) g_signal_handler_disconnect (instance, id);
instance : |
экземпляр для подключения. |
detailed_signal : |
строка в форме "signal-name::detail". |
c_handler : |
GCallback для подключения. |
gobject : |
объект помещаемый в качестве данных в c_handler .
|
connect_flags : |
комбинация GConnnectFlags. |
Возвращает : | идентификатор обработчика. |
typedef enum { G_CONNECT_AFTER = 1 << 0, G_CONNECT_SWAPPED = 1 << 1 } GConnectFlags;
Подключает флаги используемые для определения поведения подключаемого сигнала.
gulong g_signal_connect_data (gpointer instance, const gchar *detailed_signal, GCallback c_handler, gpointer data, GClosureNotify destroy_data, GConnectFlags connect_flags);
Подключает функцию GCallback к сигналу определённого объекта.
Подобна g_signal_connect()
, но позволяет обеспечить
GClosureNotify для данных которая вызывается когда обработчик
сигнала отключен и больше не используется.
Определяет connect_flags
если вам нужны
...
или
_after()
...
варианты этой функции.
_swapped()
instance : |
экземпляр для подключения. |
detailed_signal : |
строка в форме "signal-name::detail". |
c_handler : |
GCallback для подключения. |
data : |
данные помещаемые в вызов c_handler .
|
destroy_data : |
GClosureNotify для
data .
|
connect_flags : |
комбинация GConnectFlags. |
Возвращает : | идентификатор обработчика |
gulong g_signal_connect_closure (gpointer instance, const gchar *detailed_signal, GClosure *closure, gboolean after);
Подключает замыкание к сигналу для определённого объекта.
instance : |
экземпляр для подключения. |
detailed_signal : |
строка в форме "signal-name::detail". |
closure : |
подключаемое замыкание. |
after : |
вызывается ли обработчик сигнала до или после обработчика по умолчанию. |
Возвращает : | идентификатор обработчика |
gulong g_signal_connect_closure_by_id (gpointer instance, guint signal_id, GQuark detail, GClosure *closure, gboolean after);
Подключает замыкание к сигналу для определённого объекта.
instance : |
экземпляр для подключения. |
signal_id : |
идентификатор сигнала. |
detail : |
детальный параметр. |
closure : |
подключаемое замыкание. |
after : |
вызывается ли обработчик сигнала до или после обработчика по умолчанию. |
Возвращает : | идентификатор обработчика |
void g_signal_handler_block (gpointer instance, gulong handler_id);
Блокирует обработчик в экземпляре поэтому он не будет вызываться в течение эмиссии сигнала пока его не разблокируют снова. Таким образом "блокирование" означает временную деактивацию обработчика сигнала, обработчик сигнала должен разблокироваться тоже количество раз сколько был заблокирован до этого чтобы активизироваться снова.
handler_id
должен быть допустимым идентификатором обработчика сигнала,
подключаемого к сигналу экземпляра
.
instance : |
Экземпляр в котором блокируется обработчик сигнала. |
handler_id : |
Идентификатор обработчика для блокировки. |
void g_signal_handler_unblock (gpointer instance, gulong handler_id);
Отменяет эффект вызова
g_signal_handler_block()
.
Блокированный сигнал пропускается в течение эмиссии сигнала и не вызывается,
разблокирование (столько же раз сколько он был заблокирован перед этим)
переключает состояние "блокирован", поэтому обработчик распознаётся системой сигналов
и вызывается в будущей или в текущей эмиссии сигнала (так как порядок в котором обработчики вызываются в течение эмиссии сигнала
детерминирован, будет ли запрашиваемый разблокированный обработчик вызван как часть текущей продолжающейся эмиссии сигнала
зависит от того как долго эмиссия будет продолжаться).
handler_id
должен быть допустимым идентификатором обработчика сигнала который подключается
к сигналу экземпляра
и в текущий момент заблокирован.
instance : |
Экземпляр для разблокировки обработчика сигнала. |
handler_id : |
Идентификатор обработчика для разблокировки. |
void g_signal_handler_disconnect (gpointer instance, gulong handler_id);
Отключаемт обработчик из экземпляра поэтому он не будет вызываться в течение любых будущих
или текущих эмиссий сигнала к которым был подключен. handler_id
становится недопустимым
и может быть переиспользован.
handler_id
должен быть допустимым идентификатором обработчика сигнала,
подключённым к сигналу экземпляра
.
instance : |
Экземпляр из которого удаляется обработчик сигнала. |
handler_id : |
Идентификатор обработчика для отключения. |
gulong g_signal_handler_find (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data);
Находит первый обработчик сигнала который соответствует определённым критериям выбора.
Маска критерия помещается как OR-ed комбинация GSignalMatchType
флагов, а значения критерия помещаются как параметры.
Маска
соответствия должна быть не-0 для успешного соответствия.
Если обработчик не найден, возвращается 0.
instance : |
Экземпляр владеющий обработчиком сигнала для поиска. |
mask : |
Маска указывающая чему должен соответствовать обработчик, signal_id , detail , closure , func
и/или data .
|
signal_id : |
Сигнал к которому подключен обработчик. |
detail : |
Детальный параметр сигнала к которому подключен обработчик. |
closure : |
Замыкание которое вызывает обработчик. |
func : |
callback-функция "С" замыкания обработчика (бесполезно для не-C замыканий). |
data : |
Данные замыкания обработчика. |
Возвращает : | Допустимый не-0 идентификатор обработчика сигнала для успешного соответствия. |
guint g_signal_handlers_block_matched (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data);
Блокирует все обработчики в экземпляре которые соответствуют определённому критерию выбора.
Маска критерия помещается как комбинация OR-ed флагов GSignalMatchType,
а значения критерия помещаются как параметры.
Помещение по крайней мере одного из флагов соответствия
G_SIGNAL_MATCH_CLOSURE
,
G_SIGNAL_MATCH_FUNC
или
G_SIGNAL_MATCH_DATA
требуется для успешного сравнения.
Если нет найденных обработчиков, возвращается 0, иначе количество найденных обработчиков.
instance : |
Экземпляр в котором блокируются обработчики. |
mask : |
Маска указывающая какое соответствие должен иметь обработчик
signal_id , detail ,
closure , func
и/или data .
|
signal_id : |
Сигнал к которому подключается обработчик. |
detail : |
Детальный параметр сигнала к которому подключается обработчик. |
closure : |
Замыкание вызываемое обработчиком. |
func : |
callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий). |
data : |
Данные замыкания для обработчика. |
Возвращает : | Количество блокируемых обработчиков. |
guint g_signal_handlers_unblock_matched (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data);
Разблокирует все обработчики в экземпляре которые соответствуют определённому критерию выбора.
Маска критерия помещается как комбинация OR-ed флагов
GSignalMatchType,
а значения критерия помещаются как параметры.
Для успешного сравнения помещается по крайней мере один из флагов соответствия
G_SIGNAL_MATCH_CLOSURE
,
G_SIGNAL_MATCH_FUNC
или
G_SIGNAL_MATCH_DATA
.
Если нет найденных обработчиков, возвращается 0, иначе количество найденных обработчиков.
Критерии соответствия не применяются к обработчикам которые в настоящий момент не заблокированы.
instance : |
Экземпляр в котором разблокируются обработчики. |
mask : |
Маска указывающая чему должен соответствовать обработчик
signal_id , detail ,
closure , func
и/или data .
|
signal_id : |
Сигнал к которому подключается обработчик. |
detail : |
Детальный параметр сигнала к которому подключается обработчик. |
closure : |
Замыкание вызываемое обработчиком. |
func : |
callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий). |
data : |
Данные замыкания для обработчиков. |
Возвращает : | Количество разблокируемых обработчиков. |
guint g_signal_handlers_disconnect_matched (gpointer instance, GSignalMatchType mask, guint signal_id, GQuark detail, GClosure *closure, gpointer func, gpointer data);
Отключаем все сигналы в экземпляре которые соответствуют критерию отбора.
Маска критерия помещается как комбинация OR-ed флагов
GSignalMatchType,
а значения критерия как параметры.
Для успешного сравнения необходимо поместить по крайней мере один из флагов
G_SIGNAL_MATCH_CLOSURE
,
G_SIGNAL_MATCH_FUNC
или
G_SIGNAL_MATCH_DATA
.
Если обработчики не найдены, возвращается 0, иначе количество отключаемых обработчиков.
instance : |
Экземпляр из которого удаляются обработчики. |
mask : |
Маска указывающая какие соответствия должны иметь обработчики,
signal_id , detail ,
closure , func
и/или data .
|
signal_id : |
Сигнал к которому подключен обработчик. |
detail : |
Детальный параметр сигнала к которому подключен обработчик. |
closure : |
Замыкание которое вызывает обработчик. |
func : |
callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий). |
data : |
Данные замыкания для обработчика. |
Возвращает : | Количество отключаемых обработчиков. |
gboolean g_signal_handler_is_connected (gpointer instance, gulong handler_id);
Определяет подключен ли обработчик с идентификатором handler_id
в instance
.
instance : |
Экземпляр для поиска обрботчика. |
handler_id : |
идентификатор обработчика. |
Возвращает : | Подключен ли обработчик с идентификатором handler_id в instance .
|
#define g_signal_handlers_block_by_func(instance, func, data)
Блокирует все обработчики в экземпляре которые соответствуют func
и data
.
instance : |
Экземпляр в котором блокируются обработчики. |
func : |
callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий). |
data : |
Данные замыкания обработчика. |
Возвращает : | Количество блокированных обработчиков. |
#define g_signal_handlers_unblock_by_func(instance, func, data)
Разблокирует все обработчики в экземпляре которые соответствуют
func
и data
.
instance : |
Экземпляр в котором разблокируются обработчики. |
func : |
callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий). |
data : |
Данные замыкания для обработчика. |
Возвращает : | Количество разблокированных обработчиков. |
#define g_signal_handlers_disconnect_by_func(instance, func, data)
Отключаемт все обработчики в экземпляре которые соответствуют func
и data
.
instance : |
Экземпляр из которого удаляются обработчики. |
func : |
callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий). |
data : |
Данные замыкания для обработчика. |
Возвращает : | Количество удалённых обработчиков. |
gboolean g_signal_has_handler_pending (gpointer instance, guint signal_id, GQuark detail, gboolean may_be_blocked);
Определяет есть ли обработчики подключенные в instance
к сигналу с полученным идентификатором и детальным параметром.
Это может быть использовано когда сложно вычислить параметры сигнала. Конструктор класса может не издавать сигнал если к нему всё равно ничего не подключено, таким образом не расходуются ресурсы на формирование параметров.
void g_signal_stop_emission (gpointer instance, guint signal_id, GQuark detail);
Останавливает текущую эмиссию сигнала.
Это предотвратит выполнение метода по умолчанию, если сигнал был
G_SIGNAL_RUN_LAST
и вы подключились нормально (то есть без флага "after").
Напечатает предупреждение если используется в сигнале который не издаётся.
instance : |
объект чей обработчик сигнала вы останавливаете. |
signal_id : |
идентификатор сигнала, который возвращает g_signal_lookup() .
|
detail : |
детальный параметр с которым издаётся сигнал. |
void g_signal_stop_emission_by_name (gpointer instance, const gchar *detailed_signal);
Останавливает текущую эмиссию сигнала.
Похожа на g_signal_stop_emission()
но самостоятельно определит идентификатор сигнала для вас.
instance : |
объект чьи обработчики сигнала останавливаются. |
detailed_signal : |
строка в форме "signal-name::detail". |
void g_signal_override_class_closure (guint signal_id, GType instance_type, GClosure *class_closure);
Отменяет классовое замыкание (то есть обработчик по умолчанию) для данного сигнала в эмиссиях для экземпляров instance_type
. instance_type
должен происходить из типа к которому принадлежит сигнал.
signal_id : |
идентификатор сигнала |
instance_type : |
типовой экземпляр в котором отменяется классовое замыкание для сигнала. |
class_closure : |
замыкание. |
void g_signal_chain_from_overridden (const GValue *instance_and_params, GValue *return_value);
Вызывает оригинальное классовое замыкание сигнала. Эту функцию нужно вызывать только при отменённом классовом замыкании;
смотрите g_signal_override_class_closure()
.
instance_and_params : |
список параметров эмиссии сигнала. Первый элемент в массиве это GValue для экземпляра в котором издаётся сигнал. Отменяет все параметры помещённые в сигнал. |
return_value : |
Расположение для возвращаемого значения. |
gulong g_signal_add_emission_hook (guint signal_id, GQuark detail, GSignalEmissionHook hook_func, gpointer hook_data, GDestroyNotify data_destroy);
Добавляет обработчик прерывания эмиссии сигнала, который будет вызываться для любой эмиссии этого сигнала, независимо от экземпляра. Это возможно только для сигналов которые не имеют установленного флага G_SIGNAL_NO_HOOKS.
signal_id : |
идентификатор сигнала, который возвращает g_signal_lookup() .
|
detail : |
детальный параметр для вызова обработчика прерывания. |
hook_func : |
функция GSignalEmissionHook. |
hook_data : |
пользовательские данные для hook_func .
|
data_destroy : |
GDestroyNotify для
hook_data .
|
Возвращает : | идентификатор обработчика прерывания, для дальнейшего использования с
g_signal_remove_emission_hook() .
|
void g_signal_remove_emission_hook (guint signal_id, gulong hook_id);
Удаляет обработчик прерывания эмиссии.
signal_id : |
идентификатор сигнала |
hook_id : |
идентификатор обработчика прерывания эмиссии, который возвращает
g_signal_add_emission_hook()
|
gboolean g_signal_parse_name (const gchar *detailed_signal, GType itype, guint *signal_id_p, GQuark *detail_p, gboolean force_detail_quark);
Внутренняя функция для анализа имени сигнала содержащего его signal_id
и кварк detail
.
detailed_signal : |
строка в форме "signal-name::detail". |
itype : |
Типовой интерфейс/экземпляр который вводит "signal-name". |
signal_id_p : |
Расположение для хранения идентификатора сигнала. |
detail_p : |
Расположение для хранения детального кварка (detail quark). |
force_detail_quark : |
TRUE заставляет создать
GQuark для детального параметра.
|
Возвращает : | Может ли имя полностью быть проанализировано, а signal_id_p и
detail_p содержат допустимые возвращаемые значения.
|
GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance);
Возвращает подсказку вызова самой внутренней эмиссии сигнала для экземпляра.
instance : |
экземпляр для запроса |
Возвращает : | подсказка вызова самой внутренней эмиссии сигнала. |
GClosure* g_signal_type_cclosure_new (GType itype, guint struct_offset);
Создаёт новое замыкание которое вызывает функцию найденную смещением struct_offset
в структуре класса интерфейса или классифицированного типа идентифицируемого itype
.
gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy);
Предопределённый GSignalAccumulator для сигналов которые
возвращают логические значения. Назначение этого сумматора состоит в том что возвращаемые
TRUE
останавливают эмиссию сигнала:
никакие последующие callback-функции не вызываются, в то время как возвращённое
FALSE
позволяет продолжать эмиссию.
Идея в том что возвращаемое TRUE
указывает что callback-функция обработала сигнал, и дальнейшая обработка не нужна.
ihint : |
стандартный параметр GSignalAccumulator |
return_accu : |
стандартный параметр GSignalAccumulator |
handler_return : |
стандартный параметр GSignalAccumulator |
dummy : |
стандартный параметр GSignalAccumulator |
Возвращает : | стандартный результат GSignalAccumulator |
Начиная с версии 2.4
[12] Хотя сигналы могут иметь дело с любым видом инстанциируемого типа, я подразумеваю типы как "объектные типы", просто потому что большинство пользователей будет сталкиваться с сигналами именно в этом контексте.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> #define G_IS_PARAM_SPEC_BOOLEAN (pspec) #define G_PARAM_SPEC_BOOLEAN (pspec) #define G_VALUE_HOLDS_BOOLEAN (value) #define G_TYPE_PARAM_BOOLEAN GParamSpecBoolean; GParamSpec* g_param_spec_boolean (const gchar *name, const gchar *nick, const gchar *blurb, gboolean default_value, GParamFlags flags); void g_value_set_boolean (GValue *value, gboolean v_boolean); gboolean g_value_get_boolean (const GValue *value); #define G_IS_PARAM_SPEC_CHAR (pspec) #define G_PARAM_SPEC_CHAR (pspec) #define G_VALUE_HOLDS_CHAR (value) #define G_TYPE_PARAM_CHAR GParamSpecChar; GParamSpec* g_param_spec_char (const gchar *name, const gchar *nick, const gchar *blurb, gint8 minimum, gint8 maximum, gint8 default_value, GParamFlags flags); void g_value_set_char (GValue *value, gchar v_char); gchar g_value_get_char (const GValue *value); #define G_IS_PARAM_SPEC_UCHAR (pspec) #define G_PARAM_SPEC_UCHAR (pspec) #define G_VALUE_HOLDS_UCHAR (value) #define G_TYPE_PARAM_UCHAR GParamSpecUChar; GParamSpec* g_param_spec_uchar (const gchar *name, const gchar *nick, const gchar *blurb, guint8 minimum, guint8 maximum, guint8 default_value, GParamFlags flags); void g_value_set_uchar (GValue *value, guchar v_uchar); guchar g_value_get_uchar (const GValue *value); #define G_IS_PARAM_SPEC_INT (pspec) #define G_PARAM_SPEC_INT (pspec) #define G_VALUE_HOLDS_INT (value) #define G_TYPE_PARAM_INT GParamSpecInt; GParamSpec* g_param_spec_int (const gchar *name, const gchar *nick, const gchar *blurb, gint minimum, gint maximum, gint default_value, GParamFlags flags); void g_value_set_int (GValue *value, gint v_int); gint g_value_get_int (const GValue *value); #define G_IS_PARAM_SPEC_UINT (pspec) #define G_PARAM_SPEC_UINT (pspec) #define G_VALUE_HOLDS_UINT (value) #define G_TYPE_PARAM_UINT GParamSpecUInt; GParamSpec* g_param_spec_uint (const gchar *name, const gchar *nick, const gchar *blurb, guint minimum, guint maximum, guint default_value, GParamFlags flags); void g_value_set_uint (GValue *value, guint v_uint); guint g_value_get_uint (const GValue *value); #define G_IS_PARAM_SPEC_LONG (pspec) #define G_PARAM_SPEC_LONG (pspec) #define G_VALUE_HOLDS_LONG (value) #define G_TYPE_PARAM_LONG GParamSpecLong; GParamSpec* g_param_spec_long (const gchar *name, const gchar *nick, const gchar *blurb, glong minimum, glong maximum, glong default_value, GParamFlags flags); void g_value_set_long (GValue *value, glong v_long); glong g_value_get_long (const GValue *value); #define G_IS_PARAM_SPEC_ULONG (pspec) #define G_PARAM_SPEC_ULONG (pspec) #define G_VALUE_HOLDS_ULONG (value) #define G_TYPE_PARAM_ULONG GParamSpecULong; GParamSpec* g_param_spec_ulong (const gchar *name, const gchar *nick, const gchar *blurb, gulong minimum, gulong maximum, gulong default_value, GParamFlags flags); void g_value_set_ulong (GValue *value, gulong v_ulong); gulong g_value_get_ulong (const GValue *value); #define G_IS_PARAM_SPEC_INT64 (pspec) #define G_PARAM_SPEC_INT64 (pspec) #define G_VALUE_HOLDS_INT64 (value) #define G_TYPE_PARAM_INT64 GParamSpecInt64; GParamSpec* g_param_spec_int64 (const gchar *name, const gchar *nick, const gchar *blurb, gint64 minimum, gint64 maximum, gint64 default_value, GParamFlags flags); void g_value_set_int64 (GValue *value, gint64 v_int64); gint64 g_value_get_int64 (const GValue *value); #define G_IS_PARAM_SPEC_UINT64 (pspec) #define G_PARAM_SPEC_UINT64 (pspec) #define G_VALUE_HOLDS_UINT64 (value) #define G_TYPE_PARAM_UINT64 GParamSpecUInt64; GParamSpec* g_param_spec_uint64 (const gchar *name, const gchar *nick, const gchar *blurb, guint64 minimum, guint64 maximum, guint64 default_value, GParamFlags flags); void g_value_set_uint64 (GValue *value, guint64 v_uint64); guint64 g_value_get_uint64 (const GValue *value); #define G_IS_PARAM_SPEC_FLOAT (pspec) #define G_PARAM_SPEC_FLOAT (pspec) #define G_VALUE_HOLDS_FLOAT (value) #define G_TYPE_PARAM_FLOAT GParamSpecFloat; GParamSpec* g_param_spec_float (const gchar *name, const gchar *nick, const gchar *blurb, gfloat minimum, gfloat maximum, gfloat default_value, GParamFlags flags); void g_value_set_float (GValue *value, gfloat v_float); gfloat g_value_get_float (const GValue *value); #define G_IS_PARAM_SPEC_DOUBLE (pspec) #define G_PARAM_SPEC_DOUBLE (pspec) #define G_VALUE_HOLDS_DOUBLE (value) #define G_TYPE_PARAM_DOUBLE GParamSpecDouble; GParamSpec* g_param_spec_double (const gchar *name, const gchar *nick, const gchar *blurb, gdouble minimum, gdouble maximum, gdouble default_value, GParamFlags flags); void g_value_set_double (GValue *value, gdouble v_double); gdouble g_value_get_double (const GValue *value); #define G_IS_PARAM_SPEC_ENUM (pspec) #define G_PARAM_SPEC_ENUM (pspec) #define G_VALUE_HOLDS_ENUM (value) #define G_TYPE_PARAM_ENUM GParamSpecEnum; GParamSpec* g_param_spec_enum (const gchar *name, const gchar *nick, const gchar *blurb, GType enum_type, gint default_value, GParamFlags flags); void g_value_set_enum (GValue *value, gint v_enum); gint g_value_get_enum (const GValue *value); #define G_IS_PARAM_SPEC_FLAGS (pspec) #define G_PARAM_SPEC_FLAGS (pspec) #define G_VALUE_HOLDS_FLAGS (value) #define G_TYPE_PARAM_FLAGS GParamSpecFlags; GParamSpec* g_param_spec_flags (const gchar *name, const gchar *nick, const gchar *blurb, GType flags_type, guint default_value, GParamFlags flags); void g_value_set_flags (GValue *value, guint v_flags); guint g_value_get_flags (const GValue *value); #define G_IS_PARAM_SPEC_STRING (pspec) #define G_PARAM_SPEC_STRING (pspec) #define G_VALUE_HOLDS_STRING (value) #define G_TYPE_PARAM_STRING GParamSpecString; typedef gchararray; GParamSpec* g_param_spec_string (const gchar *name, const gchar *nick, const gchar *blurb, const gchar *default_value, GParamFlags flags); void g_value_set_string (GValue *value, const gchar *v_string); void g_value_set_static_string (GValue *value, const gchar *v_string); void g_value_take_string (GValue *value, gchar *v_string); void g_value_set_string_take_ownership (GValue *value, gchar *v_string); const gchar* g_value_get_string (const GValue *value); gchar* g_value_dup_string (const GValue *value); #define G_IS_PARAM_SPEC_PARAM (pspec) #define G_PARAM_SPEC_PARAM (pspec) #define G_VALUE_HOLDS_PARAM (value) #define G_TYPE_PARAM_PARAM GParamSpecParam; GParamSpec* g_param_spec_param (const gchar *name, const gchar *nick, const gchar *blurb, GType param_type, GParamFlags flags); void g_value_set_param (GValue *value, GParamSpec *param); void g_value_take_param (GValue *value, GParamSpec *param); void g_value_set_param_take_ownership (GValue *value, GParamSpec *param); GParamSpec* g_value_get_param (const GValue *value); GParamSpec* g_value_dup_param (const GValue *value); #define G_IS_PARAM_SPEC_BOXED (pspec) #define G_PARAM_SPEC_BOXED (pspec) #define G_VALUE_HOLDS_BOXED (value) #define G_TYPE_PARAM_BOXED GParamSpecBoxed; GParamSpec* g_param_spec_boxed (const gchar *name, const gchar *nick, const gchar *blurb, GType boxed_type, GParamFlags flags); void g_value_set_boxed (GValue *value, gconstpointer v_boxed); void g_value_set_static_boxed (GValue *value, gconstpointer v_boxed); void g_value_take_boxed (GValue *value, gconstpointer v_boxed); void g_value_set_boxed_take_ownership (GValue *value, gconstpointer v_boxed); gpointer g_value_get_boxed (const GValue *value); gpointer g_value_dup_boxed (const GValue *value); #define G_IS_PARAM_SPEC_POINTER (pspec) #define G_PARAM_SPEC_POINTER (pspec) #define G_VALUE_HOLDS_POINTER (value) #define G_TYPE_PARAM_POINTER GParamSpecPointer; GParamSpec* g_param_spec_pointer (const gchar *name, const gchar *nick, const gchar *blurb, GParamFlags flags); void g_value_set_pointer (GValue *value, gpointer v_pointer); gpointer g_value_get_pointer (const GValue *value); #define G_IS_PARAM_SPEC_OBJECT (pspec) #define G_PARAM_SPEC_OBJECT (pspec) #define G_VALUE_HOLDS_OBJECT (value) #define G_TYPE_PARAM_OBJECT GParamSpecObject; GParamSpec* g_param_spec_object (const gchar *name, const gchar *nick, const gchar *blurb, GType object_type, GParamFlags flags); void g_value_set_object (GValue *value, gpointer v_object); void g_value_take_object (GValue *value, gpointer v_object); void g_value_set_object_take_ownership (GValue *value, gpointer v_object); gpointer g_value_get_object (const GValue *value); gpointer g_value_dup_object (const GValue *value); #define G_IS_PARAM_SPEC_UNICHAR (pspec) #define G_PARAM_SPEC_UNICHAR (pspec) #define G_TYPE_PARAM_UNICHAR GParamSpecUnichar; GParamSpec* g_param_spec_unichar (const gchar *name, const gchar *nick, const gchar *blurb, gunichar default_value, GParamFlags flags); #define G_IS_PARAM_SPEC_VALUE_ARRAY (pspec) #define G_PARAM_SPEC_VALUE_ARRAY (pspec) #define G_TYPE_PARAM_VALUE_ARRAY GParamSpecValueArray; GParamSpec* g_param_spec_value_array (const gchar *name, const gchar *nick, const gchar *blurb, GParamSpec *element_spec, GParamFlags flags); #define G_IS_PARAM_SPEC_OVERRIDE (pspec) #define G_PARAM_SPEC_OVERRIDE (pspec) #define G_TYPE_PARAM_OVERRIDE GParamSpecOverride; GParamSpec* g_param_spec_override (const gchar *name, GParamSpec *overridden); #define G_IS_PARAM_SPEC_GTYPE (pspec) #define G_PARAM_SPEC_GTYPE (pspec) #define G_VALUE_HOLDS_GTYPE (value) #define G_TYPE_PARAM_GTYPE GParamSpecGType; GParamSpec* g_param_spec_gtype (const gchar *name, const gchar *nick, const gchar *blurb, GType is_a_type, GParamFlags flags); GType g_value_get_gtype (const GValue *value); void g_value_set_gtype (GValue *value, GType v_gtype);
GValue обеспечивает абстрактную контейнерную структуру которая может копироваться, преобразовываться и сравниваться имея значение любого (производного) типа, который зарегистрирован как GType с помощью GTypeValueTable в её структуре GTypeInfo. Спецификации параметра для большинства типовых значений могут быть созданы как GParamSpec производного экземпляра, например для реализации GObject свойств которыми оперируют контейнеры GValue.
Имена параметров должны начинаться с букв (a-z или A-Z). Последующие символы могут быть буквами, числами или символом '-'. Все остальные символы заменяются символом '-' в процессе конструирования.
#define G_IS_PARAM_SPEC_BOOLEAN(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOOLEAN))
Определяет является ли полученный GParamSpec типом
G_TYPE_PARAM_BOOLEAN
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_BOOLEAN(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOOLEAN, GParamSpecBoolean))
Приводит экземпляр GParamSpec к GParamSpecBoolean.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_BOOLEAN(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOOLEAN))
Определяет может ли полученный GValue содержать значения типа
G_TYPE_BOOLEAN
.
value : |
правильная структура GValue |
typedef struct { GParamSpec parent_instance; gboolean default_value; } GParamSpecBoolean;
Производная структура GParamSpec которая содержит метаданные для логических (boolean) свойств.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gboolean
default_value ;
|
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_boolean (const gchar *name, const gchar *nick, const gchar *blurb, gboolean default_value, GParamFlags flags);
Создаёт новый экземпляр
GParamSpecBoolean
определяющий свойство G_TYPE_BOOLEAN
.
Смотрите детали имён свойств в
g_param_spec_internal()
.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним для определённого свойства |
blurb : |
описание определённого свойства |
default_value : |
значение по умолчанию определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_boolean (GValue *value, gboolean v_boolean);
Устанавливает содержимое G_TYPE_BOOLEAN
GValue в значение v_boolean
.
value : |
допустимая структура GValue типа
G_TYPE_BOOLEAN
|
v_boolean : |
логическое значение для установки |
gboolean g_value_get_boolean (const GValue *value);
Получает содержимое G_TYPE_BOOLEAN
GValue.
value : |
допустимая структура GValue типа
G_TYPE_BOOLEAN
|
Возвращает : | логическое содержимое value
|
#define G_IS_PARAM_SPEC_CHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_CHAR))
Определяет является ли полученный GParamSpec типом
G_TYPE_PARAM_CHAR
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_CHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_CHAR, GParamSpecChar))
Приводит экземпляр GParamSpec к GParamSpecChar.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_CHAR(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_CHAR))
Определяет может ли полученная GValue содержать значения типа
G_TYPE_CHAR
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gint8 minimum; gint8 maximum; gint8 default_value; } GParamSpecChar;
Производная структура GParamSpec которая содержит метаданные для свойств символа.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gint8
minimum ; |
минимальное значение для определённого свойства |
gint8
maximum ; |
максимальное значение для определённого свойства |
gint8
default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_char (const gchar *name, const gchar *nick, const gchar *blurb, gint8 minimum, gint8 maximum, gint8 default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecChar
определённого свойства G_TYPE_CHAR
.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним для определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение для определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_char (GValue *value, gchar v_char);
Устанавливает содержимое G_TYPE_CHAR
GValue в значение v_char
.
value : |
допустимая структура GValue типа
G_TYPE_CHAR
|
v_char : |
символьное значение для установки |
gchar g_value_get_char (const GValue *value);
Получает содержимое G_TYPE_CHAR
GValue.
value : |
допустимая структура GValue типа
G_TYPE_CHAR
|
Возвращает : | символьное содержимое value
|
#define G_IS_PARAM_SPEC_UCHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UCHAR))
Определяет соответствует ли полученный GParamSpec типу
G_TYPE_PARAM_UCHAR
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_UCHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UCHAR, GParamSpecUChar))
Преобразует экземпляр GParamSpec в GParamSpecUChar.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_UCHAR(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UCHAR))
Определяет может ли полученная структура GValue
содержать значения типа G_TYPE_UCHAR
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; guint8 minimum; guint8 maximum; guint8 default_value; } GParamSpecUChar;
Производная структура GParamSpec которая содержит метаданные для свойств символа без знака (unsigned character).
GParamSpec
parent_instance ; |
закрытая часть GParamSpec |
guint8
minimum ; |
минимальное значение для определённого свойства |
guint8
maximum ; |
максимальное значение для определённого свойства |
guint8
default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_uchar (const gchar *name, const gchar *nick, const gchar *blurb, guint8 minimum, guint8 maximum, guint8 default_value, GParamFlags flags);
Создаёт новый экземпляр
GParamSpecUChar определяющий
свойство G_TYPE_UCHAR
.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_uchar (GValue *value, guchar v_uchar);
Устанавливает содержимое G_TYPE_UCHAR
GValue в значение v_uchar
.
value : |
допустимая структура GValue типа
G_TYPE_UCHAR
|
v_uchar : |
беззнаковое символьное значение для установки |
guchar g_value_get_uchar (const GValue *value);
Получает содержимое G_TYPE_UCHAR
GValue.
value : |
допустимая GValue типа G_TYPE_UCHAR
|
Возвращает : | Беззнаковый символ содержимого value
|
#define G_IS_PARAM_SPEC_INT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_INT
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_INT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT, GParamSpecInt))
Преобразует экземпляр GParamSpec в GParamSpecInt.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_INT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_INT))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_INT
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gint minimum; gint maximum; gint default_value; } GParamSpecInt;
Производная структура GParamSpec которая содержит метаданные для свойств целочисленного.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gint minimum ; |
минимальное значение для определённого свойства |
gint maximum ; |
максимальное значение определённого свойства |
gint default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_int (const gchar *name, const gchar *nick, const gchar *blurb, gint minimum, gint maximum, gint default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecInt
определяющий свойство G_TYPE_INT
.
Смотрите детали имён свойств в g_param_spec_internal()
.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_int (GValue *value, gint v_int);
Устанавливает содержимое G_TYPE_INT
GValue в значение v_int
.
value : |
допустимая структура GValue типа G_TYPE_INT
|
v_int : |
integer value to be set |
gint g_value_get_int (const GValue *value);
Получает содержимое G_TYPE_INT
GValue.
value : |
допустимая структура GValue типа G_TYPE_INT
|
Возвращает : | integer contents of value
|
#define G_IS_PARAM_SPEC_UINT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_UINT
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_UINT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT, GParamSpecUInt))
Преобразует экземпляр GParamSpec в GParamSpecUInt.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_UINT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UINT))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_UINT
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; guint minimum; guint maximum; guint default_value; } GParamSpecUInt;
Производная структура GParamSpec которая содержит метаданные для свойств целочисленного без знака (unsigned integer).
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
guint minimum ; |
минимальное значение для определённого свойства |
guint maximum ; |
максимальное значение определённого свойства |
guint default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_uint (const gchar *name, const gchar *nick, const gchar *blurb, guint minimum, guint maximum, guint default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecUInt
определяющий свойство G_TYPE_UINT
.
Смотрите детали имён свойств в g_param_spec_internal()
.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_uint (GValue *value, guint v_uint);
Устанавливает содержимое G_TYPE_UINT
GValue в значение v_uint
.
value : |
допустимая структура GValue типа G_TYPE_UINT
|
v_uint : |
Беззнаковое целочисленное значение для установки |
guint g_value_get_uint (const GValue *value);
Получает содержимое G_TYPE_UINT
GValue.
value : |
допустимая структура GValue типа G_TYPE_UINT
|
Возвращает : | Беззнаковое целочисленное содержимое value
|
#define G_IS_PARAM_SPEC_LONG(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_LONG))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_LONG
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_LONG(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_LONG, GParamSpecLong))
Преобразует экземпляр GParamSpec в GParamSpecLong.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_LONG(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_LONG))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_LONG
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; glong minimum; glong maximum; glong default_value; } GParamSpecLong;
Производная структура GParamSpec которая содержит метаданные для long integer properties.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
glong minimum ; |
минимальное значение для определённого свойства |
glong maximum ; |
максимальное значение определённого свойства |
glong default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_long (const gchar *name, const gchar *nick, const gchar *blurb, glong minimum, glong maximum, glong default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecLong определяющий свойство G_TYPE_LONG
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_long (GValue *value, glong v_long);
Устанавливает содержимое G_TYPE_LONG
GValue в значение v_long
.
value : |
допустимая структура GValue типа G_TYPE_LONG
|
v_long : |
long integer значение для установки |
glong g_value_get_long (const GValue *value);
Получает содержимое G_TYPE_LONG
GValue.
value : |
допустимая структура GValue типа G_TYPE_LONG
|
Возвращает : | long integer содержимое value
|
#define G_IS_PARAM_SPEC_ULONG(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ULONG))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_ULONG
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_ULONG(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ULONG, GParamSpecULong))
Преобразует экземпляр GParamSpec в GParamSpecULong.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_ULONG(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ULONG))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_ULONG
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gulong minimum; gulong maximum; gulong default_value; } GParamSpecULong;
Производная структура GParamSpec которая содержит метаданные для unsigned long integer properties.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gulong minimum ; |
минимальное значение для определённого свойства |
gulong maximum ; |
максимальное значение определённого свойства |
gulong default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_ulong (const gchar *name, const gchar *nick, const gchar *blurb, gulong minimum, gulong maximum, gulong default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecULong определяющий свойство G_TYPE_ULONG
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_ulong (GValue *value, gulong v_ulong);
Устанавливает содержимое G_TYPE_ULONG
GValue в значение v_ulong
.
value : |
допустимая структура GValue типа G_TYPE_ULONG
|
v_ulong : |
unsigned long integer значение для установки |
gulong g_value_get_ulong (const GValue *value);
Получает содержимое G_TYPE_ULONG
GValue.
value : |
допустимая структура GValue типа G_TYPE_ULONG
|
Возвращает : | unsigned long integer содержимое value
|
#define G_IS_PARAM_SPEC_INT64(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT64))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_INT64
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_INT64(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT64, GParamSpecInt64))
Преобразует экземпляр GParamSpec в GParamSpecInt64.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_INT64(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_INT64))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_INT64
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gint64 minimum; gint64 maximum; gint64 default_value; } GParamSpecInt64;
Производная структура GParamSpec которая содержит метаданные для свойств 64bit целочисленного.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gint64 minimum ; |
минимальное значение для определённого свойства |
gint64 maximum ; |
максимальное значение определённого свойства |
gint64 default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_int64 (const gchar *name, const gchar *nick, const gchar *blurb, gint64 minimum, gint64 maximum, gint64 default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecInt64 определяющий свойство G_TYPE_INT64
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_int64 (GValue *value, gint64 v_int64);
Устанавливает содержимое G_TYPE_INT64
GValue в значение v_int64
.
value : |
допустимая структура GValue типа G_TYPE_INT64
|
v_int64 : |
64bit integer значение для установки |
gint64 g_value_get_int64 (const GValue *value);
Получает содержимое G_TYPE_INT64
GValue.
value : |
допустимая структура GValue типа G_TYPE_INT64
|
Возвращает : | 64bit целочисленное содержимое value
|
#define G_IS_PARAM_SPEC_UINT64(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT64))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_UINT64
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_UINT64(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT64, GParamSpecUInt64))
Преобразует экземпляр GParamSpec в GParamSpecUInt64.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_UINT64(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UINT64))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_UINT64
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; guint64 minimum; guint64 maximum; guint64 default_value; } GParamSpecUInt64;
Производная структура GParamSpec которая содержит метаданные для свойств unsigned 64bit integer.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
guint64 minimum ; |
минимальное значение для определённого свойства |
guint64 maximum ; |
максимальное значение определённого свойства |
guint64 default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_uint64 (const gchar *name, const gchar *nick, const gchar *blurb, guint64 minimum, guint64 maximum, guint64 default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecUInt64 определяющий свойство G_TYPE_UINT64
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_uint64 (GValue *value, guint64 v_uint64);
Устанавливает содержимое G_TYPE_UINT64
GValue в значение v_uint64
.
value : |
допустимая структура GValue типа G_TYPE_UINT64
|
v_uint64 : |
значение типа unsigned 64bit integer для установки |
guint64 g_value_get_uint64 (const GValue *value);
Получает содержимое G_TYPE_UINT64
GValue.
value : |
допустимая структура GValue типа G_TYPE_UINT64
|
Возвращает : | unsigned 64bit integer содержимое value
|
#define G_IS_PARAM_SPEC_FLOAT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLOAT))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_FLOAT
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_FLOAT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLOAT, GParamSpecFloat))
Преобразует экземпляр GParamSpec в GParamSpecFloat.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_FLOAT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLOAT))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_FLOAT
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gfloat minimum; gfloat maximum; gfloat default_value; gfloat epsilon; } GParamSpecFloat;
Производная структура GParamSpec которая содержит метаданные для свойств типа float.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gfloat minimum ; |
минимальное значение для определённого свойства |
gfloat maximum ; |
максимальное значение определённого свойства |
gfloat default_value ; |
значение по умолчанию для определённого свойства |
gfloat epsilon ; |
значения ближе чем epsilon будут рассматриваться как идентичные
g_param_values_cmp() ;
значение по умолчанию 1e-30.
|
GParamSpec* g_param_spec_float (const gchar *name, const gchar *nick, const gchar *blurb, gfloat minimum, gfloat maximum, gfloat default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecFloat определяющий свойство G_TYPE_FLOAT
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_float (GValue *value, gfloat v_float);
Устанавливает содержимое G_TYPE_FLOAT
GValue в значение v_float
.
value : |
допустимая структура GValue типа G_TYPE_FLOAT
|
v_float : |
float значение для установки |
gfloat g_value_get_float (const GValue *value);
Получает содержимое G_TYPE_FLOAT
GValue.
value : |
допустимая структура GValue типа G_TYPE_FLOAT
|
Возвращает : | float содержимое value
|
#define G_IS_PARAM_SPEC_DOUBLE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_DOUBLE))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_DOUBLE
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_DOUBLE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_DOUBLE, GParamSpecDouble))
Преобразует экземпляр GParamSpec в GParamSpecDouble.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_DOUBLE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_DOUBLE))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_DOUBLE
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gdouble minimum; gdouble maximum; gdouble default_value; gdouble epsilon; } GParamSpecDouble;
Производная структура GParamSpec которая содержит метаданные для double properties.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gdouble minimum ; |
минимальное значение для определённого свойства |
gdouble maximum ; |
максимальное значение определённого свойства |
gdouble default_value ; |
значение по умолчанию для определённого свойства |
gdouble epsilon ; |
значения ближе чем epsilon будут рассматриваться как идентичные
g_param_values_cmp() ;
значение по умолчанию 1e-90.
|
GParamSpec* g_param_spec_double (const gchar *name, const gchar *nick, const gchar *blurb, gdouble minimum, gdouble maximum, gdouble default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecDouble определяющий свойство G_TYPE_DOUBLE
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
minimum : |
минимальное значение для определённого свойства |
maximum : |
максимальное значение определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_double (GValue *value, gdouble v_double);
Устанавливает содержимое G_TYPE_DOUBLE
GValue в значение v_double
.
value : |
допустимая структура GValue типа G_TYPE_DOUBLE
|
v_double : |
double значение для установки |
gdouble g_value_get_double (const GValue *value);
Получает содержимое G_TYPE_DOUBLE
GValue.
value : |
допустимая структура GValue типа G_TYPE_DOUBLE
|
Возвращает : | double contents of value
|
#define G_IS_PARAM_SPEC_ENUM(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ENUM))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_ENUM
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_ENUM(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ENUM, GParamSpecEnum))
Преобразует экземпляр GParamSpec в GParamSpecEnum.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_ENUM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))
Определяет может ли полученная структура GValue
содержать значения наследуемыйе из типа G_TYPE_ENUM
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; GEnumClass *enum_class; gint default_value; } GParamSpecEnum;
Производная структура GParamSpec которая содержит метаданные для свойств перечисления.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GEnumClass *enum_class ; |
GEnumClass для перечисления |
gint default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_enum (const gchar *name, const gchar *nick, const gchar *blurb, GType enum_type, gint default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecEnum определяющий свойство G_TYPE_ENUM
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
enum_type : |
GType наследуемыйй из
G_TYPE_ENUM
|
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_enum (GValue *value, gint v_enum);
Устанавливает содержимое G_TYPE_ENUM
GValue в значение v_enum
.
value : |
допустимая структура GValue
чей тип унаследован из G_TYPE_ENUM
|
v_enum : |
перечислимое значение для установки |
gint g_value_get_enum (const GValue *value);
Получает содержимое G_TYPE_ENUM
GValue.
value : |
допустимая структура GValue чей тип унаследован из G_TYPE_ENUM
|
Возвращает : | перечислимое содержимое value
|
#define G_IS_PARAM_SPEC_FLAGS(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLAGS))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_FLAGS
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_FLAGS(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLAGS, GParamSpecFlags))
Преобразует экземпляр GParamSpec в GParamSpecFlags.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_FLAGS(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))
Определяет соответствует ли GValue содержать значения наследуемыйе из типа G_TYPE_FLAGS
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; GFlagsClass *flags_class; guint default_value; } GParamSpecFlags;
Производная структура GParamSpec которая содержит метаданные для флаговых свойств.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GFlagsClass *flags_class ; |
GFlagsClass для флагов |
guint default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_flags (const gchar *name, const gchar *nick, const gchar *blurb, GType flags_type, guint default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecEnum определяющий свойство G_TYPE_FLAGS
property.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
flags_type : |
a GType derived from G_TYPE_FLAGS
|
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_flags (GValue *value, guint v_flags);
Устанавливает содержимое G_TYPE_FLAGS
GValue в значение v_flags
.
value : |
допустимая структура GValue чей тип унаследован из G_TYPE_FLAGS
|
v_flags : |
флаговое значение для установки |
guint g_value_get_flags (const GValue *value);
Получает содержимое G_TYPE_FLAGS
GValue.
value : |
допустимая структура GValue чей тип унаследован из G_TYPE_FLAGS
|
Возвращает : | флаговое содержимое value
|
#define G_IS_PARAM_SPEC_STRING(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_STRING))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_STRING
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_STRING(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_STRING, GParamSpecString))
Преобразует экземпляр GParamSpec в GParamSpecString.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_STRING(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_STRING))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_STRING
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; gchar *default_value; gchar *cset_first; gchar *cset_nth; gchar substitutor; guint null_fold_if_empty : 1; guint ensure_non_null : 1; } GParamSpecString;
Производная структура GParamSpec которая содержит метаданные для свойств строки.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gchar *default_value ; |
значение по умолчанию для определённого свойства |
gchar *cset_first ; |
строка содержащая допустимые значения для первого байта |
gchar *cset_nth ; |
строка содержащая допустимые значения для последующих байт |
gchar
substitutor ; |
заменяет байт за байтом которые не соответствуют cset_first или
cset_nth .
|
guint
null_fold_if_empty : 1; |
заменяет пустую строку NULL
|
guint
ensure_non_null : 1; |
заменяет NULL пустыми строками
|
GParamSpec* g_param_spec_string (const gchar *name, const gchar *nick, const gchar *blurb, const gchar *default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecString.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_string (GValue *value, const gchar *v_string);
Устанавливает содержимое G_TYPE_STRING
GValue в значение v_string
.
value : |
допустимая структура GValue типа G_TYPE_STRING
|
v_string : |
string to be set |
void g_value_set_static_string (GValue *value, const gchar *v_string);
Устанавливает содержимое G_TYPE_STRING
GValue в значение v_string
.
Строка, как предполагается, является статичной, и поэтому не дублируется при установке GValue.
value : |
допустимая структура GValue типа G_TYPE_STRING
|
v_string : |
статичная строка для установки |
void g_value_take_string (GValue *value, gchar *v_string);
Устанавливает содержимое G_TYPE_STRING
GValue в значение v_string
.
value : |
допустимая структура GValue типа G_TYPE_STRING
|
v_string : |
дублируемая не имеющая владельца строка для установки |
Начиная с версии 2.4
void g_value_set_string_take_ownership (GValue *value, gchar *v_string);
g_value_set_string_take_ownership
устарела начиная с версии 2.4 и не должна использоваться во вновь
создаваемом коде. Вместо неё используйте g_value_take_string()
.
Это внутренняя функция введенная главным образом для C маршаллеров.
value : |
допустимая структура GValue типа G_TYPE_STRING
|
v_string : |
дублируемая не имеющая владельца строка для установки |
const gchar* g_value_get_string (const GValue *value);
Получает содержимое G_TYPE_STRING
GValue.
value : |
допустимая структура GValue типа G_TYPE_STRING
|
Возвращает : | строковое содержимое value
|
gchar* g_value_dup_string (const GValue *value);
Получает копию содержимого G_TYPE_STRING
GValue.
value : |
допустимая структура GValue типа G_TYPE_STRING
|
Возвращает : | вновь распределённая копия строкового содержимого value
|
#define G_IS_PARAM_SPEC_PARAM(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_PARAM))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_PARAM
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_PARAM(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_PARAM, GParamSpecParam))
Преобразует экземпляр GParamSpec в GParamSpecParam.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
Определяет может ли полученная структура GValue содержать значения наследуемыйе из типа G_TYPE_PARAM
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; } GParamSpecParam;
Производная структура GParamSpec которая содержит метаданные для
свойств G_TYPE_PARAM
.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GParamSpec* g_param_spec_param (const gchar *name, const gchar *nick, const gchar *blurb, GType param_type, GParamFlags flags);
Создаёт новый экземпляр GParamSpecParam определяющий свойство G_TYPE_PARAM
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
param_type : |
a GType derived from G_TYPE_PARAM
|
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_param (GValue *value, GParamSpec *param);
Устанавливает содержимое G_TYPE_PARAM
GValue в значение param
.
value : |
допустимая структура GValue типа G_TYPE_PARAM
|
param : |
GParamSpec для установки |
void g_value_take_param (GValue *value, GParamSpec *param);
Устанавливает содержимое G_TYPE_PARAM
GValue в значение param
и принимает монопольное пользование ссылкой param
;
вызывающий больше не сможет отменить эту ссылку.
value : |
допустимая структура GValue типа G_TYPE_PARAM
|
param : |
GParamSpec для установки |
Начиная с версии 2.4
void g_value_set_param_take_ownership (GValue *value, GParamSpec *param);
g_value_set_param_take_ownership
устарела начиная с версии 2.4 и не должна использоваться во вновь создаваемом коде. Вместо неё используйте g_value_take_param()
.
Это внутренняя функция введённая в основном для С маршаллеров.
value : |
допустимая структура GValue типа G_TYPE_PARAM
|
param : |
GParamSpec для установки |
GParamSpec* g_value_get_param (const GValue *value);
Получает содержимое G_TYPE_PARAM
GValue.
value : |
допустимая структура GValue чей тип унаследован из G_TYPE_PARAM
|
Возвращает : |
GParamSpec содержимое value
|
GParamSpec* g_value_dup_param (const GValue *value);
Получает содержимое G_TYPE_PARAM
GValue, увеличивает количество ссылок.
value : |
допустимая структура GValue чей тип унаследован из G_TYPE_PARAM
|
Возвращает : |
GParamSpec содержимое
value , ссылка должна быть отменена когда больше не нужна.
|
#define G_IS_PARAM_SPEC_BOXED(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOXED))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_BOXED
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_BOXED(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOXED, GParamSpecBoxed))
Преобразует экземпляр GParamSpec в GParamSpecBoxed.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_BOXED(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOXED))
Определяет может ли полученная структура GValue содержать значения наследуемыйе из типа G_TYPE_BOXED
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; } GParamSpecBoxed;
Производная структура GParamSpec которая содержит метаданные для упаковочных свойств.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GParamSpec* g_param_spec_boxed (const gchar *name, const gchar *nick, const gchar *blurb, GType boxed_type, GParamFlags flags);
Создаёт новый экземпляр GParamSpecBoxed определяющий производное свойство G_TYPE_BOXED
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
boxed_type : |
G_TYPE_BOXED наследуемыйй тип этого свойства
|
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_boxed (GValue *value, gconstpointer v_boxed);
Устанавливает содержимое G_TYPE_BOXED
derived GValue в значение v_boxed
.
value : |
допустимая структура GValue наследуемого типа G_TYPE_BOXED
|
v_boxed : |
boxed значение для установки |
void g_value_set_static_boxed (GValue *value, gconstpointer v_boxed);
Устанавливает содержимое G_TYPE_BOXED
наследуемой GValue в значение v_boxed
.
Значение как предполагается статично, поэтому не дублируется когда устанавливается
GValue.
value : |
допустимая структура GValue
наследуемого типа G_TYPE_BOXED
|
v_boxed : |
статичное boxed значение для установки |
void g_value_take_boxed (GValue *value, gconstpointer v_boxed);
Устанавливает содержимое G_TYPE_BOXED
наследуемой GValue в значение
v_boxed
и принимает монополию использования ссылки на v_boxed
;
вызывающий уже не сможет отменить эту ссылку.
value : |
допустимая структура GValue
наследуемого типа G_TYPE_BOXED
|
v_boxed : |
дублируемое не имеющее владельца boxed значение для установки |
Начиная с версии 2.4
void g_value_set_boxed_take_ownership (GValue *value, gconstpointer v_boxed);
g_value_set_boxed_take_ownership
устарела начиная с версии 2.4 и не должна использоваться во вновь создаваемом
коде. Вместо неё используйте g_value_take_boxed()
.
Это внутренняя функция введённая в основном для С маршаллеров.
value : |
допустимая структура GValue наследуемого типа
G_TYPE_BOXED
|
v_boxed : |
дублируемое не имеющее владельца boxed значение для установки |
gpointer g_value_get_boxed (const GValue *value);
Получает содержимое G_TYPE_BOXED
наследуемой GValue.
value : |
допустимая структура GValue наследуемого типа
G_TYPE_BOXED derived type
|
Возвращает : | boxed содержимое value
|
gpointer g_value_dup_boxed (const GValue *value);
Получает содержимое G_TYPE_BOXED
наследуемой GValue.
После получения, boxed значение дублируется и должно быть освобождено позже с помощью
g_boxed_free()
,
например как: g_boxed_free (G_VALUE_TYPE (value
), return_value);
value : |
допустимая структура GValue
наследуемого типа G_TYPE_BOXED
|
Возвращает : | boxed содержимое value
|
#define G_IS_PARAM_SPEC_POINTER(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_POINTER))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_POINTER
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_POINTER(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_POINTER, GParamSpecPointer))
Преобразует экземпляр GParamSpec в GParamSpecPointer.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_POINTER(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_POINTER))
Определяет может ли полученная структура GValue содержать значения типа G_TYPE_POINTER
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; } GParamSpecPointer;
Производная структура GParamSpec которая содержит метаданные для свойств указателя.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GParamSpec* g_param_spec_pointer (const gchar *name, const gchar *nick, const gchar *blurb, GParamFlags flags);
Создаёт новый экземпляр GParamSpecPoiner определяющий свойство указателя.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_pointer (GValue *value, gpointer v_pointer);
Устанавливает содержимое указателя GValue в значение v_pointer
.
value : |
допустимая структура GValue из
G_TYPE_POINTER
|
v_pointer : |
значение указателя для установки |
gpointer g_value_get_pointer (const GValue *value);
Получает содержимое указателя GValue.
value : |
допустимая структура GValue из
G_TYPE_POINTER
|
Возвращает : | указатель содержащийся в value
|
#define G_IS_PARAM_SPEC_OBJECT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OBJECT))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_OBJECT
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_OBJECT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OBJECT, GParamSpecObject))
Преобразует экземпляр GParamSpec в GParamSpecObject.
pspec : |
допустимый экземпляр GParamSpec |
#define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT))
Определяет может ли полученная структура GValue содержать значения
наследуемыйе из типа G_TYPE_OBJECT
.
value : |
допустимая структура GValue |
typedef struct { GParamSpec parent_instance; } GParamSpecObject;
Производная структура GParamSpec которая содержит метаданные для свойств объекта.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GParamSpec* g_param_spec_object (const gchar *name, const gchar *nick, const gchar *blurb, GType object_type, GParamFlags flags);
Создаёт новый экземпляр GParamSpecBoxed определяющий свойство наследуемого G_TYPE_OBJECT
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
object_type : |
G_TYPE_OBJECT
наследуемого типа этого свойства
|
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
void g_value_set_object (GValue *value, gpointer v_object);
Устанавливает содержимое G_TYPE_OBJECT
наследуемой GValue в значение v_object
.
value : |
допустимая структура GValue наследуемого типа
G_TYPE_OBJECT
|
v_object : |
объектное значение для установки |
void g_value_take_object (GValue *value, gpointer v_object);
Устанавливает содержимое G_TYPE_OBJECT
наследуемой GValue в значение
v_object
и принимает монопольное использование ссылки на v_object
;
вызывающий уже не сможет отменить эту ссылку.
value : |
допустимая структура GValue
наследуемого типа G_TYPE_OBJECT
|
v_object : |
объектное значение для установки |
Начиная с версии 2.4
void g_value_set_object_take_ownership (GValue *value, gpointer v_object);
g_value_set_object_take_ownership
устарела начиная с версии 2.4 и не должна использоваться во вновь создаваемом
коде. Вместо неё используйте g_value_take_object()
.
Это внутренняя функция введённая в основном для С маршаллеров.
value : |
допустимая структура GValue
наследуемого типа G_TYPE_OBJECT
|
v_object : |
объектное значение для установки |
gpointer g_value_get_object (const GValue *value);
Получает содержимое G_TYPE_OBJECT
наследуемой GValue.
value : |
допустимая структура GValue
наследуемого типа G_TYPE_OBJECT
|
Возвращает : | объект содержащийся в value
|
gpointer g_value_dup_object (const GValue *value);
Получает содержимое G_TYPE_OBJECT
наследуемой GValue, увеличивая количество ссылок.
value : |
допустимая структура GValue чей тип унаследован из G_TYPE_OBJECT
|
Возвращает : | объект содержащийся в value , ссылка должна быть отменена когда больше не нужна.
|
#define G_IS_PARAM_SPEC_UNICHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UNICHAR))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_UNICHAR
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_UNICHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UNICHAR, GParamSpecUnichar))
Преобразует экземпляр GParamSpec в GParamSpecUnichar.
pspec : |
допустимый экземпляр GParamSpec |
typedef struct { GParamSpec parent_instance; gunichar default_value; } GParamSpecUnichar;
Производная структура GParamSpec которая содержит метаданные для unichar (unsigned integer) properties.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
gunichar default_value ; |
значение по умолчанию для определённого свойства |
GParamSpec* g_param_spec_unichar (const gchar *name, const gchar *nick, const gchar *blurb, gunichar default_value, GParamFlags flags);
Создаёт новый экземпляр GParamSpecUnichar определяющий свойство G_TYPE_UINT
property. GValue structures for this property can be accessed with
g_value_set_uint()
and g_value_get_uint()
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
default_value : |
значение по умолчанию для определённого свойства |
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
#define G_IS_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_VALUE_ARRAY))
Определяет соответствует ли полученная GParamSpec типу G_TYPE_PARAM_VALUE_ARRAY
.
pspec : |
допустимый экземпляр GParamSpec |
#define G_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_VALUE_ARRAY, GParamSpecValueArray))
Преобразует экземпляр GParamSpec в GParamSpecValueArray.
pspec : |
допустимый экземпляр GParamSpec |
typedef struct { GParamSpec parent_instance; GParamSpec *element_spec; guint fixed_n_elements; } GParamSpecValueArray;
Производная структура GParamSpec которая содержит метаданные для свойств GValueArray.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GParamSpec *element_spec ; |
GParamSpec описывающая элементы содержащиеся в
массиве этого свойства, может быть NULL
|
guint
fixed_n_elements ; |
если больше чем 0, массивы этого свойства будут все иметь это количество элементов |
GParamSpec* g_param_spec_value_array (const gchar *name, const gchar *nick, const gchar *blurb, GParamSpec *element_spec, GParamFlags flags);
Создаёт новый экземпляр GParamSpecValueArray определяющий свойство
G_TYPE_VALUE_ARRAY
. G_TYPE_VALUE_ARRAY
это тип G_TYPE_BOXED
,
также к структурам GValue этого свойства можно обратиться с помощью
g_value_set_boxed()
и
g_value_get_boxed()
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
element_spec : |
GParamSpec описывающая элементы содержащиеся в массиве
этого свойства, может быть NULL
|
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация свойства |
#define G_IS_PARAM_SPEC_OVERRIDE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OVERRIDE))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_OVERRIDE
.
pspec : |
a GParamSpec |
Начиная с версии 2.4
#define G_PARAM_SPEC_OVERRIDE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OVERRIDE, GParamSpecOverride))
Преобразует GParamSpec в GParamSpecOverride.
pspec : |
GParamSpec |
Начиная с версии 2.4
typedef struct { } GParamSpecOverride;
Это тип GParamSpec который просто перенаправляет операции
в другую спецификацию параметра. Все операции, кроме получения или установки значения, перенаправляются, включая доступное имя и
описание, утверждённое значение, и так далее. Смотрите
g_param_spec_get_redirect_target()
поиска свойства overidden. GParamSpecOverride используется в реализации
g_object_class_override_property()
, и в основном полезна только при реализации нового базового типа наподобие GObject.
Начиная с версии 2.4
GParamSpec* g_param_spec_override (const gchar *name, GParamSpec *overridden);
Создаёт новый экземпляр свойства типа GParamSpecOverride. Используется для направления операций в другие спецификации параметра (paramspec), и в основном полезна только при реализации нового базового типа наподобие GObject.
name : |
имя свойства. |
overridden : |
переписываемое свойство |
Возвращает : | вновь созданная GParamSpec |
Начиная с версии 2.4
#define G_IS_PARAM_SPEC_GTYPE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_GTYPE))
Определяет соответствует ли GParamSpec типу G_TYPE_PARAM_GTYPE
.
pspec : |
a GParamSpec |
Начиная с версии 2.10
#define G_PARAM_SPEC_GTYPE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_GTYPE, GParamSpecGType))
Преобразует GParamSpec в GParamSpecGType.
pspec : |
GParamSpec |
Начиная с версии 2.10
#define G_VALUE_HOLDS_GTYPE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_GTYPE))
Определяет может ли GValue содержать значения типа
G_TYPE_GTYPE
.
value : |
допустимая структура GValue |
Начиная с версии 2.12
#define G_TYPE_PARAM_GTYPE (g_param_spec_types[21])
GType из GParamSpecGType.
Начиная с версии 2.10
typedef struct { GParamSpec parent_instance; GType is_a_type; } GParamSpecGType;
Производная структура GParamSpec которая содержит метаданные для свойства GType.
GParamSpec parent_instance ; |
закрытая часть GParamSpec |
GType is_a_type ; |
GType чей подтип может использоваться как значение |
Начиная с версии 2.10
GParamSpec* g_param_spec_gtype (const gchar *name, const gchar *nick, const gchar *blurb, GType is_a_type, GParamFlags flags);
Создаёт новый экземпляр GParamSpecGType определяющий свойство
G_TYPE_GTYPE
.
Смотрите g_param_spec_internal()
относительно деталей имён свойств.
name : |
каноническое имя определённого свойства |
nick : |
псевдоним определённого свойства |
blurb : |
описание определённого свойства |
is_a_type : |
GType чей подтип доступен для использования в качестве
значения свойства
(используйте G_TYPE_NONE для любого типа)
|
flags : |
флаги для определённого свойства |
Возвращает : | вновь созданная спецификация параметра |
Начиная с версии 2.10
GType g_value_get_gtype (const GValue *value);
Получает содержимое G_TYPE_GTYPE
GValue.
value : |
допустимая структура GValue типа G_TYPE_GTYPE
|
Возвращает : | GType хранящийся в value
|
Начиная с версии 2.12
void g_value_set_gtype (GValue *value, GType v_gtype);
Устанавливает содержимое G_TYPE_GTYPE
GValue в значение v_gtype
.
value : |
допустимая структура GValue типа G_TYPE_GTYPE
|
v_gtype : |
GType для установки |
Начиная с версии 2.12
![]() |
![]() |
![]() |
Справочное описание 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 является базовым типом обеспечивающим основные атрибуты и методы для всех объектных типов в GTK+, Pango и других библиотеках основанных на GObject. Класс GObject обеспечивает методы для конструирования и уничтожения объектов, методы доступа к свойству и поддержку сигналов. Сигналы подробно описаны в Сигналы(3).
GInitiallyUnowned наследует GObject. Единственное различие между ними заключается в том что начальная ссылка GInitiallyUnowned помечается как плавающая ссылка. Это значит что ни какой частью кода ни кто не "владеет". Основная мотивация обеспечения плавающих ссылок - удобство C. В частности, это позволяет писать код как:
Если
выполнит
container_add_child()
g_object_ref_sink()
для помещённого child, ссылка на вновь созданный child не будет плавающей.
Без плавающей ссылки,
может создать ссылку на новый child
только с помощью container_add_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); /* освобождение предварительно полученной ссылки */
typedef struct _GObject GObject;
Все поля в структуре GObject являются закрытыми для реализации GObject и не должны использоваться непосредственно.
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 их родительского класса что позволяет завершить их инициализацию.
|
typedef struct { GParamSpec *pspec; GValue *value; } GObjectConstructParam;
Вспомогательная структура GObjectConstructParam используется для расположения
GParamSpec/
GValue
пар в constructor
принадлежащем
GObjectClass.
GParamSpec *pspec ; |
GParamSpec параметр конструктора |
GValue *value ; |
Значение для параметра конструктора |
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 описание свойства |
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 описание свойства |
void (*GObjectFinalizeFunc) (GObject *object);
Тип функции finalize
в
GObjectClass.
object : |
финализируемый GObject |
#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 .
|
#define G_OBJECT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject))
Приводит GObject или полученный указатель к указателю (GObject*). В зависимости от текущего уровня отладки, эта функция может вызвать определённые динамические проверки чтобы идентифицировать недопустимые приведения типов.
object : |
Объект который необходимо преобразовать. |
#define G_IS_OBJECT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT))
Проверяет допустимость указателя GTypeInstance
типа G_TYPE_OBJECT
.
object : |
Экземпляр для проверки соответствия типу
G_TYPE_OBJECT .
|
#define G_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass))
Приводит полученную структуру GObjectClass к структуре GObjectClass.
class : |
допустимая GObjectClass |
#define G_IS_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT))
Проверяет является ли class
"is a" допустимой структурой
GObjectClass типа
G_TYPE_OBJECT
или производной.
class : |
GObjectClass |
#define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass))
Возвращает классовую структуру связанную с экземпляром GObject.
object : |
экземпляр GObject. |
#define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object))
Возвращает типовой id объекта.
object : |
Объект для которого возвращается типовой id. |
Возвращает : | Типовой id для object .
|
#define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object)))
Возвращает имя объектного типа.
object : |
Объект для которого возвращается типовое имя. |
Возвращает : | Типовое имя object . Строкой владеет система типов и её не нужно освобождать.
|
#define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
Возвращает типовой id сструктуры класса.
class : |
допустимая GObjectClass |
Возвращает : | Типовой id для class .
|
#define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class)))
Возвращает имя классовой сструктуры типа.
class : |
допустимая GObjectClass |
Возвращает : | Типовое имя class . Строкой владеет система типов и она не должна освобождаться.
|
void g_object_class_install_property (GObjectClass *oclass, guint property_id, GParamSpec *pspec);
Устанавливает новое свойство. Это обычно делается в инициализации класса.
oclass : |
GObjectClass |
property_id : |
id для нового свойства |
pspec : |
GParamSpec для нового свойства |
GParamSpec* g_object_class_find_property (GObjectClass *oclass, const gchar *property_name);
Находит GParamSpec для свойства класса.
oclass : |
GObjectClass |
property_name : |
искомое имя свойства |
Возвращает : | GParamSpec для свойства,
или NULL
если класс не имеет свойства с таким именем
|
GParamSpec** g_object_class_list_properties (GObjectClass *oclass, guint *n_properties);
Возвращает массив GParamSpec* для всех свойств класса.
oclass : |
GObjectClass |
n_properties : |
расположение длины возвращаемого массива |
Возвращает : | массив GParamSpec* который должен быть освобождён после использования |
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
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
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
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
gpointer g_object_new (GType object_type, const gchar *first_property_name, ...);
Создаёт новый экземпляр GObject подтипа (subtype) и устанавливает его свойства.
Конструкционные параметры (смотрите G_PARAM_CONSTRUCT, G_PARAM_CONSTRUCT_ONLY) которые определены не явно, устанавливаются в их значения по умолчанию.
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
|
typedef struct { const gchar *name; GValue value; } GParameter;
Вспомогательная структура GParameter используется для размещения параметных пар name/value
в g_object_newv()
.
gpointer g_object_ref (gpointer object);
Увеличивает количество ссылок object
.
object : |
GObject |
Возвращает : | тот же object
|
void g_object_unref (gpointer object);
Уменьшает количество ссылок object
.
Когда количество ссылок достигает 0, объект финализируется (то есть память связанная с этим объектом освобождается).
object : |
a GObject |
gpointer g_object_ref_sink (gpointer object);
Увеличивает количество ссылок object
, и возможно удаляет
плавающую ссылку,
если object
имеет плавающую ссылку.
Другими словами, если объект плавающий, то этот вызов "принимает владение" плавающей ссылкой, преобразует её в обычную ссылку очищая плавающий флаг оставляя неизменным количество ссылок. Если объект не плавающий, то этот вызов добавляет обычную ссылку увеличивая количество ссылок на одну.
object : |
GObject |
Возвращает : |
object
|
Начиная с версии 2.10
typedef struct _GObject GInitiallyUnowned;
Все поля в структуре GInitiallyUnowned являются закрытыми для реализации GInitiallyUnowned и к ним нет непосредственного доступа.
typedef struct _GObjectClass GInitiallyUnownedClass;
Классовая структура для типа GInitiallyUnowned.
#define G_TYPE_INITIALLY_UNOWNED (g_initially_unowned_get_type())
Тип для GInitiallyUnowned.
gboolean g_object_is_floating (gpointer object);
Проверяет имеет ли object
плавающую
ссылку.
Начиная с версии 2.10
void g_object_force_floating (GObject *object);
Эта функция предназначается для реализации GObject
утвердить плавающую ссылку объекта.
Выполнение этой операции требуется редко, все
GInitiallyUnowned
создаются с плавающими ссылками которые обычно должны просто обрабатываться вызовом
g_object_ref_sink()
.
object : |
a GObject |
Начиная с версии 2.10
void (*GWeakNotify) (gpointer data, GObject *where_the_object_was);
Функция GWeakNotify может быть добавлена в объект как callback-функция которая вызывается когда объект финализирован. Так как объект уже финализирован когда вызывается GWeakNotify, вы ничего не можете делать с объектом, кроме как использовать его адрес как hash-index или нечто подобное.
data : |
данные обеспечиваемые при установке слабых ссылок |
where_the_object_was : |
объект для финализации |
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 : |
дополнительные данные помещаемые в уведомление |
void g_object_weak_unref (GObject *object, GWeakNotify notify, gpointer data);
Удаляет слабую ссылку callback-функции для объекта.
object : |
GObject для удаления слабой ссылки |
notify : |
callback-функция для поиска |
data : |
данные для поиска |
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 : |
адрес указателя в памяти. |
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 : |
адрес указателя в памяти. |
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
если переключаемая ссылка была последней ссылкой а теперь есть другая ссылка.
|
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
void g_object_remove_toggle_ref (GObject *object, GToggleNotify notify, gpointer data);
Удаляет ссылку добавленную с помощью
g_object_add_toggle_ref()
.
Количество ссылок на объект уменьшается на одну.
object : |
GObject |
notify : |
функция вызываемая когда ссылка является последней ссылкой на объект, или когда она больше не является последней ссылкой на объект. |
data : |
данные помещаемые в notify
|
Начиная с версии 2.8
gpointer g_object_connect (gpointer object, const gchar *signal_spec, ...);
Удобная функция для подключения множество сигналов сразу.
Спецификации сигналов ожидаемых этой функцией имеет форму "modifier::signal_name", где modifier может быть одним из следующего:
signal |
эквивалент |
object_signal, object-signal |
эквивалент |
swapped_signal, swapped-signal |
эквивалент |
swapped_object_signal, swapped-object-signal |
эквивалент |
signal_after, signal-after |
эквивалент |
object_signal_after, object-signal-after |
эквивалент |
swapped_signal_after, swapped-signal-after |
эквивалент |
swapped_object_signal_after, swapped-object-signal-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);
void g_object_disconnect (gpointer object, const gchar *signal_spec, ...);
Удобная функция для отключения множества сигналов сразу.
Спецификация сигналов ожидаемых этой функцией имеет форму "any_signal", которая означает отключение любых сигналов с соответствующими callback-функциями и данными, или "any_signal::signal_name", которая отключает только сигнал с именем "signal_name".
void g_object_set (gpointer object, const gchar *first_property_name, ...);
Устанавливает свойства на объект.
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);
void g_object_notify (GObject *object, const gchar *property_name);
Издаёт сигнал "notify" для свойства property_name
в object
.
object : |
GObject |
property_name : |
имя свойства установленное в класс object .
|
void g_object_freeze_notify (GObject *object);
Останавливает эмиссию сигнала "notify" в object
. Сигналы ставятся в очередь пока
g_object_thaw_notify()
не вызвана для
object
.
Это необходимо для аксессоров которые изменяют множество свойств, для предотвращения уведомления в течение модификации объекта.
object : |
GObject |
void g_object_thaw_notify (GObject *object);
Обратный эффект от предыдущего вызова
g_object_freeze_notify()
.
Это заставит все сигналы "notify" поставленные в очередь издаться на object
.
object : |
GObject |
gpointer g_object_get_data (GObject *object, const gchar *key);
Получает именованное поле из таблицы объектов ассоциации
(смотрите g_object_set_data()
).
void g_object_set_data (GObject *object, const gchar *key, gpointer data);
Каждый объект поддерживает таблицу ассоциаций от строк до указателей. Эта функция позволяет вам установить ассоциацию.
Если объект уже содержит ассоциацию с таким именем, старая ассоциация будет уничтожена.
object : |
GObject содержащий ассоциации. |
key : |
имя ключа |
data : |
данные связанные с этим ключом |
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 : |
функция вызываемая при уничтожении ассоциации |
gpointer g_object_steal_data (GObject *object, const gchar *key);
Удаляет определённую величину из объектных данных ассоциаций, без вызова обработчика уничтожения ассоциаций.
gpointer g_object_get_qdata (GObject *object, GQuark quark);
Эта функция получает назад пользовательские указатели данных сохранённые через
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 : |
Непрозрачный указатель пользовательских данных |
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 нужно освободить
|
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()
.
void g_object_set_property (GObject *object, const gchar *property_name, const GValue *value);
Устанавливает свойство для объекта.
object : |
GObject |
property_name : |
имя устанавливаемого свойства |
value : |
значение |
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 : |
расположение возвращаемого значения свойства |
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) которые явно не определены устанавливаются в значение по умолчанию.
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);
Получает свойства объекта.
В основном, создаётся копия содержимого свойства и вызывающий отвечает за освобождение памяти так как это делается для типа,
например вызовом g_free()
или
g_object_unref()
.
Смотрите g_object_get()
.
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 для отслеживания |
void g_object_run_dispose (GObject *object);
Высвобождает все ссылки на другие объекты. Это может быть использовано для прерывания циклов ссылки.
Эти функции должны вызываться только из системы реализации объекта.
object : |
GObject |
#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 свойства |
"notify"
signalvoid 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 | ![]() |
---|---|---|---|---|
#include <glib-object.h> typedef GType; #define G_TYPE_FUNDAMENTAL (type) #define G_TYPE_FUNDAMENTAL_MAX #define G_TYPE_MAKE_FUNDAMENTAL (x) #define G_TYPE_IS_ABSTRACT (type) #define G_TYPE_IS_DERIVED (type) #define G_TYPE_IS_FUNDAMENTAL (type) #define G_TYPE_IS_VALUE_TYPE (type) #define G_TYPE_HAS_VALUE_TABLE (type) #define G_TYPE_IS_CLASSED (type) #define G_TYPE_IS_INSTANTIATABLE (type) #define G_TYPE_IS_DERIVABLE (type) #define G_TYPE_IS_DEEP_DERIVABLE (type) #define G_TYPE_IS_INTERFACE (type) GTypeInterface; GTypeInstance; GTypeClass; GTypeInfo; GTypeFundamentalInfo; GInterfaceInfo; GTypeValueTable; #define G_TYPE_FROM_INSTANCE (instance) #define G_TYPE_FROM_CLASS (g_class) #define G_TYPE_FROM_INTERFACE (g_iface) #define G_TYPE_INSTANCE_GET_CLASS (instance, g_type, c_type) #define G_TYPE_INSTANCE_GET_INTERFACE (instance, g_type, c_type) #define G_TYPE_INSTANCE_GET_PRIVATE (instance, g_type, c_type) #define G_TYPE_CHECK_INSTANCE (instance) #define G_TYPE_CHECK_INSTANCE_CAST (instance, g_type, c_type) #define G_TYPE_CHECK_INSTANCE_TYPE (instance, g_type) #define G_TYPE_CHECK_CLASS_CAST (g_class, g_type, c_type) #define G_TYPE_CHECK_CLASS_TYPE (g_class, g_type) #define G_TYPE_CHECK_VALUE (value) #define G_TYPE_CHECK_VALUE_TYPE (value, g_type) #define G_TYPE_FLAG_RESERVED_ID_BIT void g_type_init (void); enum GTypeDebugFlags; void g_type_init_with_debug_flags (GTypeDebugFlags debug_flags); const gchar* g_type_name (GType type); GQuark g_type_qname (GType type); GType g_type_from_name (const gchar *name); GType g_type_parent (GType type); guint g_type_depth (GType type); GType g_type_next_base (GType leaf_type, GType root_type); gboolean g_type_is_a (GType type, GType is_a_type); gpointer g_type_class_ref (GType type); gpointer g_type_class_peek (GType type); gpointer g_type_class_peek_static (GType type); void g_type_class_unref (gpointer g_class); gpointer g_type_class_peek_parent (gpointer g_class); void g_type_class_add_private (gpointer g_class, gsize private_size); gpointer g_type_interface_peek (gpointer instance_class, GType iface_type); gpointer g_type_interface_peek_parent (gpointer g_iface); gpointer g_type_default_interface_ref (GType g_type); gpointer g_type_default_interface_peek (GType g_type); void g_type_default_interface_unref (gpointer g_iface); GType* g_type_children (GType type, guint *n_children); GType* g_type_interfaces (GType type, guint *n_interfaces); GType* g_type_interface_prerequisites (GType interface_type, guint *n_prerequisites); void g_type_set_qdata (GType type, GQuark quark, gpointer data); gpointer g_type_get_qdata (GType type, GQuark quark); void g_type_query (GType type, GTypeQuery *query); GTypeQuery; void (*GBaseInitFunc) (gpointer g_class); void (*GBaseFinalizeFunc) (gpointer g_class); void (*GClassInitFunc) (gpointer g_class, gpointer class_data); void (*GClassFinalizeFunc) (gpointer g_class, gpointer class_data); void (*GInstanceInitFunc) (GTypeInstance *instance, gpointer g_class); void (*GInterfaceInitFunc) (gpointer g_iface, gpointer iface_data); void (*GInterfaceFinalizeFunc) (gpointer g_iface, gpointer iface_data); gboolean (*GTypeClassCacheFunc) (gpointer cache_data, GTypeClass *g_class); enum GTypeFlags; enum GTypeFundamentalFlags; GType g_type_register_static (GType parent_type, const gchar *type_name, const GTypeInfo *info, GTypeFlags flags); GType g_type_register_static_simple (GType parent_type, const gchar *type_name, guint class_size, GClassInitFunc class_init, guint instance_size, GInstanceInitFunc instance_init, GTypeFlags flags); GType g_type_register_dynamic (GType parent_type, const gchar *type_name, GTypePlugin *plugin, GTypeFlags flags); GType g_type_register_fundamental (GType type_id, const gchar *type_name, const GTypeInfo *info, const GTypeFundamentalInfo *finfo, GTypeFlags flags); void g_type_add_interface_static (GType instance_type, GType interface_type, const GInterfaceInfo *info); void g_type_add_interface_dynamic (GType instance_type, GType interface_type, GTypePlugin *plugin); void g_type_interface_add_prerequisite (GType interface_type, GType prerequisite_type); GTypePlugin* g_type_get_plugin (GType type); GTypePlugin* g_type_interface_get_plugin (GType instance_type, GType interface_type); GType g_type_fundamental_next (void); GType g_type_fundamental (GType type_id); GTypeInstance* g_type_create_instance (GType type); void g_type_free_instance (GTypeInstance *instance); void g_type_add_class_cache_func (gpointer cache_data, GTypeClassCacheFunc cache_func); void g_type_remove_class_cache_func (gpointer cache_data, GTypeClassCacheFunc cache_func); void g_type_class_unref_uncached (gpointer g_class); void g_type_add_interface_check (gpointer check_data, GTypeInterfaceCheckFunc check_func); void g_type_remove_interface_check (gpointer check_data, GTypeInterfaceCheckFunc check_func); void (*GTypeInterfaceCheckFunc) (gpointer check_data, gpointer g_iface); GTypeValueTable* g_type_value_table_peek (GType type); #define G_DEFINE_TYPE (TN, t_n, T_P) #define G_DEFINE_TYPE_WITH_CODE (TN, t_n, T_P, _C_) #define G_DEFINE_ABSTRACT_TYPE (TN, t_n, T_P) #define G_DEFINE_ABSTRACT_TYPE_WITH_CODE (TN, t_n, T_P, _C_) #define G_IMPLEMENT_INTERFACE (TYPE_IFACE, iface_init) #define G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, _f_, _C_) #define G_TYPE_INVALID #define G_TYPE_NONE #define G_TYPE_INTERFACE #define G_TYPE_CHAR #define G_TYPE_UCHAR #define G_TYPE_BOOLEAN #define G_TYPE_INT #define G_TYPE_UINT #define G_TYPE_LONG #define G_TYPE_ULONG #define G_TYPE_INT64 #define G_TYPE_UINT64 #define G_TYPE_ENUM #define G_TYPE_FLAGS #define G_TYPE_FLOAT #define G_TYPE_DOUBLE #define G_TYPE_STRING #define G_TYPE_POINTER #define G_TYPE_BOXED #define G_TYPE_PARAM #define G_TYPE_OBJECT #define G_TYPE_GTYPE #define G_TYPE_RESERVED_GLIB_FIRST #define G_TYPE_RESERVED_GLIB_LAST #define G_TYPE_RESERVED_BSE_FIRST #define G_TYPE_RESERVED_BSE_LAST #define G_TYPE_RESERVED_USER_FIRST
GType API является основой системы GObject. Он обеспечивает средства для регистрации и управления всеми базовыми типами данных,
определённых пользователем объектов и типами интерфейсов. Перед использованием любых функций GType или GObject,
должна быть вызвана g_type_init()
для
инициализации системы типов.
Для создания типа и регистрационных целей, все типы относятся к одной из двух категорий: статические или динамические.
Статические типы никогда не загружаются и не выгружаются во время выполнения, как это могут делать динамические типы.
Статические типы создаются с помощью
g_type_register_static()
которая получает
определённую информацию помещаемую в неё через структуру
GTypeInfo.
Динамические типы создаются с помощью
g_type_register_dynamic()
которая принимает вместо сструктуры
GTypePlugin. Оставшаяся информация типа
(GTypeInfo структура) находится во время выполнения через
GTypePlugin
и g_type_plugin_*() API.
Эти регистрационные функции полезно вызывать только однажды из функции целью которой является возврат идентификатора типа
для определённого класса. Как только тип (либо класс или интерфейс) зарегистрирован, он может быть инстанциирован, унаследован,
или реализован в зависимости от того, что это за тип.
Есть также третья регистрационная функция для регистрации базовых типов
g_type_register_fundamental()
которая требует и структуру GTypeInfo
и структуру GTypeFundamentalInfo,
но она редко используется, так как большинство базовых типов является предопределёнными и не определяются пользователем.
В заключительном слове об именах типов. Такой идентификатор должен быть по крайней мере длиной из трёх символов. Максимального предела длины не существует. Первый символ должен быть буквой (a-z или A-Z) или символом подчёркивания '_'. Последующие символы могут быть буквами, цифрами или одним из символов '-_+'.
#define G_TYPE_FUNDAMENTAL(type) (g_type_fundamental (type))
Возвращает базовый тип который наследует type
.
Базовые типы являются типами которые служат основой для производных типов,
таким образом они являются корнями отдельных иерархий наследования.
type : |
GType значение. |
#define G_TYPE_FUNDAMENTAL_MAX (255 << G_TYPE_FUNDAMENTAL_SHIFT)
Целочисленная константа представляющая количество идентификаторов, зарезервированных для типов обозначенных во время компиляции.
#define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
Возвращает ID для базового типа с номером x
.
Используйте g_type_fundamental_next()
вместо этого макроса для создания нового базового типа.
x : |
номер базового типа. |
#define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
Возвращает TRUE
если type
является абстрактным. Абстрактный тип может не инициироваться и используется обычно
как абстрактный основной класс для наследования классов.
type : |
значение GType. |
#define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX)
Возвращает TRUE
если type
унаследован из другого типа (возвращает TRUE для всех не базовых типов).
type : |
значение GType. |
#define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX)
Возвращает TRUE
если type
является базовым типом.
type : |
значение GType. |
#define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type))
Возвращает TRUE
если type
является типовым значением и может использоваться с помощью
g_value_init()
.
type : |
значение GType. |
#define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL)
Возвращает TRUE
если type
имеет GTypeValueTable.
type : |
значение GType. |
#define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
Возвращает TRUE
если type
является классовым типом.
type : |
значение GType. |
#define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
Возвращает TRUE
если type
может быть инстанциирован.
Инстанциация - это процесс создания экземпляра объекта данного типа.
type : |
значение GType. |
#define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
Возвращает TRUE
если type
является наследником. Наследуемый тип может использоваться как основной класс
плоской (одноуровневой) иерархии класса.
type : |
значение GType. |
#define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
Возвращает TRUE
если type
глубоко наследуемыйй тип. Глубоко наследуемыйй тип может использоваться
как основной класс глубокой (многоуровневой) иерархии класса.
type : |
значение GType. |
#define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
Возвращает TRUE
если type
является интерфейсным типом.
Интерфейсные типы обеспечивают чистый API, реализация которого обеспечивается
другим типом (который, как говорится в таких случаях, соответствует интерфейсу).
GLib интерфейсы являются в некотором роде аналогами интерфейсов Java
и C++ классов содержащие только чистые виртуальные функции,
различие в том, что GType интерфейсы не наследуемый (но можно посмотреть альтернативу
g_type_interface_add_prerequisite()
).
type : |
значение GType. |
typedef struct { } GTypeInterface;
Непрозрачная структура используемая как основа всех интерфейсных типов.
typedef struct { } GTypeInstance;
Непрозрачная структура используемая как основа всех инстанциируемых типов.
typedef struct { } GTypeClass;
Непрозрачная структура используемая как основа всех классов.
typedef struct { /* interface types, classed types, instantiated types */ guint16 class_size; GBaseInitFunc base_init; GBaseFinalizeFunc base_finalize; /* interface types, classed types, instantiated types */ GClassInitFunc class_init; GClassFinalizeFunc class_finalize; gconstpointer class_data; /* instantiated types */ guint16 instance_size; guint16 n_preallocs; GInstanceInitFunc instance_init; /* value handling */ const GTypeValueTable *value_table; } GTypeInfo;
Эта структура используется для обеспечения системы типов информацией запрашиваемой для инициализации
и уничтожения (финализации) типового класса и его экземпляра.
Инициализированная структура помещается в функцию
g_type_register_static()
(или копируется в структуру GTypeInfo обеспеченную функцией
g_type_plugin_complete_type_info()
).
Система типов выполнит глубокую копию этой сструктуры, поэтому память не должна быть постоянной через вызов
g_type_register_static()
.
guint16
class_size ; |
Размер сструктуры класса (требуется для интерфейсных, классифицированных и инстанцируемых типов). |
GBaseInitFunc
base_init ; |
Расположение основной инициализирующей функции (опционально). |
GBaseFinalizeFunc
base_finalize ; |
Расположение основной финализирующей функции (опционально). |
GClassInitFunc class_init ; |
Расположение функции инициализации класса для классов и типов. Расположение по умолчанию vtable инициализирующей функции для интерфейсных типов. (опционально) Для заполнения виртуальной функции класса используется либо эта функция либо значение по умолчанию vtable, и выполняет специфичную для типа установку такую как регистрация сигналов и свойств объекта. |
GClassFinalizeFunc class_finalize ; |
Расположение функции финализации класса для классов и типов. Расположение по умолчанию в vtable функции финализации интерфейсных типов. (опционально) |
gconstpointer class_data ; |
Данные обеспечиваемые пользователем помещаемые в классовые функции инициализация/финализация. |
guint16 instance_size ; |
Размер экземпляра (объекта) сструктуры (запрашиваемый только для инстанциирования). |
guint16 n_preallocs ; |
До GLib 2.10, представлял количество предварительно распределённых (кэшированных) экземпляров для резервирования памяти (0 указывает на отсутствие кэша). Начиная с версии GLib 2.10, игнорируется, так как теперь экземпляры распределяются с помощью slice allocator. |
GInstanceInitFunc instance_init ; |
Расположение функции инициализирующей экземпляр (опционально, только для инстанциируемых типов). |
const GTypeValueTable *value_table ; |
Табличная функция GTypeValueTable для основной обработки GValues этого типа (обычно полезна только для базовых типов). |
typedef struct { GTypeFundamentalFlags type_flags; } GTypeFundamentalInfo;
Структура обеспечивающая информацией систему типов специально для управления базовыми типами.
GTypeFundamentalFlags type_flags ; |
GTypeFundamentalFlags описывает характеристики базового типа |
typedef struct { GInterfaceInitFunc interface_init; GInterfaceFinalizeFunc interface_finalize; gpointer interface_data; } GInterfaceInfo;
Структура обеспечивает информацию для системы типов которая используется специально для управления интерфейсными типами.
GInterfaceInitFunc interface_init ; |
расположение функции инициализации интерфейса |
GInterfaceFinalizeFunc interface_finalize ; |
расположение функции финализации интерфейса |
gpointer interface_data ; |
пользовательские данные для функций инициализации/финализации интерфейса |
typedef struct { void (*value_init) (GValue *value); void (*value_free) (GValue *value); void (*value_copy) (const GValue *src_value, GValue *dest_value); /* varargs functionality (optional) */ gpointer (*value_peek_pointer) (const GValue *value); gchar *collect_format; gchar* (*collect_value) (GValue *value, guint n_collect_values, GTypeCValue *collect_values, guint collect_flags); gchar *lcopy_format; gchar* (*lcopy_value) (const GValue *value, guint n_collect_values, GTypeCValue *collect_values, guint collect_flags); } GTypeValueTable;
GTypeValueTable обеспечивает функции требуемые реализацией GValue, которая служит контейнером для значений типа.
value_init () |
По умолчанию инициализирует содержимое values
записывая значения непосредственно в массив value->data. Массив данных
GValue помещённый
в эту функцию будет заполнен нулями с помощью ,
поэтому не нужно беспокоится об освобождении предыдущего содержимого. Например реализация строкового значения
которое могло бы быть не NULL ,
может выглядеть так:
{ value->data[0].v_pointer = g_strdup (""); } |
||||||||
value_free () |
Освобождает любое предыдущее содержимое массива данных помещённого в value .
Ресурсы распределённые для содержимого
GValue после вызова этой функции освобождаются.
На примере нашей строки выше:
{ /* освобождает строки только без определённого флага статического хранения */ if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); } |
||||||||
value_copy () |
dest_value это
GValue с разделом данных заполненным нулями, а
src_value надлежащим образом установленная
GValue того же или производного типа.
Цель функции заключается в копировании содержимого src_value
в dest_value , то есть даже после освобождения
src_value , содержимое dest_value
останется доступным. Типовой пример строки:
{ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); } |
||||||||
value_peek_pointer () |
Если значение содержимого заполнено указателем, таким как объекты или строки,
возвращает этот указатель, таким образом вызывающая программа может посмотреть текущее содержимое.
Расширение нашего примера строки выше:
{ return value->data[0].v_pointer; } |
||||||||
gchar *collect_format ; |
Формат строки описывающий как накапливается содержимое этого значения поразрядно.
Каждый символ в формате представляет накапливаемый параметр и непосредственно символы
указывают тип параметра. В настоящее время поддерживаются параметры:
|
||||||||
collect_value () |
функция collect_value() отвечает за преобразование накопленных значений
из списка переменных параметров в содержимое подходящее для хранения в GValue. Эта функция должна установить
value подобно value_init() ;
например для строкового значения которое не допускает
NULL указателей,
она должна либо вернуть ошибку, либо выполнить неявное преобразование сохранив пустую строку.
value помещённый в эту функцию является нулевым массивом данных,
таким образом точно так же как для value_init() гарантирует отсутствие предыдущего
содержимого которое нужно освобождать.
n_collect_values точная длина строки
collect_format ,
а collect_values массив объединений
GTypeCValue с
длиной n_collect_values , содержащий накопленные значения согласно
collect_format .
collect_flags - является параметром обеспечивающим подсказку для вызывающей
программы.
Он может содержать флаг G_VALUE_NOCOPY_CONTENTS указывающий,
что накопленное значение содержимого можно рассматривать как "static" в течение жизненного цикла
value .
Поэтому дополнительная копия содержимого сохранённого в collect_values
не требуется для назначения value .
Наш пример строки выше, мы продолжим следующим:
{ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; /* keep a flag for the value_free() implementation to not free this string */ value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; }Должно быть отмечено, что это вообще плохая идея следовать подсказке G_VALUE_NOCOPY_CONTENTS для подсчёта типовых ссылок. Из-за повторно используемого запроса и условия подсчёта ссылок с помощью кода GSignal, подсчёт ссылок должен всегда увеличиваться подсчёта ссылок содержимого хранящегося в массиве value->data. На мгновение отклонимся от нашего примера строки, и рассмотрим экземпляр реализации для collect_value() с ""
{ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */ value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); }Подсчёт ссылок для допустимых объектов всегда увеличивается, независимо от collect_flags . Для недопустимых объектов, пример
возвращает вновь распределённую строку без изменения value .
После успешного выполнения, collect_value() должен вернуть
NULL .
Однако если произошла ошибка, collect_value() может выдать ошибку
возвращая вновь распределённую
не-NULL строку,
дав подходящее описание произошедшей ошибки.
Вызываемый код не пытается определить допустимость содержимого value
при возвращении ошибки, value
просто выбрасывается без дальнейшего освобождения. Так же, это хороший метод не распределять содержимое
GValue, до возвращения ошибки,
однако, collect_values() не обязана возвращать правильно установленное
value для возврата ошибки, просто потому что любое
не-NULL
возвращение рассматривается как фатальное условие поэтому дальнейшее поведение программы не определено.
|
||||||||
gchar *lcopy_format ; |
Формат описывающий аргументы накопленные для lcopy_value ,
аналогичен collect_format . Обычно,
строка lcopy_format состоит только из 'p' для обеспечения
lcopy_value() указателями на сохраняемые расположения.
|
||||||||
lcopy_value () |
Эта функция отвечает за сохранение содержимого value в параметрах
помещаемых через список переменных параметров которые накоплены в collect_values
согласно lcopy_format .
n_collect_values равен длине строки
lcopy_format , а collect_flags
может содержать G_VALUE_NOCOPY_CONTENTS.
В отличие от collect_value() , lcopy_value() обязан всегда
должным образом поддерживать G_VALUE_NOCOPY_CONTENTS.
Подобно collect_value() функция может прерываться преждевременно
возвращая вновь распределённую строку описывающую произошедшую ошибку.
Завершаем пример строки:
{ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); }И демонстрационная версия lcopy_value() для подсчёта ссылок типов:
{ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; } |
#define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
Возвращает идентификатор типа из полученной сструктуры instance
.
Этот макрос должен использоваться только при реализации типа.
instance : |
Расположение допустимой сструктуры GTypeInstance. |
#define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type)
Возвращает идентификатор из полученной сструктуры class
.
Этот макрос должен использоваться только при реализации типа.
g_class : |
Расположение допустимой сструктуры GTypeClass. |
#define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type)
Возвращает идентификатор из полученной сструктуры interface
.
Этот макрос должен использоваться только при реализации типа.
g_iface : |
Расположение допустимой сструктуры GTypeInterface. |
#define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), (g_type), c_type))
Возвращает структуру класса полученного instance
, приводя к указанному типу предка
экземпляра g_type
.
Помните что в течение вызова
GInstanceInitFunc()
,
указатель класса изменяется, поэтому может не всегда возвращаться ожидаемый указатель.
Этот макрос должен использоваться только при реализации типа.
instance : |
Расположение сструктуры GTypeInstance. |
g_type : |
Тип возвращаемого родительского класса. |
c_type : |
C тип соответствующий g_type .
|
#define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
Возвращает структуру интерфейса для интерфейса g_type
полученного instance
.
Этот макрос должен использоваться только для реализации типа.
instance : |
Расположение сструктуры GTypeInstance. |
g_type : |
Возвращаемые интерфейсный тип. |
c_type : |
C тип соответствующий g_type .
|
#define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type)))
Выдаёт закрытую структуру для определённого типа.
Закрытая структура должна быть зарегистрирована в функции class_init с помощью
g_type_class_add_private()
.
Этот макрос должен использоваться только при реализации типа.
instance : |
экземпляр типа наследующий private_type .
|
g_type : |
идентификатор типа который определяется с помощью закрытых данных. |
c_type : |
C тип для закрытой сструктуры. |
Начиная с версии 2.4
#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
Возвращает TRUE
если instance
является допустимой структурой
GTypeInstance,
иначе издаёт предупреждение и возвращает FALSE
.
Этот макрос должен использоваться только при реализации типа.
instance : |
Расположение сструктуры GTypeInstance. |
#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
Проверяет является ли instance
экземпляром типа идентифицируемым
g_type
и издаёт предупреждение если это не так. Возвращает instance
приведённый
к указателю c_type
.
Этот макрос должен использоваться только при реализации типа.
instance : |
Расположение сструктуры GTypeInstance. |
g_type : |
возвращаемый тип. |
c_type : |
C тип соответствующий g_type .
|
#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
Возвращает TRUE
если instance
является экземпляром типа идентифицируемым
g_type
.
Иначе издаёт предупреждение и возвращает FALSE
.
Этот макрос должен использоваться только при реализации типа.
instance : |
Расположение сструктуры GTypeInstance. |
g_type : |
Проверяемый тип |
#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
Проверяет является ли g_class
классовой структурой типа идентифицируемого
g_type
и издаёт предупреждение если это не так. Возвращает g_class
приведённый
к указателю c_type
.
Этот макрос должен использоваться только при реализации типа.
g_class : |
Расположение сструктуры GTypeClass. |
g_type : |
Возвращаемый тип. |
c_type : |
C тип соответствующий g_type .
|
#define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type)))
Возвращает TRUE
если g_class
является классовой структурой типа идентифицируемого с помощью
g_type
. Иначе издаёт предупреждение и возвращает
FALSE
.
Этот макрос должен использоваться только при реализации типа.
g_class : |
Расположение сструктуры GTypeClass. |
g_type : |
Проверяемый тип. |
#define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value)))
Возвращает TRUE
если value
инициализировано типовым значением.
Этот макрос должен использоваться только при реализации типа.
value : |
GValue |
#define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type)))
Возвращает TRUE
если value
инициализировано значением типа g_type
.
Этот макрос должен использоваться только при реализации типа.
value : |
GValue |
g_type : |
Проверяемый тип. |
#define G_TYPE_FLAG_RESERVED_ID_BIT ((GType) (1 << 0))
Бит в числе типа который должен быть нетронутым.
void g_type_init (void);
Перед любым использованием системы типов, вызывается
g_type_init()
для инициализации системы типов и сортировки других частей кода
(таких как различные реализации базовых типов или системы сигналов).
typedef enum /*< skip >*/ { G_TYPE_DEBUG_NONE = 0, G_TYPE_DEBUG_OBJECTS = 1 << 0, G_TYPE_DEBUG_SIGNALS = 1 << 1, G_TYPE_DEBUG_MASK = 0x03 } GTypeDebugFlags;
Перечисление значений GTypeDebugFlags может помещаться в
g_type_init_with_debug_flags()
для переключения отладочных сообщений в процессе выполнения.
Помните что сообщения могут также переключаться с помощью установки переменной окружения
GOBJECT_DEBUG
в список разделённых между собой символом ':'
"objects" и "signals".
void g_type_init_with_debug_flags (GTypeDebugFlags debug_flags);
Подобна g_type_init()
,
но дополнительно устанавливает отладочные флаги.
debug_flags : |
Поразрядная комбинация значений GTypeDebugFlags для отладки. |
const gchar* g_type_name (GType type);
Возвращает уникальное имя которое назначено типу ID (это привилегированный метод определения был ли определённый тип зарегистрирован для помещённого ID).
type : |
Тип для которого возвращается имя. |
Возвращает : | Статичное имя типа или NULL .
|
GQuark g_type_qname (GType type);
Возвращает соответствующий кварк названия типа ID.
type : |
тип для которого возвращается кварк. |
Возвращает : | Кварк имени типа или 0. |
GType g_type_from_name (const gchar *name);
Находит типовой ID из полученного имени типа, возвращает 0 если нет зарегистрированного типа с данным именем (это привилегированный метод определения по имени был ли зарегистрирован тип).
name : |
Имя типа для поиска. |
Возвращает : | Соответствующий типу ID или 0. |
GType g_type_parent (GType type);
Возвращает прямого родителя типа переданного в типе. Если тип не имеет помещённого в него родителя, то есть это базовый тип, возвращается 0.
type : |
Производный тип. |
Возвращает : | Родительский тип. |
guint g_type_depth (GType type);
Возвращает длину родословной помещенной в тип. Это включает сам тип непосредственно, поэтому базовые типы имеют глубину 1.
type : |
значение GType. |
Возвращает : | Глубина родословной type .
|
GType g_type_next_base (GType leaf_type, GType root_type);
Получает leaf_type
и root_type
который содержится в его родителе, возвращает тип непосредственно родителя root_type
.
Другими словами, эта функция определяет тип который получен непосредственно из root_type
,
который является также базовым классом leaf_type
. Учитывая корневой тип и тип ответвления,
эта функция может использоваться для определения типов и порядка в котором тип ответвления появляется из корневого типа.
leaf_type : |
Потомок root_type и возвращаемый тип.
|
root_type : |
Непосредственный родитель возвращаемого типа. |
Возвращает : | Непосредственный ребёнок root_type и родитель leaf_type .
|
gboolean g_type_is_a (GType type, GType is_a_type);
Если is_a_type
является производным типом, проверяет является ли
type
потомком is_a_type
.
Если is_a_type
является интерфейсом, проверяет соответствует ли он
type
.
type : |
Тип для проверки родословной. |
is_a_type : |
Возможный родитель type или интерфейс соответствующий type .
|
Возвращает : | TRUE
если type содержит is_a_type .
|
gpointer g_type_class_ref (GType type);
Увеличивает количество ссылок классовой сструктуры принадлежащей type
.
Эта функция создаст запрашиваемый класс если он ещё не существует.
type : |
Типовой ID классифицируемого типа. |
Возвращает : | Структуру GTypeClass для полученного типового ID. |
gpointer g_type_class_peek (GType type);
Эта функция такая же как g_type_class_ref()
,
только количество ссылок уменьшается. Как следствие, эта функция может вернуть
NULL
если помещённый в неё классовый тип
в данный момент не существует (не имеет ссылок).
type : |
Типовой ID классифицируемого типа. |
Возвращает : | Структура GTypeClass для полученного типового ID
или NULL
если класс в данный момент не существует.
|
gpointer g_type_class_peek_static (GType type);
Более эффективная версия g_type_class_peek()
которая работает только для статических типов.
type : |
Типовой ID классифицируемого типа. |
Возвращает : | Структура GTypeClass
для полученного типового ID или NULL
если класс не существует в данный момент или загружается динамически.
|
Начиная с версии 2.4
void g_type_class_unref (gpointer g_class);
Уменьшает количество ссылок помещённой сструктуры класса.
Как только последняя ссылка была освобождена, класс может финализироваться системой типов, поэтому дальнейшее разыменование
указателя класса после g_type_class_unref()
невозможно.
g_class : |
Структура GTypeClass для сброса ссылки. |
gpointer g_type_class_peek_parent (gpointer g_class);
Эта удобная функция часто необходима при инициализации класса. Она возвращает структуру класса непосредственно родительского типа помещенного класса. Так как производные классы содержат количество ссылок их родительских классов пока они инстанциирубтся, возвращаемый класс будет всегда существовать. Эта функция очень похожа на:
g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
g_class : |
Структура GTypeClass для определения родительского класса. |
Возвращает : | Родительский класс g_class .
|
void g_type_class_add_private (gpointer g_class, gsize private_size);
Регистрирует закрытую структуру для инстанциируемого типа;
когда объект распределён, закрытая структура типа и все родительские типы
распределяются последовательно в тот же блок памяти что и общие сструктуры.
Эта функция должна вызываться в типовой функции
class_init()
.
Закрытая структура может быть найдена используя макрос
G_TYPE_INSTANCE_GET_PRIVATE()
.
В следующем примере показано прикрепление закрытой сструктуры MyObjectPrivate к объекту
MyObject определённому в стандартном стиле GObject.
typedef struct _MyObjectPrivate MyObjectPrivate; struct _MyObjectPrivate { int some_field; }; #define MY_OBJECT_GET_PRIVATE(o) \ (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate)) static void my_object_class_init (MyObjectClass *klass) { g_type_class_add_private (klass, sizeof (MyObjectPrivate)); } static int my_object_get_some_field (MyObject *my_object) { MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object); return priv->some_field; }
g_class : |
классовая структура для инстанциируемого типа |
private_size : |
размер закрытой сструктуры. |
Начиная с версии 2.4
gpointer g_type_interface_peek (gpointer instance_class, GType iface_type);
Возвращает структуру GTypeInterface интерфейса которому соответствует помещённый класс.
instance_class : |
Структура GTypeClass. |
iface_type : |
ID интерфейса которому соответствует этот класс. |
Возвращает : | Структуру GTypeInterface интерфейса iface_type если реализован с помощью instance_class ,
иначе NULL .
|
gpointer g_type_interface_peek_parent (gpointer g_iface);
Возвращает структуру GTypeInterface
соответствующего родительского типа типового экземпляра которому принадлежит g_iface
.
Это полезно когда наследуется реализация интерфейса из родительского типа и возможно отменяются некоторые методы.
g_iface : |
Структура GTypeInterface. |
Возвращает : | Соответствующую структуру GTypeInterface
родительского типа типового экземпляра к которому принадлежит g_iface ,
или NULL если родительский тип
не соответствует интерфейсу.
|
gpointer g_type_default_interface_ref (GType g_type);
Увеличивает количество ссылок для интерфейсного типа g_type
,
и возвращает значение по умолчанию интерфейс vtable для типа.
Если тип в текущий момент не используется, то значение по умолчанию vtable
для типа будет создано и инициализировано вызовом инициализации основного типа
и функций инициализации значения по умолчанию vtable для типа (@base_init
и class_init
члены GTypeInfo).
Вызов g_type_default_interface_ref()
полезен когда вам нужно убедиться что сигналы и свойства для интерфейса были установлены.
g_type : |
интерфейсный тип |
Возвращает : | значение по умолчанию vtable для интерфейса; вызовите
g_type_default_interface_unref()
после использования интерфейса.
|
Начиная с версии 2.4
gpointer g_type_default_interface_peek (GType g_type);
Если интерфейсный тип g_type
в текущий момент используется,
возвращает значение по умолчанию vtable интерфейса.
g_type : |
интерфейсный тип |
Возвращает : | значение по умолчанию vtable для интерфейса, или
NULL
если тип в текущий момент не используется.
|
Начиная с версии 2.4
void g_type_default_interface_unref (gpointer g_iface);
Уменьшает количество ссылок для типа соответствующего значению по умолчанию vtable интерфейса
g_iface
. Если тип динамический, то когда ни кто не использует
интерфейс и все ссылки сброшены, будет вызвана функция финализации для значения по умолчанию vtable интерфейса
(class_finalize
член GTypeInfo).
g_iface : |
значение по умолчанию сструктуры vtable для интерфейса, которую возвращает
g_type_default_interface_ref()
|
Начиная с версии 2.4
GType* g_type_children (GType type, guint *n_children);
Возвращает вновь распределенный и 0-завершённый массив типа ID, записывая в список дочерние типы
type
. Возвращаемое значение должно быть освобождено с помощью
g_free()
после использования.
type : |
Родительский тип. |
n_children : |
Опционально guint указатель на содержащий количество дочерних типов. |
Возвращает : | Вновь распределённый и 0-завершённый массив дочерних типов. |
GType* g_type_interfaces (GType type, guint *n_interfaces);
Возвращает вновь распределённый и 0-завершённый массив типа ID, записывая в список интерфейсные типы которым соответствует этот
type
. Возвращаемое значение должно быть освобождено с помощью
g_free()
после использования.
type : |
Тип для списка интерфейсных типов. |
n_interfaces : |
Опционально guint указатель содержащий количество интерфейсных типов. |
Возвращает : | Вновь распределённый и 0-завершённый массив интерфейсных типов. |
GType* g_type_interface_prerequisites (GType interface_type, guint *n_prerequisites);
Возвращает предпосылки интерфейсного типа.
interface_type : |
тип интерфейса |
n_prerequisites : |
расположение для возвращаемого количества предпосылок, или
NULL
|
Возвращает : | вновь распределённый 0-завершённый массив GType
содержащий предпосылки interface_type
|
Начиная с версии 2.2
void g_type_set_qdata (GType type, GQuark quark, gpointer data);
Прикрепляет произвольные данные к типу.
gpointer g_type_get_qdata (GType type, GQuark quark);
Возвращает данные предварительно прикреплённые к type
с помощью g_type_set_qdata()
.
void g_type_query (GType type, GTypeQuery *query);
Запрашивает у системы типов информацию об определённом типе.
Эта функция заполняет определённую пользователем структуру типовой информацией.
Если помещен неверный GType,
type
член GTypeQuery
равен 0. Все члены заполненные в структуре GTypeQuery
должны рассматриваться как константы и не должны изменяться.
type : |
GType значение статичного, классифицированного типа. |
query : |
Обеспеченная пользователем структура которая заполняется константными значениями в случае успешного выполнения. |
typedef struct { GType type; const gchar *type_name; guint class_size; guint instance_size; } GTypeQuery;
Структура содержащая информацию для определённого типа. Она заполняется функцией
g_type_query()
.
void (*GBaseInitFunc) (gpointer g_class);
Это callback-функция используемая системой типов для основной инициализации
классовых структур производных типов. Она вызывается как часть процесса
инициализации всех производных классов и должна перераспределить или сбросить
все динамические члены класса скопированные из родительского класса.
Например, члены класса (такие как строки) которые не достаточно обработать простым
копированием памяти родительского класса в производный класс, должны быть изменены.
Смотрите GClassInitFunc()
для обсуждения процесса инициализации классов.
g_class : |
Структура GTypeClass для инициализации. |
void (*GBaseFinalizeFunc) (gpointer g_class);
Это callback-функция используемая системой типов для финализации тех частей сструктуры класса производного типа
которые были установлены из соответствующей функции
GBaseInitFunc()
.
Финализация класса в основном работает в обратном порядке относительно процесса инициализации класса.
Смотрите GClassInitFunc()
для обсуждения процесса инициализации класса.
g_class : |
Структура GTypeClass для финализации. |
void (*GClassInitFunc) (gpointer g_class, gpointer class_data);
Это callback-функция используемая системой типов для инициализации класса определённого типа. Она должна инициализировать все статичные члены класса. Процесс инициализации класса включает:
1 - Копирование основных членов из родительского класса в структуру класса наследника. |
|
2 - Инициализация нулём оставшихся членов не скопированных из родительского класса. |
|
3 - Запрос |
|
4 - Запрос инициализатора класса |
Так как производные классы частично инициализируются через копирование памяти
родительского класса, основное правило в том, что
GBaseInitFunc()
и
GBaseFinalizeFunc()
должны заботится о необходимой переинициализации и высвобождении тех членов класса которые были введены типом
определившим эти GBaseInitFunc()
/GBaseFinalizeFunc()
.
GClassInitFunc()
должна заботиться только об инициализации статичных членов класса, в то время как динамические члены класса
(такие как распределённые строки или ресурсы подсчёта ссылок) лучше обрабатывать с помощью
GBaseInitFunc()
для данного типа, таким образом надлежащая инициализация динамических членов класса также выполняется для инициализации
классов производных типов.
Пример может помочь понять предназначение разных инициализаторов класса:
typedef struct { GObjectClass parent_class; gint static_integer; gchar *dynamic_string; } TypeAClass; static void type_a_base_class_init (TypeAClass *class) { class->dynamic_string = g_strdup ("some string"); } static void type_a_base_class_finalize (TypeAClass *class) { g_free (class->dynamic_string); } static void type_a_class_init (TypeAClass *class) { class->static_integer = 42; } typedef struct { TypeAClass parent_class; gfloat static_float; GString *dynamic_gstring; } TypeBClass; static void type_b_base_class_init (TypeBClass *class) { class->dynamic_gstring = g_string_new ("some other string"); } static void type_b_base_class_finalize (TypeBClass *class) { g_string_free (class->dynamic_gstring); } static void type_b_class_init (TypeBClass *class) { class->static_float = 3.14159265358979323846; }
Инициализация TypeBClass сначала вызовет инициализацию TypeAClass (производные классы ссылаются на их родительские классы, смотрите
g_type_class_ref()
).
Инициализация TypeAClass инициализирует нулями свои поля,
зтем вызовет свою GBaseInitFunc()
type_a_base_class_init()
для распределения своих динамических членов (dynamic_string),
и наконец вызовет свою GClassInitFunc()
type_a_class_init()
для инициализации статических членов (static_integer).
Первым шагом в процессе инициализации TypeBClass является прямое копирование памяти содержащей TypeAClass в TypeBClass
и инициализация нулями оставшихся полей в TypeBClass.
Динамические члены TypeAClass внутри TypeBClass теперь необходимо переинициализировать выполнив вызов
type_a_base_class_init()
с параметром TypeBClass.
После GBaseInitFunc()
из TypeBClass,
вызывается type_b_base_class_init()
для распределения динамических членов TypeBClass (dynamic_gstring),
и наконец GClassInitFunc()
из TypeBClass,
вызывается type_b_class_init()
для завершения процесса инициализации со статическими членами (static_float).
Соответствующее количество частей финализации для
GBaseInitFunc()
функций обеспечивают освобождение распределённых ресурсов во время финализации класса.
g_class : |
Структура GTypeClass для инициализации. |
class_data : |
Член class_data поставляемый через структуру
GTypeInfo.
|
void (*GClassFinalizeFunc) (gpointer g_class, gpointer class_data);
Это callback-функция используемая системой типов для финализации класса.
Она редко нужна, так как динамически распределяемые ресурсы классов должны обрабатываться с помощью
GBaseInitFunc()
и
GBaseFinalizeFunc()
.
Кроме того, спецификация GClassFinalizeFunc()
в структуре GTypeInfo статических типов недоступна,
потому что классы статических типов никогда не финализируются (они искусственно поддерживаются когда количество их ссылок достигает нуля).
g_class : |
Структура GTypeClass для финализации. |
class_data : |
Член class_data поставляемый через структуру
GTypeInfo.
|
void (*GInstanceInitFunc) (GTypeInstance *instance, gpointer g_class);
Это callback-функция используемая системой типов для инициализации нового экземпляра типа. Эта функция инициализирует все члены экземпляра и распределяет все ресурсы запрашиваемые ими. Инициализация производного экземпляра включает вызов всех инициализаторов экземпляров его родительских типов, поэтому член класса экземпляра изменяется в течение его инициализации чтобы всегда указывать на класс к которому принадлежит тип введённый в текущий инициализатор.
instance : |
Инициализируемый экземпляр. |
g_class : |
Класс создаваемого типового экземпляра. |
void (*GInterfaceInitFunc) (gpointer g_iface, gpointer iface_data);
Это callback-функция используемая системой типов для инициализации нового интерфейса. Эта функция должна инициализировать все внутренние данные и распределять любые ресурсы запрошенные интерфейсом.
g_iface : |
Структура для инициализации интерфейса. |
iface_data : |
class_data поставляемый через структуру
GTypeInfo.
|
void (*GInterfaceFinalizeFunc) (gpointer g_iface, gpointer iface_data);
Это callback-функция используемая системой типов для финализации интерфейса.
Эта функция должна уничтожать любые внутренние данные и освобождать любые ресурсы распределённые соответствующей функцией
GInterfaceInitFunc()
.
g_iface : |
Интерфейсная структура для финализации. |
iface_data : |
class_data поставляемый через структуру
GTypeInfo.
|
gboolean (*GTypeClassCacheFunc) (gpointer cache_data, GTypeClass *g_class);
Эта callback-функция вызывается когда количество ссылок класса сбрасывается к нулю.
Она может использовать g_type_class_ref()
чтобы предотвратить освобождение класса. Вы не должны вызывать
g_type_class_unref()
из функции
GTypeClassCacheFunc чтобы не допустить бесконечную
рекурсию, используйте вместо неё
g_type_class_unref_uncached()
.
Функции должны проверять id класса является ли он фактически кэшируеммым классом данного типа, так как все классы проходят через туже цепочку GTypeClassCacheFunc.
cache_data : |
данные помещаемые в вызов
g_type_add_class_cache_func()
|
g_class : |
Структура GTypeClass на которую нет ссылок |
Возвращает : |
TRUE для прекращения последующих вызовов
GTypeClassCacheFunc,
FALSE для продолжения.
|
typedef enum /*< skip >*/ { G_TYPE_FLAG_ABSTRACT = (1 << 4), G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5) } GTypeFlags;
Битовая маска для контроля характеристик типа.
G_TYPE_FLAG_ABSTRACT |
Указывает абстрактный тип. Экземпляры не могут быть созданы для абстрактного типа. |
G_TYPE_FLAG_VALUE_ABSTRACT |
Указывает значение абстрактного типа, то есть тип который введён в таблицу значений,
но не может использоваться для g_value_init() .
|
typedef enum /*< skip >*/ { G_TYPE_FLAG_CLASSED = (1 << 0), G_TYPE_FLAG_INSTANTIATABLE = (1 << 1), G_TYPE_FLAG_DERIVABLE = (1 << 2), G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3) } GTypeFundamentalFlags;
Битовая маска используемая для контроля специфичных характеристик базового типа.
GType g_type_register_static (GType parent_type, const gchar *type_name, const GTypeInfo *info, GTypeFlags flags);
Регистрирует type_name
как имя нового статичного типа унаследовавшего
parent_type
. Система типов использует информацию содержащуюся в структуре
GTypeInfo указанной параметром
info
для управления типом и его экземплярами (если не абстрактный).
Значение flags
определяет природу типа (например абстрактный или нет).
parent_type : |
Предок производного типа. |
type_name : |
0-завершённая строка используемая как имя нового типа. |
info : |
Структура GTypeInfo для данного типа. |
flags : |
Побитная комбинация значений GTypeFlags. |
Возвращает : | Новый идентификатор типа. |
GType g_type_register_static_simple (GType parent_type, const gchar *type_name, guint class_size, GClassInitFunc class_init, guint instance_size, GInstanceInitFunc instance_init, GTypeFlags flags);
Регистрирует type_name
как имя нового статичного типа унаследовавшего
parent_type
. Значение flags
определяет природу типа
(например абстрактный или нет). Она заполняет GTypeInfo
структуру и вызывает g_type_register_static()
.
parent_type : |
Тип который является предком производного типа. |
type_name : |
0-завершённая строка используемая как имя нового типа. |
class_size : |
Размер сструктуры класса (смотрите GTypeInfo) |
class_init : |
Расположение функции инициализации класса (смотрите GTypeInfo) |
instance_size : |
Размер сструктуры экземпляра (смотрите GTypeInfo) |
instance_init : |
Расположение функции инициализации экземпляра (смотрите GTypeInfo) |
flags : |
Побитная комбинация значений GTypeFlags. |
Возвращает : | Идентификатор нового типа. |
Начиная с версии 2.12
GType g_type_register_dynamic (GType parent_type, const gchar *type_name, GTypePlugin *plugin, GTypeFlags flags);
Регистрирует type_name
как имя нового динамического типа унаследовавшего
parent_type
. Система типов использует информацию содержащуюся в структуре
GTypePlugin указанной параметром
plugin
для управления типом и его экземпляром (если не абстрактный).
Значение flags
определяет природу типа (например абстрактный или нет).
parent_type : |
Предок данного типа. |
type_name : |
0-завершённая строка используемая как имя нового типа. |
plugin : |
Структура GTypePlugin в которой находится GTypeInfo. |
flags : |
Побитовая комбинация значений GTypeFlags. |
Возвращает : | Идентификатор нового типа или G_TYPE_INVALID если регистрация не удалась. |
GType g_type_register_fundamental (GType type_id, const gchar *type_name, const GTypeInfo *info, const GTypeFundamentalInfo *finfo, GTypeFlags flags);
Регистрирует type_id
как предопределённый идентификатор, а
type_name
как имя базового типа. Система типов использует информацию содержащуюся в структуре
GTypeInfo указанной параметром
info
и в структуре
GTypeFundamentalInfo указанной параметром
finfo
для управления экземпляром типа. Значение flags
определяет дополнительные характеристики базового типа.
type_id : |
Предопределённое значение GTypeFundamentals. |
type_name : |
0-завершённая строка используемая как имя нового типа. |
info : |
Структура GTypeInfo данного типа. |
finfo : |
Структура GTypeFundamentalInfo для данного типа. |
flags : |
Побитная комбинация значений GTypeFlags. |
Возвращает : | Предопределённый идентификатор типа. |
void g_type_add_interface_static (GType instance_type, GType interface_type, const GInterfaceInfo *info);
Добавляет статический interface_type
к instantiable_type
.
Информация содержащаяся в структуре GTypeInterfaceInfo указанная параметром
info
используется для управления связью.
instance_type : |
Значение GType инстанциируемого типа. |
interface_type : |
GType значение интерфейсного типа. |
info : |
Структура GInterfaceInfo
для данной комбинации (instance_type , interface_type ).
|
void g_type_add_interface_dynamic (GType instance_type, GType interface_type, GTypePlugin *plugin);
Добавляет динамический interface_type
к instantiable_type
.
Информация содержащаяся в структуре GTypePlugin указанной
параметром plugin
используется для управления связью.
instance_type : |
GType значение инстанциируемого типа. |
interface_type : |
GType значение интерфейсного типа. |
plugin : |
GTypePlugin структура находящаяся в GInterfaceInfo. |
void g_type_interface_add_prerequisite (GType interface_type, GType prerequisite_type);
Добавляет prerequisite_type
в список предпосылок interface_type
.
Это значит что любая реализация типа interface_type
должна так же реализовать
prerequisite_type
. Предпосылки могут рассматриваться как альтернатива интерфейсного ответвления
(которые не поддерживает GType). Интерфейс может иметь один инстанциируемый тип предпосылки.
GTypePlugin* g_type_get_plugin (GType type);
Возвращает структуру GTypePlugin для
type
или
NULL
если
type
не имеет структуру GTypePlugin.
GTypePlugin* g_type_interface_get_plugin (GType instance_type, GType interface_type);
Возвращает структуру GTypePlugin для динамического интерфейса
interface_type
который был добавлен к instance_type
, или
NULL
если
interface_type
не добавлен к instance_type
или если не имеет
GTypePlugin структуру.
Смотрите g_type_add_interface_dynamic()
.
instance_type : |
GType значение инстанциируемого типа. |
interface_type : |
GType значение интерфейсного типа. |
Возвращает : | GTypePlugin для динамического интерфейса
interface_type принадлежащего instance_type .
|
GType g_type_fundamental_next (void);
Возвращает следующий свободный идентификатор базового типа который можно использовать для регистрации нового базового типа с помощью
g_type_register_fundamental()
.
Возвращаемый ID типа представляет наивысший регистрируемый идентификатор базового типа.
Возвращает : | Следующий за последним ID зарегистрированного базового типа, или 0 если система типов исчерпала идентификаторы базовых типов. |
GType g_type_fundamental (GType type_id);
Внутренняя функция, используется для извлечения части ID базового типа.
вместо неё используйте G_TYPE_FUNDAMENTAL()
.
type_id : |
допустимый ID типа |
Возвращает : | ID базового типа |
GTypeInstance* g_type_create_instance (GType type);
Создаёт инициализированный экземпляр type
если type
является допустимым и может быть инстанциирован. Система типов выполняет только основное распределение и установку сструктуры для экземпляра:
фактически экземпляр создаётся функциями поставляемыми реализацией базового типа.
Поэтому использование g_type_create_instance()
зарезервировано только для реализации базового типа. Например экземпляры иерархии
GObject должны создаваться через
g_object_new()
и
никогда не должны создаваться непосредственно через
g_type_create_instance()
которая
не обрабатывает такие вещи как единственный ребёнок объекта или конструкцию объекта.
Помните: Не используйте эту функцию, кроме как для реализации базового типа.
Также языковые привязки не должны использовать эту функцию, а использовать вместо неё
g_object_new()
.
type : |
Инстанциируемый тип для создания экземпляра. |
Возвращает : | Распределённый и инициализированный экземпляр, подвергается дальнейшей обработке реализацией базового типа. |
void g_type_free_instance (GTypeInstance *instance);
Освобождает экземпляр типа, возвращает его в пул экземпляров типа, если он есть.
Как g_type_create_instance()
,
эта функция зарезервирована для реализаций базовых типов.
instance : |
экземпляр типа. |
void g_type_add_class_cache_func (gpointer cache_data, GTypeClassCacheFunc cache_func);
Добавляет GTypeClassCacheFunc
которая будет вызвана перед сбросом количества ссылок класса в ноль.
Это может использоваться для предотвращения преждевременного разрушения класса.
Все установленные функции GTypeClassCacheFunc
будут скованы пока одна из них не вернёт TRUE
.
Функции должны контролировать помещаемый id класс, должна ли она фактически кэшировать класс этого типа, так как все классы направляются через
туже цепочку GTypeClassCacheFunc.
cache_data : |
данные помещаемые в cache_func
|
cache_func : |
GTypeClassCacheFunc |
void g_type_remove_class_cache_func (gpointer cache_data, GTypeClassCacheFunc cache_func);
Удаляет предварительно установленную GTypeClassCacheFunc.
Кэш содержащийся в cache_func
должен быть пустым когда вызывается
g_type_remove_class_cache_func()
чтобы избежать утечек.
cache_data : |
данные полученные при добавлении cache_func
|
cache_func : |
GTypeClassCacheFunc |
void g_type_class_unref_uncached (gpointer g_class);
Вариант g_type_class_unref()
для использования
в GTypeClassCacheFunc реализации.
Она отменяет ссылку на класс без контроля цепочки
GTypeClassCacheFunc,
избегая рекурсии которая моглабы иначе произойти.
g_class : |
Структура GTypeClass для отмены ссылок. |
void g_type_add_interface_check (gpointer check_data, GTypeInterfaceCheckFunc check_func);
Добавляет функцию вызываемую после инициализации vtable интерфейса для любого класса
(то есть после вызова interface_init
члена GInterfaceInfo).
Эта функция полезна когда вам нужно контролировать логическое выражение зависящее от интерфейсного класса. Например, реализация GObject использует это средство для контроля реализации объектом всех свойств которые определены его интерфейсом.
check_data : |
данные помещаемые в check_func
|
check_func : |
функция вызываемая после каждой инициализации интерфейса. |
Начиная с версии 2.4
void g_type_remove_interface_check (gpointer check_data, GTypeInterfaceCheckFunc check_func);
Удаляет интерфейсную функцию контроля добавленную с помощью
g_type_add_interface_check()
.
check_data : |
данные callback-функции помещаемые в
g_type_add_interface_check()
|
check_func : |
callback-функция помещаемая в
g_type_add_interface_check()
|
Начиная с версии 2.4
void (*GTypeInterfaceCheckFunc) (gpointer check_data, gpointer g_iface);
Эта callback-функция вызывается после инициализации vtable интерфейса.
Смотрите g_type_add_interface_check()
.
check_data : |
данные помещаемые в
g_type_add_interface_check() .
|
g_iface : |
инициализируемый интерфейс |
Начиная с версии 2.4
GTypeValueTable* g_type_value_table_peek (GType type);
Возвращает расположение GTypeValueTable
связанной с type
.
Помните что эта функция должна использоваться только из исходного кода который реализует или знает
внутреннюю реализацию type
.
type : |
GType значение. |
Возвращает : | Расположение GTypeValueTable связанной с
type или
NULL если нет
GTypeValueTable связанной с
type .
|
#define G_DEFINE_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
Удобный макрос для реализации типа, который декларирует функцию инициализации класса, функцию инициализации экземпляра
(смотрите GTypeInfo для информации об этом)
и статическую переменную с именем t_n
_parent_class указывающую на родительский класс.
Кроме того, он определяет функцию *_get_type()
. Смотрите G_DEFINE_TYPE_EXTENDED()
для примера.
TN : |
Имя нового типа, в верхнем регистре. |
t_n : |
Имя нового типа, в нижнем регистре, со словами разделёнными символом '_'. |
T_P : |
GType родительского типа. |
Начиная с версии 2.4
#define G_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, 0) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
Удобный макрос для реализации типа.
Похож на G_DEFINE_TYPE()
,
но позволяет вставить произвольный код в функцию *_get_type()
,
например реализовать интерфейс через G_IMPLEMENT_INTERFACE()
.
Смотрите G_DEFINE_TYPE_EXTENDED()
для примера.
TN : |
имя нового типа в верхнем регистре (in Camel case). |
t_n : |
имя нового типа в нижнем регистре, со словами разделёнными знаком '_'. |
T_P : |
GType родительского типа. |
_C_ : |
Произвольный код который вставляется в функцию *_get_type() .
|
Начиная с версии 2.4
#define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
Удобный макрос для реализации типа.
Похож на G_DEFINE_TYPE()
,
но определяет абстрактный тип.
Смотрите G_DEFINE_TYPE_EXTENDED()
для примера.
TN : |
имя нового типа в верхнем регистре (in Camel case). |
t_n : |
имя нового типа в нижнем регистре, со словами разделёнными знаком '_'. |
T_P : |
GType родительского типа. |
Начиная с версии 2.4
#define G_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
Удобный макрос для реализации типа.
Похож на G_DEFINE_TYPE_WITH_CODE()
,
определяет абстрактный тип и позволяет вставить произвольный код в функцию *_get_type()
,
например реализовать интерфейс через
G_IMPLEMENT_INTERFACE()
.
Смотрите G_DEFINE_TYPE_EXTENDED()
для примера.
TN : |
имя нового типа, в верхнем регистре (in Camel case). |
t_n : |
имя нового типа в нижнем регистре, со словами разделёнными символом '_'. |
T_P : |
GType родительского типа. |
_C_ : |
Произвольный код вставляемый в функцию @type_name_get_type() .
|
Начиная с версии 2.4
#define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init)
Удобный макрос для простого добавления интерфейса в _C_
раздел
G_DEFINE_TYPE_WITH_CODE()
или
G_DEFINE_ABSTRACT_TYPE_WITH_CODE()
.
Смотрите G_DEFINE_TYPE_EXTENDED()
для примера.
Помните что этот макрос может использоваться только вместе с G_DEFINE_TYPE_* макросами, так как он зависит от переменных имён из этих макросов.
TYPE_IFACE : |
GType добавляемого интерфейса |
iface_init : |
Функция инициализации интерфейса |
Начиная с версии 2.4
#define G_DEFINE_TYPE_EXTENDED(TN, t_n, T_P, _f_, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, _f_) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
Основной макрос для удобной реализации типа, на котором основан
G_DEFINE_TYPE()
, и так далее.
G_DEFINE_TYPE_EXTENDED (GtkGadget, gtk_gadget, GTK_TYPE_WIDGET, 0, G_IMPLEMENT_INTERFACE (TYPE_GIZMO, gtk_gadget_gizmo_init));разворачивается до
static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); static gpointer gtk_gadget_parent_class = NULL; static void gtk_gadget_class_intern_init (gpointer klass) { gtk_gadget_parent_class = g_type_class_peek_parent (klass); gtk_gadget_class_init ((GtkGadgetClass*) klass); } GType gtk_gadget_get_type (void) { static GType g_define_type_id = 0; if (G_UNLIKELY (g_define_type_id == 0)) { static const GTypeInfo g_define_type_info = { sizeof (GtkGadgetClass), (GBaseInitFunc) NULL, (GBaseFinalizeFunc) NULL, (GClassInitFunc) gtk_gadget_class_intern_init, (GClassFinalizeFunc) NULL, NULL, /* class_data */ sizeof (GtkGadget), 0, /* n_preallocs */ (GInstanceInitFunc) gtk_gadget_init, }; g_define_type_id = g_type_register_static (GTK_TYPE_WIDGET, "GtkGadget", &g_define_type_info, 0); { static const GInterfaceInfo g_implement_interface_info = { (GInterfaceInitFunc) gtk_gadget_gizmo_init }; g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); } } return g_define_type_id; }Единственные части определяемые вручную это сструктуры интерфейса и класса и определение функций инициализации экземпляра и класса.
TN : |
|
t_n : |
|
T_P : |
|
_f_ : |
|
_C_ : |
Начиная с версии 2.4
#define G_TYPE_INVALID G_TYPE_MAKE_FUNDAMENTAL (0)
Недопустимый GType используется как ошибочное значение которое возвращают некоторые функции возвращающие GType.
#define G_TYPE_NONE G_TYPE_MAKE_FUNDAMENTAL (1)
Базовый тип который используется как замена для возвращаемого типа C
void
.
#define G_TYPE_INTERFACE G_TYPE_MAKE_FUNDAMENTAL (2)
Базовый тип из который наследуют все интерфейсы.
#define G_TYPE_CHAR G_TYPE_MAKE_FUNDAMENTAL (3)
Базовый тип соответствующий gchar. Тип подписываемый с помощью G_TYPE_CHAR беззаговорочно 8-битное целочисленное со знаком. Это может быть или не может быть тем же C типом "gchar".
#define G_TYPE_BOOLEAN G_TYPE_MAKE_FUNDAMENTAL (5)
Базовый тип соответствующий gboolean.
#define G_TYPE_UINT64 G_TYPE_MAKE_FUNDAMENTAL (11)
Базовый тип соответствующий guint64.
#define G_TYPE_ENUM G_TYPE_MAKE_FUNDAMENTAL (12)
Базовый тип который наследуют все перечислимые типы.
#define G_TYPE_FLAGS G_TYPE_MAKE_FUNDAMENTAL (13)
Базовый тип который наследуют все флаговые типы.
#define G_TYPE_DOUBLE G_TYPE_MAKE_FUNDAMENTAL (15)
Базовый тип соответствующий gdouble.
#define G_TYPE_STRING G_TYPE_MAKE_FUNDAMENTAL (16)
Базовый тип соответствующий nul-завершённой C строке.
#define G_TYPE_POINTER G_TYPE_MAKE_FUNDAMENTAL (17)
Базовый тип соответствующий gpointer.
#define G_TYPE_BOXED G_TYPE_MAKE_FUNDAMENTAL (18)
Базовый тип который наследуют все boxed типы.
#define G_TYPE_PARAM G_TYPE_MAKE_FUNDAMENTAL (19)
Базовый тип который наследуют все GParamSpec типы.
#define G_TYPE_RESERVED_GLIB_FIRST (21)
Первый номер базового типа для создания идентификатора базового типа с помощью
G_TYPE_MAKE_FUNDAMENTAL()
зарезервированный для GLib.
#define G_TYPE_RESERVED_GLIB_LAST (31)
Последний номер базового типа зарезервированный для GLib.
#define G_TYPE_RESERVED_BSE_FIRST (32)
Первый номер базового типа для создания идентификатора базового типа с помощью
G_TYPE_MAKE_FUNDAMENTAL()
зарезервированный для BSE.
#define G_TYPE_RESERVED_BSE_LAST (48)
Последний номер базового типа зарезервированный для BSE.
#define G_TYPE_RESERVED_USER_FIRST (49)
Первый доступный номер базового типа для создания нового идентификатора базового типа с помощью
G_TYPE_MAKE_FUNDAMENTAL()
.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> GValueArray; GValue* g_value_array_get_nth (GValueArray *value_array, guint index_); GValueArray* g_value_array_new (guint n_prealloced); GValueArray* g_value_array_copy (const GValueArray *value_array); void g_value_array_free (GValueArray *value_array); GValueArray* g_value_array_append (GValueArray *value_array, const GValue *value); GValueArray* g_value_array_prepend (GValueArray *value_array, const GValue *value); GValueArray* g_value_array_insert (GValueArray *value_array, guint index_, const GValue *value); GValueArray* g_value_array_remove (GValueArray *value_array, guint index_); GValueArray* g_value_array_sort (GValueArray *value_array, GCompareFunc compare_func); GValueArray* g_value_array_sort_with_data (GValueArray *value_array, GCompareDataFunc compare_func, gpointer user_data);
Главная цель GValueArray - использование в качестве свойства
объекта которое содержит массив значений.
GValueArray является оболочкой массива элементов
GValue чтобы использовать как упаковочный тип через
G_TYPE_VALUE_ARRAY
.
typedef struct { guint n_values; GValue *values; } GValueArray;
GValueArray содержит массив элементов GValue.
GValue* g_value_array_get_nth (GValueArray *value_array, guint index_);
Возвращает указатель на значение index_
содержащееся в
value_array
.
value_array : |
GValueArray для получения значения |
index_ : |
номер интересуемого значения |
Возвращает : | указатель значения index_ в value_array
|
GValueArray* g_value_array_new (guint n_prealloced);
Распределяет и инициализирует новую GValueArray,
опционально резервирует пространство для n_prealloced
элементов.
Новый массив всегда содержит 0 элементов,
независимо от значения n_prealloced
.
n_prealloced : |
количество элементов для предварительного распределения |
Возвращает : | вновь распределённая GValueArray с 0 значением |
GValueArray* g_value_array_copy (const GValueArray *value_array);
Конструирует существующую копию GValueArray дублируя всё её содержимое.
value_array : |
GValueArray для копирования |
Возвращает : | Вновь распределённая копия GValueArray |
void g_value_array_free (GValueArray *value_array);
Освобождает GValueArray включая её содержимое.
value_array : |
GValueArray для освобождения |
GValueArray* g_value_array_append (GValueArray *value_array, const GValue *value);
Вставляет копию value
как последний элемент value_array
.
value_array : |
GValueArray в которую добавляется элемент |
value : |
GValue для копирования в GValueArray |
Возвращает : | GValueArray для размещённой
value_array
|
GValueArray* g_value_array_prepend (GValueArray *value_array, const GValue *value);
Вставляет копию value
как первый элемент value_array
.
value_array : |
GValueArray в которую добавляется элемент |
value : |
GValue для копирования в GValueArray |
Возвращает : | GValueArray для размещённой
value_array
|
GValueArray* g_value_array_insert (GValueArray *value_array, guint index_, const GValue *value);
Вставляет копию value
в определённую позицию value_array
.
value_array : |
GValueArray для добавления в неё элемента |
index_ : |
позиция вставки, должна быть <= value_array->n_values |
value : |
GValue для копирования в GValueArray |
Возвращает : | GValueArray для размещённой
value_array
|
GValueArray* g_value_array_remove (GValueArray *value_array, guint index_);
Удаляет значение в позиции index_
из value_array
.
value_array : |
GValueArray из которой удаляется элемент |
index_ : |
позиция значения для удаления, должна быть < value_array->n_values |
Возвращает : | GValueArray для
value_array
|
GValueArray* g_value_array_sort (GValueArray *value_array, GCompareFunc compare_func);
Сортирует value_array
используя compare_func
для сравнения элементов согласно семантике GCompareFunc.
Текущая реализация использует Quick-Sort как алгоритм сортировки.
value_array : |
GValueArray для сортировки |
compare_func : |
функция для сравнения элементов |
Возвращает : | GValueArray для размещенной
value_array
|
GValueArray* g_value_array_sort_with_data (GValueArray *value_array, GCompareDataFunc compare_func, gpointer user_data);
Сортирует value_array
используя compare_func
для сравнения элементов согласно семантике GCompareDataFunc.
Текущая реализация использует Quick-Sort алгоритм сортировки.
value_array : |
GValueArray для сортировки |
compare_func : |
функция для сравнения элементов |
user_data : |
дополнительные данные в качестве аргумента для compare_func
|
Возвращает : | GValueArray для размещенной
value_array
|
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|---|---|---|---|
#include <glib-object.h> #include <gobject/gvaluecollector.h> union GTypeCValue; #define G_VALUE_COLLECT (value, var_args, flags, __error) #define G_VALUE_LCOPY (value, var_args, flags, __error) #define G_VALUE_COLLECT_FORMAT_MAX_LENGTH
Макросы в этом разделе обеспечивают анализ varargs необходимый в функциях с переменным количеством аргументов (variadic) GObject
таких как g_object_new()
или
g_object_set()
.
Они в настоящее время поддерживают накопление целочисленных типов, типов с плавающей запятой и указателей.
union GTypeCValue { gint v_int; glong v_long; gint64 v_int64; gdouble v_double; gpointer v_pointer; };
Объединение содержащее одно из накапливаемых значений.
#define G_VALUE_COLLECT(value, var_args, flags, __error)
Накапливает значения переменных аргументов из va_list. Мы должны реализовать varargs накопление как макрос, потому что в некоторых системах переменные va_list нельзя помещать с помощью ссылки.
value : |
расположение возвращаемой GValue.
value должно быть инициализировано согласно накапливаемым типовым значениям
|
var_args : |
переменная va_list; может вычисляться многократно |
flags : |
флаги которые помещаются в функцию collect_value() таблицы
GTypeValueTable
принадлежащей к value .
|
__error : |
gchar** переменная которая
модифицируется для содержания g_new()
распределяя сообщение об ошибке при неудачном выполнении
|
#define G_VALUE_LCOPY(value, var_args, flags, __error)
Накапливает значения переменных аргументов из va_list.
value : |
расположение возвращаемой GValue.
value должно быть инициализировано согласно накапливаемым значениям типа
|
var_args : |
переменная va_list; может вычисляться многократно |
flags : |
флаги которые помещаются в функцию lcopy_value() таблицы
GTypeValueTable
принадлежащей к value .
|
__error : |
gchar** переменные которые модифицируются
для помещения g_new()
распределяя сообщение об ошибке если выполнение не удалось
|
#define G_VALUE_COLLECT_FORMAT_MAX_LENGTH (8)
Максимальное количество GTypeCValue которые могут быть накоплены для единственной GValue.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
API управления памятью для GObjects немного усложнен, но сама идея довольно проста: целью является обеспечить гибкую модель основанную на подсчете ссылок которая может интегрироваться в приложения использующие или требующие разных моделей управления памятью (такие как сборка мусора (garbage collection), aso...). Методы которые используются для манипулирования подсчётом ссылок описаны ниже.
/* Подсчёт ссылок */ gpointer g_object_ref (gpointer object); void g_object_unref (gpointer object); /* Слабые ссылки */ typedef 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 g_object_run_dispose (GObject *object);
Функции g_object_ref
/
g_object_unref
соответственно
увеличивают и уменьшают количество ссылок. Эти функции потоко-безопасны начиная с версии GLib 2.8.
Подсчёт ссылок, что не удивительно, инициализируется с помощью
g_object_new
которая означает
что вызывающая программа - текущий единственный владелец вновь созданной ссылки.
Когда количество ссылок достигло нуля, то есть когда
g_object_unref
вызвал последний клиент
содержащий ссылку на объект, вызываются dispose и
finalize методы класса.
Наконец, после вызова finalize, вызывается
g_type_free_instance
для освобождения
экземпляра объекта. В зависимости от политики распределения памяти при регистрации типа (через одну из функций
g_type_register_*
), объектный экземпляр памяти будет либо освобождён либо возвращён
в пул для этого типа. Как только объект освобождён, если он был последним экземпляром типа, типовой класс будет уничтожен
как описано в “Instantiable classed types: objects” и
“Non-instantiable classed types: Interfaces.”.
Таблица ниже резюмирует процесс уничтожения GObject:
Таблица 5. g_object_unref
Время вызова | Вызываемая функция | Параметры функции | Ремарка |
---|---|---|---|
Последний вызов g_object_unref для экземпляра целевого типа
|
Располагающая функция класса целевого типа | Экземпляр GObject | Когда расположение завершено, объект не должен содержать ссылки на любые другие члены объекта. Объект также, как ожидается, будет способен ответить на вызывающий метод клиента (возможно кодом ошибки но не нарушая память) в течение процесса завершения. Расположение может выполняться больше одного раза. Расположение должно привязываться к его родительской реализации как раз перед возвращением в вызывающую программу. |
функция завершения класса целевого типа | Экземпляр GObject | Финализация завершает процесс инициализированный расположением (dispose). Она завершает уничтожение объекта. Финализация выполняется только один раз. Финализация должна привязываться к её родительской реализации как раз перед возвратом в вызывающую программу. Причина разделения процесса уничтожения на две части объясняется в “Reference counts and cycles”. | |
Последний вызов g_object_unref для последнего экземпляра целевого типа
|
Интерфейсная функция interface_finalize | В интерфейсной vtable | Практически не используется. Маловероятно что вам это понадобится. |
Интерфейсная функция base_finalize | В интерфейсной vtable | Практически не используется. Маловероятно что вам это понадобится. | |
Функция class_finalize целевого типа | В структуре класса целевого типа | Практически не используется. Маловероятно что вам это понадобится. | |
Типовая функция base_finalize | В дереве иерархии классов из базового типа в целевой тип. base_init вызывается один раз для каждой сструктуры класса. | Практически не используется. Маловероятно что вам это понадобится. |
Слабые ссылки используются для контроля процесса финализации (finalization):
g_object_weak_ref
добавляет контрольный вызов который не содержит ссылок на объект, но который вызывается когда объект запускает свой
метод размещения. Так же, каждая слабая ссылка может быть вызвана более одного раза в течение финализации объекта
(так как размещение может выполняться больше одного раза в течение финализации объекта).
g_object_weak_unref
может использоваться для удаления контролирующего вызова из объекта.
Слабые ссылки так же используются для реализации
g_object_add_weak_pointer
и g_object_remove_weak_pointer
.
Эти функции добавляют слабые ссылки на объект, они используются для аннулирования указателя полученного пользователем
когда объект финализирован.
Заметьте: следующий раздел был написан благодаря James Henstridge. Я надеюсь что все ваши благодарности и проклятия будут адресованы непосредственно ему.
Модель управления памятью GObject была спроектирована для более лёгкой интеграции в существующий код используя "сборку мусора". Именно поэтому процесс уничтожения разделён на две фазы: первая фаза, выполняется в обработчике размещения и должна освободить все ссылки на другие объекты. Вторая фаза, выполняется обработчиком финализации и должна завершить процесс уничтожения объекта. Объектные методы должны быть способны выполняться без программных ошибок (то есть, без segfault :) между двумя фазами.
Эти два шага процесса уничтожения очень полезны для прекращения подсчёта ссылок в циклах.
В течение обнаружения циклов во внешнем коде, как только циклы обнаружены,
внешний код может вызвать g_object_dispose
которая
прекратит любые существующие циклы, так как она запустит обработчик размещения связанный с объектом
и таким образом освободит все ссылки на другие объекты.
Внимательные читатели возможно поняли одно из правил обработчика размещения которое мы заявили немного раньше:
обработчик размещения может быть вызван много раз. Предположим мы имеем цикличный подсчёт ссылок:
объект A ссылается на B который в свою очередь ссылается на объект A.
Предположим мы обнаружили цикл и нам необходимо уничтожить оба объекта. Один из способов сделать это - вызов
g_object_dispose
для одного из объектов.
Если объект A освободит все ссылки на другие объекты, значит он освободит ссылку на объект B. Если объект B не принадлежит ни кому, значит это его последняя ссылка что означает выполнение обработчика размещения объекта B, который в свою очередь освободит ссылку на объект A. Если это последняя ссылка A, запустится обработчик размещения A, который выполнится второй раз прежде чем будет вызван обработчик финализации A !
Пример выше, который может показаться немного замысловатым, действительно может произойти если ваш GObject обрабатывается языковой привязкой. Таким образом я предполагаю что правила описанные ранее для уничтожения объекта соблюдаются. Иначе, могут произойти Очень плохие вещи.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Одной из замечательных особенностей GObject является родной механизм установки/получения свойств для объекта.
Когда объект инстанциирован, объектный обработчик class_init должен использоваться для регистрации свойств объекта
с помощью g_object_class_install_property
(реализована в gobject.c
).
Лучший способ понять как работают свойства объекта - посмотреть реальный пример их использования:
/************************************************/ /* Реализация */ /************************************************/ enum { MAMAN_BAR_CONSTRUCT_NAME = 1, MAMAN_BAR_PAPA_NUMBER, }; static void maman_bar_instance_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = (MamanBar *)instance; } static void maman_bar_set_property (GObject *object, guint property_id, const GValue *value, GParamSpec *pspec) { MamanBar *self = (MamanBar *) object; switch (property_id) { case MAMAN_BAR_CONSTRUCT_NAME: { g_free (self->priv->name); self->priv->name = g_value_dup_string (value); g_print ("maman: %s\n",self->priv->name); } break; case MAMAN_BAR_PAPA_NUMBER: { self->priv->papa_number = g_value_get_uchar (value); g_print ("papa: %u\n",self->priv->papa_number); } break; default: /* We don't have any other property... */ G_OBJECT_WARN_INVALID_PROPERTY_ID(object,property_id,pspec); break; } } static void maman_bar_get_property (GObject *object, guint property_id, GValue *value, GParamSpec *pspec) { MamanBar *self = (MamanBar *) object; switch (property_id) { case MAMAN_BAR_CONSTRUCT_NAME: { g_value_set_string (value, self->priv->name); } break; case MAMAN_BAR_PAPA_NUMBER: { g_value_set_uchar (value, self->priv->papa_number); } break; default: /* We don't have any other property... */ G_OBJECT_WARN_INVALID_PROPERTY_ID(object,property_id,pspec); break; } } static void maman_bar_class_init (gpointer g_class, gpointer g_class_data) { GObjectClass *gobject_class = G_OBJECT_CLASS (g_class); MamanBarClass *klass = MAMAN_BAR_CLASS (g_class); GParamSpec *pspec; gobject_class->set_property = maman_bar_set_property; gobject_class->get_property = maman_bar_get_property; pspec = g_param_spec_string ("maman-name", "Maman construct prop", "Set maman's name", "no-name-set" /* default value */, G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE); g_object_class_install_property (gobject_class, MAMAN_BAR_CONSTRUCT_NAME, pspec); pspec = g_param_spec_uchar ("papa-number", "Number of current Papa", "Set/Get papa's number", 0 /* minimum value */, 10 /* maximum value */, 2 /* default value */, G_PARAM_READWRITE); g_object_class_install_property (gobject_class, MAMAN_BAR_PAPA_NUMBER, pspec); } /************************************************/ /* Использование */ /************************************************/ GObject *bar; GValue val = {0,}; bar = g_object_new (MAMAN_TYPE_SUBBAR, NULL); g_value_init (&val, G_TYPE_CHAR); g_value_set_char (&val, 11); g_object_set_property (G_OBJECT (bar), "papa-number", &val);
Код клиента продемонстрированный выше прост, но большинство вещей происходит скоытно:
g_object_set_property
убеждается что свойство с таким названием было зарегистрировано обработчиком class_init в данной области. Если это так, она вызывает
object_set_property
которая обходит иерархию класса, от основания большинства производных типов, до
вершины базового типа в поиске класса который зарегистрировал это свойство. Затем она пытается конвертировать обеспеченную
пользователем GValue в GValue чей тип связан с этим свойством.
Если пользователь обеспечил signed char GValue, как показано здесь, и если свойство объекта было зарегистрировано как unsigned int,
g_value_transform
попытается преобразовать
введённый signed char в unsigned int. Конечно успех преобразования зависит от возможностей преобразующей функции.
На практике, почти всегда будет соответствующее преобразование [6]
и преобразование будет перенесено если необходимо.
После преобразования, GValue утверждается с помощью
g_param_value_validate
которая проверяет
чтобы пользовательские данные сохранённые в GValue
соответствовали характеристикам определённым GParamSpec
свойства. Здесь, GParamSpec мы обеспечили в функции
class_init имеющей функцию проверки допустимости значений содержащихся в GValue, которые придерживаются минимальных и максимальных
границ GParamSpec. В примере выше, GValue клиента не
придерживается этих ограничений (оно установлено в 11, тогда как максимум равен 10). Поэтому функция
g_object_set_property
вернёт ошибку.
Если пользовательское GValue установлено в допустимое значение,
g_object_set_property
продолжит процесс вызова объектного метода класса set_property. В примере, так как наша реализация Foo отменяла этот метод,
код перейдёт в foo_set_property
найдя
GParamSpec
с param_id [7]
который был сохранён с помощью
g_object_class_install_property
.
Как только свойство было установлено объектным методом класса set_property, код возвращается в
g_object_set_property
которая вызывает g_object_notify_queue_thaw
. Эта функция убеждается что сигнал "notify"
произошёл в экземпляре объекта с изменённым свойством в качестве параметра, если уведомления не были заморожены
g_object_freeze_notify
.
g_object_thaw_notify
может использоваться для нового уведомления изменения свойства через сигнал "notify". Важно помнить что даже если
свойства изменены в то время как уведомление изменения свойств заморожено, сигнал "notify" издаётся один раз для каждого
из изменённых свойств, как только уведомление изменения свойства разморожено: ни одно изменение свойства не теряется для
сигнала "notify". Сигнал может быть отсрочен с помощью механизма заморозки уведомления.
Похоже на утомительную задачу устанавливать GValues каждый раз когда необходимо изменить свойство.
На практике, очень редко придётся это делать. Функции
g_object_set_property
и g_object_get_property
предназначены для использования языковыми привязками. Для приложений есть более простой способ и он описан далее.
Интересно отметить что g_object_set
и
g_object_set_valist
(vararg версия) могут использоваться для установки множества свойств одновременно. Код клиента показанный выше можно переписать
как:
MamanBar *foo; foo = /* */; g_object_set (G_OBJECT (foo), "papa-number", 2, "maman-name", "test", NULL);
Это оберегает нас от управления GValues который мы должны были обработать используя
g_object_set_property
.
Код выше переключает одну эмиссию сигнала уведомления для каждого изменяемого свойства.
Конечно, версия _get также доступна:
g_object_get
и g_object_get_valist
(vararg версия) могут использоваться для получения множества свойств сразу.
Эти функции высокого уровня имеют один недостаток - они не обеспечивают возвращаемый результат. Нужно обращать внимание на типы аргументов и диапазон их использования. Известный источник ошибок например помещение gfloat вместо gdouble и таким образом смещение всех последующих параметров на четыре байта. Также отсутствие завершающего NULL может привести к неожиданному поведению.
Внимательные читатели теперь понимают как работают
g_object_new
,
g_object_newv
и
g_object_new_valist
:
они анализируют количество пользовательских переменных и вызывают
g_object_set
для параметров только после полного проектирования объекта.
Естественно, сигнал "notify" издаётся для каждого установленного свойства.
[6] Это может быть не то что вам нужно, но это позволяет вам решать полагаться ли на эти преобразования.
[7] Должно быть отмечено, что используемый здесь param_id уникален для идентификации каждого GParamSpec внутри FooClass так что переключение используемое в методах установка и получение фактически работает. Конечно, эти локальные уникальные целочисленные - просто оптимизация: возможно было бы использовать набор условий if (strcmp (a, b) == 0) {} else if (strcmp (a, b) == 0) {}.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
gobject-querygobject-query — Отображает дерево типов |
gobject-query
froots [options...]
gobject-query
tree [options...]
gobject-query принимает принудительный аргумент который определяет нужна ли итерация через базовые типы или напечатать дерево типов.
froots |
итерация через базовые корни |
tree |
печать дерева типа |
-r type |
определить тип корня |
-n |
не опускаться по дереву типа |
-b string |
определяет строку отступа |
-i string |
определяет итерацию строки отступа |
-s number |
определяет межстрочный интервал |
-h , --help |
Напечатать короткую справку и выйти. |
-v , --version |
Напечатать версию и выйти. |
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Есть множество пользовательских соглашений которые необходимо соблюдать при создании новых типов экспортируемых в заголовочные файлы:
Используйте шаблон object_method
для имён функций:
для вызова метода с именем foo в экземпляре типового объекта bar, назовите его
bar_foo
.
Используйте префикс для избежания конфликтов пространства имён с другими проектами.
Если ваша библиотека (или приложение) имеет имя Maman,
[3]
префикс всех имён ваших функций должен быть maman_.
Например: maman_object_method
.
Создайте макрос с именем PREFIX_OBJECT_TYPE
который всегда
возвращает GType для связанного с ним типового объекта. Для объекта типа
Bar в библиотеке с префиксом maman,
используйте: MAMAN_BAR_TYPE
.
Обычно это так, хотя нет соглашения для реализации этого макроса используя либо глобальную статическую переменную
либо функцию с именем prefix_object_get_type
.
Мы будем следовать функциональному шаблону везде где это возможно в этом документе.
Создайте макрос с именем PREFIX_OBJECT (obj)
который возвращает
указатель типа PrefixObject. Этот макрос используется для обеспечения
статической безопасности типа выполняя приведение везде где это необходимо. Он так же обеспечивает
динамическую безопасность типа выполняя проверку во время выполнения. Возможно отключение динамического
контроля типа при выполнении сборки
(смотрите сборка glib).
Например, мы должны создать MAMAN_BAR (obj)
относительно предыдущего примера.
Если тип классифицирован, создайте макрос с именем
PREFIX_OBJECT_CLASS (klass)
. Этот макрос
строго эквивалентен предыдущему макросу приведения типов: он выполняет статическое приведение типа
с динамической проверкой соответствия структурного класса. Он, как ожидается, возвращает указатель
на типовую структуру класса PrefixObjectClass. Снова, пример:
MAMAN_BAR_CLASS
.
Создайте макрос с именем PREFIX_IS_BAR (obj)
: этот макрос должен возвращать
gboolean которая указывает соответствует ввод типу объекта BAR или нет.
Если тип классифицирован, создайте макрос с именем
PREFIX_IS_OBJECT_CLASS (klass)
, который, как и предыдущий, возвращает логическое
если введенный указатель класса соответствует классу типа OBJECT.
Если тип классифицирован, создайте макрос с именем
PREFIX_OBJECT_GET_CLASS (obj)
который возвращает указатель класса связанный с экземпляром полученного типа. Этот макрос используется
для обеспечения статической и динамической безопасности типа (также как предыдущие макросы приведения).
Реализация этих макросов является достаточно прямоленейной: большинство простых в использовании
макросов обеспечивает gtype.h
. Например использованные нами выше,
мы можем записать следующим простым кодом объявляющим макросы:
#define MAMAN_BAR_TYPE (maman_bar_get_type ()) #define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_BAR_TYPE, MamanBar)) #define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_BAR_TYPE, MamanBarClass)) #define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_BAR_TYPE)) #define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_BAR_TYPE)) #define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_BAR_TYPE, MamanBarClass))
Придерживайтесь имени klass
, поскольку class
зарегистрированное ключевое слово С++.
Следующий код демонстрирует как реализовать функцию maman_bar_get_type
:
GType maman_bar_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { /* You fill this structure. */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBarType", &info, 0); } return type; }
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Типы которые регистрируются с классом и объявляются инстанциированными очень похожи на объекты object. Хотя GObjects (детали в The GObject base class) самый известный тип инстанциированного классифицированного типа, другие виды подобных объектов используемых как основа иерархии наследования была внешней разработкой и они все основаны на базовых особенностях описанных ниже.
Например, код показанный ниже демонстрирует как вы должны регистрировать такие базовые типовые объекты в системе типов:
typedef struct { GObject parent; /* instance members */ int field_a; } MamanBar; typedef struct { GObjectClass parent; /* class members */ void (*do_action_public_virtual) (MamanBar *self, guint8 i); void (*do_action_public_pure_virtual) (MamanBar *self, guint8 i); } MamanBarClass; #define MAMAN_BAR_TYPE (maman_bar_get_type ()) GType maman_bar_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBarClass), NULL, /* base_init */ NULL, /* base_finalize */ (GClassInitFunc) foo_class_init, NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBar), 0, /* n_preallocs */ (GInstanceInitFunc) NULL /* instance_init */ }; type = g_type_register_static (G_TYPE_OBJECT, "BarType", &info, 0); } return type; }
После первого вызова maman_bar_get_type
, тип с именем
BarType будет зарегистрирован в системе типов как наследник
типа G_TYPE_OBJECT.
Каждый объект должен определяться двумя структурами: структурой класса и структурой объекта.
Все сструктуры класса должны содержать GTypeClass
в качестве первого члена. Все сструктуры объекта должны содержать структуру
GTypeInstance в качестве первого члена.
Декларация этих C типов, взята из gtype.h
, показана ниже:
struct _GTypeClass { GType g_type; }; struct _GTypeInstance { GTypeClass *g_class; };
Эти ограничения позволяют системе типов удостовериться в том, что каждый экземпляр объекта (идентифицируемый указателем на экземпляр объектной сструктуры) содержит в первом байте указатель на структура класса объекта.
Эти взаимоотношения лучше демонстрируются примером: давайте возьмём объект B который наследуется из объекта A:
/* A definitions */ typedef struct { GTypeInstance parent; int field_a; int field_b; } A; typedef struct { GTypeClass parent_class; void (*method_a) (void); void (*method_b) (void); } AClass; /* B definitions. */ typedef struct { A parent; int field_c; int field_d; } B; typedef struct { AClass parent_class; void (*method_c) (void); void (*method_d) (void); } BClass;
C стандартом принято что первое поле C сструктуры начинается в первом байте буфера используемого для содержания структурных полей в памяти. Это значит что первое поле экземпляра объекта B - это первое поле A's которое в свою очередь является первым полем GTypeInstance's которая в свою очередь является g_class, указанным в структуре класса B's.
Благодаря этим условиям, возможно определить тип каждого объекта выполнив:
B *b; b->parent.parent.g_class->g_type
или, намного быстрее:
B *b; ((GTypeInstance*)b)->g_class->g_type
Инстанциирование этих типов может быть выполнено с помощью
g_type_create_instance
:
GTypeInstance* g_type_create_instance (GType type); void g_type_free_instance (GTypeInstance *instance);
g_type_create_instance
ищет информационную структуру типа связанную с запрошенным типом. Затем, размер экземпляра и инстанциируемую политику
(если поле n_preallocs установлено не в нулевое значение, система типов распределяет экземпляр сструктуры объекта в участок памяти
вместо распределения каждого экземпляра)
объявленную пользователем используемую для получения буфера содержащего экземпляр объектной сструктуры.
Если это первое инстанциирование создаваемого объекта, система типов должна создать структуру класса: это распределит буфер содержащий структуру объектного класса и инициализирует его. Сначала копируется родительская структура класса поверх этой сструктуры (если нет родителя, инициализируется нулём). Затем вызываются функции base_class_initialization (GBaseInitFunc) от самого высшего базового объекта до самого низшего объекта. Объектная функция class_init (GClassInitFunc) вызывается впоследствии, завершая инициализацию сструктуры класса. Наконец, инициализируется интерфейс объекта (позже мы обсудим инициализацию интерфейса более детально). [4]
Как только система типов получает указатель на инициализированную структуру класса, она устанавливает указатель экземпляра объектного класса в структуру объектного класса и вызывает объектные функции instance_init (GInstanceInitFunc), из самого высшего базового типа до самого низшего типа.
Уничтожается объект через
g_type_free_instance
очень просто:
экземпляр сструктуры возвращается в пул если существует, и если это был последний уничтоженный экземпляр объекта,
класс уничтожается.
Уничтожение класса [5] (понятие уничтожение иногда описывается как завершение (finalization) в GType) это симметричный процесс инициализации: интерфейсы уничтожаются первыми. Затем, вызывается функция class_finalize (ClassFinalizeFunc). Наконец вызываются функции base_class_finalize (GBaseFinalizeFunc) от самого низшего типа до самого высшего базового типа и структура класса освобождается.
Как многие читатели поняли, основы процесса инициализации/завершения очень похожи на парадигму C++ Constructor/Destructor. Практически различия в деталях, хотя это не важно при внешнем сходстве. Обычно, большинству пользователей достаточно знать что C++ constructor (то есть, список методов объекта вызывается в экземпляре объекта один раз для каждого типа иерархии наследования) не существует в GType и должны основываться на предлагаемых особенностях GType. Аналогично, GTypes не имеет механизма деструкции. Ответственность за правильную семантику уничтожения существующего кода GType, лежит на пользователе. (это то что делает GObject. Смотрите The GObject base class)
Например, если объект B который происходит из A инстанциирован, GType только вызовет instance_init объекта B, в то время как C++ окружение вызовет конструктор объекта A первым, а зтем типового объекта B. Кроме того, C++ код эквивалентный base_init и class_init callback-функциям GType обычно не необходим, потому что C++ не может создавать типовые объекты во время выполнения.
Процессс инстанциирования/завершения можно резюмировать следующим:
Таблица 1. GType Instantiation/Finalization
Время вызова | Вызываемая функция | Параметры функции |
---|---|---|
Первый вызов g_type_create_instance для целевого типа |
типовая функция base_init | В дереве наследования класса из базового типа для целевого типа. base_init вызывается один раз для каждой сструктуры класса. |
функция целевого типа class_init | В структуре класса целевого типа | |
инициализация интерфейса, смотрите раздел с названием “Interface Initialization” | ||
Каждый вызов g_type_create_instance для целевого типа |
функция instance_init целевого типа | В экземпляре объекта |
Последний вызов g_type_free_instance для целевого типа |
уничтожение интерфейса, смотрите раздел с названием “Interface Destruction” | |
функция class_finalize целевого типа | В структуре класса целевого типа | |
типовая функция base_finalize | В дереве наследования классов из базового типа в целевой тип. base_finalize вызывается один раз для каждой сструктуры класса. |
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Интерфейсы GType очень похожи на интерфейсы Java. Они позволяют описывать общий API которого будут придерживаться несколько классов. Представьте кнопки play, pause и stop в hifi-оборудовании - они могут рассматриваться как интерфейс воспроизведения. Как только вы поймёте что они значат, вы сможете управлять вашим cd-player, mp3-player или чем угодно использующим эти символы. Для объявления интерфейса вы должны зарегистрировать неинстанциируемый классифицируемый тип который происходит из GTypeInterface. Следующая часть кода объявляет такой интерфейс.
#define MAMAN_IBAZ_TYPE (maman_ibaz_get_type ()) #define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_IBAZ_TYPE, MamanIbaz)) #define MAMAN_IS_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_IBAZ_TYPE)) #define MAMAN_IBAZ_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), MAMAN_IBAZ_TYPE, MamanIbazInterface)) typedef struct _MamanIbaz MamanIbaz; /* dummy object */ typedef struct _MamanIbazInterface MamanIbazInterface; struct _MamanIbazInterface { GTypeInterface parent; void (*do_action) (MamanIbaz *self); }; GType maman_ibaz_get_type (void); void maman_ibaz_do_action (MamanIbaz *self);
Функция интерфейса, maman_ibaz_do_action
реализуется довольно простым способом:
void maman_ibaz_do_action (MamanIbaz *self) { MAMAN_IBAZ_GET_INTERFACE (self)->do_action (self); }
maman_ibaz_get_type
регистрирует тип с именем MamanIBaz
который наследует G_TYPE_INTERFACE. Все интерфейсы должны быть дочерними G_TYPE_INTERFACE в дереве иерархии.
Интерфейс определяется только одной структурой которая должна содержать структуру
GTypeInterface в качестве первого элемента.
Структура интерфейса, как ожидается, содержит указатели функции методов интерфейса. Это хороший стиль для определения
вспомогательных функций для каждого метода интерфейса который просто называют непосредственно методом интерфейса:
maman_ibaz_do_action
- один из них.
Как только интерфейсный тип зарегистрирован, вы должны зарегистрировать реализации для этих интерфейсов.
Функция с именем maman_baz_get_type
регистрируется как новый GType с именем MamanBaz
который наследует GObject и реализует
интерфейс MamanIBaz.
static void maman_baz_do_action (MamanIbaz *self) { g_print ("Baz implementation of IBaz interface Action.\n"); } static void baz_interface_init (gpointer g_iface, gpointer iface_data) { MamanIbazInterface *iface = (MamanIbazInterface *)g_iface; iface->do_action = maman_baz_do_action; } GType maman_baz_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBazInterface), NULL, /* base_init */ NULL, /* base_finalize */ NULL, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBaz), 0, /* n_preallocs */ NULL /* instance_init */ }; static const GInterfaceInfo ibaz_info = { (GInterfaceInitFunc) baz_interface_init, /* interface_init */ NULL, /* interface_finalize */ NULL /* interface_data */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBazType", &info, 0); g_type_add_interface_static (type, MAMAN_IBAZ_TYPE, &ibaz_info); } return type; }
g_type_add_interface_static
делает запись в систему типов что данный тип также реализует FooInterface
(foo_interface_get_type
возвращает тип FooInterface).
Структура GInterfaceInfo содержит информацию
о реализации интерфейса:
struct _GInterfaceInfo { GInterfaceInitFunc interface_init; GInterfaceFinalizeFunc interface_finalize; gpointer interface_data; };
Когда инстанциируемый классифицируемый тип регистрируемый при реализации интерфейса создаётся впервые,
его структура класса инициализируется процессом описанным в
раздел “Instantiable classed types: objects”. Как только структура класса инициализирована, функция
type_class_init_Wm
(реализована в gtype.c
)
инициализирует реализацию интерфейса связанного с этим типом вызывая type_iface_vtable_init_Wm
для каждого интерфейса.
Первый буфер памяти распределяется для содержания сструктуры интерфейса. Родительская структура интерфейса копируется поверх новой сструктуры интерфейса (родительский интерфейс уже инициализирован в этой точке). Если нет родителя интерфейса, структура интерфейса инициализируется нулями. Затем инициализируются поля g_type и g_instance_type: g_type устанавливается в значение типа наследуемого интерфейса, а g_instance_type устанавливается в значение типа который реализует этот интерфейс.
Наконец, интерфейс наследует функцию base_init
и зтем вызывается функция реализации
interface_init
. Важно понять, что если есть множество реализаций интерфейса, функции
base_init
и interface_init
будут вызваны один раз для каждой
инициализируемой реализиции.
Таким образом функции base_init обычно содержат локальную статическую логическую переменную которая гарантирует что тип интерфейса инициализирован только один раз, даже если есть множество реализаций интерфейса:
static void maman_ibaz_base_init (gpointer g_iface) { static gboolean initialized = FALSE; if (!initialized) { /* create interface signals here. */ initialized = TRUE; } }
Если вы находите материал об иерархии интерфейса непостежимым, вы правы: он непостежим, но я ничего не могу с этим сделать. Я могу только суммировать то что вы должны знать об интерфейсах:
Процессс описанный выше может быть резюмирован следующим:
Таблица 2. Инициализация интерфейса
Время вызова | Вызываемая функция | Параметры функции | Ремарка |
---|---|---|---|
Первый вызов g_type_create_instance для реализации типового интерфейса
|
Интерфейсная функция base_init | В интерфейсной vtable | Здесь регистрируются сигналы интерфейса (используйте локальную статическую логическую переменную как описано выше, чтобы исключить двойную регистрацию). |
Интерфейсная функция interface_init | В интерфейсной vtable | Инициализирует реализацию интерфейса. То есть, инициализирует указатели метода интерфейса в структуре интерфейса в функции реализации. |
Маловероятно (то есть: я не знаю никого кто использует это)
что вам потребуются другие более причудливые вещи которые описаны в следующем разделе
(раздел “Interface Destruction”).
Когда последний экземпляр инстанциированного типа, зарегистрированного реализацией интерфейса, уничтожен,
реализация интерфейса связанная с типом тоже уничтожается с помощью
type_iface_vtable_finalize_Wm
(в gtype.c
).
type_iface_vtable_finalize_Wm
вызывает сначала функцию реализации
interface_finalize
, а зтем функцию наивысшего наследуемого интерфейса
base_finalize
.
Снова, важно понять, как в
разделе “Interface Initialization”,
и interface_finalize
и base_finalize
вызываются только один раз для уничтожения каждой реализации интерфейса. Таким образом,
если вы используете одну из этих функций, вы должны использовать статическую целочисленную переменную
которая должна считать количество экземпляров реализации интерфейса чтобы класс интерфейса был уничтожен
только один раз (когда целочисленная переменная достигает нуля).
Выше описанный процесс можно резюмировать следующим:
Таблица 3. Уничтожение интерфейса
Время вызова | Вызываемая функция | Параметры функции |
---|---|---|
Последний вызов g_type_free_instance для типовой реализации интерфейса
|
интерфейсная функция interface_finalize | В интерфейсной vtable |
интерфейсная функция base_finalize | В интерфейсной vtable |
Теперь когда вы прочли этот раздел, вы можете забыть про него. Пожалуйста, забудьте так быстро как только возможно.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Многие типы неиснстанциированы системой типов и не имеют класса.
Большинство таких типов являются тривиальными базовыми типами такие как gchar,
регистрируются g_value_types_init
(в gvaluetypes.c
).
Для регистрации таких типов в системе типов, вам нужно просто заполнить структуру GTypeInfo нулями, так как эти типы базовые:
GTypeInfo info = { 0, /* class_size */ NULL, /* base_init */ NULL, /* base_destroy */ NULL, /* class_init */ NULL, /* class_destroy */ NULL, /* class_data */ 0, /* instance_size */ 0, /* n_preallocs */ NULL, /* instance_init */ NULL, /* value_table */ }; static const GTypeValueTable value_table = { value_init_long0, /* value_init */ NULL, /* value_free */ value_copy_long0, /* value_copy */ NULL, /* value_peek_pointer */ "i", /* collect_format */ value_collect_int, /* collect_value */ "p", /* lcopy_format */ value_lcopy_char, /* lcopy_value */ }; info.value_table = &value_table; type = g_type_register_fundamental (G_TYPE_CHAR, "gchar", &info, &finfo, 0);
Наличие неинстанциированных типов может показаться немного бесполезным: что хорошего в типе если вы не можете инстанциировать экземпляр этого типа? Большинство этих типов используются вместе с GValues: GValue инициализируется целочисленным или строкой и размещается используя value_table зарегистрированного типа. GValues (и расширение тривиального базового типа) полезна когда используется вместе со свойствами объекта и сигналами.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Формирование цепочки часто неточно определяется следующим набором условий:
Родительский класс A определяет общий виртуальный метод с именем foo
и
обеспечивает реализацию по умолчанию.
Дочерний класс B перереализует метод foo
.
В методе B::foo, дочерний класс B вызывает его родительский классовый метод A::foo.
Эту идиому можно использовать по разному:
Вам нужно изменить поведение класса без изменения его кода. Вы создаёте подкласс чтобы унаследовать его реализацию, перереализуете общий виртуальный метод для незначительного изменения поведения и формируете цепочку убедившись что предыдущее поведение действительно не изменилось, а только расширилось.
Вы ленивы, у вас есть доступ к исходному коду родительского класса но вы не хотите изменять его добавляя вызовы метода в новые специализированные вызовы метода: быстрее хакнуть дочерний класс сформировав цепочку чем изменять родительский для вызова вниз.
Вам нужно реализовать шаблон Chain Of Responsability: каждый объект наследует дерево сформированных цепочек родителя (обычно, в начале или в конце метода) гарантируя что каждый их обработчик выполнится в свою очередь.
Я лично не уверен что два последних способа использования являются хорошей идеей, н так как эта идиома программирования часто используется, этот раздел попытается объяснить как это реализуется.
Для явного формирования цепочки в реализации виртуального метода в родительском классе, вам сначала нужно обработать оригинальную структуру родительского класса. Этот указатель можно зтем использовать для доступа к оригинальному указателю функции класса и вызывать её непосредственно. [13]
Функция g_type_class_peek_parent
используется для доступа к оригинальной родительской классовой структуре. Её ввод - это указатель на класс производного объекта
и она возвращает указатель на оригинальную родительскую структуру класса. Код ниже показывает как вы должны её использовать:
static void b_method_to_call (B *obj, int a) { BClass *klass; AClass *parent_class; klass = B_GET_CLASS (obj); parent_class = g_type_class_peek_parent (klass); /* do stuff before chain up */ parent_class->method_to_call (obj, a); /* do stuff after chain up */ }
Многие люди использующие эту идиому в GTK+ хранят указатель на родительскую классовую структуру в глобальной статической переменной,
чтобы избегать расточительных вызовов
g_type_class_peek_parent
для каждого вызова функции.
Обычно, class_init callback-функция инициализирует глобальную статичную переменную.
Это делает gtk/gtkhscale.c
.
[13]
Оригинальное прилагательное используемое в этом предложении весьма вредное.
Для полного понимания что это значит, вы должны повторить как сструктуры класса инициализируются: для каждого объектного типа,
классовая структура привязанная к объекту создаётся с помощью начального копирования классовой сструктуры родительского типа
(просто memcpy
) а зтем вызывается class_init callback-функция в результирующей структуре.
Так как class_init callback-функция отвечает за перезапись классовой сструктуры с пользовательской перереализацией методов класса,
мы не можем просто использовать изменённую копию родительской сструктуры класса сохранённую в нашем производном экземпляре.
Мы хотим получить копию классовой сструктуры экземпляра родительского класса.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
В вашем коде, первый шаг это включение (#include) необходимых заголовков: в зависимости от вашей стратегии включения заголовков, это может быть просто #include "maman-bar.h" или десятки строк #include заканчивая строкой #include "maman-bar.h":
/* * Правовая информация * Copyright information */ #include "maman-bar.h" /* Если вы используете Pimpls, включите определение закрытых структур здесь * Некоторые люди создают заголовочные файлы maman-bar-private.h * которые включаются в файл maman-bar.c и которые содержат * определения для этих закрытых структур. */ struct _MamanBarPrivate { int member_1; /* наполнение */ }; /* * следующие определения * forward definitions */
Реализуйте maman_bar_get_type
и убедитесь что код компилируется:
GType maman_bar_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBarClass), NULL, /* base_init */ NULL, /* base_finalize */ NULL, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBar), 0, /* n_preallocs */ NULL /* instance_init */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBarType", &info, 0); } return type; }
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Люди часто запутываются пытаясь конструировать собственный объект GObjects, из-за множества разных способов монтирования в процессе конструирования объекта: трудно сформулировать который является правильным, рекомендованным способом.
Table 4, “g_object_new” показывает что функции обеспечиваемые пользователем вызываются в течение инстанциации объекта и в каком порядке они вызываются. Пользователь ищущий эквивалент простой функции конструктора C++ должен использовать instance_init метод. Он будет вызван после всех родительских функций instance_init. Эта функция не принимает произвольных параметров конструирования (как в C++), но если ваш объект нуждается в произвольных параметрах для завершения инициализации, вы можете использовать свойства конструирования.
Свойства конструкции будут установлены только после всех выполненных функций instance_init.
Ссылка объекта не будет возвращена клиенту g_object_new>
пока не будут установлены все свойства конструкции.
Также, я рекомендовал бы сначала писать следующий код:
static void maman_bar_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = (MamanBar *)instance; self->private = g_new0 (MamanBarPrivate, 1); /* Инициализируем все общие и закрытые члены в разумные значения по умолчанию. */ /* Если вам нужно специфичное свойство конструирования для завершения инициализации, * инициализация задерживается пока не установлено свойство. */ }
Убедитесь что вы установили maman_bar_init
как типовую функцию instance_init
в maman_bar_get_type
. Убедитесь что код собирается и выполняется: создайте экземпляр объекта и
убедитесь что maman_bar_init
вызывается (добавьте в него вызов
g_print
).
Теперь, если вам нужны специальные свойства конструирования, установите свойства в функцию class_init, отмените установленные и полученные методы и реализуйте получение и установку методов как описано в the section called “Object properties”. Убедитесь что эти свойства используются только конструируя GParamSpec, установив флаговое поле спецификации параметра в значение G_PARAM_CONSTRUCT_ONLY: это поможет GType убедится что свойства не установятся позже снова злонамеренным пользовательским кодом.
static void bar_class_init (MamanBarClass *klass) { GObjectClass *gobject_class = G_OBJECT_CLASS (klass); GParamSpec *maman_param_spec; gobject_class->set_property = bar_set_property; gobject_class->get_property = bar_get_property; maman_param_spec = g_param_spec_string ("maman", "Maman construct prop", "Set maman's name", "no-name-set" /* default value */, G_PARAM_CONSTRUCT_ONLY |G_PARAM_READWRITE); g_object_class_install_property (gobject_class, PROP_MAMAN, maman_param_spec); }
Если вам это нужно, убедитесь что вы можете собрать и запустить код подобный коду показанному выше.
Убедитесь что ваши конструкционные свойства могут правильно устанавливаться в течение конструирования,
убедитесь что вы не можете установить их впоследствие и убедитесь что без вызова
g_object_new
с необходимыми свойствами конструирования, они будут инициализированы значениями по умолчанию.
Я думаю что правильно останавливать выполнение программы если конструкционное свойство установлено в значение по умолчанию. Это позволит вам перехватить клиентский код который не предаёт разумное значение свойствам конструирования. Конечно вы можете не согласиться с этим, но вы должны иметь для этого веские причины.
Некоторые люди иногда нуждаются в конструировании собственных объектов, но только после установки конструкционных свойств. Это возможно благодаря использованию классовому методу конструирования как описано в the section called “Object instanciation”. Однако, я не вижу никаких разумных причин использовать эту особенность. Также, для инициализации вашего экземпляра объекта, используйте функцию base_init и конструкционные свойства по умолчанию.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Опять, часто сложно выяснить какой механизм использовать для обработки процесса уничтожения объекта:
когда сделан последний вызов функции
g_object_unref
,
многое происходит как описано в
Table 5, “g_object_unref”.
Процессс уничтожения вашего объекта должен быть разбит на две фазы: вы должны отменить и методы распределения и методы финализации класса.
struct _MamanBarPrivate { gboolean dispose_has_run; }; static GObjectClass parent_class = NULL; static void bar_dispose (GObject *obj) { MamanBar *self = (MamanBar *)obj; if (self->priv->dispose_has_run) { /* если распределение уже выполнено, возвращаемся. */ return; } /* убеждаемся что распределение не выполняется дважды. */ object->priv->dispose_has_run = TRUE; /* * В распределении, вы должны освободить все типы ссылок из этого объекта * которые могут сами содержать ссылки на себя. В основном, * самое простое решение освободить ссылки всех членов которыми вы * владеете. */ /* Формируем цепочку до родительского класса */ G_OBJECT_CLASS (parent_class)->dispose (obj); } static void bar_finalize (GObject *obj) { MamanBar *self = (MamanBar *)obj; /* Формируем цепочку до родительского класса */ G_OBJECT_CLASS (parent_class)->finalize (obj); } static void bar_class_init (BarClass *klass) { GObjectClass *gobject_class = G_OBJECT_CLASS (klass); gobject_class->dispose = bar_dispose; gobject_class->finalize = bar_finalize; parent_class = g_type_class_peek_parent (klass); g_type_class_add_private(klass,sizeof(MamanBarPrivate)); } static void maman_bar_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = (MamanBar *)instance; self->priv = G_TYPE_INSTANCE_GET_PRIVATE(self, BT_TYPE_PATTERN, BtPatternPrivate); self->priv->dispose_has_run = FALSE; }
Добавьте подобный код в ваш GObject, убедитесь что код собирается и выполняется: распределение и финализация должны быть вызваны в течение последнего освобождения ссылки. Возможно что методы объекта могут быть вызваны после выполнения распределения и перед выполнением финализации. GObject не предполагает что это ошибка программы: вы должны изящно обнаружить это и не предупреждая пользователя не допустить краха. Для этого, вам потребуется следующий код в начале каждого объектного метода, чтобы убедиться что объектные данные остаются доступными перед манипулированием ими:
if (self->private->dispose_has_run) { /* Распределение было выполнено. Данные больше недоступны. */ return; }
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Так же как в C++, есть много разных способов определить методы объекта и дополнить их: следующее описание и разделы используют словарь C++. (Ожидается что читатель знает основные базовые термины C++. Те кто давно не писал код на C++ могут обратиться например к http://www.cplusplus.com/doc/tutorial/ чтобы освежить свою память.)
невиртуальные общие методы (non-virtual public methods),
виртуальные общие методы (virtual public methods) и
виртуальные закрытые методы (virtual private methods)
Они являются самыми простыми: вам нужно обеспечить простой метод который может взаимодействовать с вашим объектом. Всё что вам нужно сделать это обеспечить прототип функции в заголовочном файле и реализовать её прототип в исходном файле.
/* декларация в заголовочном файле. */ void maman_bar_do_action (MamanBar *self, /* parameters */); /* реализация в исходном фале */ void maman_bar_do_action (MamanBar *self, /* parameters */) { /* наполнение. */ }
В этом нет ничего страшного.
Это предпочтительный способ создания полиморфных объектов GObjects. Всё что вам нужно сделать это определить основной метод и его классовую функцию в общем заголовке, реализовать основной метод в исходном файле и перереализовать классовую функцию в каждом объекте который вас интересует.
/* декларация в maman-bar.h. */ struct _MamanBarClass { GObjectClass parent; /* наполнение */ void (*do_action) (MamanBar *self, /* параметры */); }; void maman_bar_do_action (MamanBar *self, /* параметры */); /* реализация в maman-bar.c */ void maman_bar_do_action (MamanBar *self, /* параметры */) { MAMAN_BAR_GET_CLASS (self)->do_action (self, /* параметры */); }
Код выше просто переадресует вызов do_action в подходящую классовую функцию. Некоторые пользователи,
заинтересованные в производительности, не обеспечивают maman_bar_do_action
функцию оболочку и требуют чтобы пользователи самостоятельно разыменовывали классовый указатель. Это не очень
хорошая идея в период инкапсуляции и мешает изменять реализацию объекта в последствие.
Другие пользователи, также заинтересованные в производительности, декларируют maman_bar_do_action
функцию inline в заголовочном файле. Это также мешает изменять реализацию объекта в последствие
(хотя проще чем требование от пользователей непосредственного разыменования классовой функции)
и часто сложно написать переносимым способом (ключевое слово inline
не является частью стандарта C).
Сомневайтесь, пока пользователь не показал вам твёрдые цифры о производительности функционального вызова,
по сравнению с простой maman_bar_do_action
в исходном файле.
Пожалуйста, помните что это возможно обеспечит для вас реализованная по умолчанию объектная функция для этого метода класса: инициализируйте поле klass->do_action указателем на фактическую реализацию. Вы можете так же сделать этот метод класса чисто виртуальным инициализировав поле klass->do_action в значение NULL:
static void maman_bar_real_do_action_two (MamanBar *self, /* параметры */) { /* реализация по умолчанию для виртуального метода. */ } static void maman_bar_class_init (BarClass *klass) { /* чисто виртуальный метод: мандаты реализуются в наследниках (children). */ klass->do_action_one = NULL; /* просто виртуальный метод. */ klass->do_action_two = maman_bar_real_do_action_two; } void maman_bar_do_action_one (MamanBar *self, /* параметры */) { MAMAN_BAR_GET_CLASS (self)->do_action_one (self, /* параметры */); } void maman_bar_do_action_two (MamanBar *self, /* параметры */) { MAMAN_BAR_GET_CLASS (self)->do_action_two (self, /* параметры */); }
Это очень похожие на Virtual Public методы. Просто они не имеют общих функций для непосредственного вызова функции. Заголовочный файл содержит только декларацию классовой функции:
/* декларация в maman-bar.h. */ struct _MamanBarClass { GObjectClass parent; /* наполнение */ void (*helper_do_specific_action) (MamanBar *self, /* параметры */); }; void maman_bar_do_any_action (MamanBar *self, /* параметры */);
Эти классовые функции часто используются для делегирования части работы в дочерние классы:
/* статичная функция аксессор: она не экспортируется за пределы этого файла. */ static void maman_bar_do_specific_action (MamanBar *self, /* параметры */) { MAMAN_BAR_GET_CLASS (self)->do_specific_action (self, /* параметры */); } void maman_bar_do_any_action (MamanBar *self, /* параметры */) { /* здесь произвольный код */ /* * Пробуем выполнить требуемое действие. Возможно требуемое действие не может быть реализовано * здесь. Поэтому мы делегируем его реализацию в дочерний класс: */ maman_bar_do_specific_action (self, /* параметры */); /* здесь другой произвольный код */ }
Снова, возможно обеспечить реализацию по умолчанию для этой закрытой виртуальной классовой функции:
static void maman_bar_class_init (MamanBarClass *klass) { /* чисто виртуальный метод: мандаты реализуются в наследниках (children). */ klass->do_specific_action_one = NULL; /* просто виртуальный метод. */ klass->do_specific_action_two = maman_bar_real_do_specific_action_two; }
Наследники могут реализовать подкласс с помощью похожего кода:
static void maman_bar_subtype_class_init (MamanBarSubTypeClass *klass) { MamanBarClass *bar_class = MAMAN_BAR_CLASS (klass); /* реализуем чисто виртуальную функцию класса. */ bar_class->do_specific_action_one = maman_bar_subtype_do_specific_action_one; }
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Конечно, в основном люди задаются вопросом: как реализовать подкласс GObject.
Иногда потому что нужно создать собственную иерархию класса, иногда потому что нужен подкласс одного из виджетов GTK+.
Этот раздел сфокусирован над реализацией подтипов GObject. Пример исходного кода связанного с этим разделом может быть найден
в исходниках документации, в каталоге sample/gobject
:
maman-bar.{h|c}
: это исходник для объекта который наследует
GObject и который показывает как
декларируются разные типовые методы объекта.
maman-subbar.{h|c}
: это исходник для объекта который наследует
MamanBar и который показывает как переписать некоторые его родительские методы.
maman-foo.{h|c}
: это исходник для объекта который наследует
GObject и который декларирует сигнал.
test.c
: это основной исходник который инстанциирует экземпляр типа и осуществляет API.
Первый шаг написания кода для вашего GObject - написать типовой заголовок который содержит необходимые декларации типа, функций и макросов. Каждый из этих элементов является соглашением которому следует не только код GTK+, но также большинство пользователей GObject. Подумайте дважды прежде чем нарушать правила заявленные ниже:
Если пользователи немного привыкли к коду GTK+ или любому коду Glib, они будут удивлены вашими нарушениями и привыкание к тому что вы нарушили соглашения займёт время (деньги) и будет их раздражать (это нехорошо)
Вы должны понимать что возможно эти соглашения разрабатывали достаточно умные и опытные люди: возможно они были по крайней мере частично правы. Попробуйте преодолеть своё эго.
Выберете согласованное имя для ваших файлов заголовков и исходного кода и придерживайтесь его:
использовать тире для отделения префикса от типового имени: maman-bar.h
и
maman-bar.c
(это соглашение используется Nautilus и большинством библиотек GNOME).
использовать символ подчеркивания для разделения префикса и типового имени: maman_bar.h
и
maman_bar.c
.
Не отделять префикс от типового имени: mamanbar.h
и
mamanbar.c
. (это соглашение используется в GTK+)
Я лично предпочитаю первое соглашение: оно позволяет легче читать имена файлов людям со слабым зрением, таким как я.
Когда вам необходимы некоторые закрытые (внутренние) декларации в нескольких (под)классах,
вы можете определить их в закрытом заголовочном файле который часто называют добавляя ключевое слово
private к общему имени заголовочных файлов.
Например, можно было бы использовать maman-bar-private.h
,
maman_bar_private.h
или mamanbarprivate.h
.
Обычно такие закрытые заголовочные файлы не устанавливаются.
Основные соглашения для любых заголовков GType описаны в “Conventions”. Большинство кода основанного на GObject также придерживается следующих соглашений: выберете одно из них и придерживайтесь его.
Если вы хотите задекларировать тип с именем bar и префиксом maman, имя типового экземпляра
MamanBar
и его класс MamanBarClass
(имена регистрозависимы). Общепринято декларировать это кодом подобно следующему:
/* * Информация о правах и лицензионных соглашениях. */ #ifndef MAMAN_BAR_H #define MAMAN_BAR_H /* * Потенциально, включите другие заголовочные файлы от которого зависит этот. */ /* * Напечатайте макроопределения. */ typedef struct _MamanBar MamanBar; typedef struct _MamanBarClass MamanBarClass; struct _MamanBar { GObject parent; /* члены экземпляра */ }; struct _MamanBarClass { GObjectClass parent; /* члены класса */ }; /* используемый MAMAN_BAR_TYPE */ GType maman_bar_get_type (void); /* * Определения метода. */ #endif
Большинство GTK+ типов декларируют свои закрытые поля в общих заголовках с комментарием /* private */, рассчитывая на благоразумие пользователей не пытаться играть с этими полями. Поля не отмеченные как закрытые рассматриваются как общие по умолчанию. Комментарий /* protected */ (с семантикой C++) также используются, главным образом в библиотеке GType, в коде написанном Tim Janik.
struct _MamanBar { GObject parent; /*< private >*/ int hsize; };
Весь код Nautilus и большинство библиотек GNOME используют закрытые косвенные члены, как описано Herb Sutter в его статьях Pimpl (смотрите Compilation Firewalls и The Fast Pimpl Idiom : он суммировал разные проблемы лучше меня).
typedef struct _MamanBarPrivate MamanBarPrivate; struct _MamanBar { GObject parent; /*< private >*/ MamanBarPrivate *priv; };
Не используйте имя private
, так как это зарегистрированное ключевое слово c++.
Закрытая структура определяемая в .c файле, инстанциируется в объектной функции
init
а уничтожается в объектной функции finalize
.
static void maman_bar_finalize (GObject *object) { MamanBar *self = MAMAN_BAR (object); /* do stuff */ g_free (self->priv); } static void maman_bar_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = MAMAN_BAR (instance); self->priv = g_new0 (MamanBarPrivate,1); /* do stuff */ }
Подобная альтернативная возможность, начиная с версии Glib 2.4, определить закрытую структуру в .c файле,
декларируя её как закрытую структуру в maman_bar_class_init
используя
g_type_class_add_private
.
Вместо распределения памяти в maman_bar_init
указать закрытую область памяти сохранённую в
экземпляре позволяя удобный доступ к этой структуре.
Таким образом закрытая структура будет прикреплена к каждому вновь созданному объекту системы GObject.
Вам не нужно освобождать или распределять закрытую структуру, только объекты или указатели которые она может содержать.
Другое преимущество этой версии перед предыдущей в том что это уменьшает фрагментацию памяти, так как общие и закрытые
части памяти экземпляра распределяются одновременно.
typedef struct _MamanBarPrivate MamanBarPrivate; struct _MamanBarPrivate { int private_field; }; static void maman_bar_class_init (MamanBarClass *klass) { ... g_type_class_add_private (klass, sizeof (MamanBarPrivate)); ... } static void maman_bar_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = MAMAN_BAR (instance); self->priv = G_TYPE_INSTANCE_GET_PRIVATE (self, MAMAN_BAR_TYPE, MamanBarPrivate); /* do stuff */ }
Наконец, есть различные соглашения включения заголовков. Снова, выберете одно и придерживайтесь ему. Я лично использую любое из двух без разницы, в зависимости от кодовой базы в которой работаю: согласованное правило.
Некоторые люди добавляют заголовочный файл с множеством директив #include для перемещения по всем заголовкам необходимым для компиляции кода клиента. Это позволяет коду клиента просто включить #include "maman-bar.h".
Другие не делают никаких #include и ожидают что клиент включит #include самостоятельно заголовочные файлы в которых нуждается перед включением вашего заголовочного файла. Это ускоряет компиляцию потому что минимизирует работу препроцессора. Это может быть использовано вместе с повторной декларацией определённых неиспользуемых типов в клиентском коде для минимизации времени компилирования зависимостей и таким образом укорить компиляцию.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Как только интерфейс определён, его реализация довольно тривиальна. Исходный код, показывающий как это делается для
определённого интерфейса IBaz в предыдущем разделе, расположен в
sample/interface/maman-baz.{h|c}
.
Первый шаг - определяем обычную GType. Здесь мы решили использовать GType которая наследует GObject. Её имя MamanBaz:
#ifndef MAMAN_BAZ_H #define MAMAN_BAZ_H #include <glib-object.h> #define MAMAN_TYPE_BAZ (maman_baz_get_type ()) #define MAMAN_BAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAZ, Mamanbaz)) #define MAMAN_BAZ_CLASS(vtable) (G_TYPE_CHECK_CLASS_CAST ((vtable), MAMAN_TYPE_BAZ, MamanbazClass)) #define MAMAN_IS_BAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAZ)) #define MAMAN_IS_BAZ_CLASS(vtable) (G_TYPE_CHECK_CLASS_TYPE ((vtable), MAMAN_TYPE_BAZ)) #define MAMAN_BAZ_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), MAMAN_TYPE_BAZ, MamanbazClass)) typedef struct _MamanBaz MamanBaz; typedef struct _MamanBazClass MamanBazClass; struct _MamanBaz { GObject parent; int instance_member; }; struct _MamanBazClass { GObjectClass parent; }; GType maman_baz_get_type (void); #endif //MAMAN_BAZ_H
В этом заголовке нет ничего сверхъестественного или страшного: он не определяет никакого особенного API и не наследует особенный тип.
Второй шаг - реализация maman_baz_get_type
:
GType maman_baz_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBazClass), NULL, /* base_init */ NULL, /* base_finalize */ NULL, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBaz), 0, /* n_preallocs */ baz_instance_init /* instance_init */ }; static const GInterfaceInfo ibaz_info = { (GInterfaceInitFunc) baz_interface_init, /* interface_init */ NULL, /* interface_finalize */ NULL /* interface_data */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBazType", &info, 0); g_type_add_interface_static (type, MAMAN_TYPE_IBAZ, &ibaz_info); } return type; }
Эта функция очень похожа на подобные функции рассматриваемые нами ранее. Единственный интерфейсно-специфичный код представленный здесь
это вызов g_type_add_interface_static
который используется для информирования системы типов что зарегистрированный тип
GType также реализует интерфейс
MAMAN_TYPE_IBAZ
.
baz_interface_init
, функция инициализации интерфейса, она тоже очень проста:
static void baz_do_action (MamanBaz *self) { g_print ("Baz implementation of IBaz interface Action: 0x%x.\n", self->instance_member); } static void baz_interface_init (gpointer g_iface, gpointer iface_data) { MamanIbazInteface *iface = (MamanIbazInteface *)g_iface; iface->do_action = (void (*) (MamanIbaz *self))baz_do_action; } static void baz_instance_init (GTypeInstance *instance, gpointer g_class) { MamanBaz *self = MAMAN_BAZ(instance); self->instance_member = 0xdeadbeaf; }
baz_interface_init
просто инициализирует интерфейсные методы для реализации определённого
MamanBaz: maman_baz_do_action
не делает ничего полезного но могла бы :)
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Начиная с версии glib 2.4, GObject интерфейсы могут также иметь свойства.
Декларация свойств интерфейса похожа на декларацию свойств обычных типов GObject как показано в
“Object properties”,
исключая то, что g_object_interface_install_property
используется для декларации свойств вместо g_object_class_install_property
.
Для включения свойства с именем 'name' типа string в код выше приведённого примера интерфейса
maman_ibaz, нам нужно добавить только одну[14]
строчку в maman_ibaz_base_init
[15]
как показано ниже:
static void maman_ibaz_base_init (gpointer g_iface) { static gboolean initialized = FALSE; if (!initialized) { /* здесь создаём сигналы интерфейса. */ g_object_interface_install_property (g_iface, g_param_spec_string ("name", "maman_ibaz_name", "Name of the MamanIbaz", "maman", G_PARAM_READWRITE)); initialized = TRUE; } }
Одно замечание - задекларированному свойству не был присвоен целочисленный ID. Причина в том, что целочисленный ID этого свойства используется только внутри методов получения и установки, а так как интерфейс не реализует свойства, нет необходимости привязывать целочисленный ID к свойствам интерфейса.
История для конструкторов интерфейса также весьма тривиальна.
Конструктор должен задекларировать и определить свойства обычным способом как описано в
the section called “Object properties”,
за исключением одной мелочи: он должен задекларировать свойства интерфейса используя
g_object_class_override_property
вместо
g_object_class_install_property
.
Следующий код демонстрирует изменения необходимые в декларации и реализации MamanBaz показанной выше:
struct _MamanBaz { GObject parent; gint instance_member; gchar *name; /* метка для свойства */ }; enum { ARG_0, ARG_NAME }; GType maman_baz_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanBazClass), NULL, /* base_init */ NULL, /* base_finalize */ baz_class_init, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ sizeof (MamanBaz), 0, /* n_preallocs */ baz_instance_init /* instance_init */ }; static const GInterfaceInfo ibaz_info = { (GInterfaceInitFunc) baz_interface_init, /* interface_init */ NULL, /* interface_finalize */ NULL /* interface_data */ }; type = g_type_register_static (G_TYPE_OBJECT, "MamanBazType", &info, 0); g_type_add_interface_static (type, MAMAN_TYPE_IBAZ, &ibaz_info); } return type; } static void maman_baz_class_init (MamanBazClass * klass) { GObjectClass *gobject_class; gobject_class = (GObjectClass *) klass; parent_class = g_type_class_ref (G_TYPE_OBJECT); gobject_class->set_property = maman_baz_set_property; gobject_class->get_property = maman_baz_get_property; g_object_class_override_property (gobject_class, ARG_NAME, "name"); } static void maman_baz_set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec * pspec) { MamanBaz *baz; GObject *obj; /* it's not null if we got it, but it might not be ours */ g_return_if_fail (G_IS_MAMAN_BAZ (object)); baz = MAMAN_BAZ (object); switch (prop_id) { case ARG_NAME: baz->name = g_value_get_string (value); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; } } static void maman_baz_get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspec) { MamanBaz *baz; /* it's not null if we got it, but it might not be ours */ g_return_if_fail (G_IS_TEXT_PLUGIN (object)); baz = MAMAN_BAZ (object); switch (prop_id) { case ARG_NAME: g_value_set_string (value, baz->name); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); break; } }
[14] Это действительно одна строка расширенная на шесть для ясности
[15]
g_object_interface_install_property
может также быть вызвана из
class_init
но её нельзя вызвать после этой точки.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Большая часть определения интерфейса уже показана “Non-instantiable classed types: Interfaces.”
но я чувствую что нужно показать как конкретно создаётся интерфейс. Исходные коды примеров связанных с этим разделом можно найти
в исходном пакете документации, в файле sample/interface/maman-ibaz.{h|c}
.
Как и раньше, сначала получаем правильный заголовок:
#ifndef MAMAN_IBAZ_H #define MAMAN_IBAZ_H #include <glib-object.h> #define MAMAN_TYPE_IBAZ (maman_ibaz_get_type ()) #define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_IBAZ, MamanIbaz)) #define MAMAN_IS_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_IBAZ)) #define MAMAN_IBAZ_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), MAMAN_TYPE_IBAZ, MamanIbazInterface)) typedef struct _MamanIbaz MamanIbaz; /* макет объекта */ typedef struct _MamanIbazInterface MamanIbazInterface; struct _MamanIbazInterface { GTypeInterface parent; void (*do_action) (MamanIbaz *self); }; GType maman_ibaz_get_type (void); void maman_ibaz_do_action (MamanIbaz *self); #endif /*MAMAN_IBAZ_H*/
Этот код похож на обычную GType которая наследует GObject за исключением некоторых деталей:
_GET_CLASS
макрос называется _GET_INTERFACE
и реализуется не с помощью G_TYPE_INSTANCE_GET_CLASS
, а с помощью
G_TYPE_INSTANCE_GET_INTERFACE
.
Тип экземпляра MamanIbaz определён не полностью: он используется просто как абстрактный тип который представляет экземпляр любого объекта реализующего интерфейс.
Реализация самого типа MamanIbaz тривиальна:
maman_ibaz_get_type
регистрирует тип в системе типов.
maman_ibaz_base_init
как ожидается регистрирует интерфейсные сигналы если они есть
(позже мы рассмотрим как их использовать). Убедитесь что используете статичную локальную логическую переменную
чтобы не выполнять код инициализации дважды (как описано в
“Interface Initialization”,
base_init
выполняется один раз для каждой реализованной инстанциации интерфейса)
maman_ibaz_do_action
разыменовывает структуру класса
для доступа к связанным с ней функциям класса и их вызова.
static void maman_ibaz_base_init (gpointer g_class) { static gboolean initialized = FALSE; if (!initialized) { /* здесь создаём сигналы интерфейса. */ initialized = TRUE; } } GType maman_ibaz_get_type (void) { static GType type = 0; if (type == 0) { static const GTypeInfo info = { sizeof (MamanIbazInterface), maman_ibaz_base_init, /* base_init */ NULL, /* base_finalize */ NULL, /* class_init */ NULL, /* class_finalize */ NULL, /* class_data */ 0, 0, /* n_preallocs */ NULL /* instance_init */ }; type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbaz", &info, 0); } return type; } void maman_ibaz_do_action (MamanIbaz *self) { MAMAN_IBAZ_GET_INTERFACE (self)->do_action (self); }
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Система сигналов которая была создана в GType довольно сложная и гибкая: она позволяет пользователям подключать в основном цикле любое количество callback-функций (реализовано в любом языке для которого есть привязка) [16] к любому сигналу и останавливать эмиссию любого сигнала в любом состоянии. Эта гибкость делает возможным использование GSignal намного шире чем простое издание событий которые могут быть получены многочисленными клиентами.
Самое основное использование сигналов это осуществление простого уведомления о произошедшем событии:
например, если вы имеете объект MamanFile, и если этот объект имеет написанный метод, можно получать уведомление
каждый раз когда кто-нибудь использует этот метод. Код ниже показывает как пользователь может подключить callback-функцию
к созданному сигналу. Полный код этого примера расположен в sample/signal/maman-file.{h|c}
и в
sample/signal/test.c
file = g_object_new (MAMAN_FILE_TYPE, NULL); g_signal_connect (G_OBJECT (file), "write", (GCallback)write_event, NULL); maman_file_write (file, buffer, 50);
Сигнал MamanFile регистрируется в функции class_init:
klass->write_signal_id = g_signal_newv ("write", G_TYPE_FROM_CLASS (g_class), G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS, NULL /* class closure */, NULL /* accumulator */, NULL /* accu_data */, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE /* return_type */, 0 /* n_params */, NULL /* param_types */);
а издаётся сигнал в maman_file_write
:
void maman_file_write (MamanFile *self, guint8 *buffer, guint32 size) { /* Сначала записываем данные. */ /* Затем, сообщаем пользователю о записанных данных. */ g_signal_emit (self, MAMAN_FILE_GET_CLASS (self)->write_signal_id, 0 /* details */, NULL); }
Как показано выше, вы можете безопасно установить детальный параметр в ноль если вы не знаете для чего его использовать. Обсуждение того где он может использоваться, смотрите “The detail argument”
Сигнатура обработчика сигнала в примере выше определена как
g_cclosure_marshal_VOID__VOID
. Это название
следует простому соглашению - кодировать параметр функции и тип
возвращаемого значения в имени функции. Определено что, значение перед двойным подчёркиванием
это тип возвращаемого значения, в то время как значение(я) после двойного подчёркивания обозначает
тип параметров. Заголовок gobject/gmarshal.h
определяет основной набор
необходимых замыканий которые можно использовать.
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
![]() |
![]() |
Справочное описание GObject |
---|
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Большинство современных языков программирования идут с собственной объектной системой и дополнительными базовыми языковыми алгоритмическими конструкциями. Так же как GLib предоставляет реализацию таких базовых типов и алгоритмов (связанные списки, хэш таблицы и т.д.), объектная система GLib Object System обеспечивает необходимую реализацию гибкой, расширяемой и преднамеренно лёгкой (для других языков) объектно-ориентированной оболочки (framework) для C. Подытожить обеспечиваемые существенные элементы можно так:
Родная система типов для регистрации произвольных прямых наследников и глубоко унаследованных типов а также интерфейсы для структурных типов. Она отвечает за создание, инициализацию и управление памятью различных объектов и классовых структур, поддерживает взаимоотношения родитель/наследник и всё что связанно с динамической реализацией таких типов. То есть, их типо-специфичная реализация является перераспределяемой/не загружаемой в течение выполнения.
Коллекция реализованных базовых типов, таких как integers, doubles, enums и структурные типы.
Простая реализация базового типа для основной объектной иерархии - базовый тип GObject.
Система сигналов которая позволяет очень гибкую пользовательскую настройку виртуальных/перезаписываемых объектных методов и может служить как мощный механизм уведомления.
Расширяемая система параметр/значение, поддерживает все обеспечиваемые базовые типы, которая может быть использована для общей обработки объектных свойств или иначе параметризованных типов.
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Table of Contents
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
В этой главе я попытался ответить на реальные вопросы пользователей и представил самые общие сценарии использования, которые только смог придумать. Случаи использования представлены от наиболее вероятных до менее вероятных.
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Несколько полезных инструментов разработчика были созданы для технологии GObject. Следующий раздел кратко представляет их и ссылки на соответствующие страницы проекта.
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Содержание
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Table of Contents
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Сигналы GObject не имеют никакого отношения к стандартным сигналам UNIX: они подключают произвольные события определённые приложением с любым количеством слушающих. Например, в GTK+, каждое пользовательское событие (нажатие клавиши или перемещение курсора) происходит из X сервера и генерирует GTK+ событие через форму эмиссии сигнала в данном экземпляре объекта.
Каждый сигнал регистрируется в системе типов вместе с типом который может его издать: пользователи типа, как говорится подключают в данный экземпляр типа когда он регистрирует замыкание вызываемое при эмиссии сигнала. Пользователи могут так же издать сигнал или остановить эмиссию сигнала изнутри одного из замыканий к которому подключен сигнал.
Когда сигнал издаётся на данном экземпляре типа, вызываются все замыкания подключенные в данном типовом экземпляре. Все замыкания связанные с такими сигналами представляют callback-функцию следующей сигнатуры:
return_type function_callback (gpointer instance, ... , gpointer user_data);
Для регистрации сигнала в существующем типе, мы можем использовать одну из функций
g_signal_newv
,
g_signal_new_valist
или
g_signal_new
:
guint g_signal_newv (const gchar *signal_name, GType itype, GSignalFlags signal_flags, GClosure *class_closure, GSignalAccumulator accumulator, gpointer accu_data, GSignalCMarshaller c_marshaller, GType return_type, guint n_params, GType *param_types);
Количество параметров у этих функций является немного запутывающим, но они достаточно просты:
signal_name: строка которая может использоваться для уникальной идентификации данного сигнала.
itype: экземпляр типа который может издавать данный сигнал.
signal_flags: частично определённый порядок в котором вызываются замыкания связанные с сигналом.
class_closure: замыкание по умолчанию для сигнала: если эмиссия сигнала не NULL, она будет вызвана в этой эмиссии сигнала. Момент вызова этого замыкания по сравнению с вызовом других замыканий связанных с этим игналом, частично зависит от signal_flags.
accumulator: указатель функции которая вызывается после каждого вызванного замыкания. Если она возвращает FALSE, эмиссия сигнала останавливается. Если возвращает TRUE, эмиссия сигнала выполняется нормально. Это также используется для вычисления возвращаемого значения сигнала, основываясь на возвращённом значении всех вызванных замыканий.
accumulator_data: этот указатель будет передан в каждый запрос accumulator в течение эмиссии.
c_marshaller: C маршаллер по умолчанию для любого замыкания которое подключено к этому сигналу.
return_type: тип значения возвращаемого сигналом.
n_params: количество принимаемых сигналом параметров.
param_types: массив GTypes который указывает тип каждого параметра сигнала. Длина массива указывается с помощью n_params.
Как вы видите в выше приведённых определениях, сигнал - это в основном описание замыканий которые могут быть подключены к этому сигналу и описание порядка в котором вызываются замыкания подключенные к данному сигналу.
Если вы хотите подключить к сигналу замыкание, у вас есть три возможности:
Вы можете зарегистрировать классовое замыкание при регистрации сигнала: это системная операция. То есть: class_closure будет вызван в течение каждой эмиссии данного сигнала на всех экземплярах типа которые поддерживают этот сигнал.
Вы можете использовать g_signal_override_class_closure
которая отменит class_closure полученного типа. Эту функцию возможно вызвать только в унаследованном типе,
типе в котором сигнал был зарегистрирован. Эта функция используется только языковыми привязками.
Вы можете зарегистрировать замыкание с помощью семейства функций g_signal_connect
.
Это экземпляро-специфичная операция: замыкание будет вызвано только в течение эмиссии данного сигнала в данном экземпляре.
Также возможно подключить различные виды callback-функций к данному сигналу:
обработчики прерываний эмиссии вызываются всякий раз когда издаётся данный сигнал
для экземпляра на котором он издаётся. Обработчики прерываний эмиссии используются
например чтобы заставить все эмиссии mouse_clicked в приложении издавать звук небольшого нажатия кнопки мыши.
Обработчики прерываний эмиссии подключаются с помощью g_signal_add_emission_hook
и удаляются с помощью g_signal_remove_emission_hook
.
Эмиссия сигнала выполняется через использование семейства функций
g_signal_emit
.
void g_signal_emitv (const GValue *instance_and_params, guint signal_id, GQuark detail, GValue *return_value);
Массив instance_and_params GValues содержит список вводимых в сигнал параметров. Первый элемент массива это указатель экземпляра для вызова сигнала. Следующие элементы массива содержат список параметров для сигнала.
signal_id идентифицирует вызываемый сигнал.
подробную идентификацию определяют детали вызываемого сигнала. Деталь - это своего рода магическая пара символ/параметр которая помещается в течение эмиссии сигнала и которая используется замыканием подключённым к сигналу для фильтрации нежелательных эмиссий сигнала. В большинстве случаев, вы можете безопасно установить это значение в ноль. Смотрите the section called “ The detail argument” для подробностей об этом параметре.
return_value содержит возвращаемое значение последнего вызванного замыкания в течение эмиссии если не был определён accumulator. Если accumulator был определён в процессе создания сигнала, этот сумматор используется для вычисления return_value как функция возвращаемых значений всех замыканий вызываемых в течение эмиссии. [10] Если нет замыканий вызываемых в течение эмиссии, return_value тем не менее инициализируется в null.
Внутренне, массив GValue помещается в надлежащую функцию эмиссии,
signal_emit_unlocked_R
(реализована в gsignal.c
).
Эмиссия сигнала может быть разделена на 5 шагов:
RUN_FIRST: если был использован флаг G_SIGNAL_RUN_FIRST при регистрации сигнала вызывается class_closure для этого сигнала если есть. Переходим в состояние EMISSION_HOOK.
EMISSION_HOOK: если обработчики прерывания эмиссии были добавлены в сигнал, они вызываются от первого добавленного до последнего. Аккумулируем возвращаемые значения и переходим в состояние HANDLER_RUN_FIRST.
HANDLER_RUN_FIRST: если есть замыкания подключенные с помощью
семейства функций g_signal_connect
,
и если они не заблокированы (с помощью семейства функций g_signal_handler_block
) они выполняются, от первого до последнего подключения.
Переходим в состояние RUN_LAST.
RUN_LAST: если флаг G_SIGNAL_RUN_LAST был установлен в течение регистрации и если было установлено замыкание class_closure, оно вызывается. Переходим в состояние HANDLER_RUN_LAST.
HANDLER_RUN_LAST: если есть замыкания подключенные с помощью
семейства функций g_signal_connect_after
, если они не вызваны в течение
HANDLER_RUN_FIRST и не заблокированы, они выполняются здесь, от первого до последнего подключения.
Переходим в состояние RUN_CLEANUP.
RUN_CLEANUP: если флаг G_SIGNAL_RUN_CLEANUP был установлен в процессе регистрации и если было установлено class_closure, оно вызывается. Здесь эмиссия сигнала завершается.
Если в какой нибудь точке выполнения эмиссии (исключая состояние RUN_CLEANUP), одно из замыканий
или обработчиков прерывания эмиссии остановят эмиссию сигнала с помощью
g_signal_stop
, эмиссия переходит в состояние CLEANUP.
Если, в какой нибудь точке выполнения эмиссии, одно из замыканий или обработчиков прерывания издаст тот же сигнал в том же экземпляре, эмиссия перегрузится в состояние RUN_FIRST.
Функция суммирования вызывается во всех состояниях, после вызова каждого замыкания (исключая EMISSION_HOOK и CLEANUP). Это суммирует возвращаемые значения замыканий в возвращаемое значение сигнала и возвращает TRUE или FALSE. Если, в каком нибудь пункте, не возвращено TRUE, эмиссия переходит в состояние CLEANUP.
Если нет суммирующей функции, возвращаемое значение последнего обработчика будет возвращено
функцией g_signal_emit
.
Все функции связанные с эмиссией сигнала или подключением сигнала имеют параметр с названием детальный. Иногда этот параметр скрыт с помощью API, но он всегда присутствует в той или иной форме.
Из трёх основных функций подключения, только одна имеет явный детальный параметр в виде GQuark [11]:
gulong g_signal_connect_closure_by_id (gpointer instance, guint signal_id, GQuark detail, GClosure *closure, gboolean after);
Две другие функции скрывают детальный параметр в идентифицирующем имени сигнала:
gulong g_signal_connect_closure (gpointer instance, const gchar *detailed_signal, GClosure *closure, gboolean after); gulong g_signal_connect_data (gpointer instance, const gchar *detailed_signal, GCallback c_handler, gpointer data, GClosureNotify destroy_data, GConnectFlags connect_flags);
Здесь параметр detailed_signal - это строка которая идентифицирует имя подключаемого сигнала. Однако, формат этой строки структурирован как signal_name::detail_name. Подключение к сигналу с именем notify::cursor_position будет фактически подключением к сигналу notify с именем cursor_position. Внутренне, строка преобразуется в GQuark если она представлена.
Из четырёх основных функций эмиссии сигнала, три имеют явный детальный параметр как GQuark:
void g_signal_emitv (const GValue *instance_and_params, guint signal_id, GQuark detail, GValue *return_value); void g_signal_emit_valist (gpointer instance, guint signal_id, GQuark detail, va_list var_args); void g_signal_emit (gpointer instance, guint signal_id, GQuark detail, ...);
Четвёртая функция скрывает его в параметре имени сигнала:
void g_signal_emit_by_name (gpointer instance, const gchar *detailed_signal, ...);
Формат параметра detailed_signal такой же как формат используемый функциями
g_signal_connect
:
signal_name::detail_name.
Если детальный параметр обеспечивается пользователем в функции эмиссии, он используется в течение эмиссии вместо соответствующего детального параметра обеспеченного замыканиями. Если детальный параметр замыкания не соответствует детальному параметру предоставленного пользователем, то они будут вызваны (даже если они подключены к издаваемому сигналу).
Это полностью опциональный механизм фильтрации главным образом используется как оптимизация сигналов которые часто издаются по разным причинам: клиенты могут фильтровать вывод который интересует их перед выполнением кода маршаллера замыкания. Например, это используется экстенсивно сигналом notify GObject: каждый раз когда изменяется свойство в GObject, вместо простого издания сигнала notify, GObject привязывается как детальный параметр для этой эмиссии сигнала с именем изменённого свойства. Это позволяет клиентам, которые желают получать уведомления об изменениях только к одному свойству, фильтровать большинство сообщений перед их получением.
Как простое правило, пользователи могут и должны установить детальный параметр в ноль: это полностью отключит дополнительную фильтрацию.
[10] James (снова!!) привёл несколько нетривиальных примеров сумматоров: “ Например, вы можете иметь сумматор который игнорирует возвращаемый NULL из замыкания, а только суммирует не-NULL значения. Другой сумматор может попытаться вернуть список возвращенных замыканиями значений. ”
[11]
GQuark это целочисленное которое представлено уникальной строкой. Оно может преобразовываться между строкой и целочисленным с помощью функций
g_quark_from_string
и
g_quark_to_string
.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Ещё один инструмент который может оказаться полезным при работе с GObjects - это G-Inspector. Он умеет отображать объекты Glib/Gtk+ и их свойства.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Создание GObjects может быть утомительной задачей. Требуется много печатать и даже copy/paste приносит много хлопот. Одной очевидной идеей является использование некоторого рода шаблонных заготовок для классов, а зтем запуск специального инструмента для генерации реального C файла. GOB/ (или GOB2) является таким инструментом. Это препроцессор который может быть использован для конструирования GObjects с действующим C кодом, поэтому нет необходимости редактировать сгенерерованный C код. Синтаксис в стиле Java и Yacc или Lex. Реализация преднамеренно сделана простой: действующий C код пользователя не анализируется.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
API документация для большинства библиотек Glib, GObject, GTK+ и GNOME создаётся с помощью комбинации разных инструментов. Обычно, часть документации которая описывает поведение каждой функции извлекается из специально отформатированных комментариев исходного кода с помощью утилиты с названием gtk-doc которая генерирует docbook xml и соединяет этот docbook xml с набором master xml docbook файлов. Эти xml docbook файлы обрабатываются с помощью xsltproc (небольшая программа, часть библиотеки libxslt) для генерации заключительного html вывода. Другие инструменты могут использоваться для генерации pdf вывода из исходного xml. Следующий код выборочно показывает как выглядят такие комментарии.
/** * gtk_widget_freeze_child_notify: * @widget: a #GtkWidget * * Stops emission of "child-notify" signals on @widget. The signals are * queued until gtk_widget_thaw_child_notify() is called on @widget. * * This is the analogue of g_object_freeze_notify() for child properties. **/ void gtk_widget_freeze_child_notify (GtkWidget *widget) { ...
Более полная документация о том как установить и использовать gtk-doc в вашем проекте приведена на сайте разработчиков GNOME.
![]() |
![]() |
![]() |
Справочное описание GObject | ![]() |
---|
Схема подсчёта ссылок используемая в GObject действительно решает многие проблемы управления памятью, но также добавляет новые ошибки в исходный код. В большинстве приложений, найти точно где счётчик ссылок Object может быть обработан не правильно, очень сложно. Хотелось бы надеяться что существующий инструмент с именем refdbg/ может использоваться для автоматического отслеживания недопустимого кода имеющего отношение к подсчёту ссылок. Это приложение перехватывает вызовы подсчёта ссылок и пытается обнаружить недопустимое поведение. Она поддерживает механизм фильтрации правил позволяя вам отслеживать только интересующие вас объекты и может использоваться совместно с gdb.
Помните что если GObject скомпилирован с параметром --enable-debug=yes
,
это экспортирует переменную прерывания программы в случае ошибки
static volatile GObject *g_trap_object_ref;
Если установлено в не-NULL значение, g_object_ref() и g_object_unref() будут перехвачены когда получат вызов с таким значением.