GtkСтроитель

Определения пользовательского интерфейса 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+ резервирует идентификаторы, начинающиеся и заканчивающиеся символами «___» (три нижних подчёркивания) для собственных целей.

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

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

GVariants могут быть указаны в формате, понимаемом g_variant_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 UI, создавая только запрошенные объекты и объединяя их с текущим содержимым 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 UI, создавая только запрошенные объекты и объединяя их с текущим содержимым 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 UI, создавая только запрошенные объекты и объединяя их с текущим содержимым 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), чтобы просмотреть таблицу символов приложения. Затем он пытается сопоставить имена обработчиков сигналов, указанные в описании интерфейса, с символами в приложении и подключает сигналы. Обратите внимание, что эту функцию можно вызвать только один раз, последующие вызовы ничего не сделают.

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

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

При компиляции приложений для Windows вы должны объявлять обратные вызовы сигналов с G_MODULE_EXPORT, иначе они не будут помещены в таблицу символов. В Linux и Unices это необязательно; приложения следует вместо этого скомпилировать с CFLAGS -Wl,--export-dynamic и связать с 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 в реализации add_child GtkBuildable.