Сигналы

Signals — Средство для настройки поведения объекта и универсальный механизм уведомления

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



#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 - Вызов обработчика объектного метода для сигналов `G_SIGNAL_RUN_FIRST`
	2 - Вызов обычного обеспечиваемого пользователем обработчика сигнала (после флага `FALSE`)
	3 - Вызов обработчика объектного метода для сигналов `G_SIGNAL_RUN_LAST`
	4 - Вызов обеспечиваемых пользователем обработчиков, подключаемых после флага `TRUE`
	5 - Вызов обработчика объектного метода для сигналов `G_SIGNAL_RUN_CLEANUP`

Обеспечиваемые пользователем обработчики сигналов вызываются в том порядке в каком были подключены. Все обработчики могут преждевременно остановить эмиссию сигнала, и любое количество обработчиков может быть подключено, отключено, заблокировано или разблокировано в течение эмиссии сигнала. Есть определённые критерии для пропуска пользовательских обработчиков в стадиях 2 и 4 эмиссии сигнала. Во первых, пользовательские обработчики могут быть блокированы, блокированные обработчики пропускаются в течение вызова callback-функции, для возвращения из "блокированного" состояния, обработчик должен получить разблокировку столько же раз сколько был заблокирован перед этим. Во вторых, в эмиссию сигнала G_SIGNAL_DETAILED, дополнительный "детальный" ("detail") параметр помещаемый в g_signal_emit() должен соответствовать детальному параметру обработчика сигнала текущего субъекта вызова. Спецификация не детального параметра для обработчика сигнала (исключая детальную часть спецификации сигнала на подключение) служит в качестве шаблона соответствующего любому детальному параметру помещаемому в эмиссию сигнала.

Детали

GSignalInvocationHint

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

GSignalAccumulator ()

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` означает продолжение.

GSignalCMarshaller

typedef GClosureMarshal			 GSignalCMarshaller;

Это сигнатура функций маршаллеров, требуемая для маршаллерных массивов значений параметра в эмиссиях сигнала внутри вызовов callback-функций языка С. Это просто псевдоним для GClosureMarshal так как механизм GClosure несёт ответственность за фактический вызов функции для системы сигналов.

GSignalEmissionHook ()

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`, обработчик прерывания сигнала отключается (и уничтожается).

enum GSignalFlags

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`	Сигнал не поддерживает обработчики прерываний эмиссий.

enum GSignalMatchType

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

`G_SIGNAL_MATCH_ID`	Идентификатор сигнала должен быть эквивалентным.
`G_SIGNAL_MATCH_DETAIL`	Детальный параметр сигнала должен быть эквивалентным.
`G_SIGNAL_MATCH_CLOSURE`	Замыкание должно быть тем же самым.
`G_SIGNAL_MATCH_FUNC`	Callback-функция С замыкания должна быть такой же.
`G_SIGNAL_MATCH_DATA`	Данные замыкания должны быть теми же.
`G_SIGNAL_MATCH_UNBLOCKED`	Только разблокированные сигналы могут соответствовать.

GSignalQuery

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

G_SIGNAL_TYPE_STATIC_SCOPE

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

G_SIGNAL_MATCH_MASK

#define G_SIGNAL_MATCH_MASK  0x3f

Маска для всех бит GSignalMatchType.

G_SIGNAL_FLAGS_MASK

#define G_SIGNAL_FLAGS_MASK  0x7f

Маска для всех бит GSignalFlags.

g_signal_new ()

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` :	Количество последующих типовых параметров.
`...` :	список типов, один для каждого параметра.
Возвращает :	идентификатор сигнала

g_signal_newv ()

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` :	массив типов, один для каждого параметра.
Возвращает :	идентификатор сигнала

g_signal_new_valist ()

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, один для каждого параметра.
Возвращает :	идентификатор параметра

g_signal_query ()

void                g_signal_query                      (guint signal_id,
                                                         GSignalQuery *query);

Запрашивает у системы сигналов подробную информацию для определённого сигнала. Эта функция заполняет определённую пользователем структуру информацией для определённого сигнала. Если помещён несуществующий идентификатор сигнала, signal_id член GSignalQuery равен 0. Все заполненные члены сструктуры GSignalQuery должны рассматриваться как константы и должны оставаться нетронутыми.

`signal_id` :	Идентификатор сигнала для которого запрашивается информация.
`query` :	Определённая пользователем структура которая заполняется константными значениями при успешном выполнении.

g_signal_lookup ()

guint               g_signal_lookup                     (const gchar *name,
                                                         GType itype);

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

Также проверяет предков полученного типа.

Смотрите подробности относительно имён сигналов в g_signal_new().

`name` :	имя сигнала.
`itype` :	тип с которым оперирует данный сигнал.
Возвращает :	номер который идентифицирует сигнал, или 0 если сигнал не найден.

g_signal_name ()

const gchar* g_signal_name (guint signal_id);

Находит идентификатор сигнала по его имени.

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

`signal_id` :	номер идентифицирующий сигнал.
Возвращает :	имя сигнала, или `NULL` если номер сигнала был недопустимым.

g_signal_list_ids ()

guint*              g_signal_list_ids                   (GType itype,
                                                         guint *n_ids);

Создаёт список идентификаторов сигнала для определённого типового экземпляра или интерфейса. Дальнейшая информация о сигналах может быть запрошена через g_signal_query().

`itype` :	Типовой экземпляр или интерфейс.
`n_ids` :	Расположение для хранения количества идентификаторов сигнала для `itype`.
Возвращает :	Вновь распределённый массив идентификаторов сигналов.

g_signal_emit ()

void                g_signal_emit                       (gpointer instance,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         ...);

Издаёт сигнал.

Помните что g_signal_emit() сбрасывает возвращаемое значение в значение по умолчанию если нет подключенного обработчика, в отличие от g_signal_emitv().

`instance` :	экземпляр в котором издаётся сигнал.
`signal_id` :	идентификатор сигнала
`detail` :	детальный параметр
`...` :	параметры помещаемые в сигнал, следом расположение для возвращаемого значения. Если возвращаемый тип сигнала G_TYPE_NONE, расположение возвращаемого значения может быть опущено.

g_signal_emit_by_name ()

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, расположение возвращаемого значения может быть опущено.

g_signal_emitv ()

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` :	Расположение для хранения возвращаемого значения эмиссии сигнала.

