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) также будет создан запасной вариант (меню с единственной записью «Выход»).

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

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

Эта функция вернёт 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