GtkApplication

gtk_application_new ()

GtkApplication *
gtk_application_new (const gchar *application_id,
                     GApplicationFlags flags);

Создаёт новый экземпляр GtkApplication.

При использовании GtkApplication, нет необходимости вручную вызывать gtk_init(). Он вызывается, как только приложение зарегистрировано в качестве основного экземпляра.

Конкретно, gtk_init() вызывается в обработчике по умолчанию для сигнала “startup”. Поэтому подклассы GtkApplication должны выполнять цепочку вызовов в своём обработчике “startup” перед использованием любого API GTK+.

Обратите внимание, что аргументы командной строки не передаются в gtk_init(). Вся функциональность GTK+, доступная через аргументы командной строки, также может быть достигнута с помощью соответствующих переменных окружения, таких как G_DEBUG, поэтому это не должно быть большой проблемой. Если вам абсолютно необходимо поддерживать аргументы командной строки GTK+, вы можете явно вызвать gtk_init() перед созданием экземпляра приложения.

Если не NULL, идентификатор приложения должен быть корректным. См. g_application_id_is_valid().

Если идентификатор приложения не задан, некоторые функции (в первую очередь уникальность приложения) будут отключены. Идентификатор приложения со значением null допустим только с GTK+ 3.6 или более поздней версии.

С: 3.0

gtk_application_add_window ()

void
gtk_application_add_window (GtkApplication *application,
                            GtkWindow *window);

Добавляет окно в application.

Этот вызов может происходить только после запуска application; обычно, новые окна приложения следует добавлять в ответ на выброс сигнала “activate”.

Этот вызов эквивалентен установке свойства “application” окна window в application.

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

GTK+ будет держать application запущенным, пока у него есть окна.

С: 3.0

gtk_application_remove_window ()

void
gtk_application_remove_window (GtkApplication *application,
                               GtkWindow *window);

Удаляет окно из application.

Если window принадлежит application, то этот вызов эквивалентен установке свойства “application” окна window в NULL.

В результате вызова этой функции приложение может быть остановлено.

С: 3.0

gtk_application_get_windows ()

GList *
gtk_application_get_windows (GtkApplication *application);

Возвращает список GtkWindows, связанных с application.

Список отсортирован по последнему сфокусированному окну, так что первый элемент — это текущее сфокусированное окно. (Полезно для выбора родительского окна для временного окна.)

Возвращённый список не следует изменять. Он будет действителен только до следующего изменения фокуса или создания/удаления окна.

С: 3.0

gtk_application_get_window_by_id ()

GtkWindow *
gtk_application_get_window_by_id (GtkApplication *application,
                                  guint id);

Возвращает GtkApplicationWindow с заданным идентификатором.

Идентификатор GtkApplicationWindow можно получить с помощью gtk_application_window_get_id().

С: 3.6

gtk_application_get_active_window ()

GtkWindow *
gtk_application_get_active_window (GtkApplication *application);

Получает «активное» окно для приложения.

Активное окно — это окно, которое было последним сфокусированным (в пределах приложения). Это окно может не иметь фокуса в данный момент, если им пользуется другое приложение — это просто последнее сфокусированное окно в этом приложении.

С: 3.6

gtk_application_inhibit ()

guint
gtk_application_inhibit (GtkApplication *application,
                         GtkWindow *window,
                         GtkApplicationInhibitFlags flags,
                         const gchar *reason);

Сообщите диспетчеру сеанса, что определённые типы действий должны быть заблокированы. Это не гарантируется на всех платформах и для всех типов действий.

Приложения должны вызывать этот метод, когда они начинают операцию, которую не следует прерывать, например, создание CD или DVD. Типы действий, которые могут быть заблокированы, задаются параметром flags. Когда приложение завершает операцию, оно должно вызвать gtk_application_uninhibit() для удаления ингибитора. Обратите внимание, что приложение может иметь несколько ингибиторов, и все они должны быть удалены индивидуально. Ингибиторы также очищаются при выходе приложения.

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

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

Если указан window, диспетчер сеанса может перенаправить пользователя на это окно, чтобы узнать больше о причине блокировки действия.

С: 3.4

gtk_application_uninhibit ()

void
gtk_application_uninhibit (GtkApplication *application,
                           guint cookie);

Удаляет ингибитор, установленный с помощью gtk_application_inhibit(). Ингибиторы также очищаются при выходе приложения.

С: 3.4

gtk_application_is_inhibited ()

gboolean
gtk_application_is_inhibited (GtkApplication *application,
                              GtkApplicationInhibitFlags flags);

Определяет, заблокированы ли какие-либо действия, указанные в flags (возможно, другим приложением).

Обратите внимание, что эта информация может быть недоступна (например, когда приложение выполняется в песочнице).

С: 3.4

gtk_application_prefers_app_menu ()

gboolean
gtk_application_prefers_app_menu (GtkApplication *application);

Определяет, предпочитает ли среда рабочего стола, в которой выполняется приложение, отображение меню приложения.

Если эта функция возвращает TRUE, приложение должно вызвать gtk_application_set_app_menu() с содержимым меню приложения, которое будет отображено средой рабочего стола. Если возвращается FALSE, следует рассмотреть альтернативный подход, например, использование строки меню.

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

Приложения аналогично свободны не устанавливать меню приложения, даже если среда рабочего стола хочет отобразить его. В этом случае среда рабочего стола также создаст резервный вариант (например, GNOME использует меню только с пунктом «Выход»).

Возвращаемое значение этой функции никогда не меняется. После того как оно вернёт определённое значение, гарантируется, что оно всегда будет возвращать то же самое значение.

