GtkBuilder

Определения пользовательского интерфейса GtkBuilder

GtkBuilder парсит текстовые описания пользовательских интерфейсов, которые заданы в формате XML, приблизительно описываемом схемой RELAX NG ниже. Мы будем называть эти описания "определениями пользовательского интерфейса GtkBuilder" или просто "определениями интерфейса", если контекст понятен. Не путайте определения пользовательского интерфейса GtkBuilder с определениями интерфейса GtkUIManager, которые ограничены в своём применении. Обычно в качестве расширения файла для файлов, содержащих определения пользовательского интерфейса GtkBuilder, используется .ui.

Компактный синтаксис RELAX NG

Главный элемент — <interface>. Он необязательно принимает атрибут «domain», который заставит билдер искать переведённые строки, используя dgettext() в заданном домене. Это также можно сделать, вызвав gtk_builder_set_translation_domain() в билдере. Объекты описываются элементами <object>, которые могут содержать элементы <property> для установки свойств, элементы <signal> для подключения сигналов к обработчикам и элементы <child>, которые описывают дочерние объекты (чаще всего виджеты внутри контейнера, но также, например, действия в группе действий или столбцы в модели дерева). Элемент <child> содержит элемент <object>, который описывает дочерний объект. Целевые версии инструментария описываются элементами <requires>, атрибут «lib» указывает библиотеку виджетов (в настоящее время единственное поддерживаемое значение — «gtk+»), а атрибут «version» указывает целевую версию в формате «<major>.<minor>». Билдер выдаст ошибку, если требования к версии не будут соблюдены.

Как правило, конкретный тип объекта, представленный элементом <object>, задаётся атрибутом «class». Если тип ещё не загружен, GTK+ пытается найти функцию get_type() из имени класса, применяя эвристику. Это работает в большинстве случаев, но при необходимости можно явно указать имя функции get_type() с помощью атрибута "type-func". В качестве специального случая GtkBuilder позволяет использовать объект, созданный GtkUIManager в другой части определения пользовательского интерфейса, указав идентификатор GtkUIManager в атрибуте «constructor» и имя объекта в атрибуте «id».

Объектам может быть присвоено имя с помощью атрибута «id», что позволяет приложению извлекать их из билдера с помощью gtk_builder_get_object(). Идентификатор также необходим для использования объекта в качестве значения свойства в других частях определения пользовательского интерфейса. GTK+ резервирует идентификаторы, начинающиеся и заканчивающиеся подчёркиваниями (3 подчёркивания), для собственных нужд.

Установка свойств объектов довольно проста с помощью элемента <property>: атрибут «name» указывает имя свойства, а содержимое элемента указывает значение. Если атрибут «translatable» имеет значение true, GTK+ использует gettext() (или dgettext() если в билдере установлен домен перевода) для поиска перевода значения. Это происходит до разбора значения, поэтому его можно использовать для свойств любого типа, но он, вероятно, наиболее полезен для строковых свойств. Также можно указать контекст для устранения неоднозначности коротких строк и комментарии, которые могут помочь переводчикам.

GtkBuilder может парсить текстовые представления для наиболее распространённых типов свойств: символов, строк, целых чисел, чисел с плавающей точкой, логических значений (строки типа «TRUE», «t», «yes», «y», «1» интерпретируются как TRUE, строки типа «FALSE», «f», «no», «n», «0» интерпретируются как FALSE), перечислений (могут быть указаны по имени, нику или целому значению), флагов (могут быть указаны по имени, нику, целому значению, необязательно комбинируясь с «|», например, «GTK_VISIBLE|GTK_REALIZED») и цветов (в формате, понятном gdk_rgba_parse()). Pixbuфы могут быть указаны как имя файла изображения для загрузки. Объекты могут быть указаны по имени и по умолчанию относятся к объектам, объявленным в локальном фрагменте XML, и к объектам, доступным через gtk_builder_expose_object().

В общем случае GtkBuilder допускает ссылки на вперёд на объекты — объявленные в локальном XML; объект не должен быть создан, прежде чем на него можно будет сослаться. Исключением из этого правила является то, что объект должен быть создан, прежде чем он может быть использован в качестве значения свойства, предназначенного только для построения.

