Prev

Up

Home

GTK+ Reference Manual

Next

Top  |  Description  |  Object Hierarchy  |  Properties  |  Signals

GtkUIManager

GtkUIManager Создание меню и панелей инструментов из XML описания

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

#include <gtk/gtk.h> GtkUIManager; GtkUIManager* gtk_ui_manager_new (void); void gtk_ui_manager_set_add_tearoffs (GtkUIManager *self, gboolean add_tearoffs); gboolean gtk_ui_manager_get_add_tearoffs (GtkUIManager *self); void gtk_ui_manager_insert_action_group (GtkUIManager *self, GtkActionGroup *action_group, gint pos); void gtk_ui_manager_remove_action_group (GtkUIManager *self, GtkActionGroup *action_group); GList* gtk_ui_manager_get_action_groups (GtkUIManager *self); GtkAccelGroup* gtk_ui_manager_get_accel_group (GtkUIManager *self); GtkWidget* gtk_ui_manager_get_widget (GtkUIManager *self, const gchar *path); GSList* gtk_ui_manager_get_toplevels (GtkUIManager *self, GtkUIManagerItemType types); GtkAction* gtk_ui_manager_get_action (GtkUIManager *self, const gchar *path); guint gtk_ui_manager_add_ui_from_string (GtkUIManager *self, const gchar *buffer, gssize length, GError **error); guint gtk_ui_manager_add_ui_from_file (GtkUIManager *self, const gchar *filename, GError **error); guint gtk_ui_manager_new_merge_id (GtkUIManager *self); enum GtkUIManagerItemType; void gtk_ui_manager_add_ui (GtkUIManager *self, guint merge_id, const gchar *path, const gchar *name, const gchar *action, GtkUIManagerItemType type, gboolean top); void gtk_ui_manager_remove_ui (GtkUIManager *self, guint merge_id); gchar* gtk_ui_manager_get_ui (GtkUIManager *self); void gtk_ui_manager_ensure_update (GtkUIManager *self);

Иерархия объектов

GObject +----GtkUIManager

Свойства

"add-tearoffs" gboolean : Read / Write "ui" gchararray : Read

Сигналы

"actions-changed" void user_function (GtkUIManager *merge, gpointer user_data) : Run first / No recursion "add-widget" void user_function (GtkUIManager *merge, GtkWidget *widget, gpointer user_data) : Run first / No recursion "connect-proxy" void user_function (GtkUIManager *uimanager, GtkAction *action, GtkWidget *proxy, gpointer user_data) : Run first / No recursion "disconnect-proxy" void user_function (GtkUIManager *uimanager, GtkAction *action, GtkWidget *proxy, gpointer user_data) : Run first / No recursion "post-activate" void user_function (GtkUIManager *uimanager, GtkAction *action, gpointer user_data) : Run first / No recursion "pre-activate" void user_function (GtkUIManager *uimanager, GtkAction *action, gpointer user_data) : Run first / No recursion

Описание

GtkUIManager конструирует интерфейс пользователя (меню и панели инструментов) из одного или более UI описаний, с указанием действий из одной или более групп действий.

UI Определения

UI описание представляется в XML формате который может быть примерно описан с помощью следующего DTD.

<!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 > <!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 > <!ATTLIST toolitem name #IMPLIED action #REQUIRED position (top|bot) #IMPLIED > <!ATTLIST accelerator name #IMPLIED action #REQUIRED >

Есть дополнительные ограничения выходящие за определения DTD, например каждый инструментальный пункт (toolitem) должен иметь панель инструментов (toolbar) в своей родословной и каждый пункт меню должен иметь панель меню или всплывающее меню в своей родословной. Так как GMarkup анализатор используется для анализа UI описания, оно должно быть не только в правильном XML формате, но и допустимом GMarkup.