g_signal_emit_valist ()

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, расположение возвращаемого значения может быть опущено.

g_signal_connect()

#define g_signal_connect(instance, detailed_signal, c_handler, data)

Подключает GCallback функцию к сигналу определённого объекта.

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

`instance` :	экземпляр для подключения.
`detailed_signal` :	строка в форме "signal-name::detail".
`c_handler` :	GCallback для подключения.
`data` :	данные помещаемые в вызов `c_handler`.
Возвращает :	идентификатор обработчика

g_signal_connect_after()

#define g_signal_connect_after(instance, detailed_signal, c_handler, data)

Подключает GCallback функцию к сигналу определённого объекта.

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

`instance` :	экземпляр для подключения.
`detailed_signal` :	строка в форме "signal-name::detail".
`c_handler` :	GCallback для подключения.
`data` :	данные помещаемые в вызов `c_handler`.
Возвращает :	идентификатор обработчика

g_signal_connect_swapped()

#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`.
Возвращает :	идентификатор обработчика

g_signal_connect_object ()

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

enum GConnectFlags

typedef enum
{
  G_CONNECT_AFTER	= 1 << 0,
  G_CONNECT_SWAPPED	= 1 << 1
} GConnectFlags;

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

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

g_signal_connect_data ()

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

g_signal_connect_closure ()

gulong              g_signal_connect_closure            (gpointer instance,
                                                         const gchar *detailed_signal,
                                                         GClosure *closure,
                                                         gboolean after);

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

`instance` :	экземпляр для подключения.
`detailed_signal` :	строка в форме "signal-name::detail".
`closure` :	подключаемое замыкание.
`after` :	вызывается ли обработчик сигнала до или после обработчика по умолчанию.
Возвращает :	идентификатор обработчика

g_signal_connect_closure_by_id ()

gulong              g_signal_connect_closure_by_id      (gpointer instance,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         GClosure *closure,
                                                         gboolean after);

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

`instance` :	экземпляр для подключения.
`signal_id` :	идентификатор сигнала.
`detail` :	детальный параметр.
`closure` :	подключаемое замыкание.
`after` :	вызывается ли обработчик сигнала до или после обработчика по умолчанию.
Возвращает :	идентификатор обработчика

g_signal_handler_block ()

void                g_signal_handler_block              (gpointer instance,
                                                         gulong handler_id);

Блокирует обработчик в экземпляре поэтому он не будет вызываться в течение эмиссии сигнала пока его не разблокируют снова. Таким образом "блокирование" означает временную деактивацию обработчика сигнала, обработчик сигнала должен разблокироваться тоже количество раз сколько был заблокирован до этого чтобы активизироваться снова.

handler_id должен быть допустимым идентификатором обработчика сигнала, подключаемого к сигналу экземпляра.

`instance` :	Экземпляр в котором блокируется обработчик сигнала.
`handler_id` :	Идентификатор обработчика для блокировки.

g_signal_handler_unblock ()

void                g_signal_handler_unblock            (gpointer instance,
                                                         gulong handler_id);

Отменяет эффект вызова g_signal_handler_block(). Блокированный сигнал пропускается в течение эмиссии сигнала и не вызывается, разблокирование (столько же раз сколько он был заблокирован перед этим) переключает состояние "блокирован", поэтому обработчик распознаётся системой сигналов и вызывается в будущей или в текущей эмиссии сигнала (так как порядок в котором обработчики вызываются в течение эмиссии сигнала детерминирован, будет ли запрашиваемый разблокированный обработчик вызван как часть текущей продолжающейся эмиссии сигнала зависит от того как долго эмиссия будет продолжаться).

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

`instance` :	Экземпляр для разблокировки обработчика сигнала.
`handler_id` :	Идентификатор обработчика для разблокировки.

g_signal_handler_disconnect ()

void                g_signal_handler_disconnect         (gpointer instance,
                                                         gulong handler_id);

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

