From 584fd36a5f8413adbb975aed87c8001d055c837f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Trevisan=20=28Trevi=C3=B1o=29?= Date: Fri, 14 Apr 2023 18:05:21 +0200 Subject: [PATCH] gtk: Improve documentation on returned nodes for snapshot Closes: #5747 --- gtk/gskpango.c | 3 +++ gtk/gtksnapshot.c | 9 ++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/gtk/gskpango.c b/gtk/gskpango.c index 41a4b1a7bc..0b64e75121 100644 --- a/gtk/gskpango.c +++ b/gtk/gskpango.c @@ -460,6 +460,9 @@ gsk_pango_renderer_release (GskPangoRenderer *renderer) * Creates render nodes for rendering @layout in the given foregound @color * and appends them to the current node of @snapshot without changing the * current node. + * + * Note that if the layout does not contain any printable character, then + * no node will be added to the @snapshot. **/ void gtk_snapshot_append_layout (GtkSnapshot *snapshot, diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c index 76005769d8..0ec116265b 100644 --- a/gtk/gtksnapshot.c +++ b/gtk/gtksnapshot.c @@ -300,6 +300,8 @@ gtk_snapshot_new (void) * Returns the node that was constructed by @snapshot * and frees @snapshot. * + * See also gtk_snapshot_to_node(). + * * Returns: (transfer full) (nullable): a newly-created [class@Gsk.RenderNode] */ GskRenderNode * @@ -1569,11 +1571,16 @@ gtk_snapshot_pop_collect (GtkSnapshot *snapshot) * Returns the render node that was constructed * by @snapshot. * + * Note that this function may return %NULL if nothing has been + * added to the snapshot or if its content does not produce pixels + * to be rendered. + * * 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 [method@GObject.Object.unref]. * - * Returns: (transfer full) (nullable): the constructed `GskRenderNode` + * Returns: (transfer full) (nullable): the constructed `GskRenderNode` or + * %NULL if there are no nodes to render. */ GskRenderNode * gtk_snapshot_to_node (GtkSnapshot *snapshot)