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 | Без рекурсии |
Типы и значения
| структура | GtkUIManager |
| перечисление | GtkUIManagerItemType |
Иерархия объектов
GObject ╰── GtkUIManager
Реализованные интерфейсы
GtkUIManager реализует GtkBuildable.
Включаемые файлы
#include <gtk/gtk.h>
Описание
A GtkUIManager создаёт пользовательский интерфейс (меню и панели инструментов) из одного или нескольких определений пользовательского интерфейса, которые ссылаются на действия из одной или нескольких групп действий.
Определения пользовательского интерфейса
Определения пользовательского интерфейса задаются в формате XML, который можно примерно описать с помощью следующего DTD.
Не следует путать определения пользовательского интерфейса GtkUIManager, описанные здесь, с определениями пользовательского интерфейса GtkBuilder с аналогичным названием Определения пользовательского интерфейса GtkBuilder.
Существуют некоторые дополнительные ограничения помимо тех, которые указаны в DTD, например, каждый элемент панели инструментов должен иметь панель инструментов в своём предке, а каждый элемент меню должен иметь главную панель меню или всплывающее меню в своём предке. Поскольку для разбора описания пользовательского интерфейса используется GMarkupParser, оно должно быть не только корректным XML, но и корректной разметкой.
Если имя не указано, оно по умолчанию соответствует действию. Если действие также не указано, используется имя элемента. Атрибуты name и action не должны содержать символов «/» после разбора (так как это нарушит поиск по пути) и должны быть применимы в качестве атрибутов XML, когда заключены в двойные кавычки, следовательно, они не должны содержать символы «"» или ссылки на сущность ".
Определение пользовательского интерфейса
Конструируемая иерархия виджетов очень похожа на древовидную структуру элементов XML, за исключением того, что заполнители объединяются со своими родительскими элементами. Соответствие элементов XML виджетам должно быть почти очевидным:
-
menubar
-
toolbar
-
popup
a toplevel GtkMenu
-
menu
a GtkMenu прикреплённый к пункту меню
-
menuitem
a GtkMenuItem подкласс, точный тип зависит от действия
-
toolitem
a GtkToolItem подкласс, точный тип зависит от действия. Обратите внимание, что элементы toolitem могут содержать элемент меню, но только если соответствующее действие указывает GtkMenuToolButton в качестве прокси.
-
separator
-
accelerator
a клавишная комбинация
Атрибут «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, описанное выше, может быть встроено в элемент GtkUIManager <object> в определении пользовательского интерфейса 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 | путь |
Возвращаемое значение
найденный виджет по указанному пути или NULL, если виджет не найден.
[transfer none]
С: 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 и не должно использоваться в новом коде.
Парсит файл ресурса, содержащий определение пользовательского интерфейса, и объединяет его с текущим содержимым manager .
Параметры
manager | объект GtkUIManager | |
resource_path | путь к файлу ресурса для парсинга | |
error | место для возврата ошибки |
Возвращаемое значение
Идентификатор слияния для объединённого пользовательского интерфейса. Идентификатор слияния можно использовать для разбиения пользовательского интерфейса с помощью 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 и не должно использоваться в новом коде.
Парсит строку, содержащую определение пользовательского интерфейса, и объединяет его с текущим содержимым manager . Добавляется окружающий элемент <ui>, если он отсутствует.
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 и не должно использоваться в новом коде.
Парсит файл, содержащий определение пользовательского интерфейса, и объединяет его с текущим содержимым manager .
Параметры
manager | объект GtkUIManager | |
filename | имя файла для парсинга. | [type filename] |
error | место для возврата ошибки |
Возвращаемое значение
Идентификатор слияния для объединённого пользовательского интерфейса. Идентификатор слияния можно использовать для разбиения пользовательского интерфейса с помощью 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 и не должно использоваться в новых кодах.
Добавляет элемент пользовательского интерфейса к текущему содержимому manager .
Если type равен GTK_UI_MANAGER_AUTO, GTK+ вставляет элемент меню, элемент панели инструментов или разделитель, если такой элемент может быть вставлен в место, определяемое path . В противном случае type должен указывать элемент, который может быть вставлен в место, определённое path .
Если path указывает на элемент меню или элемент панели инструментов, новый элемент будет вставлен перед или после этого элемента, в зависимости от top .
Параметры
manager | объект GtkUIManager | |
merge_id | Идентификатор слияния для объединённого пользовательского интерфейса, см. | |
path | путь | |
name | название добавляемого элемента пользовательского интерфейса | |
action | имя действия для проксирования, или | [allow-none] |
type | тип добавляемого элемента пользовательского интерфейса. | |
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 и не должно использоваться в новых кодах.
Создаёт определение пользовательского интерфейса объединённого пользовательского интерфейса.
Параметры
manager | объект GtkUIManager |
Возвращает
Новую строку, содержащую XML-представление объединённого пользовательского интерфейса.
С: 2.4
gtk_ui_manager_ensure_update ()
void
gtk_ui_manager_ensure_update (GtkUIManager *manager); gtk_ui_manager_ensure_update устарело с версии 3.10 и не должно использоваться в новых кодах.
Обеспечивает завершение всех ожидающих обновлений пользовательского интерфейса.
Это может потребоваться иногда, так как GtkUIManager обновляет пользовательский интерфейс в функции обработки задач. Пример, где эта функция полезна – это гарантировать, что строка меню и панель инструментов были добавлены в главное окно до его отображения:
<!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() для определения того, какой элемент пользовательского интерфейса создать.
Члены
GTK_UI_MANAGER_AUTO | Выберите тип элемента пользовательского интерфейса в зависимости от контекста. | |
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>\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.22/GtkUIManager.html