GioApplication

自:2.28

描述 [src]

class Gio.Application : GObject.Object
  implements Gio.ActionGroup, Gio.ActionMap {
  /* No available fields */
}

GApplication 是应用程序支持的核心类。

GApplication 是应用程序的基础。它封装了一些与平台相关的底层服务,旨在作为 GtkApplicationMxApplication 等更高级别的应用程序类的基础。通常情况下,你不应在高级别框架之外使用这个类。

GApplication 通过维护主应用程序实例的“使用计数”来提供便利的生命周期管理。可以使用 g_application_hold()g_application_release() 来更改使用计数。如果计数降至零,应用程序将退出。如 GtkApplication 等更高级别的类利用使用计数来确保应用程序在其拥有任何已打开窗口时保持活动状态。

GApplication(可选地)提供的另一个特性是进程唯一性。应用程序可以通过提供一个应用程序唯一 ID 来利用此功能。如果提供了该 ID,则每次会话中只能运行一个带有此 ID 的应用程序。会话概念依赖于平台,但大致对应于图形桌面登录。当你的应用程序再次启动时,其参数将通过平台通信传递给正在运行的程序。该程序的正在运行实例称为“主实例”;对于非唯一应用程序,这始终是当前实例。在 Linux 上,D-Bus 会话总线用于进行通信。

GApplication 的使用方式在重要方面与其他一些常用的唯一性库(如 libunique)不同。应用程序无需手动注册自身和检查是否为主实例。相反,GApplicationmain() 函数几乎不需要做太多事,只需实例化应用程序实例,可能连接信号处理程序,然后调用 g_application_run()。所有唯一性检查都将在内部完成。如果应用程序为主实例,则会发出启动信号并运行主循环。如果应用程序不是主实例,则会向主实例发送信号,并且 g_application_run() 会立即返回。请参阅以下提供的示例代码。

如果使用,应用程序标识符的预期形式与 D-Bus 众所周知的总线名称 相同。示例包括:com.example.MyApporg.example.internal_apps.Calculatororg._7_zip.Archiver。有关有效的应用程序标识符的详细信息,请参阅 g_application_id_is_valid()

在 Linux 上,应用程序标识符被宣称是一个在用户会话总线上明确的总线名称。这意味着您的应用程序的唯一性限定于当前会话。它还意味着您的应用程序可以提供附加服务(通过注册其他对象路径)给定的总线名称。这些对象路径的注册应该与共享的 GDBus 会话总线一起完成。请注意,由于 GDBus 的内部架构,方法调用可以在任何时间调度(即使一个主循环没有在运行)。由于这个原因,您必须确保您希望注册的任何对象路径是在 GApplication 尝试获取您应用程序的总线名称(这在 g_application_register())之前注册的。不幸的是,这意味着您不能使用 GApplication:is-remote 来确定您是否想要注册对象路径。

GApplication 也实现了 GActionGroupGActionMap 接口,并让您通过使用 g_action_map_add_action() 添加操作轻松地导出操作。当通过使用应用程序上的 g_action_group_activate_action() 调用一个操作时,它始终在主要实例中被调用。这些操作也在会话总线上导出,GIO 提供 GDBusActionGroup 包装器来方便地远程访问它们。GIO 提供一个 GDBusMenuModel 包装器,用于远程访问导出的 GMenuModel

注意:由于操作在会话总线上导出,因此不支持使用 maybe 参数,因为 D-Bus 不支持 maybe 类型。

有许多不同的进入点进入一个 GApplication

  • 通过“激活”(也就是说,仅仅启动应用程序)

  • 通过“打开”(也就是说,打开一些文件)

  • 通过处理命令行

  • 通过激活一个操作

GApplication::startup 信号让您单点处理所有这些的应用程序初始化。

无论使用哪个进入点来启动应用程序,GApplication 都会从启动实例传递一些“平台数据”到主要实例,以 GVariant 字典的形式,将字符串映射到变量。若要使用平台数据,请覆盖您的 GApplication 子类中的 Gio.ApplicationClass.before_emitGio.ApplicationClass.after_emit 虚函数。当处理 GApplicationCommandLine 对象时,平台数据直接通过 g_application_command_line_get_cwd()g_application_command_line_get_environ()g_application_command_line_get_platform_data() 提供。