Также возможно привязать значение свойства к значению свойства другого объекта, используя атрибуты «bind-source» для указания исходного объекта привязки, «bind-property» для указания исходного свойства и необязательно «bind-flags» для указания флагов привязки. Внутренне билдер реализует это с помощью объектов GBinding. Более подробная информация представлена в g_object_bind_property().

Обработчики сигналов настраиваются с помощью элемента <signal>. Атрибут «name» указывает имя сигнала, а атрибут «handler» указывает функцию для подключения к сигналу. По умолчанию GTK+ пытается найти обработчик, используя g_module_symbol(), но это можно изменить, передав пользовательскую функцию GtkBuilderConnectFunc в gtk_builder_connect_signals_full(). Остальные атрибуты «after», «swapped» и «object» имеют тот же смысл, что и соответствующие параметры функций g_signal_connect_object() или g_signal_connect_data(). Атрибут «last_modification_time» также разрешён, но он не имеет значения для билдера.

Иногда необходимо обратиться к виджетам, которые были неявно созданы GTK+ в качестве части составного виджета, для установки свойств на них или для добавления дополнительных дочерних элементов (например, vbox диалога GtkDialog). Этого можно достичь, установив свойство «internal-child» элемента <child> в значение true. Обратите внимание, что GtkBuilder всё ещё требует элемента <object> для внутреннего дочернего элемента, даже если он уже был создан.

У ряда виджетов есть разные места, где можно добавить дочерний элемент (например, вкладки по сравнению с содержимым страницы в книгах). Это может быть отражено в определении пользовательского интерфейса с помощью атрибута «type» в элементе <child>. Возможные значения атрибута «type» описаны в разделах, описывающих специфичные для виджетов части определений пользовательского интерфейса.

Определение пользовательского интерфейса GtkBuilder

<interface>
<object class="GtkDialog" id="dialog1">
<child internal-child="vbox">
<object class="GtkBox" id="vbox1">
<property name="border-width">10</property>
<child internal-child="action_area">
<object class="GtkButtonBox" id="hbuttonbox1">
<property name="border-width">20</property>
<child>
<object class="GtkButton" id="ok_button">
<property name="label">gtk-ok</property>
<property name="use-stock">TRUE</property>
<signal name="clicked" handler="ok_button_clicked"/>
</object>
</child>
</object>
</child>
</object>
</child>
</object>
</interface>

Помимо этой общей структуры, несколько классов объектов определяют собственные фрагменты XML DTD для заполнения заполнительных элементов ANY в вышеприведённом DTD. Обратите внимание, что пользовательский элемент в элементе <child> анализируется обработчиком пользовательских тегов родительского объекта, а пользовательский элемент в элементе <object> — обработчиком пользовательских тегов объекта.

Эти фрагменты XML поясняются в документации соответствующих объектов.

Кроме того, начиная с версии 3.10, для определения компонентов виджета класса был добавлен специальный тег <template>. Подробности см. в документации GtkWidget.

GtkBuilderConnectFunc ()

void
(*GtkBuilderConnectFunc) (GtkBuilder *builder,
                          GObject *object,
                          const gchar *signal_name,
                          const gchar *handler_name,
                          GObject *connect_object,
                          GConnectFlags flags,
                          gpointer user_data);

Это сигнатура функции, используемой для подключения сигналов. Она используется методами gtk_builder_connect_signals() и gtk_builder_connect_signals_full(). Она предназначена в основном для языковых библиотек интерпретируемых языков, но может быть полезна, когда программист хочет больше контролировать процесс подключения сигналов. Обратите внимание, что эту функцию можно вызвать только один раз, последующие вызовы ничего не сделают.

С: 2.12

gtk_builder_new ()

GtkBuilder *
gtk_builder_new (void);

Создаёт новый пустой объект билдера.

Эта функция полезна только если вы планируете выполнить несколько вызовов gtk_builder_add_from_file(), gtk_builder_add_from_resource() или gtk_builder_add_from_string() для объединения нескольких описаний пользовательского интерфейса в один билдер.