Если имя не определено, по умолчанию выполняется действие. Если действие также не определено, используется имя элемента. Имя и свойства действия не должны содержать знак '/' после синтаксического анализа (так как это помешает поиску пути) и должны быть удобны как XML свойства когда помещены в двойные кавычки, таким образом они не должны иметь символы '"' или ссылку на > объект.

Пример 1. UI определение

<ui> <menubar> <menu name="FileMenu" action="FileMenuAction"> <menuitem name="New" action="New2Action" /> <placeholder name="FileMenuAdditions" /> </menu> <menu name="JustifyMenu" action="JustifyMenuAction"> <menuitem name="Left" action="justify-left"/> <menuitem name="Centre" action="justify-center"/> <menuitem name="Right" action="justify-right"/> <menuitem name="Fill" action="justify-fill"/> </menu> </menubar> <toolbar action="toolbar1"> <placeholder name="JustifyToolItems"> <separator/> <toolitem name="Left" action="justify-left"/> <toolitem name="Centre" action="justify-center"/> <toolitem name="Right" action="justify-right"/> <toolitem name="Fill" action="justify-fill"/> <separator/> </placeholder> </toolbar> </ui>

Созданная иерархия виджетов очень похожа на элементы дерева XML, за исключением того, что метки-заполнители сливаются с их родителем. Соответствие XML элементов виджетам должно быть очевидно:

menubar

GtkMenuBar

toolbar

GtkToolbar

popup

Верхний уровень GtkMenu

menu

GtkMenu прикреплённое к пункту меню

menuitem

GtkMenuItem подкласс, точный тип зависит от действия

toolitem

GtkToolItem подкласс, точный тип зависит от действия. Помните этот элемент может содержать пункт меню, но только если действие связанное с ними определяет GtkMenuToolButton как полномочие.

separator

GtkSeparatorMenuItem или GtkSeparatorToolItem

accelerator

Клавиатурный акселератор

Свойство "position" определяет где создаваемый виджет разместиться относительно аналогичных элементов частично созданного дерева. Если оно "top", виджет расположится перед, иначе после.


UI Слияние

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

Слияние выполняется основываясь на имени XML элементов. Каждый элемент идентифицируется путем который состоит из имен его прародителя, разделенных слэшами. Например, пункт меню с именем "Left" в примере выше имеет путь /ui/menubar/JustifyMenu/Left а инструментальный пункт (toolitem) с таким же именем имеет путь /ui/toolbar1/JustifyToolItems/Left.


Акселераторы

Каждое действие имеет путь акселератора. Акселераторы устанавливаются вместе с полномочиями пунктов меню, но они так же могут быть явно добавлены как <accelerator> элемент в UI описание. Это позволяет иметь акселераторы для действий даже если они не имеют видимых полномочий.


Умные разделители

Разделители создаваемые GtkUIManager являются "умными", например они не показываются в UI если они не заканчиваются между двумя видимыми меню или инструментальными пунктами. Разделители которые расположены в самом начале или конце меню или инструментальной панели, или множественные разделители расположенные друг за другом, являются скрытыми. Это очень полезная особенность, так как слияние UI элементов из множественных источников может сделать сложным или невозможным определение того, что разделитель находится в такой неудобной позиции.

Для разделителей на панели инструментов, вы можете установить expand="true" чтобы развернуть их из небольшого, видимого разделителя к расширенному, невидимому. Инструментальные пункты после расширенного разделителя фактически выравниваются по правому краю.


Пустые меню

Подменю ставят похожие проблемы для разделителей связанные со слиянием. Невозможно знать заранее будет ли оно пустым после слияния. GtkUIManager предлагает два способа обработки пустых подменю:

Поведение выбирается на основании свойства действий "hide_if_empty", с которым связано подменю.

Детали

GtkUIManager

typedef struct _GtkUIManager GtkUIManager;

Структура GtkUIManager содержит только закрытые данные и к ним нельзя обращаться непосредственно.


gtk_ui_manager_new ()

GtkUIManager* gtk_ui_manager_new            (void);

Создаёт новый объект управления пользовательским интерфейсом (ui manager).