正如名字所指出的,平台数据可能因操作系统而异,但它始终包括当前目录(键 cwd),并且可选地有调用进程的环境(即,环境变量集合及其值)(键 environ)。只有当 G_APPLICATION_SEND_ENVIRONMENT 标记设置时,才会将环境添加到平台数据中。GApplication 子类可以通过覆盖 Gio.ApplicationClass.add_platform_data 虚函数来添加自己的平台数据。例如,GtkApplication 以这种方式添加启动通知数据。

若要解析命令行参数,您应该处理GApplication::command-line信号,或重写Gio.ApplicationClass.local_command_line的虚拟函数,以便分别在主实例或本地实例中解析这些参数。

有关使用GApplication打开文件的示例,请参见gapplication-example-open.c

有关如何使用包含GApplication的操作的示例,请参见gapplication-example-actions.c

有关如何使用包含GApplication的额外 D-Bus 挂钩的示例,请参见gapplication-example-dbushooks.c

此功能自 2.28 版起可用

祖先

构造函数

g_application_new

创建一个新的GApplication实例

函数

g_application_get_default

将此进程中默认的GApplication实例返回。

自 2.32 版起可用

g_application_id_is_valid

检查application_id是否为有效的应用程序

实例方法

g_application_activate

激活该

自:2.28

g_application_add_main_option

添加一个供application处理的选项。

自 2.42 版起可用

g_application_add_main_option_entries

添加要由application处理的主选项条目。

自 2.40 版起可用

g_application_add_option_group

GOptionGroup添加到对application的命令行处理。

自 2.40 版起可用

g_application_bind_busy_property

objectpropertyTRUE时,将application标记为繁忙(请参阅 g_application_mark_busy())。

自 2.44 版起可用

g_application_get_application_id

获取application的唯一标识符。

自:2.28

g_application_get_dbus_connection

获取由该应用程序使用的GDBusConnection或获取NULL

自 2.34 版起可用

g_application_get_dbus_object_path

获取由该应用程序使用的 D-Bus 对象路径或获取NULL

自 2.34 版起可用

g_application_get_flags

获取application的标志。

自:2.28

g_application_get_inactivity_timeout

获取应用程序的当前不活动超时。

自:2.28

g_application_get_is_busy

获取应用程序当前的繁忙状态,如通过 g_application_mark_busy()g_application_bind_busy_property() 设置的那样。

自 2.44 版起可用

g_application_get_is_registered

检查application是否已

自:2.28

g_application_get_is_remote

检查application是否

自:2.28

g_application_get_resource_base_path

获取application的资源基准路径。

自 2.42 版起可用

g_application_get_version

获取application的版本。

自 2.80 版起可用

g_application_hold

增加application的使用计数。

g_application_mark_busy

增加application的繁忙计数。

自 2.38 版起可用

g_application_open

打开给定的

自:2.28

g_application_quit

立即退出该

自 2.32 版起可用

g_application_register

尝试注册该

自:2.28

g_application_release

减少application的使用计数。

g_application_run

运行该

自:2.28

g_application_send_notification

代表application将通知发送到桌面外壳。不保证会立即显示通知,甚至不会

自 2.40 版起可用

g_application_set_action_group

过去,操作就是用这种方式与 GApplication 关联的。现在包含 GActionMap,目的是

已弃用:2.32  自 2.28 版起可用

g_application_set_application_id

设置application的唯一标识符。

自:2.28

g_application_set_default

设置或取消设置进程的默认应用程序,如 g_application_get_default() 返回的那样。

自 2.32 版起可用

g_application_set_flags

设置 application 的标志。

自:2.28

g_application_set_inactivity_timeout

设置应用程序的当前非活动超时时间。

自:2.28

g_application_set_option_context_description

application 选项上下文添加一个描述。

since: 2.56

g_application_set_option_context_parameter_string

设置由 application 的命令行处理程序使用的参数字符串。

since: 2.56

g_application_set_option_context_summary

application 选项上下文添加一个摘要。

since: 2.56