Большинство пользователей, вероятно, захотят использовать gtk_builder_new_from_file(), gtk_builder_new_from_resource() или gtk_builder_new_from_string().

С: 2.12

gtk_builder_new_from_file ()

GtkBuilder *
gtk_builder_new_from_file (const gchar *filename);

Создаёт определение пользовательского интерфейса GtkBuilder из файла filename .

Если возникает ошибка при открытии файла или разборе описания, программа завершится аварийно. Вы должны пытаться парсить описания пользовательского интерфейса только из файлов, поставляемых с вашей программой.

С: 3.10

gtk_builder_new_from_resource ()

GtkBuilder *
gtk_builder_new_from_resource (const gchar *resource_path);

Создаёт определение пользовательского интерфейса GtkBuilder по пути resource_path .

Если возникает ошибка при поиске ресурса или разборе описания, программа завершится аварийно.

С: 3.10

gtk_builder_new_from_string ()

GtkBuilder *
gtk_builder_new_from_string (const gchar *string,
                             gssize length);

Создаёт пользовательский интерфейс, описанный в string (в формате определения пользовательского интерфейса GtkBuilder).

Если string имеет завершение NULL, тогда length должно быть -1. Если length не равно -1, то это длина string .

Если при разборе string возникает ошибка, программа завершится аварийно. Не пытайтесь парсить описания пользовательского интерфейса из ненадежных источников.

С: 3.10

gtk_builder_add_callback_symbol ()

void
gtk_builder_add_callback_symbol (GtkBuilder *builder,
                                 const gchar *callback_name,
                                 GCallback callback_symbol);

Добавляет callback_symbol в область действия builder под заданным callback_name .

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

С: 3.10

gtk_builder_add_callback_symbols ()

void
gtk_builder_add_callback_symbols (GtkBuilder *builder,
                                  const gchar *first_callback_name,
                                  GCallback first_callback_symbol,
                                  ...);

Функция для удобства добавления многих обратных вызовов вместо вызова gtk_builder_add_callback_symbol() для каждого символа.

С: 3.10

gtk_builder_lookup_callback_symbol ()

GCallback
gtk_builder_lookup_callback_symbol (GtkBuilder *builder,
                                    const gchar *callback_name);

Извлекает символ, ранее добавленный в builder с помощью gtk_builder_add_callback_symbols()

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

[skip]

С версии: 3.10

gtk_builder_add_from_file ()

guint
gtk_builder_add_from_file (GtkBuilder *builder,
                           const gchar *filename,
                           GError **error);

Разбирает файл, содержащий определение пользовательского интерфейса GtkBuilder, и объединяет его с текущим содержимым builder .

Большинство пользователей, вероятно, захотят использовать gtk_builder_new_from_file().

Если произошла ошибка, будет возвращено 0, и error получит GError из области GTK_BUILDER_ERROR, G_MARKUP_ERROR или G_FILE_ERROR.

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

С версии: 2.12

gtk_builder_add_from_resource ()

guint
gtk_builder_add_from_resource (GtkBuilder *builder,
                               const gchar *resource_path,
                               GError **error);

Разбирает ресурсный файл, содержащий определение пользовательского интерфейса GtkBuilder, и объединяет его с текущим содержимым builder .

Большинство пользователей, вероятно, захотят использовать gtk_builder_new_from_resource().

Если произошла ошибка, будет возвращено 0, и error получит GError из области GTK_BUILDER_ERROR, G_MARKUP_ERROR или G_RESOURCE_ERROR.

Вряд ли стоит пытаться обрабатывать ошибки этого вызова. Единственное разумное действие при обнаружении ошибки — вызвать g_error().

С версии: 3.4

gtk_builder_add_from_string ()

guint
gtk_builder_add_from_string (GtkBuilder *builder,
                             const gchar *buffer,
                             gsize length,
                             GError **error);

Разбирает строку, содержащую определение пользовательского интерфейса GtkBuilder, и объединяет её с текущим содержимым builder .

Большинство пользователей, вероятно, захотят использовать gtk_builder_new_from_string().

При ошибке будет возвращено 0, и error получит GError из области GTK_BUILDER_ERROR, G_MARKUP_ERROR или G_VARIANT_PARSE_ERROR.

