Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'docs-improvs-i' into 'main'

Browse Source 
docs: Improve docs for four classes

See merge request GNOME/gtk!4337
This commit is contained in:
Matthias Clasen
2022-01-06 19:19:31 +00:00
parent 8e8a746cce 1229032b4e
commit 9dccdd1008
7 changed files with 61 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
gsk/gskrendernode.c
View File

@@ -20,7 +20,7 @@
* GskRenderNode: (ref-func gsk_render_node_ref) (unref-func gsk_render_node_unref) (set-value-func gsk_value_set_render_node) (get-value-func gsk_value_get_render_node)
*
* `GskRenderNode` is the basic block in a scene graph to be
* rendered using `GskRenderer`.
* rendered using [class@Gsk.Renderer].
*
* Each node has a parent, except the top-level node; each node may have
* children nodes.
@@ -424,7 +424,7 @@ gsk_render_node_get_bounds (GskRenderNode *node,
*
* Typically, you'll use this function to implement fallback rendering
* of `GskRenderNode`s on an intermediate Cairo context, instead of using
* the drawing context associated to a `GdkSurface`'s rendering buffer.
* the drawing context associated to a [class@Gdk.Surface]'s rendering buffer.
*
* For advanced nodes that cannot be supported using Cairo, in particular
* for nodes doing 3D operations, this function may fail.
@@ -565,8 +565,8 @@ gsk_render_node_diff (GskRenderNode *node1,
* @filename: (type filename): the file to save it to.
* @error: Return location for a potential error
*
* This function is equivalent to calling gsk_render_node_serialize()
* followed by g_file_set_contents().
* This function is equivalent to calling [method@Gsk.RenderNode.serialize]
* followed by [func@GLib.file_set_contents].
*
* See those two functions for details on the arguments.
*
@@ -603,7 +603,7 @@ gsk_render_node_write_to_file (GskRenderNode *node,
* @error_func: (nullable) (scope call): Callback on parsing errors
* @user_data: (closure error_func): user_data for @error_func
*
* Loads data previously created via gsk_render_node_serialize().
* Loads data previously created via [method@Gsk.RenderNode.serialize].
*
* For a discussion of the supported format, see that function.
*
@@ -623,12 +623,12 @@ gsk_render_node_deserialize (GBytes *bytes,
/**
* gsk_value_set_render_node:
* @value: a `GValue` initialized with type `GSK_TYPE_RENDER_NODE`
* @value: a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE`
* @node: a `GskRenderNode`
*
* Stores the given `GskRenderNode` inside `value`.
*
* The `GValue` will acquire a reference to the `node`.
* The [struct@GObject.Value] will acquire a reference to the `node`.
*
* Since: 4.6
*/
@@ -659,7 +659,7 @@ gsk_value_set_render_node (GValue *value,
/**
* gsk_value_take_render_node:
* @value: a `GValue` initialized with type `GSK_TYPE_RENDER_NODE`
* @value: a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE`
* @node: (transfer full) (nullable): a `GskRenderNode`
*
* Stores the given `GskRenderNode` inside `value`.
@@ -713,7 +713,7 @@ gsk_value_get_render_node (const GValue *value)
/**
* gsk_value_dup_render_node:
* @value: a `GValue` initialized with type `GSK_TYPE_RENDER_NODE`
* @value: a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE`
*
* Retrieves the `GskRenderNode` stored inside the given `value`, and acquires
* a reference to it.

2
gtk/css/gtkcsssection.h
View File

@@ -36,7 +36,7 @@ G_BEGIN_DECLS
* Defines a part of a CSS document.
*
* Because sections are nested into one another, you can use
* gtk_css_section_get_parent() to get the containing region.
* [method@CssSection.get_parent] to get the containing region.
*/
typedef struct _GtkCssSection GtkCssSection;

22
gtk/gtkactionable.c
View File

@@ -44,10 +44,10 @@
/**
* GtkActionableInterface:
* @get_action_name: virtual function for gtk_actionable_get_action_name()
* @set_action_name: virtual function for gtk_actionable_set_action_name()
* @get_action_target_value: virtual function for gtk_actionable_get_action_target_value()
* @set_action_target_value: virtual function for gtk_actionable_set_action_target_value()
* @get_action_name: virtual function for [method@Actionable.get_action_name]
* @set_action_name: virtual function for [method@Actionable.set_action_name]
* @get_action_target_value: virtual function for [method@Actionable.get_action_target_value]
* @set_action_target_value: virtual function for [method@Actionable.set_action_target_value]
*
* The interface vtable for `GtkActionable`.
**/
@@ -100,8 +100,8 @@ gtk_actionable_get_action_name (GtkActionable *actionable)
* located) within the hierarchy of a `GtkApplicationWindow`.
*
* Names are of the form “win.save” or “app.quit” for actions on the
* containing `GtkApplicationWindow` or its associated `GtkApplication`,
* respectively. This is the same form used for actions in the `GMenu`
* containing [class@ApplicationWindow] or its associated [class@Application],
* respectively. This is the same form used for actions in the [class@Gio.Menu]
* associated with the window.
*/
void
@@ -134,7 +134,7 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable)
/**
* gtk_actionable_set_action_target_value: (attributes org.gtk.Method.set_property=action-target)
* @actionable: a `GtkActionable` widget
* @target_value: (nullable): a `GVariant` to set as the target value
* @target_value: (nullable): a [struct@GLib.Variant] to set as the target value
*
* Sets the target value of an actionable widget.
*
@@ -145,7 +145,7 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable)
* Second, it is used to determine if the widget should be rendered as
* “active” — the widget is active if the state is equal to the given target.
*
* Consider the example of associating a set of buttons with a `GAction`
* Consider the example of associating a set of buttons with a [iface@Gio.Action]
* with string state in a typical “radio button” situation. Each button
* will be associated with the same action, but with a different target
* value for that action. Clicking on a particular button will activate
@@ -168,12 +168,12 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable,
/**
* gtk_actionable_set_action_target:
* @actionable: a `GtkActionable` widget
* @format_string: a GVariant format string
* @format_string: a [struct@GLib.Variant] format string
* @...: arguments appropriate for @format_string
*
* Sets the target of an actionable widget.
*
* This is a convenience function that calls g_variant_new() for
* This is a convenience function that calls [ctor@GLib.Variant.new] for
* @format_string and uses the result to call
* [method@Gtk.Actionable.set_action_target_value].
*
@@ -202,7 +202,7 @@ gtk_actionable_set_action_target (GtkActionable *actionable,
* actionable widget.
*
* @detailed_action_name is a string in the format accepted by
* g_action_parse_detailed_name().
* [func@Gio.Action.parse_detailed_name].
*/
void
gtk_actionable_set_detailed_action_name (GtkActionable *actionable,

10
gtk/gtkpadcontroller.c
View File

@@ -28,7 +28,7 @@
*
* These buttons and sensors have no implicit meaning, and by default they
* perform no action. `GtkPadController` is provided to map those to
* `GAction` objects, thus letting the application give them a more
* [iface@Gio.Action] objects, thus letting the application give them a more
* semantic meaning.
*
* Buttons and sensors are not constrained to triggering a single action,
@@ -41,10 +41,10 @@
* different modes. See [method@Gdk.DevicePad.get_n_groups] and
* [method@Gdk.DevicePad.get_group_n_modes].
*
* Each of the actions that a given button/strip/ring performs for a given
* mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action
* name that will be looked up in the given `GActionGroup` and activated
* whenever the specified input element and mode are triggered.
* Each of the actions that a given button/strip/ring performs for a given mode
* is defined by a [struct@Gtk.PadActionEntry]. It contains an action name that
* will be looked up in the given [iface@Gio.ActionGroup] and activated whenever
* the specified input element and mode are triggered.
*
* A simple example of `GtkPadController` usage: Assigning button 1 in all
* modes and pad devices to an "invert-selection" action:

2
gtk/gtksizerequest.h
View File

@@ -36,7 +36,7 @@ typedef struct _GtkRequestedSize GtkRequestedSize;
*
* Represents a request of a screen object in a given orientation. These
* are primarily used in container implementations when allocating a natural
* size for children calling. See gtk_distribute_natural_allocation().
* size for children calling. See [func@distribute_natural_allocation].
*/
struct _GtkRequestedSize
{

63
gtk/gtksnapshot.c
View File

@@ -46,14 +46,14 @@
/**
* GtkSnapshot:
*
* `GtkSnapshot` assists in creating `GskRenderNodes` for widgets.
* `GtkSnapshot` assists in creating [class@Gsk.RenderNode]s for widgets.
*
* It functions in a similar way to a cairo context, and maintains a stack
* of render nodes and their associated transformations.
*
* The node at the top of the stack is the one that gtk_snapshot_append_…
* functions operate on. Use the gtk_snapshot_push_… functions and
* gtk_snapshot_pop() to change the current node.
* The node at the top of the stack is the one that `gtk_snapshot_append_…()`
* functions operate on. Use the `gtk_snapshot_push_…()` functions and
* [method@Snapshot.pop] to change the current node.
*
* The typical way to obtain a `GtkSnapshot` object is as an argument to
* the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own
@@ -302,7 +302,7 @@ gtk_snapshot_new (void)
* Returns the node that was constructed by @snapshot
* and frees @snapshot.
*
* Returns: (transfer full): a newly-created `GskRenderNode`
* Returns: (transfer full): a newly-created [class@Gsk.RenderNode]
*/
GskRenderNode *
gtk_snapshot_free_to_node (GtkSnapshot *snapshot)
@@ -324,7 +324,7 @@ gtk_snapshot_free_to_node (GtkSnapshot *snapshot)
* Returns a paintable for the node that was
* constructed by @snapshot and frees @snapshot.
*
* Returns: (transfer full): a newly-created `GdkPaintable`
* Returns: (transfer full): a newly-created [iface@Gdk.Paintable]
*/
GdkPaintable *
gtk_snapshot_free_to_paintable (GtkSnapshot *snapshot,
@@ -955,11 +955,11 @@ gtk_snapshot_collect_gl_shader_texture (GtkSnapshot *snapshot,
* @bounds: the rectangle to render into
* @take_args: (transfer full): Data block with arguments for the shader.
*
* Push a `GskGLShaderNode`.
* Push a [class@Gsk.GLShaderNode].
*
* The node uses the given [class@Gsk.GLShader] and uniform values
* Additionally this takes a list of @n_children other nodes
* which will be passed to the `GskGLShaderNode`.
* which will be passed to the [class@Gsk.GLShaderNode].
*
* The @take_args argument is a block of data to use for uniform
* arguments, as per types and offsets defined by the @shader.
@@ -1495,7 +1495,7 @@ gtk_snapshot_pop_collect (GtkSnapshot *snapshot)
*
* After calling this function, it is no longer possible to
* add more nodes to @snapshot. The only function that should
* be called after this is g_object_unref().
* be called after this is [method@GObject.Object.unref].
*
* Returns: (transfer full): the constructed `GskRenderNode`
*/
@@ -1530,7 +1530,7 @@ gtk_snapshot_to_node (GtkSnapshot *snapshot)
*
* After calling this function, it is no longer possible to
* add more nodes to @snapshot. The only function that should
* be called after this is g_object_unref().
* be called after this is [method@GObject.Object.unref].
*
* Returns: (transfer full): a new `GdkPaintable`
*/
@@ -1585,7 +1585,7 @@ gtk_snapshot_pop (GtkSnapshot *snapshot)
* @snapshot: a `GtkSnapshot`
*
* Removes the top element from the stack of render nodes and
* adds it to the nearest `GskGLShaderNode` below it.
* adds it to the nearest [class@Gsk.GLShaderNode] below it.
*
* This must be called the same number of times as the number
* of textures is needed for the shader in
@@ -1610,12 +1610,12 @@ gtk_snapshot_gl_shader_pop_texture (GtkSnapshot *snapshot)
*
* When [method@Gtk.Snapshot.restore] is called, @snapshot will
* be restored to the saved state. Multiple calls to
* gtk_snapshot_save() and gtk_snapshot_restore() can be nested;
* each call to gtk_snapshot_restore() restores the state from
* the matching paired gtk_snapshot_save().
* [method@Snapshot.save] and [class@Snapshot.restore] can be nested;
* each call to `gtk_snapshot_restore()` restores the state from
* the matching paired `gtk_snapshot_save()`.
*
* It is necessary to clear all saved states with corresponding
* calls to gtk_snapshot_restore().
* calls to `gtk_snapshot_restore()`.
*/
void
gtk_snapshot_save (GtkSnapshot *snapshot)
@@ -1633,7 +1633,7 @@ gtk_snapshot_save (GtkSnapshot *snapshot)
* @snapshot: a `GtkSnapshot`
*
* Restores @snapshot to the state saved by a preceding call to
* gtk_snapshot_save() and removes that state from the stack of
* [method@Snapshot.save] and removes that state from the stack of
* saved states.
*/
void
@@ -1882,7 +1882,7 @@ gtk_snapshot_append_node (GtkSnapshot *snapshot,
* @snapshot: a `GtkSnapshot`
* @bounds: the bounds for the new node
*
* Creates a new `GskCairoNode` and appends it to the current
* Creates a new [class@Gsk.CairoNode] and appends it to the current
* render node of @snapshot, without changing the current node.
*
* Returns: a `cairo_t` suitable for drawing the contents of
@@ -1918,7 +1918,7 @@ gtk_snapshot_append_cairo (GtkSnapshot *snapshot,
/**
* gtk_snapshot_append_texture:
* @snapshot: a `GtkSnapshot`
* @texture: the `GdkTexture` to render
* @texture: the texture to render
* @bounds: the bounds for the new node
*
* Creates a new render node drawing the @texture
@@ -1948,7 +1948,7 @@ gtk_snapshot_append_texture (GtkSnapshot *snapshot,
/**
* gtk_snapshot_append_color:
* @snapshot: a `GtkSnapshot`
* @color: the `GdkRGBA` to draw
* @color: the color to draw
* @bounds: the bounds for the new node
*
* Creates a new render node drawing the @color into the
@@ -1982,7 +1982,7 @@ gtk_snapshot_append_color (GtkSnapshot *snapshot,
/**
* gtk_snapshot_render_background:
* @snapshot: a `GtkSnapshot`
* @context: the `GtkStyleContext` to use
* @context: the style context that defines the background
* @x: X origin of the rectangle
* @y: Y origin of the rectangle
* @width: rectangle width
@@ -2014,7 +2014,7 @@ gtk_snapshot_render_background (GtkSnapshot *snapshot,
/**
* gtk_snapshot_render_frame:
* @snapshot: a `GtkSnapshot`
* @context: the `GtkStyleContext` to use
* @context: the style context that defines the frame
* @x: X origin of the rectangle
* @y: Y origin of the rectangle
* @width: rectangle width
@@ -2046,7 +2046,7 @@ gtk_snapshot_render_frame (GtkSnapshot *snapshot,
/**
* gtk_snapshot_render_focus:
* @snapshot: a `GtkSnapshot`
* @context: the `GtkStyleContext` to use
* @context: the style context that defines the focus ring
* @x: X origin of the rectangle
* @y: Y origin of the rectangle
* @width: rectangle width
@@ -2078,7 +2078,7 @@ gtk_snapshot_render_focus (GtkSnapshot *snapshot,
/**
* gtk_snapshot_render_layout:
* @snapshot: a `GtkSnapshot`
* @context: the `GtkStyleContext` to use
* @context: the style context that defines the text
* @x: X origin of the rectangle
* @y: Y origin of the rectangle
* @layout: the `PangoLayout` to render
@@ -2152,8 +2152,7 @@ gtk_snapshot_append_text (GtkSnapshot *snapshot,
* @bounds: the rectangle to render the linear gradient into
* @start_point: the point at which the linear gradient will begin
* @end_point: the point at which the linear gradient will finish
* @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
* defining the gradient
* @stops: (array length=n_stops): the color stops defining the gradient
* @n_stops: the number of elements in @stops
*
* Appends a linear gradient node with the given stops to @snapshot.
@@ -2220,8 +2219,7 @@ gtk_snapshot_append_linear_gradient (GtkSnapshot *snapshot,
* @bounds: the rectangle to render the linear gradient into
* @start_point: the point at which the linear gradient will begin
* @end_point: the point at which the linear gradient will finish
* @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
* defining the gradient
* @stops: (array length=n_stops): the color stops defining the gradient
* @n_stops: the number of elements in @stops
*
* Appends a repeating linear gradient node with the given stops to @snapshot.
@@ -2289,8 +2287,7 @@ gtk_snapshot_append_repeating_linear_gradient (GtkSnapshot *snapshot,
* @center: the center point of the conic gradient
* @rotation: the clockwise rotation in degrees of the starting angle.
* 0 means the starting angle is the top.
* @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
* defining the gradient
* @stops: (array length=n_stops): the color stops defining the gradient
* @n_stops: the number of elements in @stops
*
* Appends a conic gradient node with the given stops to @snapshot.
@@ -2352,8 +2349,7 @@ gtk_snapshot_append_conic_gradient (GtkSnapshot *snapshot,
* @vradius: the vertical radius
* @start: the start position (on the horizontal axis)
* @end: the end position (on the horizontal axis)
* @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
* defining the gradient
* @stops: (array length=n_stops): the color stops defining the gradient
* @n_stops: the number of elements in @stops
*
* Appends a radial gradient node with the given stops to @snapshot.
@@ -2426,8 +2422,7 @@ gtk_snapshot_append_radial_gradient (GtkSnapshot *snapshot,
* @vradius: the vertical radius
* @start: the start position (on the horizontal axis)
* @end: the end position (on the horizontal axis)
* @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
* defining the gradient
* @stops: (array length=n_stops): the color stops defining the gradient
* @n_stops: the number of elements in @stops
*
* Appends a repeating radial gradient node with the given stops to @snapshot.
@@ -2493,7 +2488,7 @@ gtk_snapshot_append_repeating_radial_gradient (GtkSnapshot *snapshot,
/**
* gtk_snapshot_append_border:
* @snapshot: a `GtkSnapshot`
* @outline: a `GskRoundedRect` describing the outline of the border
* @outline: the outline of the border
* @border_width: (array fixed-size=4): the stroke width of the border on
* the top, right, bottom and left side respectively.
* @border_color: (array fixed-size=4): the color used on the top, right,

10
gtk/gtkversion.h.in
View File

@@ -36,7 +36,7 @@ G_BEGIN_DECLS
/**
* GTK_MAJOR_VERSION:
*
* Like gtk_get_major_version(), but from the headers used at
* Like [func@get_major_version], but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
@@ -45,7 +45,7 @@ G_BEGIN_DECLS
/**
* GTK_MINOR_VERSION:
*
* Like gtk_get_minor_version(), but from the headers used at
* Like [func@get_minor_version], but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
@@ -54,7 +54,7 @@ G_BEGIN_DECLS
/**
* GTK_MICRO_VERSION:
*
* Like gtk_get_micro_version(), but from the headers used at
* Like [func@get_micro_version], but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
@@ -63,7 +63,7 @@ G_BEGIN_DECLS
/**
* GTK_BINARY_AGE:
*
* Like gtk_get_binary_age(), but from the headers used at
* Like [func@get_binary_age], but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/
@@ -72,7 +72,7 @@ G_BEGIN_DECLS
/**
* GTK_INTERFACE_AGE:
*
* Like gtk_get_interface_age(), but from the headers used at
* Like [func@get_interface_age], but from the headers used at
* application compile time, rather than from the library linked
* against at application run time.
*/