g_application_set_resource_base_path

设置(或取消设置)application 的基本资源路径。

自 2.42 版起可用

g_application_set_version

设置 application 的版本号。这将用于执行 --version 命令行参数。

自 2.80 版起可用

g_application_unbind_busy_property

销毁 propertyapplication 繁忙状态之间的绑定,该绑定先前使用 g_application_bind_busy_property() 创建。

自 2.44 版起可用

g_application_unmark_busy

减少 application 的繁忙计数。

自 2.38 版起可用

g_application_withdraw_notification

撤回使用 g_application_send_notification() 发送的通知。

自 2.40 版起可用

GObject (43) 继承的方法

有关方法的完整列表,请参见 GObject

GActionGroup (14) 继承的方法
g_action_group_action_added

action_group 上发出 GActionGroup::action-added 信号。

自:2.28

g_action_group_action_enabled_changed

action_group 上发出 GActionGroup::action-enabled-changed 信号。

自:2.28

g_action_group_action_removed

action_group 上发出 GActionGroup::action-removed 信号。

自:2.28

g_action_group_action_state_changed

action_group 上发出 GActionGroup::action-state-changed 信号。

自:2.28

g_action_group_activate_action

激活 action_group 内的命名操作。

自:2.28

g_action_group_change_action_state

请求将 action_group 内的命名操作的状态更改为 value

自:2.28

g_action_group_get_action_enabled

检查 action_group 内的命名操作当前是否处于启用状态。

自:2.28

g_action_group_get_action_parameter_type

查询激活 action_group 内的命名操作时必须提供参数的类型。

自:2.28

g_action_group_get_action_state

查询 action_group 内的命名操作的当前状态。

自:2.28

g_action_group_get_action_state_hint

请求关于 action_group 内的命名操作的状态的有效值范围的提示。

自:2.28

g_action_group_get_action_state_type

查询 action_group 内的命名操作的状态类型。

自:2.28

g_action_group_has_action

检查 action_group 内是否存在命名操作。

自:2.28

g_action_group_list_actions

列出 action_group 内包含的操作。

自:2.28

g_action_group_query_action

查询 action_group 内的命名操作的所有方面。

自 2.32 版起可用

GActionMap (5) 继承的方法
g_action_map_add_action

action_map 添加一个操作。

自 2.32 版起可用

g_action_map_add_action_entries

一个用于创建多个 GSimpleAction 实例并将它们添加到 GActionMap 的便捷函数。

自 2.32 版起可用

g_action_map_lookup_action

action_map 中查找名为 action_name 的操作。

自 2.32 版起可用

g_action_map_remove_action

从操作映射中删除命名的操作。

自 2.32 版起可用

g_action_map_remove_action_entries

GActionMap 中删除操作。这被认为是 g_action_map_add_action_entries() 的逆操作。

since: 2.78

属性

Gio.Application:action-group

应用程序导出的动作组。

已弃用:2.32  自 2.28 版起可用

Gio.Application:application-id

应用程序的唯一标识符。

自:2.28

Gio.Application:flags

指定应用程序行为的标志。

自:2.28

Gio.Application:inactivity-timeout

一段时间(以毫秒为单位),在此时间段内应用程序保持活动状态,即使其进入空闲状态也是如此。

自:2.28

Gio.Application:is-busy

根据 `g_application_mark_busy()` 或 `g_application_bind_busy_property()` 将应用程序标记为繁忙。

自 2.44 版起可用

Gio.Application:is-registered

`g_application_register()` 是否已被

自:2.28

Gio.Application:is-remote

此应用程序实例是否为远程实例。

自:2.28

Gio.Application:resource-base-path

应用程序的基本资源路径。

自:2.28

Gio.Application:version

应用程序的可读版本号。

自 2.80 版起可用

信号

Gio.Application::activate

发生激活时,在主实例上发出 ::activate 信号。请参阅 `g_application_activate()`。

Gio.Application::command-line

当本地未处理命令行时,在主实例上发出 ::command-line 信号。有关更多信息,请参阅 `g_application_run()` 和 `GApplicationCommandLine` 文档。

Gio.Application::handle-local-options