Вряд ли стоит пытаться обрабатывать ошибки этого вызова. Единственное разумное действие при обнаружении ошибки — вызвать g_error().

С версии: 2.12

gtk_builder_add_objects_from_file ()

guint
gtk_builder_add_objects_from_file (GtkBuilder *builder,
                                   const gchar *filename,
                                   gchar **object_ids,
                                   GError **error);

Парсит файл, содержащий определение пользовательского интерфейса GtkBuilder, создавая только запрошенные объекты и объединяя их с текущим содержимым builder .

При ошибках возвращается 0, и error получает GError из области GTK_BUILDER_ERROR, G_MARKUP_ERROR или G_FILE_ERROR.

Если вы добавляете объект, зависящий от объекта, который не является его потомком (например, GtkTreeView, зависящий от его GtkTreeModel), необходимо явно указать все из них в object_ids .

С: 2.14

gtk_builder_add_objects_from_string ()

guint
gtk_builder_add_objects_from_string (GtkBuilder *builder,
                                     const gchar *buffer,
                                     gsize length,
                                     gchar **object_ids,
                                     GError **error);

Парсит строку, содержащую определение пользовательского интерфейса GtkBuilder, создавая только запрошенные объекты и объединяя их с текущим содержимым builder .

При ошибках возвращается 0, и error получает GError из области GTK_BUILDER_ERROR или G_MARKUP_ERROR.

Если вы добавляете объект, зависящий от объекта, который не является его потомком (например, GtkTreeView, зависящий от его GtkTreeModel), необходимо явно указать все из них в object_ids .

С: 2.14

gtk_builder_add_objects_from_resource ()

guint
gtk_builder_add_objects_from_resource (GtkBuilder *builder,
                                       const gchar *resource_path,
                                       gchar **object_ids,
                                       GError **error);

Парсит ресурсный файл, содержащий определение пользовательского интерфейса GtkBuilder, создавая только запрошенные объекты и объединяя их с текущим содержимым builder .

При ошибках возвращается 0, и error получает GError из области GTK_BUILDER_ERROR, G_MARKUP_ERROR или G_RESOURCE_ERROR.

Если вы добавляете объект, зависящий от объекта, который не является его потомком (например, GtkTreeView, зависящий от его GtkTreeModel), необходимо явно указать все из них в object_ids .

С: 3.4

gtk_builder_extend_with_template ()

guint
gtk_builder_extend_with_template (GtkBuilder *builder,
                                  GtkWidget *widget,
                                  GType template_type,
                                  const gchar *buffer,
                                  gsize length,
                                  GError **error);

Основной приватный входной пункт для построения составных контейнерных компонентов из шаблона XML.

Экспортировано исключительно для проверки шаблонов инструментом gtk-builder-tool, приложениям нет необходимости вызывать эту функцию.

gtk_builder_get_object ()

GObject *
gtk_builder_get_object (GtkBuilder *builder,
                        const gchar *name);

Получает объект с именем name. Обратите внимание, что эта функция не увеличивает счётчик ссылок возвращаемого объекта.

С момента: 2.12

gtk_builder_get_objects ()

GSList *
gtk_builder_get_objects (GtkBuilder *builder);

Получает все объекты, созданные builder. Обратите внимание, что эта функция не увеличивает счётчики ссылок возвращённых объектов.

С момента: 2.12

gtk_builder_expose_object ()

void
gtk_builder_expose_object (GtkBuilder *builder,
                           const gchar *name,
                           GObject *object);

Добавляет object в пул объектов builder, чтобы его можно было использовать, как и любой другой объект, созданный конструктором.

С момента: 3.8

gtk_builder_connect_signals ()

void
gtk_builder_connect_signals (GtkBuilder *builder,
                             gpointer user_data);

Этот метод является более простым вариантом gtk_builder_connect_signals_full(). Он использует символы, явно добавленные в builder с помощью предыдущих вызовов gtk_builder_add_callback_symbol(). В случае, если символы не добавлены явно, он использует возможности интроспекции GModule (открывая модуль NULL), чтобы просмотреть таблицу символов приложения. Отсюда он пытается сопоставить имена обработчиков сигналов, указанные в описании интерфейса, с символами в приложении и подключает сигналы. Обратите внимание, что эту функцию можно вызвать только один раз, последующие вызовы ничего не сделают.