Вы можете вызвать эту функцию только после регистрации приложения и после выполнения обработчика базового запуска. Вероятно, вы захотите использовать её из своего собственного обработчика запуска. Может также иметь смысл обратиться к этой функции при построении пользовательского интерфейса (в обработчиках activate, open или активации действия), чтобы определить, нужно ли отображать меню настроек.

Эта функция вернёт FALSE на Mac OS, и автоматически будет создано стандартное меню приложения с типичным для большинства приложений Mac OS содержимым. Если вы всё равно вызовете gtk_application_set_app_menu(), то это меню будет заменено вашим собственным.

С: 3.14

gtk_application_get_app_menu ()

GMenuModel *
gtk_application_get_app_menu (GtkApplication *application);

Возвращает модель меню, установленную с помощью gtk_application_set_app_menu().

С: 3.4

gtk_application_set_app_menu ()

void
gtk_application_set_app_menu (GtkApplication *application,
                              GMenuModel *app_menu);

Устанавливает или отменяет меню приложения для application.

Это можно сделать только в главном экземпляре приложения после его регистрации. “startup” — хорошее место для вызова этой функции.

Меню приложения — это единственное меню, содержащее пункты, которые обычно влияют на приложение в целом, а не на конкретное окно или документ. Например, в меню приложения вы ожидаете увидеть «Настройки» или «Выход», но не «Сохранить» или «Печать».

Если поддерживается, меню приложения будет отрисовываться средой рабочего стола.

Используйте базовый интерфейс GActionMap, чтобы добавить действия и реагировать на выбор пользователем этих пунктов меню.

С: 3.4

gtk_application_get_menubar ()

GMenuModel *
gtk_application_get_menubar (GtkApplication *application);

Возвращает модель меню, установленную с помощью gtk_application_set_menubar().

С версии: 3.4

gtk_application_set_menubar ()

void
gtk_application_set_menubar (GtkApplication *application,
                             GMenuModel *menubar);

Устанавливает или отключает строку меню для окон application .

Это строка меню в традиционном смысле.

Это можно сделать только в основном экземпляре приложения после его регистрации. “startup” — хорошее место для вызова этой функции.

В зависимости от среды рабочего стола, оно может отображаться вверху каждого окна или вверху экрана. В некоторых средах, если установлены как меню приложения, так и строка меню, меню приложения будет представлено как первый элемент строки меню. В других средах эти два элемента рассматриваются как совершенно отдельные — например, меню приложения может быть отображено оболочкой рабочего стола, а строка меню (если она установлена) остаётся в каждом отдельном окне.

Используйте базовый интерфейс GActionMap, чтобы добавить действия и отреагировать на выбор пользователем пунктов этого меню.

С версии: 3.4

gtk_application_get_menu_by_id ()

GMenu *
gtk_application_get_menu_by_id (GtkApplication *application,
                                const gchar *id);

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

С версии: 3.14

gtk_application_add_accelerator ()

void
gtk_application_add_accelerator (GtkApplication *application,
                                 const gchar *accelerator,
                                 const gchar *action_name,
                                 GVariant *parameter);

Устанавливает ускоритель, который активирует указанное действие при нажатии комбинации клавиш, указанной в accelerator.

accelerator должна быть строка, которую можно проанализировать с помощью gtk_accelerator_parse(), например, "<Primary>q" или “<Control><Alt>p”.

action_name должно быть именем действия, как оно используется в меню приложения, то есть действия, добавленные в приложение, обозначаются префиксом “app.”, а действия, относящиеся к окну, — префиксом “win.”.

GtkApplication также извлекает ускорители из атрибутов “accel” в GMenuModels, передаваемых в gtk_application_set_app_menu() и gtk_application_set_menubar(), что обычно более удобно, чем вызывать эту функцию для каждого ускорителя.

С версии: 3.4

gtk_application_remove_accelerator ()

void
gtk_application_remove_accelerator (GtkApplication *application,
                                    const gchar *action_name,
                                    GVariant *parameter);

Удаляет ускоритель, ранее добавленный с помощью gtk_application_add_accelerator().

С версии: 3.4

gtk_application_list_action_descriptions ()

gchar **
gtk_application_list_action_descriptions
                               (GtkApplication *application);

Выводит подробные имена действий, к которым привязаны ускорители. Подробнее см. gtk_application_set_accels_for_action().

С версии: 3.12

gtk_application_get_accels_for_action ()

gchar **
gtk_application_get_accels_for_action (GtkApplication *application,
                                       const gchar *detailed_action_name);

Возвращает ускорители, которые в данный момент ассоциированы с заданным действием.

С версии: 3.12

gtk_application_set_accels_for_action ()

void
gtk_application_set_accels_for_action (GtkApplication *application,
                                       const gchar *detailed_action_name,
                                       const gchar * const *accels);

Устанавливает один или более сочетаний клавиш, которые будут вызывать заданное действие. Первый элемент в accels будет основным сочетанием клавиш, которое может отображаться в пользовательском интерфейсе.

Чтобы удалить все сочетания клавиш для действия, используйте пустой, завершаемый нулём массив для accels.

Для detailed_action_name, см. g_action_parse_detailed_name() и g_action_print_detailed_name().

С: 3.12

gtk_application_get_actions_for_accel ()

gchar **
gtk_application_get_actions_for_accel (GtkApplication *application,
                                       const gchar *accel);

Возвращает список действий (возможно, пустой), которым accel сопоставлены. Каждый элемент списка — это подробное имя действия в обычном формате.

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

В случае отсутствия действий для данного сочетания клавиш возвращается пустой массив. NULL никогда не возвращается.

Ошибка программиста — передавать неверную строку сочетания клавиш. Если вы не уверены, сначала проверьте её с помощью gtk_accelerator_parse().

С: 3.14