在解析命令行选项后,在本地实例上发出 ::handle-local-options 信号。

自 2.40 版起可用

Gio.Application::name-lost

当新实例接管时,仅在注册的主实例上发出 ::name-lost 信号。仅当应用程序使用 `G_APPLICATION_ALLOW_REPLACEMENT` 标志时,才会发生这种情况。

自:2.60

Gio.Application::open

当有要打开的文件时,在主实例上发出 ::open 信号。有关更多信息,请参阅 `g_application_open()`。

Gio.Application::shutdown

在主循环结束后,仅在注册的主实例上发出 ::shutdown 信号。

Gio.Application::startup

注册后立即在主实例上发出 ::startup 信号。请参阅 `g_application_register()`。

GObject(1)继承的信号
GObject::notify

当通过 `g_object_set_property()`, `g_object_set()` 等方式设置对象的某个属性的值时,便会发出 notify 信号。

GActionGroup(4)继承的信号
GActionGroup::action-added

发出信号表示刚向组中添加了一个新动作。

自:2.28

GActionGroup::action-enabled-changed

发出信号表示名为动作的启用状态已

自:2.28

GActionGroup::action-removed

发出信号表示某个动作即将从组中移除。

自:2.28

GActionGroup::action-state-changed

发出信号表示名为动作的状态已

自:2.28

类结构

struct GioApplicationClass {
  void (* startup) (
    GApplication* application
  );
  void (* activate) (
    GApplication* application
  );
  void (* open) (
    GApplication* application,
    GFile** files,
    gint n_files,
    const gchar* hint
  );
  int (* command_line) (
    GApplication* application,
    GApplicationCommandLine* command_line
  );
  gboolean (* local_command_line) (
    GApplication* application,
    gchar*** arguments,
    int* exit_status
  );
  void (* before_emit) (
    GApplication* application,
    GVariant* platform_data
  );
  void (* after_emit) (
    GApplication* application,
    GVariant* platform_data
  );
  void (* add_platform_data) (
    GApplication* application,
    GVariantBuilder* builder
  );
  void (* quit_mainloop) (
    GApplication* application
  );
  void (* run_mainloop) (
    GApplication* application
  );
  void (* shutdown) (
    GApplication* application
  );
  gboolean (* dbus_register) (
    GApplication* application,
    GDBusConnection* connection,
    const gchar* object_path,
    GError** error
  );
  void (* dbus_unregister) (
    GApplication* application,
    GDBusConnection* connection,
    const gchar* object_path
  );
  gint (* handle_local_options) (
    GApplication* application,
    GVariantDict* options
  );
  gboolean (* name_lost) (
    GApplication* application
  );
  
}

用于 `GApplication` 的虚拟函数表。

类成员
startup: void (* startup)(GApplication * application)

注册后立即在主实例上调用。

activate: void (* activate)(GApplication * application)

发生激活时在主实例上调用。

open: void (* open)(GApplication * application, GFile ** files, gint n_files, const gchar * hint)

当有要打开的文件时在主实例上调用。

command_line: int (* command_line) ( GApplication* application, GApplicationCommandLine* command_line )

当命令行未本地处理时,在第一实例上调用。

local_command_line: gboolean (* local_command_line) ( GApplication* application, gchar*** arguments, int* exit_status )

调用(本地)。虚拟函数有机会检查(并可能替换)命令行参数。有关更多信息,请参阅 g_application_run()。另请参阅 GApplication::handle-local-options 信号,它是一种更简单的替代方法,用于在本地处理一些命令行选项。

before_emit: void (* before_emit) ( GApplication* application, GVariant* platform_data )

在 ‘activate’、‘open’、‘command-line’ 或任何操作调用之前在第一实例上调用,从调用实例获取 ‘platform data’。

after_emit: void (* after_emit) ( GApplication* application, GVariant* platform_data )

在 ‘activate’、‘open’、‘command-line’ 或任何操作调用之后在第一实例上调用,从调用实例获取 ‘platform data’。

add_platform_data: void (* add_platform_data) ( GApplication* application, GVariantBuilder* builder )

在激活、打开或调用操作时,调用(本地)以添加 ‘platform data’ 以发送到第一实例。

