[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Программирование, языки" / Оглавление документа

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

#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 элементов виджетам должно быть очевидно:

Свойство "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).

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

gtk_ui_manager_set_add_tearoffs ()

void        gtk_ui_manager_set_add_tearoffs (GtkUIManager *self,
                                             gboolean add_tearoffs);

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

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

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

gtk_ui_manager_get_add_tearoffs ()

gboolean    gtk_ui_manager_get_add_tearoffs (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. Действия в более ранних группах скрывают действия с тем же именем в более поздних группах.

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

gtk_ui_manager_remove_action_group ()

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

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

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

gtk_ui_manager_get_action_groups ()

GList*      gtk_ui_manager_get_action_groups
                                            (GtkUIManager *self);

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

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

gtk_ui_manager_get_accel_group ()

GtkAccelGroup* gtk_ui_manager_get_accel_group
                                            (GtkUIManager *self);

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

Начиная с версии 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).

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

gtk_ui_manager_get_toplevels ()

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

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

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

gtk_ui_manager_get_action ()

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

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

Начиная с версии 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> элемент если он пропущен.

Начиная с версии 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.

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

gtk_ui_manager_new_merge_id ()

guint       gtk_ui_manager_new_merge_id     (GtkUIManager *self);

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

Начиная с версии 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_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.

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

gtk_ui_manager_remove_ui ()

void        gtk_ui_manager_remove_ui        (GtkUIManager *self,
                                             guint merge_id);

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

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

gtk_ui_manager_get_ui ()

gchar*      gtk_ui_manager_get_ui           (GtkUIManager *self);

Создаёт UI definition совмещенного 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);

Начиная с версии 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" издаётся всякий раз когда изменяется набор действий.

Начиная с версии 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().

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

Сигнал "connect-proxy"

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

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

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

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

Сигнал "disconnect-proxy"

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

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

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

Сигнал "post-activate"

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

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

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

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

Сигнал "pre-activate"

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

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

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

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

Партнёры:

Хостинг: