forked from AuroraMiddleware/gtk
expression: Update docs format
And add documentation stanzas for GtkExpression sub-types.
This commit is contained in:
Emmanuele Bassi
parent
1eb9d699b5
commit
cf707cbfaa
@ -36,9 +36,9 @@
|
||||
*
|
||||
* An important aspect of expressions is that the value can be obtained
|
||||
* from a source that is several steps away. For example, an expression
|
||||
* may describe ‘the value of property A of @object1, which is itself the
|
||||
* value of a property of @object2’. And @object1 may not even exist yet
|
||||
* at the time that the expression is created. This is contrast to GObject
|
||||
* may describe ‘the value of property A of `object1`, which is itself the
|
||||
* value of a property of `object2`’. And `object1` may not even exist yet
|
||||
* at the time that the expression is created. This is contrast to `GObject`
|
||||
* property bindings, which can only create direct connections between
|
||||
* the properties of two objects that must both exist for the duration
|
||||
* of the binding.
|
||||
@ -47,53 +47,56 @@
|
||||
* refers to. An evaluation always happens in the context of a current object
|
||||
* called `this` (it mirrors the behavior of object-oriented languages),
|
||||
* which may or may not influence the result of the evaluation. Use
|
||||
* gtk_expression_evaluate() for evaluating an expression.
|
||||
* [method@Gtk.Expression.evaluate] for evaluating an expression.
|
||||
*
|
||||
* Various methods for defining expressions exist, from simple constants via
|
||||
* gtk_constant_expression_new() to looking up properties in a #GObject (even
|
||||
* recursively) via gtk_property_expression_new() or providing custom functions
|
||||
* to transform and combine expressions via gtk_closure_expression_new().
|
||||
* [ctor@Gtk.ConstantExpression.new] to looking up properties in a `GObject`
|
||||
* (even recursively) via [ctor@Gtk.PropertyExpression.new] or providing
|
||||
* custom functions to transform and combine expressions via
|
||||
* [ctor@Gtk.ClosureExpression.new].
|
||||
*
|
||||
* Here is an example of a complex expression:
|
||||
* |[
|
||||
*
|
||||
* ```c
|
||||
* color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM,
|
||||
* NULL, "item");
|
||||
* expression = gtk_property_expression_new (GTK_TYPE_COLOR,
|
||||
* color_expr, "name");
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* when evaluated with `this` being a GtkListItem, it will obtain the
|
||||
* "item" property from the GtkListItem, and then obtain the "name" property
|
||||
* from the resulting object (which is assumed to be of type GTK_TYPE_COLOR).
|
||||
* when evaluated with `this` being a `GtkListItem`, it will obtain the
|
||||
* "item" property from the `GtkListItem`, and then obtain the "name" property
|
||||
* from the resulting object (which is assumed to be of type `GTK_TYPE_COLOR`).
|
||||
*
|
||||
* A more concise way to describe this would be
|
||||
* |[
|
||||
*
|
||||
* ```
|
||||
* this->item->name
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* The most likely place where you will encounter expressions is in the context
|
||||
* of list models and list widgets using them. For example, #GtkDropDown is
|
||||
* evaluating a GtkExpression to obtain strings from the items in its model
|
||||
* of list models and list widgets using them. For example, `GtkDropDown` is
|
||||
* evaluating a `GtkExpression` to obtain strings from the items in its model
|
||||
* that it can then use to match against the contents of its search entry.
|
||||
* #GtkStringFilter is using a GtkExpression for similar reasons.
|
||||
* `GtkStringFilter` is using a `GtkExpression` for similar reasons.
|
||||
*
|
||||
* By default, expressions are not paying attention to changes and evaluation is
|
||||
* just a snapshot of the current state at a given time. To get informed about
|
||||
* changes, an expression needs to be "watched" via a #GtkExpressionWatch, which
|
||||
* will cause a callback to be called whenever the value of the expression may
|
||||
* have changed. gtk_expression_watch() starts watching an expression, and
|
||||
* gtk_expression_watch_unwatch() stops.
|
||||
* changes, an expression needs to be "watched" via a [struct@Gtk.ExpressionWatch],
|
||||
* which will cause a callback to be called whenever the value of the expression may
|
||||
* have changed; [method@Gtk.Expression.watch] starts watching an expression, and
|
||||
* [method@Gtk.ExpressionWatch.unwatch] stops.
|
||||
*
|
||||
* Watches can be created for automatically updating the property of an object,
|
||||
* similar to GObject's #GBinding mechanism, by using gtk_expression_bind().
|
||||
* similar to GObject's `GBinding` mechanism, by using [method@Gtk.Expression.bind].
|
||||
*
|
||||
* # GtkExpression in GObject properties
|
||||
* ## GtkExpression in GObject properties
|
||||
*
|
||||
* In order to use a #GtkExpression as a #GObject property, you must use the
|
||||
* gtk_param_spec_expression() when creating a #GParamSpec to install in the
|
||||
* #GObject class being defined; for instance:
|
||||
* In order to use a `GtkExpression` as a `GObject` property, you must use the
|
||||
* [id@gtk_param_spec_expression] when creating a `GParamSpec` to install in the
|
||||
* `GObject` class being defined; for instance:
|
||||
*
|
||||
* |[
|
||||
* ```c
|
||||
* obj_props[PROP_EXPRESSION] =
|
||||
* gtk_param_spec_expression ("expression",
|
||||
* "Expression",
|
||||
@ -101,14 +104,14 @@
|
||||
* G_PARAM_READWRITE |
|
||||
* G_PARAM_STATIC_STRINGS |
|
||||
* G_PARAM_EXPLICIT_NOTIFY);
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* When implementing the #GObjectClass.set_property() and #GObjectClass.get_property()
|
||||
* virtual functions, you must use gtk_value_get_expression(), to retrieve the
|
||||
* stored #GtkExpression from the #GValue container, and gtk_value_set_expression(),
|
||||
* to store the #GtkExpression into the #GValue; for instance:
|
||||
* When implementing the `GObjectClass.set_property` and `GObjectClass.get_property`
|
||||
* virtual functions, you must use [id@gtk_value_get_expression], to retrieve the
|
||||
* stored `GtkExpression` from the `GValue` container, and [id@gtk_value_set_expression],
|
||||
* to store the `GtkExpression` into the `GValue`; for instance:
|
||||
*
|
||||
* |[
|
||||
* ```c
|
||||
* // in set_property()...
|
||||
* case PROP_EXPRESSION:
|
||||
* foo_widget_set_expression (foo, gtk_value_get_expression (value));
|
||||
@ -118,45 +121,44 @@
|
||||
* case PROP_EXPRESSION:
|
||||
* gtk_value_set_expression (value, foo->expression);
|
||||
* break;
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* # GtkExpression in .ui files
|
||||
* ## GtkExpression in .ui files
|
||||
*
|
||||
* GtkBuilder has support for creating expressions. The syntax here can be used where
|
||||
* a #GtkExpression object is needed like in a <property> tag for an expression
|
||||
* property, or in a <binding> tag to bind a property to an expression.
|
||||
* `GtkBuilder` has support for creating expressions. The syntax here can be used where
|
||||
* a `GtkExpression` object is needed like in a `<property>` tag for an expression
|
||||
* property, or in a `<binding>` tag to bind a property to an expression.
|
||||
*
|
||||
* To create an property expression, use the <lookup> element. It can have a `type`
|
||||
* To create an property expression, use the `<lookup>` element. It can have a `type`
|
||||
* attribute to specify the object type, and a `name` attribute to specify the property
|
||||
* to look up. The content of <lookup> can either be an element specfiying the expression
|
||||
* to look up. The content of `<lookup>` can either be an element specfiying the expression
|
||||
* to use the object, or a string that specifies the name of the object to use.
|
||||
*
|
||||
* Example:
|
||||
* |[
|
||||
*
|
||||
* ```xml
|
||||
* <lookup name='search'>string_filter</lookup>
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* To create a constant expression, use the <constant> element. If the type attribute
|
||||
* To create a constant expression, use the `<constant>` element. If the type attribute
|
||||
* is specified, the element content is interpreted as a value of that type. Otherwise,
|
||||
* it is assumed to be an object.
|
||||
* it is assumed to be an object. For instance:
|
||||
*
|
||||
* Example:
|
||||
* |[
|
||||
* ```xml
|
||||
* <constant>string_filter</constant>
|
||||
* <constant type='gchararray'>Hello, world</constant>
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* To create a closure expression, use the <closure> element. The `type` and `function`
|
||||
* To create a closure expression, use the `<closure>` element. The `type` and `function`
|
||||
* attributes specify what function to use for the closure, the content of the element
|
||||
* contains the expressions for the parameters.
|
||||
* contains the expressions for the parameters. For instance:
|
||||
*
|
||||
* Example:
|
||||
* |[
|
||||
* ```xml
|
||||
* <closure type='gchararray' function='combine_args_somehow'>
|
||||
* <constant type='gchararray'>File size:</constant>
|
||||
* <lookup type='GFile' name='size'>myfile</lookup>
|
||||
* </closure>
|
||||
* ]|
|
||||
* ```
|
||||
*/
|
||||
|
||||
|
||||
@ -222,6 +224,14 @@ struct _GtkExpressionTypeInfo
|
||||
GtkExpressionSubWatch *watch);
|
||||
};
|
||||
|
||||
/**
|
||||
* GtkExpressionWatch:
|
||||
*
|
||||
* An opaque structure representing a watched [class@Gtk.Expression].
|
||||
*
|
||||
* The contents of `GtkExpressionWatch` should only be accessed through the
|
||||
* provided API.
|
||||
*/
|
||||
struct _GtkExpressionWatch
|
||||
{
|
||||
GtkExpression *expression;
|
||||
@ -352,12 +362,12 @@ value_expression_lcopy_value (const GValue *value,
|
||||
|
||||
/**
|
||||
* gtk_value_set_expression:
|
||||
* @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
|
||||
* @expression: a #GtkExpression
|
||||
* @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
|
||||
* @expression: a `GtkExpression`
|
||||
*
|
||||
* Stores the given #GtkExpression inside @value.
|
||||
* Stores the given `GtkExpression` inside `value`.
|
||||
*
|
||||
* The #GValue will acquire a reference to the @expression.
|
||||
* The `GValue` will acquire a reference to the `expression`.
|
||||
*/
|
||||
void
|
||||
gtk_value_set_expression (GValue *value,
|
||||
@ -384,12 +394,12 @@ gtk_value_set_expression (GValue *value,
|
||||
|
||||
/**
|
||||
* gtk_value_take_expression:
|
||||
* @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
|
||||
* @expression: (transfer full) (nullable): a #GtkExpression
|
||||
* @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
|
||||
* @expression: (transfer full) (nullable): a `GtkExpression`
|
||||
*
|
||||
* Stores the given #GtkExpression inside @value.
|
||||
* Stores the given `GtkExpression` inside `value`.
|
||||
*
|
||||
* This function transfers the ownership of the @expression to the #GValue.
|
||||
* This function transfers the ownership of the `expression` to the `GValue`.
|
||||
*/
|
||||
void
|
||||
gtk_value_take_expression (GValue *value,
|
||||
@ -416,11 +426,11 @@ gtk_value_take_expression (GValue *value,
|
||||
|
||||
/**
|
||||
* gtk_value_get_expression:
|
||||
* @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
|
||||
* @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
|
||||
*
|
||||
* Retrieves the #GtkExpression stored inside the given @value.
|
||||
* Retrieves the `GtkExpression` stored inside the given `value`.
|
||||
*
|
||||
* Returns: (transfer none) (nullable): a #GtkExpression
|
||||
* Returns: (transfer none) (nullable): a `GtkExpression`
|
||||
*/
|
||||
GtkExpression *
|
||||
gtk_value_get_expression (const GValue *value)
|
||||
@ -432,12 +442,12 @@ gtk_value_get_expression (const GValue *value)
|
||||
|
||||
/**
|
||||
* gtk_value_dup_expression:
|
||||
* @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
|
||||
* @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
|
||||
*
|
||||
* Retrieves the #GtkExpression stored inside the given @value, and acquires
|
||||
* Retrieves the `GtkExpression` stored inside the given `value`, and acquires
|
||||
* a reference to it.
|
||||
*
|
||||
* Returns: (transfer full) (nullable): a #GtkExpression
|
||||
* Returns: (transfer full) (nullable): a `GtkExpression`
|
||||
*/
|
||||
GtkExpression *
|
||||
gtk_value_dup_expression (const GValue *value)
|
||||
@ -529,9 +539,9 @@ gtk_param_expression_get_type (void)
|
||||
* @blurb: a user-readable description of the property
|
||||
* @flags: flags for the property
|
||||
*
|
||||
* Creates a new #GParamSpec instance for a property holding a #GtkExpression.
|
||||
* Creates a new `GParamSpec` instance for a property holding a `GtkExpression`.
|
||||
*
|
||||
* See g_param_spec_internal() for details on the property strings.
|
||||
* See `g_param_spec_internal()` for details on the property strings.
|
||||
*
|
||||
* Returns: (transfer full): a newly created property specification
|
||||
*/
|
||||
@ -707,7 +717,7 @@ gtk_expression_type_register_static (const char *type_name,
|
||||
* @expression_type: the type of expression to create
|
||||
* @value_type: the type of the value returned by this expression
|
||||
*
|
||||
* Returns: (transfer full): the newly created #GtkExpression
|
||||
* Returns: (transfer full): the newly created `GtkExpression`
|
||||
*/
|
||||
static gpointer
|
||||
gtk_expression_alloc (GType expression_type,
|
||||
@ -743,8 +753,11 @@ gtk_expression_subwatch_finish (GtkExpression *self,
|
||||
|
||||
/* {{{ GtkConstantExpression */
|
||||
|
||||
typedef struct _GtkConstantExpression GtkConstantExpression;
|
||||
|
||||
/**
|
||||
* GtkConstantExpression:
|
||||
*
|
||||
* A constant value in a `GtkExpression`.
|
||||
*/
|
||||
struct _GtkConstantExpression
|
||||
{
|
||||
GtkExpression parent;
|
||||
@ -801,10 +814,10 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkConstantExpression,
|
||||
* @value_type: The type of the object
|
||||
* @...: arguments to create the object from
|
||||
*
|
||||
* Creates a GtkExpression that evaluates to the
|
||||
* Creates a `GtkExpression` that evaluates to the
|
||||
* object given by the arguments.
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (transfer full) (type GtkConstantExpression): a new `GtkExpression`
|
||||
*/
|
||||
GtkExpression *
|
||||
gtk_constant_expression_new (GType value_type,
|
||||
@ -838,12 +851,12 @@ gtk_constant_expression_new (GType value_type,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_constant_expression_new_for_value:
|
||||
* @value: a #GValue
|
||||
* gtk_constant_expression_new_for_value: (constructor)
|
||||
* @value: a `GValue`
|
||||
*
|
||||
* Creates an expression that always evaluates to the given @value.
|
||||
* Creates an expression that always evaluates to the given `value`.
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (transfer full) (type GtkConstantExpression): a new `GtkExpression`
|
||||
**/
|
||||
GtkExpression *
|
||||
gtk_constant_expression_new_for_value (const GValue *value)
|
||||
@ -864,7 +877,7 @@ gtk_constant_expression_new_for_value (const GValue *value)
|
||||
|
||||
/**
|
||||
* gtk_constant_expression_get_value:
|
||||
* @expression: (type GtkConstantExpression): a constant #GtkExpression
|
||||
* @expression: (type GtkConstantExpression): a constant `GtkExpression`
|
||||
*
|
||||
* Gets the value that a constant expression evaluates to.
|
||||
*
|
||||
@ -884,9 +897,13 @@ gtk_constant_expression_get_value (GtkExpression *expression)
|
||||
|
||||
/* {{{ GtkObjectExpression */
|
||||
|
||||
typedef struct _GtkObjectExpression GtkObjectExpression;
|
||||
typedef struct _GtkObjectExpressionWatch GtkObjectExpressionWatch;
|
||||
|
||||
/**
|
||||
* GtkObjectExpression:
|
||||
*
|
||||
* A `GObject` value in a `GtkExpression`.
|
||||
*/
|
||||
struct _GtkObjectExpression
|
||||
{
|
||||
GtkExpression parent;
|
||||
@ -999,16 +1016,18 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkObjectExpression,
|
||||
>k_object_expression_info)
|
||||
|
||||
/**
|
||||
* gtk_object_expression_new:
|
||||
* gtk_object_expression_new: (constructor)
|
||||
* @object: (transfer none): object to watch
|
||||
*
|
||||
* Creates an expression evaluating to the given @object with a weak reference.
|
||||
* Once the @object is disposed, it will fail to evaluate.
|
||||
* Creates an expression evaluating to the given `object` with a weak reference.
|
||||
*
|
||||
* Once the `object` is disposed, it will fail to evaluate.
|
||||
*
|
||||
* This expression is meant to break reference cycles.
|
||||
*
|
||||
* If you want to keep a reference to @object, use gtk_constant_expression_new().
|
||||
* If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.new].
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (type GtkObjectExpression) (transfer full): a new `GtkExpression`
|
||||
**/
|
||||
GtkExpression *
|
||||
gtk_object_expression_new (GObject *object)
|
||||
@ -1029,11 +1048,11 @@ gtk_object_expression_new (GObject *object)
|
||||
|
||||
/**
|
||||
* gtk_object_expression_get_object:
|
||||
* @expression: (type GtkObjectExpression): an object #GtkExpression
|
||||
* @expression: (type GtkObjectExpression): an object `GtkExpression`
|
||||
*
|
||||
* Gets the object that the expression evaluates to.
|
||||
*
|
||||
* Returns: (transfer none) (nullable): the object, or %NULL
|
||||
* Returns: (transfer none) (nullable): the object, or `NULL`
|
||||
*/
|
||||
GObject *
|
||||
gtk_object_expression_get_object (GtkExpression *expression)
|
||||
@ -1049,8 +1068,11 @@ gtk_object_expression_get_object (GtkExpression *expression)
|
||||
|
||||
/* {{{ GtkPropertyExpression */
|
||||
|
||||
typedef struct _GtkPropertyExpression GtkPropertyExpression;
|
||||
|
||||
/**
|
||||
* GtkPropertyExpression:
|
||||
*
|
||||
* A `GObject` property value in a `GtkExpression`.
|
||||
*/
|
||||
struct _GtkPropertyExpression
|
||||
{
|
||||
GtkExpression parent;
|
||||
@ -1264,24 +1286,24 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkPropertyExpression,
|
||||
>k_property_expression_info)
|
||||
|
||||
/**
|
||||
* gtk_property_expression_new:
|
||||
* gtk_property_expression_new: (constructor)
|
||||
* @this_type: The type to expect for the this type
|
||||
* @expression: (nullable) (transfer full): Expression to
|
||||
* evaluate to get the object to query or %NULL to
|
||||
* query the `this` object
|
||||
* evaluate to get the object to query or `NULL` to
|
||||
* query the `this` object
|
||||
* @property_name: name of the property
|
||||
*
|
||||
* Creates an expression that looks up a property via the
|
||||
* given @expression or the `this` argument when @expression
|
||||
* is %NULL.
|
||||
* given `expression` or the `this` argument when `expression`
|
||||
* is `NULL`.
|
||||
*
|
||||
* If the resulting object conforms to @this_type, its property
|
||||
* named @property_name will be queried.
|
||||
* Otherwise, this expression's evaluation will fail.
|
||||
* If the resulting object conforms to `this_type`, its property named
|
||||
* `property_name` will be queried. Otherwise, this expression's
|
||||
* evaluation will fail.
|
||||
*
|
||||
* The given @this_type must have a property with @property_name.
|
||||
* The given `this_type` must have a property with `property_name`.
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (type GtkPropertyExpression) (transfer full): a new `GtkExpression`
|
||||
**/
|
||||
GtkExpression *
|
||||
gtk_property_expression_new (GType this_type,
|
||||
@ -1318,21 +1340,21 @@ gtk_property_expression_new (GType this_type,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_property_expression_new_for_pspec:
|
||||
* gtk_property_expression_new_for_pspec: (constructor)
|
||||
* @expression: (nullable) (transfer full): Expression to
|
||||
* evaluate to get the object to query or %NULL to
|
||||
* query the `this` object
|
||||
* @pspec: the #GParamSpec for the property to query
|
||||
* evaluate to get the object to query or `NULL` to
|
||||
* query the `this` object
|
||||
* @pspec: the `GParamSpec` for the property to query
|
||||
*
|
||||
* Creates an expression that looks up a property via the
|
||||
* given @expression or the `this` argument when @expression
|
||||
* is %NULL.
|
||||
* given `expression` or the `this` argument when `expression`
|
||||
* is `NULL`.
|
||||
*
|
||||
* If the resulting object conforms to @this_type, its
|
||||
* property specified by @pspec will be queried.
|
||||
* If the resulting object conforms to `this_type`, its
|
||||
* property specified by `pspec` will be queried.
|
||||
* Otherwise, this expression's evaluation will fail.
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (type GtkPropertyExpression) (transfer full): a new `GtkExpression`
|
||||
**/
|
||||
GtkExpression *
|
||||
gtk_property_expression_new_for_pspec (GtkExpression *expression,
|
||||
@ -1352,7 +1374,7 @@ gtk_property_expression_new_for_pspec (GtkExpression *expression,
|
||||
|
||||
/**
|
||||
* gtk_property_expression_get_expression:
|
||||
* @expression: (type GtkPropertyExpression): a property #GtkExpression
|
||||
* @expression: (type GtkPropertyExpression): a property `GtkExpression`
|
||||
*
|
||||
* Gets the expression specifying the object of
|
||||
* a property expression.
|
||||
@ -1371,12 +1393,12 @@ gtk_property_expression_get_expression (GtkExpression *expression)
|
||||
|
||||
/**
|
||||
* gtk_property_expression_get_pspec:
|
||||
* @expression: (type GtkPropertyExpression): a property #GtkExpression
|
||||
* @expression: (type GtkPropertyExpression): a property `GtkExpression`
|
||||
*
|
||||
* Gets the #GParamSpec specifying the property of
|
||||
* Gets the `GParamSpec` specifying the property of
|
||||
* a property expression.
|
||||
*
|
||||
* Returns: (transfer none): the #GParamSpec
|
||||
* Returns: (transfer none): the `GParamSpec` for the property
|
||||
*/
|
||||
GParamSpec *
|
||||
gtk_property_expression_get_pspec (GtkExpression *expression)
|
||||
@ -1392,8 +1414,12 @@ gtk_property_expression_get_pspec (GtkExpression *expression)
|
||||
|
||||
/* {{{ GtkClosureExpression */
|
||||
|
||||
typedef struct _GtkClosureExpression GtkClosureExpression;
|
||||
|
||||
/**
|
||||
* GtkClosureExpression:
|
||||
*
|
||||
* An expression using a custom `GClosure` to compute the value from
|
||||
* its parameters.
|
||||
*/
|
||||
struct _GtkClosureExpression
|
||||
{
|
||||
GtkExpression parent;
|
||||
@ -1580,17 +1606,17 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkClosureExpression,
|
||||
>k_closure_expression_info)
|
||||
|
||||
/**
|
||||
* gtk_closure_expression_new:
|
||||
* gtk_closure_expression_new: (constructor)
|
||||
* @value_type: the type of the value that this expression evaluates to
|
||||
* @closure: closure to call when evaluating this expression. If closure is floating, it is adopted
|
||||
* @n_params: the number of params needed for evaluating @closure
|
||||
* @n_params: the number of params needed for evaluating `closure`
|
||||
* @params: (nullable) (array length=n_params) (transfer full): expressions for each parameter
|
||||
*
|
||||
* Creates a GtkExpression that calls @closure when it is evaluated.
|
||||
* @closure is called with the @this object and the results of evaluating
|
||||
* the @params expressions.
|
||||
* Creates a `GtkExpression` that calls `closure` when it is evaluated.
|
||||
* `closure` is called with the `this` object and the results of evaluating
|
||||
* the `params` expressions.
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (transfer full) (type GtkClosureExpression): a new `GtkExpression`
|
||||
*/
|
||||
GtkExpression *
|
||||
gtk_closure_expression_new (GType value_type,
|
||||
@ -1625,8 +1651,11 @@ gtk_closure_expression_new (GType value_type,
|
||||
|
||||
/* {{{ GtkCClosureExpression */
|
||||
|
||||
typedef struct _GtkCClosureExpression GtkCClosureExpression;
|
||||
|
||||
/**
|
||||
* GtkCClosureExpression:
|
||||
*
|
||||
* A variant of [class@Gtk.ClosureExpression] using a C closure.
|
||||
*/
|
||||
struct _GtkCClosureExpression
|
||||
{
|
||||
GtkClosureExpression parent;
|
||||
@ -1649,7 +1678,7 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression,
|
||||
>k_cclosure_expression_info)
|
||||
|
||||
/**
|
||||
* gtk_cclosure_expression_new:
|
||||
* gtk_cclosure_expression_new: (constructor)
|
||||
* @value_type: the type of the value that this expression evaluates to
|
||||
* @marshal: (scope call) (nullable): marshaller used for creating a closure
|
||||
* @n_params: the number of params needed for evaluating @closure
|
||||
@ -1658,11 +1687,11 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression,
|
||||
* @user_data: (nullable): user data used for creating a closure
|
||||
* @user_destroy: (nullable): destroy notify for @user_data
|
||||
*
|
||||
* This function is a variant of gtk_closure_expression_new() that
|
||||
* creates a #GClosure by calling g_cclosure_new() with the given
|
||||
* @callback_func, @user_data and @user_destroy.
|
||||
* This function is a variant of [ctor@Gtk.ClosureExpression.new] that
|
||||
* creates a `GClosure` by calling `g_cclosure_new()` with the given
|
||||
* `callback_func`, `user_data` and `user_destroy`.
|
||||
*
|
||||
* Returns: a new #GtkExpression
|
||||
* Returns: (transfer full) (type GtkCClosureExpression): a new `GtkExpression`
|
||||
*/
|
||||
GtkExpression *
|
||||
gtk_cclosure_expression_new (GType value_type,
|
||||
@ -1707,11 +1736,11 @@ gtk_cclosure_expression_new (GType value_type,
|
||||
|
||||
/**
|
||||
* gtk_expression_ref:
|
||||
* @self: (allow-none): a #GtkExpression
|
||||
* @self: a `GtkExpression`
|
||||
*
|
||||
* Acquires a reference on the given #GtkExpression.
|
||||
* Acquires a reference on the given `GtkExpression`.
|
||||
*
|
||||
* Returns: (transfer none): the #GtkExpression with an additional reference
|
||||
* Returns: (transfer full): the `GtkExpression` with an additional reference
|
||||
*/
|
||||
GtkExpression *
|
||||
gtk_expression_ref (GtkExpression *self)
|
||||
@ -1725,11 +1754,11 @@ gtk_expression_ref (GtkExpression *self)
|
||||
|
||||
/**
|
||||
* gtk_expression_unref:
|
||||
* @self: (allow-none): a #GtkExpression
|
||||
* @self: (transfer full): a `GtkExpression`
|
||||
*
|
||||
* Releases a reference on the given #GtkExpression.
|
||||
* Releases a reference on the given `GtkExpression`.
|
||||
*
|
||||
* If the reference was the last, the resources associated to the @self are
|
||||
* If the reference was the last, the resources associated to the `self` are
|
||||
* freed.
|
||||
*/
|
||||
void
|
||||
@ -1743,12 +1772,12 @@ gtk_expression_unref (GtkExpression *self)
|
||||
|
||||
/**
|
||||
* gtk_expression_get_value_type:
|
||||
* @self: a #GtkExpression
|
||||
* @self: a `GtkExpression`
|
||||
*
|
||||
* Gets the #GType that this expression evaluates to. This type
|
||||
* Gets the `GType` that this expression evaluates to. This type
|
||||
* is constant and will not change over the lifetime of this expression.
|
||||
*
|
||||
* Returns: The type returned from gtk_expression_evaluate()
|
||||
* Returns: The type returned from [method@Gtk.Expression.evaluate]
|
||||
**/
|
||||
GType
|
||||
gtk_expression_get_value_type (GtkExpression *self)
|
||||
@ -1760,20 +1789,22 @@ gtk_expression_get_value_type (GtkExpression *self)
|
||||
|
||||
/**
|
||||
* gtk_expression_evaluate:
|
||||
* @self: a #GtkExpression
|
||||
* @self: a `GtkExpression`
|
||||
* @this_: (transfer none) (type GObject) (nullable): the this argument for the evaluation
|
||||
* @value: an empty #GValue
|
||||
* @value: an empty `GValue`
|
||||
*
|
||||
* Evaluates the given expression and on success stores the result
|
||||
* in @value. The #GType of @value will be the type given by
|
||||
* gtk_expression_get_value_type().
|
||||
* in @value.
|
||||
*
|
||||
* The `GType` of `value` will be the type given by
|
||||
* [method@Gtk.Expression.get_value_type].
|
||||
*
|
||||
* It is possible that expressions cannot be evaluated - for example
|
||||
* when the expression references objects that have been destroyed or
|
||||
* set to %NULL. In that case @value will remain empty and %FALSE
|
||||
* set to `NULL`. In that case `value` will remain empty and `FALSE`
|
||||
* will be returned.
|
||||
*
|
||||
* Returns: %TRUE if the expression could be evaluated
|
||||
* Returns: `TRUE` if the expression could be evaluated
|
||||
**/
|
||||
gboolean
|
||||
gtk_expression_evaluate (GtkExpression *self,
|
||||
@ -1789,17 +1820,17 @@ gtk_expression_evaluate (GtkExpression *self,
|
||||
|
||||
/**
|
||||
* gtk_expression_is_static:
|
||||
* @self: a #GtkExpression
|
||||
* @self: a `GtkExpression`
|
||||
*
|
||||
* Checks if the expression is static.
|
||||
*
|
||||
* A static expression will never change its result when
|
||||
* gtk_expression_evaluate() is called on it with the same arguments.
|
||||
* [method@Gtk.Expression.evaluate] is called on it with the same arguments.
|
||||
*
|
||||
* That means a call to gtk_expression_watch() is not necessary because
|
||||
* That means a call to [method@Gtk.Expression.watch] is not necessary because
|
||||
* it will never trigger a notify.
|
||||
*
|
||||
* Returns: %TRUE if the expression is static
|
||||
* Returns: `TRUE` if the expression is static
|
||||
**/
|
||||
gboolean
|
||||
gtk_expression_is_static (GtkExpression *self)
|
||||
@ -1840,26 +1871,26 @@ gtk_expression_watch_cb (gpointer data)
|
||||
|
||||
/**
|
||||
* gtk_expression_watch:
|
||||
* @self: a #GtkExpression
|
||||
* @self: a `GtkExpression`
|
||||
* @this_: (transfer none) (type GObject) (nullable): the `this` argument to
|
||||
* watch
|
||||
* @notify: (closure user_data): callback to invoke when the
|
||||
* expression changes
|
||||
* @user_data: user data to pass to @notify callback
|
||||
* @user_destroy: destroy notify for @user_data
|
||||
* @user_data: user data to pass to the `notify` callback
|
||||
* @user_destroy: destroy notify for `user_data`
|
||||
*
|
||||
* Installs a watch for the given @expression that calls the @notify function
|
||||
* whenever the evaluation of @self may have changed.
|
||||
* Installs a watch for the given `expression` that calls the `notify` function
|
||||
* whenever the evaluation of `self` may have changed.
|
||||
*
|
||||
* GTK cannot guarantee that the evaluation did indeed change when the @notify
|
||||
* gets invoked, but it guarantees the opposite: When it did in fact change,
|
||||
* the @notify will be invoked.
|
||||
* the `notify` will be invoked.
|
||||
*
|
||||
* Returns: (transfer none): The newly installed watch. Note that the only
|
||||
* reference held to the watch will be released when the watch is unwatched
|
||||
* which can happen automatically, and not just via
|
||||
* gtk_expression_watch_unwatch(). You should call gtk_expression_watch_ref()
|
||||
* if you want to keep the watch around.
|
||||
* reference held to the watch will be released when the watch is unwatched
|
||||
* which can happen automatically, and not just via
|
||||
* [method@Gtk.ExpressionWatch.unwatch]. You should call [method@Gtk.ExpressionWatch.ref]
|
||||
* if you want to keep the watch around.
|
||||
**/
|
||||
GtkExpressionWatch *
|
||||
gtk_expression_watch (GtkExpression *self,
|
||||
@ -1895,11 +1926,11 @@ gtk_expression_watch (GtkExpression *self,
|
||||
|
||||
/**
|
||||
* gtk_expression_watch_ref:
|
||||
* @watch: (allow-none): a #GtkExpressionWatch
|
||||
* @watch: a `GtkExpressionWatch`
|
||||
*
|
||||
* Acquires a reference on the given #GtkExpressionWatch.
|
||||
* Acquires a reference on the given `GtkExpressionWatch`.
|
||||
*
|
||||
* Returns: (transfer none): the #GtkExpression with an additional reference
|
||||
* Returns: (transfer full): the `GtkExpressionWatch` with an additional reference
|
||||
*/
|
||||
GtkExpressionWatch *
|
||||
gtk_expression_watch_ref (GtkExpressionWatch *watch)
|
||||
@ -1917,11 +1948,11 @@ gtk_expression_watch_finalize (gpointer data)
|
||||
|
||||
/**
|
||||
* gtk_expression_watch_unref:
|
||||
* @watch: (allow-none): a #GtkExpressionWatch
|
||||
* @watch: (transfer full): a `GtkExpressionWatch`
|
||||
*
|
||||
* Releases a reference on the given #GtkExpressionWatch.
|
||||
* Releases a reference on the given `GtkExpressionWatch`.
|
||||
*
|
||||
* If the reference was the last, the resources associated to @self are
|
||||
* If the reference was the last, the resources associated to `self` are
|
||||
* freed.
|
||||
*/
|
||||
void
|
||||
@ -1934,7 +1965,7 @@ gtk_expression_watch_unref (GtkExpressionWatch *watch)
|
||||
* gtk_expression_watch_unwatch:
|
||||
* @watch: (transfer none): watch to release
|
||||
*
|
||||
* Stops watching an expression that was established via gtk_expression_watch().
|
||||
* Stops watching an expression that was established via [method@Gtk.Expression.watch].
|
||||
**/
|
||||
void
|
||||
gtk_expression_watch_unwatch (GtkExpressionWatch *watch)
|
||||
@ -1957,16 +1988,16 @@ gtk_expression_watch_unwatch (GtkExpressionWatch *watch)
|
||||
|
||||
/**
|
||||
* gtk_expression_watch_evaluate:
|
||||
* @watch: a #GtkExpressionWatch
|
||||
* @value: an empty #GValue to be set
|
||||
* @watch: a `GtkExpressionWatch`
|
||||
* @value: an empty `GValue` to be set
|
||||
*
|
||||
* Evaluates the watched expression and on success stores the result
|
||||
* in @value.
|
||||
* in `value`.
|
||||
*
|
||||
* This is equivalent to calling gtk_expression_evaluate() with the
|
||||
* expression and this pointer originally used to create @watch.
|
||||
* This is equivalent to calling [method@Gtk.Expression.evaluate] with the
|
||||
* expression and this pointer originally used to create `watch`.
|
||||
*
|
||||
* Returns: %TRUE if the expression could be evaluated and @value was set
|
||||
* Returns: `TRUE` if the expression could be evaluated and `value` was set
|
||||
**/
|
||||
gboolean
|
||||
gtk_expression_watch_evaluate (GtkExpressionWatch *watch,
|
||||
@ -2072,26 +2103,26 @@ gtk_expression_bind_notify (gpointer data)
|
||||
|
||||
/**
|
||||
* gtk_expression_bind:
|
||||
* @self: (transfer full): a #GtkExpression
|
||||
* @self: (transfer full): a `GtkExpression`
|
||||
* @target: (transfer none) (type GObject): the target object to bind to
|
||||
* @property: name of the property on @target to bind to
|
||||
* @property: name of the property on `target` to bind to
|
||||
* @this_: (transfer none) (type GObject) (nullable): the this argument for
|
||||
* the evaluation of @self
|
||||
* the evaluation of `self`
|
||||
*
|
||||
* Bind @target's property named @property to @self.
|
||||
* Bind `target`'s property named `property` to `self`.
|
||||
*
|
||||
* The value that @self evaluates to is set via g_object_set() on
|
||||
* @target. This is repeated whenever @self changes to ensure that
|
||||
* the object's property stays synchronized with @self.
|
||||
* The value that `self` evaluates to is set via `g_object_set()` on
|
||||
* `target`. This is repeated whenever `self` changes to ensure that
|
||||
* the object's property stays synchronized with `self`.
|
||||
*
|
||||
* If @self's evaluation fails, @target's @property is not updated.
|
||||
* If `self`'s evaluation fails, `target`'s `property` is not updated.
|
||||
* You can ensure that this doesn't happen by using a fallback
|
||||
* expression.
|
||||
*
|
||||
* Note that this function takes ownership of @self. If you want
|
||||
* to keep it around, you should gtk_expression_ref() it beforehand.
|
||||
* Note that this function takes ownership of `self`. If you want
|
||||
* to keep it around, you should [method@Gtk.Expression.ref] it beforehand.
|
||||
*
|
||||
* Returns: (transfer none): a #GtkExpressionWatch
|
||||
* Returns: (transfer none): a `GtkExpressionWatch`
|
||||
**/
|
||||
GtkExpressionWatch *
|
||||
gtk_expression_bind (GtkExpression *self,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user