quit_mainloop: void (* quit_mainloop) ( GApplication* application )

从 2.32 开始不再使用。习惯于在应用程序的使用计数降至零(以及在任何非活动超时之后,如果请求)时在第一实例上调用。

run_mainloop: void (* run_mainloop) ( GApplication* application )

g_application_run() 习惯于从第一实例调用如果使用计数非零。自 2.32 起,GApplication 直接迭代主上下文,不再使用 run_mainloop

shutdown: void (* shutdown) ( GApplication* application )

仅在主循环终止后立即在已注册的第一实例上调用。

dbus_register: gboolean (* dbus_register) ( GApplication* application, GDBusConnection* connection, const gchar* object_path, GError** error )

如果应用程序正在使用 D-Bus 后端,则在注册期间在本地调用。你可以使用此方法在总线上导出额外的对象,该对象在应用程序尝试拥有总线名称之前需要存在。该函数将 GDBusConnection 传递给会话总线,以及 GApplication 将用来导出其 D-Bus API 的对象路径。如果此函数返回 TRUE,则注册将继续进行;否则,注册将中止。自: 2.34。

dbus_unregister: void (* dbus_unregister) ( GApplication* application, GDBusConnection* connection, const gchar* object_path )

如果应用程序正在使用 D-Bus 后端,则在注销期间在本地调用。使用此方法撤消 dbus_register vfunc 所做的任何操作。自: 2.34。

handle_local_options: gint (* handle_local_options) ( GApplication* application, GVariantDict* options )

在命令行选项解析发生后在本地调用。自: 2.40。

name_lost: gboolean (* name_lost) ( GApplication* application )

当另一个实例接管名称时调用。自: 2.60。

虚拟方法

Gio.ApplicationClass.activate

激活该

自:2.28

Gio.ApplicationClass.add_platform_data

在激活、打开或调用操作时,调用(本地)以添加 ‘platform data’ 以发送到第一实例。

Gio.ApplicationClass.after_emit

在 ‘activate’、‘open’、‘command-line’ 或任何操作调用之后在第一实例上调用,从调用实例获取 ‘platform data’。

Gio.ApplicationClass.before_emit

在 ‘activate’、‘open’、‘command-line’ 或任何操作调用之前在第一实例上调用,从调用实例获取 ‘platform data’。

Gio.ApplicationClass.command_line

当命令行未本地处理时,在第一实例上调用。

Gio.ApplicationClass.dbus_register

如果应用程序正在使用 D-Bus 后端,则在注册期间在本地调用。你可以使用此方法在总线上导出额外的对象,该对象在应用程序尝试拥有总线名称之前需要存在。该函数将 GDBusConnection 传递给会话总线,以及 GApplication 将用来导出其 D-Bus API 的对象路径。如果此函数返回 TRUE,则注册将继续进行;否则,注册将中止。自: 2.34。

Gio.ApplicationClass.dbus_unregister

如果应用程序正在使用 D-Bus 后端,则在注销期间在本地调用。使用此方法撤消 dbus_register vfunc 所做的任何操作。自: 2.34。

Gio.ApplicationClass.handle_local_options

在命令行选项解析发生后在本地调用。自: 2.40。

Gio.ApplicationClass.local_command_line

总是调用此虚拟函数在本地实例中。它得到一个指向 argvNULL 终止副本的指针并希望删除它处理的参数(向上移动剩余参数)。

Gio.ApplicationClass.name_lost

当另一个实例接管名称时调用。自: 2.60。

Gio.ApplicationClass.open

打开给定的

自:2.28

Gio.ApplicationClass.quit_mainloop

从 2.32 开始不再使用。习惯于在应用程序的使用计数降至零(以及在任何非活动超时之后,如果请求)时在第一实例上调用。

Gio.ApplicationClass.run_mainloop

g_application_run() 习惯于从第一实例调用如果使用计数非零。自 2.32 起,GApplication 直接迭代主上下文,不再使用 run_mainloop

Gio.ApplicationClass.shutdown

仅在主循环终止后立即在已注册的第一实例上调用。

Gio.ApplicationClass.startup

注册后立即在主实例上调用。