GParamSpec

GParamSpec — Метаданные для спецификации параметра

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

#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). Последующие символы могут быть буквами, цифрами или символом '-'. Все другие символы заменяются символом '-' в процессе конструирования. Результат этого замещения называется каноническим именем параметра.

Детали

G_TYPE_IS_PARAM()

#define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)

Определяет соответствует ли type "is a" G_TYPE_PARAM.

type : GType ID

G_PARAM_SPEC()

#define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))

Преобразует производный объект GParamSpec (например тип GParamSpecInt) в объект GParamSpec.

pspec : допустимая структура GParamSpec

G_IS_PARAM_SPEC()

#define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))

Проверяет является ли pspec "is a" допустимой структурой GParamSpec типа G_TYPE_PARAM или производной.

pspec : GParamSpec

G_PARAM_SPEC_CLASS()

#define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))

Преобразует производную структуру GParamSpecClass в структуру GParamSpecClass.

pclass : допустимая структура GParamSpecClass

G_IS_PARAM_SPEC_CLASS()

#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

G_PARAM_SPEC_GET_CLASS()

#define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))

Находит GParamSpecClass из GParamSpec.

pspec : допустимая структура GParamSpec

G_PARAM_SPEC_TYPE()

#define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec))

Находит GType этой pspec.

pspec : допустимая структура GParamSpec

G_PARAM_SPEC_TYPE_NAME()

#define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec)))

Находит GType имя этой pspec.

pspec : допустимая структура GParamSpec

G_PARAM_SPEC_VALUE_TYPE()

#define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type)

Находит GType для инициализации GValue этого параметра.

pspec : допустимая структура GParamSpec

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 который использует (вводит) этот параметр

GParamSpecClass

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

enum GParamFlags

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

G_PARAM_READWRITE

#define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE)

GParamFlags значение псевдонима для G_PARAM_READABLE | G_PARAM_WRITABLE.

G_PARAM_STATIC_STRINGS

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

G_PARAM_MASK

#define G_PARAM_MASK (0x000000ff)

Маска содержащая биты GParamSpec.flags которые зарезервированы для GLib.

G_PARAM_USER_SHIFT

#define G_PARAM_USER_SHIFT (8)

Минимальный сдвиг счетчика используемый для флагов определяемых пользователем, сохраняемых в GParamSpec.flags.

g_param_spec_ref ()

GParamSpec* g_param_spec_ref (GParamSpec *pspec);

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

pspec : допустимая структура GParamSpec
Возвращает : GParamSpec которая была помещена в эту функцию

g_param_spec_unref ()

void g_param_spec_unref (GParamSpec *pspec);

Уменьшает количество ссылок pspec.

pspec : допустимая структура GParamSpec

g_param_spec_sink ()

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

g_param_spec_ref_sink ()

GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec);

Удобная функция для создания ссылки и отмены плавающей GParamSpec.

pspec : допустимая структура GParamSpec
Возвращает : GParamSpec которая помещается в функцию

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

g_param_value_set_default ()

void g_param_value_set_default (GParamSpec *pspec, GValue *value);

Устанавливает value в значение по умолчанию как определено в pspec.

pspec : допустимая структура GParamSpec
value : GValue правильного типа для pspec

g_param_value_defaults ()

gboolean g_param_value_defaults (GParamSpec *pspec, GValue *value);

Проверяет содержит ли value значение по умолчанию определённое в pspec.

pspec : допустимая структура GParamSpec
value : GValue правильного типа для pspec
Возвращает : содержит ли value каноническое значение по умолчанию для этой pspec

g_param_value_validate ()

gboolean g_param_value_validate (GParamSpec *pspec, GValue *value);

Гарантирует что содержимое value соответствует спецификации установленной с помощью pspec. Например, GParamSpecInt может потребовать чтобы целочисленные хранящиеся в value были не меньше чем -42 и не больше чем +42. Если целочисленное содержимое value выходит за этот диапазон, оно соответственно изменяется, чтобы результирующее значение вписывалось в диапазон -42 .. +42.