handler_id должен быть допустимым идентификатором обработчика сигнала, подключённым к сигналу экземпляра.

`instance` :	Экземпляр из которого удаляется обработчик сигнала.
`handler_id` :	Идентификатор обработчика для отключения.

g_signal_handler_find ()

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 идентификатор обработчика сигнала для успешного соответствия.

g_signal_handlers_block_matched ()

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` :	Данные замыкания для обработчика.
Возвращает :	Количество блокируемых обработчиков.

g_signal_handlers_unblock_matched ()

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` :	Данные замыкания для обработчиков.
Возвращает :	Количество разблокируемых обработчиков.

g_signal_handlers_disconnect_matched ()

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` :	Данные замыкания для обработчика.
Возвращает :	Количество отключаемых обработчиков.

g_signal_handler_is_connected ()

gboolean            g_signal_handler_is_connected       (gpointer instance,
                                                         gulong handler_id);

Определяет подключен ли обработчик с идентификатором handler_id в instance.

`instance` :	Экземпляр для поиска обрботчика.
`handler_id` :	идентификатор обработчика.
Возвращает :	Подключен ли обработчик с идентификатором `handler_id` в `instance`.

g_signal_handlers_block_by_func()

#define g_signal_handlers_block_by_func(instance, func, data)

Блокирует все обработчики в экземпляре которые соответствуют func и data.

`instance` :	Экземпляр в котором блокируются обработчики.
`func` :	callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий).
`data` :	Данные замыкания обработчика.
Возвращает :	Количество блокированных обработчиков.

g_signal_handlers_unblock_by_func()

#define g_signal_handlers_unblock_by_func(instance, func, data)

Разблокирует все обработчики в экземпляре которые соответствуют func и data.

`instance` :	Экземпляр в котором разблокируются обработчики.
`func` :	callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий).
`data` :	Данные замыкания для обработчика.
Возвращает :	Количество разблокированных обработчиков.

g_signal_handlers_disconnect_by_func()

#define g_signal_handlers_disconnect_by_func(instance, func, data)

Отключаемт все обработчики в экземпляре которые соответствуют func и data.

`instance` :	Экземпляр из которого удаляются обработчики.
`func` :	callback-функция "С" замыкания обработчика (недопустимо для не-C замыканий).
`data` :	Данные замыкания для обработчика.
Возвращает :	Количество удалённых обработчиков.

g_signal_has_handler_pending ()

gboolean            g_signal_has_handler_pending        (gpointer instance,
                                                         guint signal_id,
                                                         GQuark detail,
                                                         gboolean may_be_blocked);

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

Это может быть использовано когда сложно вычислить параметры сигнала. Конструктор класса может не издавать сигнал если к нему всё равно ничего не подключено, таким образом не расходуются ресурсы на формирование параметров.

`instance` :	Объект для поиска сигнала.
`signal_id` :	Идентификатор сигнала.
`detail` :	детальный параметр.
`may_be_blocked` :	должны ли блокированные обработчики рассматриваться как соответствующие.
Возвращает :	`TRUE` если обработчик подключен к сигналу, иначе `FALSE`.

g_signal_stop_emission ()

void                g_signal_stop_emission              (gpointer instance,
                                                         guint signal_id,
                                                         GQuark detail);

Останавливает текущую эмиссию сигнала.

Это предотвратит выполнение метода по умолчанию, если сигнал был G_SIGNAL_RUN_LAST и вы подключились нормально (то есть без флага "after").

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

`instance` :	объект чей обработчик сигнала вы останавливаете.
`signal_id` :	идентификатор сигнала, который возвращает `g_signal_lookup()`.
`detail` :	детальный параметр с которым издаётся сигнал.

g_signal_stop_emission_by_name ()

void                g_signal_stop_emission_by_name      (gpointer instance,
                                                         const gchar *detailed_signal);

Останавливает текущую эмиссию сигнала.

Похожа на g_signal_stop_emission() но самостоятельно определит идентификатор сигнала для вас.

`instance` :	объект чьи обработчики сигнала останавливаются.
`detailed_signal` :	строка в форме "signal-name::detail".

g_signal_override_class_closure ()

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` :	замыкание.

g_signal_chain_from_overridden ()

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` :	Расположение для возвращаемого значения.

g_signal_add_emission_hook ()

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

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

g_signal_parse_name ()

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` содержат допустимые возвращаемые значения.

g_signal_get_invocation_hint ()

GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance);

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

`instance` :	экземпляр для запроса
Возвращает :	подсказка вызова самой внутренней эмиссии сигнала.

g_signal_type_cclosure_new ()

GClosure*           g_signal_type_cclosure_new          (GType itype,
                                                         guint struct_offset);

Создаёт новое замыкание которое вызывает функцию найденную смещением struct_offset в структуре класса интерфейса или классифицированного типа идентифицируемого itype.

`itype` :	GType идентифицирующий интерфейс или классифицируемый тип
`struct_offset` :	смещение функции члена классовой сструктуры `itype` которая вызывается новым замыканием
Возвращает :	новое GCClosure

g_signal_accumulator_true_handled ()

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
Top \| Описание