Возвращает :

Новый объект ui manager.

Начиная с версии 2.4


gtk_ui_manager_set_add_tearoffs ()

void gtk_ui_manager_set_add_tearoffs (GtkUIManager *self, gboolean add_tearoffs);

Устанавливает свойство "add_tearoffs", которое контролирует будет ли меню сгенерированное этим GtkUIManager иметь отсоединяемые пункты меню.

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

self :

GtkUIManager

add_tearoffs :

Добавлены ли отсоединяемые пункты меню

Начиная с версии 2.4


gtk_ui_manager_get_add_tearoffs ()

gboolean    gtk_ui_manager_get_add_tearoffs (GtkUIManager *self);

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

self :

GtkUIManager

Возвращает :

Добавлены ли отсоединяемые пункты меню

Начиная с версии 2.4


gtk_ui_manager_insert_action_group ()

void gtk_ui_manager_insert_action_group (GtkUIManager *self, GtkActionGroup *action_group, gint pos);

Вставляет группу действий в список ассоциированный с self. Действия в более ранних группах скрывают действия с тем же именем в более поздних группах.

self :

объект GtkUIManager

action_group :

Вставляемая группа действий

pos :

Позиция в которую вставляется группа.

Начиная с версии 2.4


gtk_ui_manager_remove_action_group ()

void gtk_ui_manager_remove_action_group (GtkUIManager *self, GtkActionGroup *action_group);

Удаляет группу действий из списка ассоциированного с self.

self :

Объект GtkUIManager

action_group :

Удаляемая группа действий

Начиная с версии 2.4


gtk_ui_manager_get_action_groups ()

GList* gtk_ui_manager_get_action_groups (GtkUIManager *self);

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

self :

GtkUIManager объект

Возвращает :

GList групп действий. Списком владеет GTK+ и он не должен изменяться.

Начиная с версии 2.4


gtk_ui_manager_get_accel_group ()

GtkAccelGroup* gtk_ui_manager_get_accel_group (GtkUIManager *self);

Возвращает GtkAccelGroup связанный с self.

self :

GtkUIManager объект

Возвращает :

GtkAccelGroup.

Начиная с версии 2.4


gtk_ui_manager_get_widget ()

GtkWidget* gtk_ui_manager_get_widget (GtkUIManager *self, const gchar *path);

Ищет виджет следующий за путём. Путь состоит из имени определенного в XML описании UI. разделенного '/'. К элементам не имеющим имени свойств действия в XML (например <popup>) можно обратиться по их имени элемента XML (например "popup"). Основной элемент пути ("/ui") может быть пропущен.

Помните что виджет найденный следующим в пути который заканчивается элементом <menu> - это пункт меню к которому прикреплено меню, а не само меню.

Также помните что виджеты созданные ui manager не входят в цикл (lifecycle) ui manager. Если вы добавите виджеты возвращенные этой функцией в какой нибудь контейнер или непосредственно сошлётесь на них, они не разрушаться при разрушении управляющего пользовательским интерфейсом (ui manager).

self :

GtkUIManager

path :

путь

Возвращает :

Виджет найденный по следующему пути, или NULL если виджет не найден.

Начиная с версии 2.4


gtk_ui_manager_get_toplevels ()

GSList* gtk_ui_manager_get_toplevels (GtkUIManager *self, GtkUIManagerItemType types);

Выдаёт список всех виджетов верхнего уровня требуемых типов.

self :

GtkUIManager

types :

Типы виджетов верхнего уровня. Допустимые типы: GTK_UI_MANAGER_MENUBAR, GTK_UI_MANAGER_TOOLBAR и GTK_UI_MANAGER_POPUP.

Возвращает :

Вновь-размещенный список всех виджетов верхнего уровня требуемых типов.

Начиная с версии 2.4


gtk_ui_manager_get_action ()

GtkAction* gtk_ui_manager_get_action (GtkUIManager *self, const gchar *path);

