GTK+ Reference Manual |
||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
GtkUIManagerGtkUIManager Создание меню и панелей инструментов из 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 описание представляется в 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 |
|
toolbar |
|
popup |
Верхний уровень GtkMenu |
menu |
GtkMenu прикреплённое к пункту меню |
menuitem |
GtkMenuItem подкласс, точный тип зависит от действия |
toolitem |
GtkToolItem подкласс, точный тип зависит от действия. Помните этот элемент может содержать пункт меню, но только если действие связанное с ними определяет GtkMenuToolButton как полномочие. |
separator |
|
accelerator |
Клавиатурный акселератор |
Свойство "position" определяет где создаваемый виджет разместиться относительно аналогичных элементов частично созданного дерева. Если оно "top", виджет расположится перед, иначе после.
Самая замечательная особенность GtkUIManager в том что он может производить установки пунктов меню и инструментальных элементов поверх других и отсоединять их позже.
Слияние выполняется основываясь на имени XML элементов. Каждый элемент идентифицируется путем который состоит из имен его прародителя, разделенных слэшами. Например, пункт меню с именем "Left" в примере выше имеет путь /ui/menubar/JustifyMenu/Left а инструментальный пункт (toolitem) с таким же именем имеет путь /ui/toolbar1/JustifyToolItems/Left.
Каждое действие имеет путь акселератора. Акселераторы устанавливаются вместе с полномочиями пунктов меню, но они так же могут быть явно добавлены как <accelerator> элемент в UI описание. Это позволяет иметь акселераторы для действий даже если они не имеют видимых полномочий.
Разделители создаваемые GtkUIManager являются "умными", например они не показываются в UI если они не заканчиваются между двумя видимыми меню или инструментальными пунктами. Разделители которые расположены в самом начале или конце меню или инструментальной панели, или множественные разделители расположенные друг за другом, являются скрытыми. Это очень полезная особенность, так как слияние UI элементов из множественных источников может сделать сложным или невозможным определение того, что разделитель находится в такой неудобной позиции.
Для разделителей на панели инструментов, вы можете установить expand="true" чтобы развернуть их из небольшого, видимого разделителя к расширенному, невидимому. Инструментальные пункты после расширенного разделителя фактически выравниваются по правому краю.
Подменю ставят похожие проблемы для разделителей связанные со слиянием. Невозможно знать заранее будет ли оно пустым после слияния. GtkUIManager предлагает два способа обработки пустых подменю:
делает их невидимыми скрывая меню к которому они прикреплены
добавляет нечувствительный "Пустой" элемент
Поведение выбирается на основании свойства действий "hide_if_empty", с которым связано подменю.
typedef struct _GtkUIManager GtkUIManager;Структура GtkUIManager содержит только закрытые данные и к ним нельзя обращаться непосредственно.
gtk_ui_manager_new ()
GtkUIManager* gtk_ui_manager_new (void);Создаёт новый объект управления пользовательским интерфейсом (ui manager).
Возвращает : |
Новый объект ui manager. |
Начиная с версии 2.4
void gtk_ui_manager_set_add_tearoffs (GtkUIManager *self,
gboolean add_tearoffs);
Устанавливает свойство "add_tearoffs", которое контролирует будет ли меню сгенерированное этим GtkUIManager иметь отсоединяемые пункты меню.
Помните что это действует только на обычные меню. Генерируемые всплывающие меню никогда не имеют отсоединяемые пункты.
self : |
|
add_tearoffs : |
Добавлены ли отсоединяемые пункты меню |
Начиная с версии 2.4
gboolean gtk_ui_manager_get_add_tearoffs (GtkUIManager *self);Возвращает будут ли иметь отсоединяемые пункты меню сгенерированные этим GtkUIManager.
self : |
|
Возвращает : |
Добавлены ли отсоединяемые пункты меню |
Начиная с версии 2.4
void gtk_ui_manager_insert_action_group
(GtkUIManager *self,
GtkActionGroup *action_group,
gint pos);
Вставляет группу действий в список ассоциированный с self. Действия в более ранних группах скрывают действия с тем же именем в более поздних группах.
self : |
объект GtkUIManager |
action_group : |
Вставляемая группа действий |
pos : |
Позиция в которую вставляется группа. |
Начиная с версии 2.4
void gtk_ui_manager_remove_action_group
(GtkUIManager *self,
GtkActionGroup *action_group);
Удаляет группу действий из списка ассоциированного с self.
self : |
Объект GtkUIManager |
action_group : |
Удаляемая группа действий |
Начиная с версии 2.4
GList* gtk_ui_manager_get_action_groups
(GtkUIManager *self);
Возвращает список групп действий связанный с self.
self : |
GtkUIManager объект |
Возвращает : |
GList групп действий. Списком владеет GTK+ и он не должен изменяться. |
Начиная с версии 2.4
GtkAccelGroup* gtk_ui_manager_get_accel_group
(GtkUIManager *self);
Возвращает GtkAccelGroup связанный с self.
self : |
GtkUIManager объект |
Возвращает : |
Начиная с версии 2.4
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 : |
|
path : |
путь |
Возвращает : |
Виджет найденный по следующему пути, или NULL если виджет не найден. |
Начиная с версии 2.4
GSList* gtk_ui_manager_get_toplevels (GtkUIManager *self,
GtkUIManagerItemType types);
Выдаёт список всех виджетов верхнего уровня требуемых типов.
self : |
|
types : |
Типы виджетов верхнего уровня. Допустимые типы: GTK_UI_MANAGER_MENUBAR, GTK_UI_MANAGER_TOOLBAR и GTK_UI_MANAGER_POPUP. |
Возвращает : |
Вновь-размещенный список всех виджетов верхнего уровня требуемых типов. |
Начиная с версии 2.4
GtkAction* gtk_ui_manager_get_action (GtkUIManager *self,
const gchar *path);
Ищет действие следующее за путём. Смотрите gtk_ui_manager_get_widget() для большей информации о путях.
self : |
|
path : |
путь |
Возвращает : |
Действие принадлежащее виджету найденному следующим в пути, или NULL если виджет не найден. |
Начиная с версии 2.4
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
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
guint gtk_ui_manager_new_merge_id (GtkUIManager *self);Возвращает неиспользуемый id слияния, подходящий для использования в gtk_ui_manager_add_ui().
self : |
|
Возвращает : |
Неиспользуемый id. |
Начиная с версии 2.4
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 |
Устанавливает акселератор. |
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 : |
|
merge_id : |
id для совмещенного UI, смотрите gtk_ui_manager_new_merge_id() |
path : |
путь |
name : |
Имя для добавляемого UI элемента |
action : |
Имя действия, или NULL для добавления разделителя |
type : |
Тип добавляемого UI элемента. |
top : |
Если TRUE, UI элемент добавлен перед родственным, иначе добавлен после родственного элемента. |
Начиная с версии 2.4
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
gchar* gtk_ui_manager_get_ui (GtkUIManager *self);Создаёт UI definition совмещенного UI.
self : |
|
Возвращает : |
Вновь размещённая строка содержащая XML представляющий совмещённый UI. |
Начиная с версии 2.4
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 : |
Начиная с версии 2.4
"add-tearoffs" gboolean : Read / WriteСвойство "add-tearoffs" контролирует должно ли меню иметь отсоединяемые пункты меню.
Помните это эффективно только для обычных меню. Генерируемые всплывающие меню никогда не имеют отсоединяемых пунктов.
Значение по умолчанию : FALSE
Начиная с версии 2.4
Свойство "ui"
"ui" gchararray : ReadXML строка описывающая совмещенный UI.
Значение по умолчанию : "<ui>\n</ui>"
Детали сигнала
Сигнал "actions-changed"
void user_function (GtkUIManager *merge, gpointer user_data) : Run first / No recursion
Сигнал "actions-changed" издаётся всякий раз когда изменяется набор действий.
merge : |
|
user_data : |
Пользовательские данные устанавливаемые при подключении обработчика сигнала. |
Начиная с версии 2.4
void user_function (GtkUIManager *merge,
GtkWidget *widget,
gpointer user_data) : Run first / No recursion
Сигнал add_widget издаётся для каждой сгенерированной панели меню и панели инструментов. Он не издаётся для сгенерированного всплывающего меню, которые могут быть получены gtk_ui_manager_get_widget().
merge : |
|
widget : |
Добавляемый виджет |
user_data : |
Пользовательские данные устанавливаемые при подключении обработчика сигнала. |
Начиная с версии 2.4
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
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
void user_function (GtkUIManager *uimanager,
GtkAction *action,
gpointer user_data) : Run first / No recursion
Сигнал post_activate издаётся только после выполнения action.
Это предназначено для приложений получающих оповещение только после выполнения действия.
uimanager : |
Управляющий пользовательским интерфейсом |
action : |
действие |
user_data : |
Пользовательские данные устанавливаемые при подключении обработчика сигнала. |
Начиная с версии 2.4
void user_function (GtkUIManager *uimanager,
GtkAction *action,
gpointer user_data) : Run first / No recursion
Сигнал pre_activate издаётся непосредственно перед тем как выполнено action.
Это предназначено для приложений получающих оповещение непосредственно перед выполнением действия.
uimanager : |
Управляющий пользовательским интерфейсом |
action : |
действие |
user_data : |
Пользовательские данные устанавливаемые при подключении обработчика сигнала. |
Начиная с версии 2.4