Обратите внимание, что, если gtk_builder_add_callback_symbol() не вызывается для всех сигнальных обратных вызовов, на которые ссылается загруженный XML, эта функция потребует поддержки GModule на платформе.

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

При компиляции приложений для Windows вы должны объявлять сигнальные обратные вызовы с G_MODULE_EXPORT, иначе они не будут помещены в таблицу символов. В Linux и Unix это необязательно; приложения вместо этого должны быть скомпилированы с флагом -Wl,--export-dynamic CFLAGS и связаны с gmodule-export-2.0.

С момента: 2.12

gtk_builder_connect_signals_full ()

void
gtk_builder_connect_signals_full (GtkBuilder *builder,
                                  GtkBuilderConnectFunc func,
                                  gpointer user_data);

Эта функция может быть рассмотрена как версия связывания интерпретируемого языка gtk_builder_connect_signals(), за исключением того, что она не требует GModule для корректной работы.

С момента: 2.12

gtk_builder_set_translation-domain ()

void
gtk_builder_set_translation_domain (GtkBuilder *builder,
                                    const gchar *domain);

Устанавливает домен перевода для builder. См. свойство “translation-domain”.

С момента: 2.12

gtk_builder_get_translation-domain ()

const gchar *
gtk_builder_get_translation_domain (GtkBuilder *builder);

Получает домен перевода для builder.

С момента: 2.12

gtk_builder_set_application ()

void
gtk_builder_set_application (GtkBuilder *builder,
                             GtkApplication *application);

Устанавливает приложение, связанное с builder.

Вам нужна эта функция только если в вашем процессе существует более одного GApplication. application не может быть NULL.

С момента: 3.10

gtk_builder_get_application ()

GtkApplication *
gtk_builder_get_application (GtkBuilder *builder);

Получает связанное с билдером приложение GtkApplication.

Приложение GtkApplication используется для создания прокси-сервисов действий, как запрошено из XML, которое загружает билдер.

По умолчанию билдер использует приложение по умолчанию: то, которое из g_application_get_default(). Если вы хотите использовать другое приложение для построения прокси-сервисов, используйте gtk_builder_set_application().

С: 3.10

gtk_builder_get_type_from_name ()

GType
gtk_builder_get_type_from_name (GtkBuilder *builder,
                                const char *type_name);

Ищет тип по имени, используя виртуальную функцию, которой обладает GtkBuilder для этой цели. Это используется в основном при реализации интерфейса GtkBuildable для определённого типа.

С: 2.12

gtk_builder_value_from_string ()

gboolean
gtk_builder_value_from_string (GtkBuilder *builder,
                               GParamSpec *pspec,
                               const gchar *string,
                               GValue *value,
                               GError **error);

Эта функция разбирает значение из строки. Эта функция вызывает g_value_init() для аргумента value, поэтому предварительная инициализация не требуется.

Эта функция может обрабатывать значения типа char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, GdkColor, GdkRGBA и GtkAdjustment. Поддержка значений типа GtkWidget ещё предстоит.

При ошибках возвращается FALSE, и error будет назначен GError из области GTK_BUILDER_ERROR.

С: 2.12

gtk_builder_value_from_string_type ()

gboolean
gtk_builder_value_from_string_type (GtkBuilder *builder,
                                    GType type,
                                    const gchar *string,
                                    GValue *value,
                                    GError **error);

Как gtk_builder_value_from_string(), эта функция разбирает значение из строки, но принимает GType вместо GParamSpec. Эта функция вызывает g_value_init() для аргумента value, поэтому предварительная инициализация не требуется.

При ошибках возвращается FALSE, и error будет назначен GError из области GTK_BUILDER_ERROR.

С: 2.12

GTK_BUILDER_WARN_INVALID_CHILD_TYPE()

#define             GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type)

Этот макрос должен использоваться для вывода предупреждения об неожиданном значении type в реализации GtkBuildable add_child.