Ищет действие следующее за путём. Смотрите gtk_ui_manager_get_widget() для большей информации о путях.

self :

GtkUIManager

path :

путь

Возвращает :

Действие принадлежащее виджету найденному следующим в пути, или NULL если виджет не найден.

Начиная с версии 2.4


gtk_ui_manager_add_ui_from_string ()

guint gtk_ui_manager_add_ui_from_string (GtkUIManager *self, const gchar *buffer, gssize length, GError **error);

Анализирует строку содержащую UI definition и соединяет с текущим содержимым self. Добавляет <ui> элемент если он пропущен.

self :

GtkUIManager объект

buffer :

Анализируемая строка

length :

длина buffer (может быть -1 если buffer заканчивается нулём (nul-terminated))

error :

размещение для возвращаемой ошибки

Возвращает :

id для совмещенного UI. id может использоваться для разделения 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 *self, const gchar *filename, GError **error);

Анализирует файл содержащий UI definition и совмещает с текущим содержимым self.

self :

GtkUIManager объект

filename :

Имя файла для анализа

error :

Расположение для возвращаемой ошибки

Возвращает :

id для совмещенного UI. id может использоваться для разделения UI с помощью gtk_ui_manager_remove_ui(). Если произошла ошибка возвращается 0.

Начиная с версии 2.4


gtk_ui_manager_new_merge_id ()

guint       gtk_ui_manager_new_merge_id     (GtkUIManager *self);

Возвращает неиспользуемый id слияния, подходящий для использования в gtk_ui_manager_add_ui().

self :

GtkUIManager

Возвращает :

Неиспользуемый id.

Начиная с версии 2.4


enum GtkUIManagerItemType

typedef enum { GTK_UI_MANAGER_AUTO = 0, GTK_UI_MANAGER_MENUBAR = 1 << 0, GTK_UI_MANAGER_MENU = 1 << 1, GTK_UI_MANAGER_TOOLBAR = 1 << 2, GTK_UI_MANAGER_PLACEHOLDER = 1 << 3, GTK_UI_MANAGER_POPUP = 1 << 4, GTK_UI_MANAGER_MENUITEM = 1 << 5, GTK_UI_MANAGER_TOOLITEM = 1 << 6, GTK_UI_MANAGER_SEPARATOR = 1 << 7, GTK_UI_MANAGER_ACCELERATOR = 1 << 8 } GtkUIManagerItemType;

Значения этого перечисления используются 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_add_ui ()

void gtk_ui_manager_add_ui (GtkUIManager *self, guint merge_id, const gchar *path, const gchar *name, const gchar *action, GtkUIManagerItemType type, gboolean top);

Добавляет элемент UI к текущемму контексту self.

Если type равен GTK_UI_MANAGER_AUTO, GTK+ вставляет пункт меню, инструментальный пункт или разделитель если такой элемент может быть вставлен в место определённое path. Иначе type должен отображать элемент который может быть вставлен в место определенное path.

Если path указатель для пункта меню или инструментального пункта, то новый элемент будет вставлен перед или после этого пункта, в зависимости от top.

self :

GtkUIManager

merge_id :

id для совмещенного UI, смотрите gtk_ui_manager_new_merge_id()

path :

путь

name :

Имя для добавляемого UI элемента

action :

Имя действия, или NULL для добавления разделителя

type :

Тип добавляемого UI элемента.

top :

Если TRUE, UI элемент добавлен перед родственным, иначе добавлен после родственного элемента.

Начиная с версии 2.4


gtk_ui_manager_remove_ui ()

void gtk_ui_manager_remove_ui (GtkUIManager *self, guint merge_id);

Разделяет части selfs содержимого определенного merge_id.

self :

GtkUIManager объект

merge_id :

id как возвращаемый gtk_ui_manager_add_ui_from_string()

Начиная с версии 2.4


gtk_ui_manager_get_ui ()

gchar*      gtk_ui_manager_get_ui           (GtkUIManager *self);

