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