类
GioApplication
自:2.28
描述 [src]
class Gio.Application : GObject.Object
implements Gio.ActionGroup, Gio.ActionMap {
/* No available fields */
}
GApplication
是应用程序支持的核心类。
GApplication
是应用程序的基础。它封装了一些与平台相关的底层服务,旨在作为 GtkApplication
或 MxApplication
等更高级别的应用程序类的基础。通常情况下,你不应在高级别框架之外使用这个类。
GApplication
通过维护主应用程序实例的“使用计数”来提供便利的生命周期管理。可以使用 g_application_hold()
和 g_application_release()
来更改使用计数。如果计数降至零,应用程序将退出。如 GtkApplication
等更高级别的类利用使用计数来确保应用程序在其拥有任何已打开窗口时保持活动状态。
GApplication
(可选地)提供的另一个特性是进程唯一性。应用程序可以通过提供一个应用程序唯一 ID 来利用此功能。如果提供了该 ID,则每次会话中只能运行一个带有此 ID 的应用程序。会话概念依赖于平台,但大致对应于图形桌面登录。当你的应用程序再次启动时,其参数将通过平台通信传递给正在运行的程序。该程序的正在运行实例称为“主实例”;对于非唯一应用程序,这始终是当前实例。在 Linux 上,D-Bus 会话总线用于进行通信。
GApplication
的使用方式在重要方面与其他一些常用的唯一性库(如 libunique)不同。应用程序无需手动注册自身和检查是否为主实例。相反,GApplication
的 main()
函数几乎不需要做太多事,只需实例化应用程序实例,可能连接信号处理程序,然后调用 g_application_run()
。所有唯一性检查都将在内部完成。如果应用程序为主实例,则会发出启动信号并运行主循环。如果应用程序不是主实例,则会向主实例发送信号,并且 g_application_run()
会立即返回。请参阅以下提供的示例代码。
如果使用,应用程序标识符的预期形式与 D-Bus 众所周知的总线名称 相同。示例包括:com.example.MyApp
、org.example.internal_apps.Calculator
、org._7_zip.Archiver
。有关有效的应用程序标识符的详细信息,请参阅 g_application_id_is_valid()
。
在 Linux 上,应用程序标识符被宣称是一个在用户会话总线上明确的总线名称。这意味着您的应用程序的唯一性限定于当前会话。它还意味着您的应用程序可以提供附加服务(通过注册其他对象路径)给定的总线名称。这些对象路径的注册应该与共享的 GDBus 会话总线一起完成。请注意,由于 GDBus 的内部架构,方法调用可以在任何时间调度(即使一个主循环没有在运行)。由于这个原因,您必须确保您希望注册的任何对象路径是在 GApplication
尝试获取您应用程序的总线名称(这在 g_application_register()
)之前注册的。不幸的是,这意味着您不能使用 GApplication:is-remote
来确定您是否想要注册对象路径。
GApplication
也实现了 GActionGroup
和 GActionMap
接口,并让您通过使用 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_emit
或 Gio.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_bind_busy_property
当object
的property
为TRUE
时,将application
标记为繁忙(请参阅 g_application_mark_busy())。
自 2.44 版起可用
g_application_get_is_busy
获取应用程序当前的繁忙状态,如通过 g_application_mark_busy()
或 g_application_bind_busy_property()
设置的那样。
自 2.44 版起可用
g_application_set_action_group
过去,操作就是用这种方式与 GApplication
关联的。现在包含 GActionMap
,目的是
已弃用:2.32 自 2.28 版起可用
g_application_unbind_busy_property
销毁 property
和 application
繁忙状态之间的绑定,该绑定先前使用 g_application_bind_busy_property() 创建。
自 2.44 版起可用
从 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:is-busy
根据 `g_application_mark_busy()` 或 `g_application_bind_busy_property()` 将应用程序标记为繁忙。
自 2.44 版起可用
信号
Gio.Application::command-line
当本地未处理命令行时,在主实例上发出 ::command-line 信号。有关更多信息,请参阅 `g_application_run()` 和 `GApplicationCommandLine` 文档。
Gio.Application::name-lost
当新实例接管时,仅在注册的主实例上发出 ::name-lost 信号。仅当应用程序使用 `G_APPLICATION_ALLOW_REPLACEMENT` 标志时,才会发生这种情况。
自:2.60
从 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.after_emit
在 ‘activate’、‘open’、‘command-line’ 或任何操作调用之后在第一实例上调用,从调用实例获取 ‘platform data’。
Gio.ApplicationClass.before_emit
在 ‘activate’、‘open’、‘command-line’ 或任何操作调用之前在第一实例上调用,从调用实例获取 ‘platform data’。
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.local_command_line
总是调用此虚拟函数在本地实例中。它得到一个指向 argv
的 NULL
终止副本的指针并希望删除它处理的参数(向上移动剩余参数)。
Gio.ApplicationClass.run_mainloop
从 g_application_run()
习惯于从第一实例调用如果使用计数非零。自 2.32 起,GApplication 直接迭代主上下文,不再使用 run_mainloop
。