gtkuimanager

			gtk+ reference manual
top \| description \| object hierarchy \| properties \| signals

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

gtkuimanager

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

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

свойства

сигналы

описание

ui определения

ui слияние

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

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

пустые меню

детали

gtkuimanager

gtk_ui_manager_new ()

gtk_ui_manager_set_add_tearoffs ()

gtk_ui_manager_get_add_tearoffs ()

gtk_ui_manager_insert_action_group ()

gtk_ui_manager_remove_action_group ()

gtk_ui_manager_get_action_groups ()

gtk_ui_manager_get_accel_group ()

gtk_ui_manager_get_widget ()

gtk_ui_manager_get_toplevels ()

gtk_ui_manager_get_action ()

gtk_ui_manager_add_ui_from_string ()

gtk_ui_manager_add_ui_from_file ()

gtk_ui_manager_new_merge_id ()

enum gtkuimanageritemtype

gtk_ui_manager_add_ui ()

gtk_ui_manager_remove_ui ()

gtk_ui_manager_get_ui ()

gtk_ui_manager_ensure_update ()

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

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

свойство "ui"

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

сигнал "actions-changed"

сигнал "add-widget"

сигнал "connect-proxy"

сигнал "disconnect-proxy"

сигнал "post-activate"

сигнал "pre-activate"

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

свойство "`ui`"