Создаёт UI definition совмещенного UI.

self :

GtkUIManager

Возвращает :

Вновь размещённая строка содержащая XML представляющий совмещённый UI.

Начиная с версии 2.4


gtk_ui_manager_ensure_update ()

void        gtk_ui_manager_ensure_update    (GtkUIManager *self);

Удостоверяется в завершении всех обновлений UI.

Это иногда может быть необходимо, так как GtkUIManager обновляет UI в неактивной функции. Типичный пример того когда эта функция необходима это добавление панели меню и панели инструментов к основному окну после его отображения:

gtk_container_add (GTK_CONTAINER (window), vbox); g_signal_connect (merge, "add_widget", G_CALLBACK (add_widget), vbox); gtk_ui_manager_add_ui_from_file (merge, "my-menus"); gtk_ui_manager_add_ui_from_file (merge, "my-toolbars"); gtk_ui_manager_ensure_update (merge); gtk_widget_show (window);

self :

GtkUIManager

Начиная с версии 2.4

Детали свойств

Свойство "add-tearoffs"

  "add-tearoffs"         gboolean              : Read / Write

Свойство "add-tearoffs" контролирует должно ли меню иметь отсоединяемые пункты меню.

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

Значение по умолчанию : FALSE

Начиная с версии 2.4


Свойство "ui"

  "ui"                   gchararray            : Read

XML строка описывающая совмещенный UI.

Значение по умолчанию : "<ui>\n</ui>"

Детали сигнала

Сигнал "actions-changed"

void user_function (GtkUIManager *merge, gpointer user_data) : Run first / No recursion

Сигнал "actions-changed" издаётся всякий раз когда изменяется набор действий.

merge :

GtkUIManager

user_data :

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

Начиная с версии 2.4


Сигнал "add-widget"

void user_function (GtkUIManager *merge, GtkWidget *widget, gpointer user_data) : Run first / No recursion

Сигнал add_widget издаётся для каждой сгенерированной панели меню и панели инструментов. Он не издаётся для сгенерированного всплывающего меню, которые могут быть получены gtk_ui_manager_get_widget().

merge :

GtkUIManager

widget :

Добавляемый виджет

user_data :

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

Начиная с версии 2.4


Сигнал "connect-proxy"

void user_function (GtkUIManager *uimanager, GtkAction *action, GtkWidget *proxy, gpointer user_data) : Run first / No recursion

Сигнал connect_proxy издаётся после подключения полномочий к действию в группе.

Это предназначено для простых настроек для которых настройка класса действий было бы излишним, например отображение быстрых подсказок пунктов меню в панели состояния.

uimanager :

Управляющий пользовательским интерфейсом

action :

действие

proxy :

полномочия

user_data :

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

Начиная с версии 2.4


Сигнал "disconnect-proxy"

void user_function (GtkUIManager *uimanager, GtkAction *action, GtkWidget *proxy, gpointer user_data) : Run first / No recursion

Сигнал disconnect_proxy издаётся после отключения полномочий от действия в группе.

uimanager :

Управляющий пользовательским интерфейсом

action :

действие

proxy :

полномочие

user_data :

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

Начиная с версии 2.4


Сигнал "post-activate"

void user_function (GtkUIManager *uimanager, GtkAction *action, gpointer user_data) : Run first / No recursion

Сигнал post_activate издаётся только после выполнения action.

Это предназначено для приложений получающих оповещение только после выполнения действия.

uimanager :

Управляющий пользовательским интерфейсом

action :

действие

user_data :

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

Начиная с версии 2.4


Сигнал "pre-activate"

void user_function (GtkUIManager *uimanager, GtkAction *action, gpointer user_data) : Run first / No recursion

Сигнал pre_activate издаётся непосредственно перед тем как выполнено action.

Это предназначено для приложений получающих оповещение непосредственно перед выполнением действия.

uimanager :

Управляющий пользовательским интерфейсом

action :

действие

user_data :

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

Начиная с версии 2.4