GtkUIManager
GtkUIManager — Создание меню и панелей инструментов по описанию XML
Функции
Свойства
| gboolean | add-tearoffs | Чтение/Запись |
| gchar * | ui | Чтение |
Сигналы
| void | actions-changed | Без рекурсии |
| void | add-widget | Без рекурсии |
| void | connect-proxy | Без рекурсии |
| void | disconnect-proxy | Без рекурсии |
| void | post-activate | Без рекурсии |
| void | pre-activate | Без рекурсии |
Типы и значения
| struct | GtkUIManager |
| enum | GtkUIManagerItemType |
Иерархия объектов
GObject ╰── GtkUIManager
Реализованные интерфейсы
GtkUIManager реализует GtkBuildable.
Файлы заголовков
#include <gtk/gtk.h>
Описание
Класс GtkUIManager строит пользовательский интерфейс (меню и панели инструментов) по одному или нескольким определениям интерфейса, которые ссылаются на действия из одной или нескольких групп действий.
Определения интерфейса
Определения интерфейса задаются в формате XML, который можно примерно описать с помощью следующего DTD.
Не путайте определения интерфейса GtkUIManager, описанные здесь, с определениями интерфейса GtkBuilder с аналогичным названием определения интерфейса GtkBuilder.
Существуют некоторые дополнительные ограничения, помимо тех, что указаны в DTD, например, каждый элемент панели инструментов должен иметь панель инструментов в своем предке, а каждый элемент меню должен иметь главную панель меню или всплывающее меню в своем предке. Так как для разбора описания интерфейса используется GMarkupParser, оно должно быть не только корректным XML, но и корректным разметкой.
Если имя не указано, оно по умолчанию соответствует имени действия. Если действие также не указано, используется имя элемента. Атрибуты name и action не должны содержать символов «/» после разбора (так как это нарушит поиск пути) и должны быть применимы в качестве атрибутов XML, когда заключены в двойные кавычки, поэтому они не должны содержать символы «"» или ссылки на сущность ".
Определение интерфейса
Построенная иерархия виджетов очень похожа на древовидную структуру элементов XML, за исключением того, что заглушки объединяются с родительскими элементами. Соответствие элементов XML виджетам должно быть почти очевидным:
-
menubar
главная панель меню GtkMenuBar
-
toolbar
панель инструментов GtkToolbar
-
popup
главное всплывающее меню GtkMenu
-
menu
меню GtkMenu, прикрепленное к элементу меню
-
menuitem
подкласс GtkMenuItem, точный тип зависит от действия
-
toolitem
подкласс GtkToolItem, точный тип зависит от действия. Обратите внимание, что элементы toolitem могут содержать элемент меню, только если соответствующее действие указывает GtkMenuToolButton в качестве прокси.
-
separator
элемент разделителя GtkSeparatorMenuItem или GtkSeparatorToolItem
-
accelerator
горячая клавиша
Атрибут «position» определяет, где построенный виджет позиционируется относительно своих соседей в частично построенном дереве. Если это «top», виджет добавляется в начало, иначе — в конец.
Объединение интерфейсов
Самая примечательная особенность GtkUIManager заключается в том, что он может наложить набор элементов меню и элементов панели инструментов друг на друга и позже их разъединить.
Объединение выполняется на основе имен элементов XML. Каждый элемент идентифицируется путем, который состоит из имен его предков, разделенных слешами. Например, элемент меню с именем «Left» в примере выше имеет путь /ui/menubar/JustifyMenu/Left, а элемент панели инструментов с тем же именем имеет путь /ui/toolbar1/JustifyToolItems/Left.
Горячие клавиши
У каждого действия есть путь горячей клавиши. Горячие клавиши устанавливаются вместе с прокси-элементами меню, но их также можно явно добавить с помощью элементов <accelerator> в определении интерфейса. Это позволяет иметь горячие клавиши для действий даже если у них нет видимых прокси.
Умные разделители
Разделители, созданные классом GtkUIManager, «умные», т. е. они не отображаются в интерфейсе, если они не оказываются между двумя видимыми элементами меню или панели инструментов. Разделители, которые расположены в самом начале или конце содержащего их меню или панели инструментов, или несколько разделителей рядом друг с другом, скрываются. Это полезная функция, так как объединение элементов интерфейса из нескольких источников может затруднить или сделать невозможным предварительно определить, окажется ли разделитель в таком неудачном положении.
Для разделителей на панелях инструментов можно установить expand="true", чтобы превратить их из небольшого видимого разделителя в расширяющийся невидимый. Элементы панели инструментов, следующие за расширяющимся разделителем, фактически выравниваются по правому краю.
Пустые меню
Всплывающие меню представляют аналогичные проблемы разделителям в связи с объединением. Невозможно заранее узнать, окажутся ли они пустыми после объединения. Класс GtkUIManager предлагает два способа обработки пустых всплывающих меню:
спрятать их, скрыв элемент меню, к которому они прикреплены
добавить неактивный элемент «Пусто»
Поведение выбирается на основе свойства «hide_if_empty» действия, к которому относится всплывающее меню.
GtkUIManager как GtkBuildable
Реализация GtkUIManager интерфейса GtkBuildable принимает объекты GtkActionGroup в качестве элементов <child> в определениях интерфейса.
Определение интерфейса GtkUIManager, описанное выше, может быть вложено в элемент <object> GtkUIManager в определении интерфейса GtkBuilder.
Виджеты, которые строятся классом GtkUIManager, могут быть встроены в другие части построенного пользовательского интерфейса с помощью атрибута «constructor». См. пример ниже.
Встроенное определение интерфейса GtkUIManager
Функции
gtk_ui_manager_new ()
GtkUIManager *
gtk_ui_manager_new (void); gtk_ui_manager_new устарела с версии 3.10 и не должна использоваться в новом коде.
Создаёт новый объект менеджера пользовательского интерфейса.
Возвращаемое значение
новый объект менеджера пользовательского интерфейса.
С версии: 2.4
gtk_ui_manager_set_add_tearoffs ()
void gtk_ui_manager_set_add_tearoffs (GtkUIManager *manager,gboolean add_tearoffs);
gtk_ui_manager_set_add_tearoffs устарела с версии 3.4 и не должна использоваться в новом коде.
Вспомогательные меню устарели и не должны использоваться в новом коде.
Устанавливает свойство «add_tearoffs», которое контролирует, будут ли в меню, сгенерированные этим GtkUIManager, элементы вспомогательных меню.
Обратите внимание, что это относится только к обычным меню. Сгенерированные всплывающие меню никогда не имеют элементов вспомогательных меню.
Параметры
manager | объект GtkUIManager | |
add_tearoffs | добавлять ли элементы вспомогательных меню |
С версии: 2.4
gtk_ui_manager_get_add_tearoffs ()
gboolean
gtk_ui_manager_get_add_tearoffs (GtkUIManager *manager); gtk_ui_manager_get_add_tearoffs устарела с версии 3.4 и не должна использоваться в новом коде.
Вспомогательные меню устарели и не должны использоваться в новом коде.
Возвращает значение, указывающее, будут ли в меню, сгенерированные этим GtkUIManager, элементы вспомогательных меню.
Параметры
manager | объект GtkUIManager |
Возвращаемое значение
добавлять ли элементы вспомогательных меню
С версии: 2.4
gtk_ui_manager_insert_action_group ()
void gtk_ui_manager_insert_action_group (GtkUIManager *manager,GtkActionGroup *action_group,gint pos);
gtk_ui_manager_insert_action_group устарела с версии 3.10 и не должна использоваться в новом коде.
Вставляет группу действий в список групп действий, связанных с manager. Действия в более ранних группах скрывают действия с тем же именем в более поздних группах.
Если pos больше, чем количество групп действий в manager, или отрицательно, action_group будет вставлено в конец внутреннего списка.
Параметры
manager | объект GtkUIManager | |
action_group | группа действий, подлежащая вставке | |
pos | позиция, в которую будет вставлена группа. |
С версии: 2.4
gtk_ui_manager_remove_action_group ()
void gtk_ui_manager_remove_action_group (GtkUIManager *manager,GtkActionGroup *action_group);
gtk_ui_manager_remove_action_group устарела с версии 3.10 и не должна использоваться в новом коде.
Удаляет группу действий из списка групп действий, связанных с manager.
Параметры
manager | объект GtkUIManager | |
action_group | группа действий, подлежащая удалению |
С версии: 2.4
gtk_ui_manager_get_action_groups ()
GList *
gtk_ui_manager_get_action_groups (GtkUIManager *manager); gtk_ui_manager_get_action_groups устарела с версии 3.10 и не должна использоваться в новом коде.
Возвращает список групп действий, связанных с manager.
Параметры
manager | объект GtkUIManager |
Возвращаемое значение
GList групп действий. Список принадлежит GTK+ и не должен изменяться.
[element-type GtkActionGroup][transfer none]
С версии: 2.4
gtk_ui_manager_get_accel_group ()
GtkAccelGroup *
gtk_ui_manager_get_accel_group (GtkUIManager *manager); gtk_ui_manager_get_accel_group устарела с версии 3.10 и не должна использоваться в новом коде.
Возвращает GtkAccelGroup, связанный с manager.
Параметры
manager | объект GtkUIManager |
С версии: 2.4
gtk_ui_manager_get_widget ()
GtkWidget * gtk_ui_manager_get_widget (GtkUIManager *manager,const gchar *path);
gtk_ui_manager_get_widget устарела с версии 3.10 и не должна использоваться в новом коде.
Ищет виджет по пути. Путь состоит из имён, указанных в XML-описании пользовательского интерфейса, разделённых символом «/». Элементы, у которых нет атрибутов имени или действия в XML (например, <popup>), могут быть адресованы по имени XML-элемента (например, "popup"). Корневой элемент ("/ui") может быть опущен в пути.
Обратите внимание, что виджет, найденный по пути, заканчивающемуся элементом <menu>, является элементом меню, к которому прикреплено меню, а не самим меню.
Также обратите внимание, что виджеты, созданные менеджером пользовательского интерфейса, не привязаны к жизненному циклу менеджера пользовательского интерфейса. Если вы добавляете виджеты, возвращаемые этой функцией, в какой-либо контейнер или явно ссылаетесь на них, они будут существовать после уничтожения менеджера пользовательского интерфейса.
Параметры
manager | объект GtkUIManager | |
path | путь |
С версии: 2.4
gtk_ui_manager_get_toplevels ()
GSList * gtk_ui_manager_get_toplevels (GtkUIManager *manager,GtkUIManagerItemType types);
gtk_ui_manager_get_toplevels устарела с версии 3.10 и не должна использоваться в новом коде.
Получает список всех виджетов верхнего уровня заданных типов.
Параметры
manager | объект GtkUIManager | |
types | указывают типы виджетов верхнего уровня, которые необходимо включить. Разрешённые типы: GTK_UI_MANAGER_MENUBAR, GTK_UI_MANAGER_TOOLBAR и GTK_UI_MANAGER_POPUP. |
Возвращаемое значение
новый, выделенный GSList всех виджетов верхнего уровня указанных типов. Освободите возвращённый список с помощью g_slist_free().
[element-type GtkWidget][transfer container]
С версии: 2.4
gtk_ui_manager_get_action ()
GtkAction * gtk_ui_manager_get_action (GtkUIManager *manager,const gchar *path);
gtk_ui_manager_get_action устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Ищет действие, следуя по пути. См. gtk_ui_manager_get_widget() для получения дополнительной информации о путях.
Параметры
manager | объект GtkUIManager | |
path | путь |
Возвращаемое значение
действие, чья прокси-виджет найдена путем следования по пути, или NULL, если такой виджет не найден.
[transfer none]
С: 2.4
gtk_ui_manager_add_ui_from_resource ()
guint gtk_ui_manager_add_ui_from_resource (GtkUIManager *manager,const gchar *resource_path,GError **error);
gtk_ui_manager_add_ui_from_resource устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Парсит файл ресурсов, содержащий определение пользовательского интерфейса (определение UI), и объединяет его с текущим содержимым manager .
Параметры
manager | объект GtkUIManager | |
resource_path | путь к файлу ресурсов для парсинга | |
error | место для возврата ошибки |
Возвращаемое значение
Идентификатор объединения объединенного UI. Идентификатор объединения можно использовать для разрыва объединения UI с помощью gtk_ui_manager_remove_ui(). В случае ошибки возвращается 0.
С: 3.4
gtk_ui_manager_add_ui_from_string ()
guint gtk_ui_manager_add_ui_from_string (GtkUIManager *manager,const gchar *buffer,gssize length,GError **error);
gtk_ui_manager_add_ui_from_string устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Парсит строку, содержащую определение пользовательского интерфейса (определение UI), и объединяет его с текущим содержимым manager. Если отсутствует элемент <ui>, он будет добавлен.
Параметры
manager | объект GtkUIManager | |
buffer | строка для парсинга | |
length | длина | |
error | место для возврата ошибки |
Возвращаемое значение
Идентификатор объединения объединенного UI. Идентификатор объединения можно использовать для разрыва объединения UI с помощью gtk_ui_manager_remove_ui(). В случае ошибки возвращается 0.
С: 2.4
gtk_ui_manager_add_ui_from_file ()
guint gtk_ui_manager_add_ui_from_file (GtkUIManager *manager,const gchar *filename,GError **error);
gtk_ui_manager_add_ui_from_file устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Парсит файл, содержащий определение пользовательского интерфейса (определение UI), и объединяет его с текущим содержимым manager .
Параметры
manager | объект GtkUIManager | |
filename | имя файла для парсинга. | [type filename] |
error | место для возврата ошибки |
Возвращаемое значение
Идентификатор объединения объединенного UI. Идентификатор объединения можно использовать для разрыва объединения UI с помощью gtk_ui_manager_remove_ui(). В случае ошибки возвращается 0.
С: 2.4
gtk_ui_manager_new_merge_id ()
guint
gtk_ui_manager_new_merge_id (GtkUIManager *manager); gtk_ui_manager_new_merge_id устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Возвращает свободный идентификатор объединения, подходящий для использования с gtk_ui_manager_add_ui().
Параметры
manager | объект GtkUIManager |
Возвращаемое значение
свободный идентификатор объединения.
С: 2.4
gtk_ui_manager_add_ui ()
void gtk_ui_manager_add_ui (GtkUIManager *manager,guint merge_id,const gchar *path,const gchar *name,const gchar *action,GtkUIManagerItemType type,gboolean top);
gtk_ui_manager_add_ui устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Добавляет элемент UI в текущее содержимое manager.
Если type равно GTK_UI_MANAGER_AUTO, GTK+ вставляет элемент меню, элемент инструмента или разделитель, если такой элемент можно вставить в указанное место path. В противном случае, type должен указывать элемент, который можно вставить в место, определенное path.
Если path указывает на элемент меню или инструмента, новый элемент будет вставлен перед или после этого элемента в зависимости от top.
Параметры
manager | объект GtkUIManager | |
merge_id | идентификатор объединения объединенного UI, см. | |
path | путь | |
name | имя добавляемого элемента UI | |
action | имя действия, подлежащего проксированию, или | [allow-none] |
type | тип добавляемого элемента UI. | |
top | если |
С: 2.4
gtk_ui_manager_remove_ui ()
void gtk_ui_manager_remove_ui (GtkUIManager *manager,guint merge_id);
gtk_ui_manager_remove_ui устарело начиная с версии 3.10 и не должно использоваться в новом коде.
Разъединяет часть содержимого manager, идентифицируемую по merge_id.
Параметры
manager | объект GtkUIManager | |
merge_id | идентификатор объединения, возвращаемый функцией |
С: 2.4
gtk_ui_manager_get_ui ()
gchar *
gtk_ui_manager_get_ui (GtkUIManager *manager); gtk_ui_manager_get_ui устарело начиная с версии 3.10 и не должно использоваться в новом коде.
Создаёт определение UI объединённого пользовательского интерфейса.
Параметры
manager | объект GtkUIManager |
Возвращаемое значение
Новую строку, содержащую XML-представление объединённого UI.
С: 2.4
gtk_ui_manager_ensure_update ()
void
gtk_ui_manager_ensure_update (GtkUIManager *manager); gtk_ui_manager_ensure_update устарело начиная с версии 3.10 и не должно использоваться в новом коде.
Убеждается, что все ожидающие обновления UI завершены.
Это может быть иногда необходимо, так как GtkUIManager обновляет UI в функции обработки событий. Типичный пример, где эта функция полезна, — это гарантировать, что главная панель и панель инструментов добавлены в главное окно перед его отображением:
<!ELEMENT ui (menubar|toolbar|popup|accelerator)* >
<!ELEMENT menubar (menuitem|separator|placeholder|menu)* >
<!ELEMENT menu (menuitem|separator|placeholder|menu)* >
<!ELEMENT popup (menuitem|separator|placeholder|menu)* >
<!ELEMENT toolbar (toolitem|separator|placeholder)* >
<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
<!ELEMENT menuitem EMPTY >
<!ELEMENT toolitem (menu?) >
<!ELEMENT separator EMPTY >
<!ELEMENT accelerator EMPTY >
<!ATTLIST menubar name #IMPLIED
action #IMPLIED >
<!ATTLIST toolbar name #IMPLIED
action #IMPLIED >
<!ATTLIST popup name #IMPLIED
action #IMPLIED
accelerators (true|false) #IMPLIED >
<!ATTLIST placeholder name #IMPLIED
action #IMPLIED >
<!ATTLIST separator name #IMPLIED
action #IMPLIED
expand (true|false) #IMPLIED >
<!ATTLIST menu name #IMPLIED
action #REQUIRED
position (top|bot) #IMPLIED >
<!ATTLIST menuitem name #IMPLIED
action #REQUIRED
position (top|bot) #IMPLIED
always-show-image (true|false) #IMPLIED >
<!ATTLIST toolitem name #IMPLIED
action #REQUIRED
position (top|bot) #IMPLIED >
<!ATTLIST accelerator name #IMPLIED
action #REQUIRED >Параметры
manager | объект GtkUIManager |
С: 2.4
Типы и значения
struct GtkUIManager
struct GtkUIManager;
перечисление GtkUIManagerItemType
GtkUIManagerItemType устарело начиная с версии 3.10 и не должно использоваться в новом коде.
Эти значения перечисления используются функцией gtk_ui_manager_add_ui() для определения создаваемого элемента UI.
Члены
GTK_UI_MANAGER_AUTO | Выбор типа элемента UI в зависимости от контекста. | |
GTK_UI_MANAGER_MENUBAR | Создание панели меню. | |
GTK_UI_MANAGER_MENU | Создание меню. | |
GTK_UI_MANAGER_TOOLBAR | Создание панели инструментов. | |
GTK_UI_MANAGER_PLACEHOLDER | Вставка заполнительного элемента. | |
GTK_UI_MANAGER_POPUP | Создание всплывающего меню. | |
GTK_UI_MANAGER_MENUITEM | Создание пункта меню. | |
GTK_UI_MANAGER_TOOLITEM | Создание элемента панели инструментов. | |
GTK_UI_MANAGER_SEPARATOR | Создание разделителя. | |
GTK_UI_MANAGER_ACCELERATOR | Установка ускорителя. | |
GTK_UI_MANAGER_POPUP_WITH_ACCELS | То же, что и |
Подробности свойств
Свойство “add-tearoffs”
“add-tearoffs” gboolean
Свойство "add-tearoffs" управляет наличием пунктов меню «отрывного» типа в сгенерированных меню.
Обратите внимание, что это касается только обычных меню. В сгенерированных всплывающих меню пунктов меню «отрывного» типа никогда не бывает.
GtkUIManager:add-tearoffs устарело начиная с версии 3.4 и не должно использоваться в новом коде.
Меню «отрывного» типа устарели и не должны использоваться в новом коде.
Флаги: Чтение/Запись
Значение по умолчанию: FALSE
С: 2.4
Свойство “ui”
“ui” gchar *
Строка XML, описывающая объединённый UI.
Флаги: Чтение
Значение по умолчанию: "<ui>\n</ui>\n"
Подробности сигналов
Сигнал “actions-changed”
void user_function (GtkUIManager *manager, gpointer user_data)
Сигнал ::actions-changed генерируется всякий раз, когда изменяется набор действий.
GtkUIManager::actions-changed устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Параметры
manager | объект GtkUIManager | |
user_data | данные пользователя, заданные при подключении обработчика сигнала. |
Флаги: Без рекурсии
С версии: 2.4
Сигнал “add-widget”
void user_function (GtkUIManager *manager, GtkWidget *widget, gpointer user_data)
Сигнал ::add-widget генерируется для каждого сгенерированного меню и панели инструментов. Он не генерируется для сгенерированных всплывающих меню, которые можно получить с помощью gtk_ui_manager_get_widget().
GtkUIManager::add-widget устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Параметры
manager | объект GtkUIManager | |
widget | добавляемый виджет | |
user_data | данные пользователя, заданные при подключении обработчика сигнала. |
Флаги: Без рекурсии
С версии: 2.4
Сигнал “connect-proxy”
void user_function (GtkUIManager *manager, GtkAction *action, GtkWidget *proxy, gpointer user_data)
Сигнал ::connect-proxy генерируется после подключения прокси к действию в группе.
Это предназначено для простых кастомизаций, для которых пользовательский класс действия был бы слишком громоздким, например, для отображения всплывающих подсказок для пунктов меню в строке состояния.
GtkUIManager::connect-proxy устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Параметры
manager | менеджер пользовательского интерфейса | |
action | действие | |
proxy | прокси | |
user_data | данные пользователя, заданные при подключении обработчика сигнала. |
Флаги: Без рекурсии
С версии: 2.4
Сигнал “disconnect-proxy”
void user_function (GtkUIManager *manager, GtkAction *action, GtkWidget *proxy, gpointer user_data)
Сигнал ::disconnect-proxy генерируется после отключения прокси от действия в группе.
GtkUIManager::disconnect-proxy устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Параметры
manager | менеджер пользовательского интерфейса | |
action | действие | |
proxy | прокси | |
user_data | данные пользователя, заданные при подключении обработчика сигнала. |
Флаги: Без рекурсии
С версии: 2.4
Сигнал “post-activate”
void user_function (GtkUIManager *manager, GtkAction *action, gpointer user_data)
Сигнал ::post-activate генерируется сразу после активации action.
Это предназначено для уведомления приложений сразу после активации любого действия.
GtkUIManager::post-activate устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Параметры
manager | менеджер пользовательского интерфейса | |
action | действие | |
user_data | данные пользователя, заданные при подключении обработчика сигнала. |
Флаги: Без рекурсии
С версии: 2.4
Сигнал “pre-activate”
void user_function (GtkUIManager *manager, GtkAction *action, gpointer user_data)
Сигнал ::pre-activate генерируется непосредственно перед активацией action.
Это предназначено для уведомления приложений непосредственно перед активацией любого действия.
GtkUIManager::pre-activate устарел начиная с версии 3.10 и не должен использоваться в новом коде.
Параметры
manager | менеджер пользовательского интерфейса | |
action | действие | |
user_data | данные пользователя, заданные при подключении обработчика сигнала. |
Флаги: Без рекурсии
С версии: 2.4
См. также
© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk3/3.20/GtkUIManager.html