3.3.2 GtkExpression
3.3.2 GtkExpression
GtkExpression — 用于获取值的表达式。
函数
| void | (*GtkExpressionNotify) () | GtkExpression * | gtk_expression_ref () |
| void | gtk_expression_unref () | GType | gtk_expression_get_value_type () |
| gboolean | gtk_expression_is_static () | gboolean | gtk_expression_evaluate () |
| GtkExpressionWatch * | gtk_expression_watch () | GtkExpressionWatch * | gtk_expression_bind () |
| GtkExpressionWatch * | gtk_expression_watch_ref () | void | gtk_expression_watch_unref () |
| gboolean | gtk_expression_watch_evaluate () | void | gtk_expression_watch_unwatch () |
| GtkExpression * | gtk_property_expression_new () | GtkExpression * | gtk_property_expression_new_for_pspec () |
| GtkExpression * | gtk_property_expression_get_expression () | GParamSpec * | gtk_property_expression_get_pspec () |
| GtkExpression * | gtk_constant_expression_new () | GtkExpression * | gtk_constant_expression_new_for_value () |
| const GValue * | gtk_constant_expression_get_value () | GtkExpression * | gtk_object_expression_new () |
| GObject * | gtk_object_expression_get_object () | GtkExpression * | gtk_closure_expression_new () |
| GtkExpression * | gtk_cclosure_expression_new () | #define | GTK_VALUE_HOLDS_EXPRESSION() |
| void | gtk_value_set_expression () | void | gtk_value_take_expression () |
| GtkExpression * | gtk_value_get_expression () | GtkExpression * | gtk_value_dup_expression () |
| GParamSpec * | gtk_param_spec_expression () | ||
类型与值
| GtkExpression | |
| GtkExpressionWatch | |
| GtkParamSpecExpression | |
对象层次结构
GtkExpression
头文件
#include <gtk/gtk.h>
概述
GtkExpression 提供了一种描述值引用的方式。
表达式的一个重要方面是，值可以从多个步骤之外的源获取。例如，一个表达式可能描述 “object1 的属性 A 的值，而 object1 本身是 object2 的某个属性的值”。甚至在创建表达式时，object1 可能尚未存在。这与 GObject 属性绑定形成对比，后者只能在两个对象的属性之间建立直接连接，且这两个对象在绑定期间必须都存在。
表达式需要 “求值” 才能获取它当前引用的值。求值始终在一个称为 this 的当前对象上下文中进行（这与面向对象语言的行为类似），该对象可能会影响求值结果，也可能不会。使用 gtk_expression_evaluate() 进行表达式求值。
存在多种定义表达式的方法，从通过 gtk_constant_expression_new() 创建简单常量，到通过 gtk_property_expression_new() 查找 GObject 中的属性（甚至递归查找），或通过 gtk_closure_expression_new() 提供自定义函数来转换和组合表达式。
以下是一个复杂表达式的示例：
当以 GtkListItem 作为 this 求值时，它会从 GtkListItem 中获取 “item” 属性，然后从结果对象（假设为 GTK_TYPE_COLOR 类型）中获取 “name” 属性。
更简洁的描述方式为：this.item.name。
你最有可能在列表模型和使用列表模型的列表控件中遇到表达式。例如，GtkDropDown 会求值 GtkExpression 以从其模型的项中获取字符串，然后用于与搜索框内容匹配。GtkStringFilter 出于类似原因使用 GtkExpression。
默认情况下，表达式不会关注变化，求值结果只是特定时间点当前状态的快照。若要获取变化通知，需要通过 GtkExpressionWatch 对表达式进行 “监视”，这会在表达式的值可能发生变化时触发回调。gtk_expression_watch() 开始监视表达式，gtk_expression_watch_unwatch() 停止监视。
你可以创建监视以自动更新对象的属性，类似 GObject 的 GBinding 机制，方法是使用 gtk_expression_bind()。
GObject 属性中的 GtkExpression
要将 GtkExpression 用作 GObject 属性，在创建要安装到所定义的 GObject 类中的 GParamSpec 时，必须使用 gtk_param_spec_expression()。
在实现 GObjectClass.set_property () 和 GObjectClass.get_property () 虚函数时，必须使用 gtk_value_get_expression() 从 GValue 容器中检索存储的 GtkExpression，并使用 gtk_value_set_expression() 将 GtkExpression 存储到 GValue 中。
.ui 文件中的 GtkExpression
GtkBuilder 支持创建表达式。以下语法可用于需要 GtkExpression 对象的场景，例如表达式属性的
- 创建属性表达式：使用
元素。它可以通过 type 属性指定对象类型，通过 name 属性指定要查找的属性。 的内容可以是指定表达式所用对象的元素，也可以是指定所用对象名称的字符串。示例：
color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM,
NULL, "item");
expression = gtk_property_expression_new (GTK_TYPE_COLOR,
color_expr, "name");
- 创建常量表达式：使用
元素。如果指定了 type 属性，元素内容会被解释为该类型的值；否则，默认视为对象。 - 创建闭包表达式：使用
元素。type 和 function 属性指定闭包所用的函数，元素内容包含用于参数的表达式。
函数详解
GtkExpressionNotify ()
void
(*GtkExpressionNotify) (gpointer user_data);
当表达式的值发生变化时，由 gtk_expression_watch() 调用的回调函数。
参数
user_data 传递给 gtk_expression_watch() 的数据。
gtk_expression_ref ()
GtkExpression *
gtk_expression_ref (GtkExpression *self);
获取给定 GtkExpression 的引用。
参数
self 一个 GtkExpression 实例。
[允许为 NULL]
返回值
带有额外引用的 GtkExpression。
[不转移所有权]
gtk_expression_unref ()
void
gtk_expression_unref (GtkExpression *self);
释放给定 GtkExpression 的引用。
若该引用是最后一个引用，与 self 关联的资源将被释放。
参数
self 一个 GtkExpression 实例。
[允许为 NULL]
gtk_expression_get_value_type ()
GType
gtk_expression_get_value_type (GtkExpression *self);
获取此表达式求值结果的 GType。该类型是常量，在表达式的生命周期内不会改变。
参数
self 一个 GtkExpression 实例。
返回值
gtk_expression_evaluate() 返回的类型。
gtk_expression_is_static ()
gboolean
gtk_expression_is_static (GtkExpression *self);
检查表达式是否为静态的。
静态表达式在使用相同参数调用 gtk_expression_evaluate() 时，其结果永远不会改变。
这意味着无需调用 gtk_expression_watch()，因为它永远不会触发通知。
参数
self 一个 GtkExpression 实例。
返回值
如果表达式是静态的，则返回 TRUE。
gtk_expression_evaluate ()
gboolean
gtk_expression_evaluate (GtkExpression *self,
gpointer this_,
GValue *value);
对给定表达式求值，成功时将结果存储在 value 中。value 的 GType 即为 gtk_expression_get_value_type() 返回的类型。
表达式可能无法求值（例如，当表达式引用的对象已销毁或被设为 NULL 时）。这种情况下，value 将保持为空，并返回 FALSE。
参数
self 一个 GtkExpression 实例。
this_ 求值时的 this 参数。 [不转移所有权][type GObject][可为空]
value 一个空的 GValue 实例。
返回值
如果表达式可被求值，则返回 TRUE。
gtk_expression_watch ()
GtkExpressionWatch *
gtk_expression_watch (GtkExpression *self,
gpointer this_,
GtkExpressionNotify notify,
gpointer user_data,
GDestroyNotify user_destroy);
为给定表达式安装一个监视器，当 self 的求值结果可能发生变化时，调用 notify 函数。
GTK 无法保证当 notify 被调用时求值结果确实发生了变化，但能保证相反情况：当结果确实变化时，notify 一定会被调用。
参数
self 一个 GtkExpression 实例。
this_ 要监视的 this 参数。 [不转移所有权][type GObject][可为空]
notify 当表达式变化时调用的回调函数。 [闭包关联 user_data]
user_data 传递给 notify 回调的用户数据。
user_destroy user_data 的销毁通知函数。
返回值
新安装的监视器。
请注意，对监视器的唯一引用将在监视器被取消监视时释放（这可能自动发生，而非仅通过 gtk_expression_watch_unwatch()）。如果希望保留监视器，应调用 gtk_expression_watch_ref()。
[不转移所有权]
gtk_expression_bind ()
GtkExpressionWatch *
gtk_expression_bind (GtkExpression *self,
gpointer target,
const char *property,
gpointer this_);
将 target 的 property 属性绑定到 self。
self 的求值结果通过 g_object_set() 设置到 target 上。每当 self 变化时，此操作会重复执行，以确保对象的属性与 self 保持同步。
如果 self 求值失败，target 的属性不会更新。你可以通过使用回退表达式来避免这种情况。
注意：此函数获取 self 的所有权。如果希望保留 self，应提前调用 gtk_expression_ref()。
参数
self 一个 GtkExpression 实例。
[完全转移所有权]
target 要绑定到的目标对象。 [不转移所有权][type GObject]
property target 上要绑定的属性名称。
this_ self 求值时的 this 参数。 [不转移所有权][type GObject][可为空]
返回值
一个 GtkExpressionWatch 实例。
[不转移所有权]
gtk_expression_watch_ref ()
GtkExpressionWatch *
gtk_expression_watch_ref (GtkExpressionWatch *watch);
获取给定 GtkExpressionWatch 的引用。
参数
watch 一个 GtkExpressionWatch 实例。
[允许为 NULL]
返回值
带有额外引用的 GtkExpressionWatch 实例。
[不转移所有权]
gtk_expression_watch_unref ()
void
gtk_expression_watch_unref (GtkExpressionWatch *watch);
释放给定 GtkExpressionWatch 的引用。
若该引用是最后一个引用，与 watch 关联的资源将被释放。
参数
watch 一个 GtkExpressionWatch 实例。
[允许为 NULL]
gtk_expression_watch_evaluate ()
gboolean
gtk_expression_watch_evaluate (GtkExpressionWatch *watch,
GValue *value);
对被监视的表达式求值，成功时将结果存储在 value 中。
此操作等效于使用创建 watch 时原始的表达式和 this 指针调用 gtk_expression_evaluate()。
参数
watch 一个 GtkExpressionWatch 实例。
value 待设置的空 GValue 实例。
返回值
如果表达式可被求值且 value 已被设置，则返回 TRUE。
gtk_expression_watch_unwatch ()
void
gtk_expression_watch_unwatch (GtkExpressionWatch *watch);
停止监视通过 gtk_expression_watch() 建立的表达式。
参数
watch 要释放的监视器。 [不转移所有权]
gtk_property_expression_new ()
GtkExpression *
gtk_property_expression_new (GType this_type,
GtkExpression *expression,
const char *property_name);
创建一个表达式，该表达式通过给定的 expression 查找属性；若 expression 为 NULL，则通过 this 参数查找。
如果结果对象符合 this_type 类型，将查询其名为 property_name 的属性。否则，此表达式的求值将失败。
给定的 this_type 必须具有名为 property_name 的属性。
参数
this_type 期望的 this 参数类型。
expression 要求值以获取待查询对象的表达式；若为 NULL，则查询 this 对象。 [可为空][完全转移所有权]
property_name 属性的名称。
返回值
一个新的 GtkExpression 实例。
gtk_property_expression_new_for_pspec ()
GtkExpression *
gtk_property_expression_new_for_pspec (GtkExpression *expression,
GParamSpec *pspec);
创建一个表达式，该表达式通过给定的 expression 查找属性；若 expression 为 NULL，则通过 this 参数查找。
如果结果对象符合 this_type 类型，将查询由 pspec 指定的属性。否则，此表达式的求值将失败。
参数
expression 要求值以获取待查询对象的表达式；若为 NULL，则查询 this 对象。 [可为空][完全转移所有权]
pspec 待查询属性的 GParamSpec。
返回值
一个新的 GtkExpression 实例。
gtk_property_expression_get_expression ()
GtkExpression *
gtk_property_expression_get_expression
(GtkExpression *expression);
获取指定属性表达式中用于指定对象的表达式。
参数
expression 一个属性 GtkExpression 实例。
[type GtkPropertyExpression]
返回值
对象表达式。
[不转移所有权]
gtk_property_expression_get_pspec ()
GParamSpec *
gtk_property_expression_get_pspec (GtkExpression *expression);
获取指定属性表达式中用于指定属性的 GParamSpec。
参数
expression 一个属性 GtkExpression 实例。
[type GtkPropertyExpression]
返回值
GParamSpec 实例。
[不转移所有权]
gtk_constant_expression_new ()
GtkExpression *
gtk_constant_expression_new (GType value_type,
...);
创建一个 GtkExpression，其求值结果为通过参数指定的对象。
参数
value_type 对象的类型。
... 用于创建对象的参数。
返回值
一个新的 GtkExpression 实例。
gtk_constant_expression_new_for_value ()
GtkExpression *
gtk_constant_expression_new_for_value (const GValue *value);
创建一个表达式，其求值结果始终为给定的 value。
参数
value 一个 GValue 实例。
返回值
一个新的 GtkExpression 实例。
gtk_constant_expression_get_value ()
const GValue *
gtk_constant_expression_get_value (GtkExpression *expression);
获取常量表达式的求值结果值。
参数
expression 一个常量 GtkExpression 实例。
[type GtkConstantExpression]
返回值
该值。
[不转移所有权]
gtk_object_expression_new ()
GtkExpression *
gtk_object_expression_new (GObject *object);
创建一个表达式，其求值结果为给定的对象（使用弱引用）。一旦该对象被销毁，表达式将无法求值。此表达式用于打破引用循环。
如果希望保留对 object 的引用，使用 gtk_constant_expression_new() 。
参数
object 要监视的对象。 [不转移所有权]
返回值
一个新的 GtkExpression 实例。
gtk_object_expression_get_object ()
GObject *
gtk_object_expression_get_object (GtkExpression *expression);
获取表达式的求值结果对象。
参数
expression 一个对象 GtkExpression 实例。 [type GtkObjectExpression]
返回值
该对象，或 NULL。
[不转移所有权][可为空]
gtk_closure_expression_new ()
GtkExpression *
gtk_closure_expression_new (GType value_type,
GClosure *closure,
guint n_params,
GtkExpression **params);
创建一个 GtkExpression，在求值时会调用 closure。调用 closure 时会传入 this 对象以及对 params 表达式求值的结果。
参数
value_type 此表达式求值结果的类型。
closure 求值时要调用的闭包（closure）。如果闭包是浮动的，会被接管。
n_params 求值 closure 所需的参数数量。
params 每个参数对应的表达式。 [可为空][array length=n_params][完全转移所有权]
返回值
一个新的 GtkExpression 实例。
gtk_cclosure_expression_new ()
GtkExpression *
gtk_cclosure_expression_new (GType value_type,
GClosureMarshal marshal,
guint n_params,
GtkExpression **params,
GCallback callback_func,
gpointer user_data,
GClosureNotify user_destroy);
此函数是 gtk_closure_expression_new() 的变体，通过调用 g_cclosure_new() 并传入给定的 callback_func、user_data 和 user_destroy 来创建 GClosure。
参数
value_type 此表达式求值结果的类型。
marshal 用于创建闭包的封送器。 [调用期有效][可为空]
n_params 求值闭包所需的参数数量。
params 每个参数对应的表达式。 [array length=n_params][完全转移所有权]
callback_func 用于创建闭包的回调函数。 [scope notified][闭包关联 user_data][destroy user_destroy]
user_data 用于创建闭包的用户数据。 [可为空]
user_destroy user_data 的销毁通知函数。 [可为空]
返回值
一个新的GtkExpression 实例。
GTK_VALUE_HOLDS_EXPRESSION()
#define GTK_VALUE_HOLDS_EXPRESSION(value) (G_VALUE_HOLDS ((value), GTK_TYPE_EXPRESSION))
如果 value 是用 GTK_TYPE_EXPRESSION 初始化的，则求值结果为 TRUE。
参数
value 一个 GValue 实例。
gtk_value_set_expression ()
void
gtk_value_set_expression (GValue *value,
GtkExpression *expression);
将给定的 GtkExpression 存储到 value 中。
GValue 会获取该表达式的一个引用。
参数
value 用 GTK_TYPE_EXPRESSION 类型初始化的 GValue 实例。
expression 一个 GtkExpression 实例。
gtk_value_take_expression ()
void
gtk_value_take_expression (GValue *value,
GtkExpression *expression);
将给定的 GtkExpression 存储到 value 中。
此函数会将表达式的所有权转移给 GValue。
参数
value 用 GTK_TYPE_EXPRESSION 类型初始化的 GValue 实例。
expression 一个 GtkExpression 实例。 [完全转移所有权][可为空]
gtk_value_get_expression ()
GtkExpression *
gtk_value_get_expression (const GValue *value);
检索存储在给定 value 中的 GtkExpression。
参数
value 用 GTK_TYPE_EXPRESSION 类型初始化的 GValue 实例。
返回值
一个 GtkExpression 实例。
[不转移所有权][可为空]
gtk_value_dup_expression ()
GtkExpression *
gtk_value_dup_expression (const GValue *value);
检索存储在给定 value 中的 GtkExpression，并获取其一个引用。
参数
value 用 GTK_TYPE_EXPRESSION 类型初始化的 GValue 实例。
返回值
一个 GtkExpression 实例。
[完全转移所有权][可为空]
gtk_param_spec_expression ()
GParamSpec *
gtk_param_spec_expression (const char *name,
const char *nick,
const char *blurb,
GParamFlags flags);
为持有 GtkExpression 的属性创建一个新的 GParamSpec 实例。
有关属性字符串的详细信息，参见 g_param_spec_internal()。
参数
name 属性的规范名称。
nick 属性的用户可读名称。
blurb 属性的用户可读描述。
flags 属性的标志。
返回值
新的属性规范。
[完全转移所有权]
类型与值详解
GtkExpression
typedef struct _GtkExpression GtkExpression;
GtkExpression 结构仅包含私有数据。
GtkExpressionWatch
typedef struct _GtkExpressionWatch GtkExpressionWatch;
GtkParamSpecExpression
typedef struct {
} GtkParamSpecExpression;
用于持有 GtkExpression 的属性的 GParamSpec。
做网页好麻烦，想下载的到百度网盘中查看，翻译进度更快。
通过网盘分享的知识：GTK 4 Reference Manual
链接: https://pan.baidu.com/s/57mKoejMZPrxs_wh3a7Kj9g
--来自百度网盘超级会员v7的分享
浙公网安备 33010602011771号