pspec : допустимая структура GParamSpec
value : GValue правильного типа для pspec
Возвращает : необходимо ли изменить value чтобы гарантировать его допустимость

g_param_value_convert ()

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 остаётся нетронутым.

g_param_values_cmp ()

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, для меньше, равно или больше чем результат

g_param_spec_get_name ()

const gchar* g_param_spec_get_name (GParamSpec *pspec);

Возвращает имя GParamSpec.

pspec : допустимая структура GParamSpec
Возвращает : имя pspec.

g_param_spec_get_nick ()

const gchar* g_param_spec_get_nick (GParamSpec *pspec);

Возвращает псевдоним GParamSpec.

pspec : допустимая структура GParamSpec
Возвращает : псевдоним pspec.

g_param_spec_get_blurb ()

const gchar* g_param_spec_get_blurb (GParamSpec *pspec);

Возвращает короткое описание GParamSpec.

pspec : допустимая структура GParamSpec
Возвращает : короткое описание pspec.

g_param_spec_get_qdata ()

gpointer g_param_spec_get_qdata (GParamSpec *pspec, GQuark quark);

Получает назад указатели пользовательских данных сохранённые через g_param_spec_set_qdata().

pspec : допустимая структура GParamSpec
quark : GQuark, именующий указатель пользовательских данных
Возвращает : установленный указатель пользовательских данных, или NULL

g_param_spec_set_qdata ()

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 : непрозрачный указатель пользовательских данных

g_param_spec_set_qdata_full ()

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 необходимо освободить

g_param_spec_steal_qdata ()

gpointer g_param_spec_steal_qdata (GParamSpec *pspec, GQuark quark);

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

pspec : GParamSpec для получения сохраненного указателя пользовательских данных
quark : GQuark, именующий указатель пользовательских данных
Возвращает : установленный указатель пользовательских данных, или NULL

g_param_spec_get_redirect_target ()

GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec);

Если спецификация параметра перенаправила операции в другую спецификацию параметра (paramspec), возвращается эта спецификация параметра. Перенаправление обычно используется для обеспечения новой реализации свойств в производном типе сохраняя все свойства родительского типа. Перенаправление устанавливается созданием свойства типа GParamSpecOverride. Смотрите пример использования этой возможности в g_object_override_property().

pspec : GParamSpec
Возвращает : спецификация параметра в которую переадресованы операции, или NULL если нет.

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

g_param_spec_internal ()

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

GParamSpecTypeInfo

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

g_param_type_register_static ()

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.
Возвращает : Новый идентификатор типа.

GParamSpecPool

typedef struct _GParamSpecPool GParamSpecPool;

GParamSpecPool содержащая накопленные GParamSpec быстрый доступ к которым может осуществляться по имени и владельцу. Реализованное свойство GObject система использует как пул для хранения свойств GParamSpecs всех типовых объектов.

g_param_spec_pool_new ()

GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing);

Создаёт новую GParamSpecPool.

Если type_prefixing это TRUE, поиск во вновь созданном пуле позволит определять владельца как отделённый двоеточием префикс имени свойства, например "GtkContainer:border-width". Эта особенность устарела, поэтому вы должны всегда устанавливать type_prefixing в значение FALSE.

type_prefixing : Поддерживает ли пул имена свойств с типовыми префиксами.
Возвращает : вновь распределённый GParamSpecPool.

g_param_spec_pool_insert ()

void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type);

Вставляет GParamSpec в пул.

pool : GParamSpecPool.
pspec : вставляемая GParamSpec
owner_type : GType идентифицирующий владельца pspec

g_param_spec_pool_remove ()

void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec);

Удаляет GParamSpec из пула.

pool : GParamSpecPool
pspec : GParamSpec для удаления

g_param_spec_pool_lookup ()

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 не найдена.

g_param_spec_pool_list ()

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 в пуле

g_param_spec_pool_list_owned ()

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.

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

g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func()