+2006-12-05 Behdad Esfahbod <behdad@gnome.org>
+
+ * docs/pango-sections.txt:
+ * docs/tmpl/layout.sgml:
+ * pango/pango-layout.c (pango_layout_get_lines_readonly),
+ (pango_layout_get_line_readonly),
+ (pango_layout_iter_get_run_readonly),
+ (_pango_layout_iter_get_line), (pango_layout_iter_get_line),
+ (pango_layout_iter_get_line_readonly):
+ * pango/pango-layout.h:
+ * pango/pango-renderer.c (pango_renderer_draw_layout):
+ * pango/pango.def:
+ Add new functions:
+ pango_layout_iter_get_line_readonly()
+ pango_layout_get_lines_readonly()
+ pango_layout_iter_get_line_readonly()
+ pango_layout_iter_get_run_readonly()
+ These should be used when you do not intend to modify the run/line,
+ which is more than most of the time. So, update your app, benefit
+ from more optimizations (in this case, line extents caching)!
+
2006-12-04 Behdad Esfahbod <behdad@gnome.org>
* === Released 1.15.1 ===
* @layout: a #PangoLayout
*
* Returns the lines of the @layout as a list.
+ *
+ * Use the faster pango_layout_get_lines_readonly() if you do not plan
+ * to modify the contents of the lines (glyphs, glyph widths, etc.).
*
* Return value: a #GSList containing the lines in the layout. This
* points to internal data of the #PangoLayout and must be used with
}
/**
+ * pango_layout_get_lines_readonly:
+ * @layout: a #PangoLayout
+ *
+ * Returns the lines of the @layout as a list.
+ *
+ * This is a faster alternative to pango_layout_get_lines(),
+ * but the user is not expected
+ * to modify the contents of the lines (glyphs, glyph widths, etc.).
+ *
+ * Return value: a #GSList containing the lines in the layout. This
+ * points to internal data of the #PangoLayout and must be used with
+ * care. It will become invalid on any change to the layout's
+ * text or properties. No changes should be made to the lines.
+ *
+ * Since: 1.16
+ **/
+GSList *
+pango_layout_get_lines_readonly (PangoLayout *layout)
+{
+ pango_layout_check_lines (layout);
+
+ return layout->lines;
+}
+
+/**
* pango_layout_get_line:
* @layout: a #PangoLayout
* @line: the index of a line, which must be between 0 and
*
* Retrieves a particular line from a #PangoLayout.
*
+ * Use the faster pango_layout_get_line_readonly() if you do not plan
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
+ *
* Return value: the requested #PangoLayoutLine, or %NULL if the
* index is out of range. This layout line can
* be ref'ed and retained, but will become invalid
}
/**
+ * pango_layout_get_line_readonly:
+ * @layout: a #PangoLayout
+ * @line: the index of a line, which must be between 0 and
+ * <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
+ *
+ * Retrieves a particular line from a #PangoLayout.
+ *
+ * This is a faster alternative to pango_layout_get_line(),
+ * but the user is not expected
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
+ *
+ * Return value: the requested #PangoLayoutLine, or %NULL if the
+ * index is out of range. This layout line can
+ * be ref'ed and retained, but will become invalid
+ * if changes are made to the #PangoLayout.
+ * No changes should be made to the line.
+ *
+ * Since: 1.16
+ **/
+PangoLayoutLine *
+pango_layout_get_line_readonly (PangoLayout *layout,
+ int line)
+{
+ GSList *list_item;
+ g_return_val_if_fail (layout != NULL, NULL);
+ g_return_val_if_fail (line >= 0, NULL);
+
+ if (line < 0)
+ return NULL;
+
+ pango_layout_check_lines (layout);
+
+ list_item = g_slist_nth (layout->lines, line);
+
+ if (list_item)
+ {
+ PangoLayoutLine *line = list_item->data;
+ return line;
+ }
+
+ return NULL;
+}
+
+/**
* pango_layout_line_index_to_x:
* @line: a #PangoLayoutLine
* @index_: byte offset of a grapheme within the layout
* line, there's a position with a %NULL run, so this function can return
* %NULL. The %NULL run at the end of each line ensures that all lines have
* at least one run, even lines consisting of only a newline.
+ *
+ * Use the faster pango_layout_iter_get_run_readonly() if you do not plan
+ * to modify the contents of the run (glyphs, glyph widths, etc.).
*
* Return value: the current run.
**/
return iter->run;
}
-/* an inline-able version for local use */
-static PangoLayoutLine*
-_pango_layout_iter_get_line (PangoLayoutIter *iter)
+/**
+ * pango_layout_iter_get_run_readonly:
+ * @iter: a #PangoLayoutIter
+ *
+ * Gets the current run. When iterating by run, at the end of each
+ * line, there's a position with a %NULL run, so this function can return
+ * %NULL. The %NULL run at the end of each line ensures that all lines have
+ * at least one run, even lines consisting of only a newline.
+ *
+ * This is a faster alternative to pango_layout_iter_get_run(),
+ * but the user is not expected
+ * to modify the contents of the run (glyphs, glyph widths, etc.).
+ *
+ * Return value: the current run, that should not be modified.
+ *
+ * Since: 1.16
+ **/
+PangoLayoutRun*
+pango_layout_iter_get_run_readonly (PangoLayoutIter *iter)
{
- return iter->line;
+ if (ITER_IS_INVALID (iter))
+ return NULL;
+
+ pango_layout_line_leaked (iter->line);
+
+ return iter->run;
}
-/* a private one for pango-renderer.c use */
-PangoLayoutLine*
-_pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
+/* an inline-able version for local use */
+static PangoLayoutLine*
+_pango_layout_iter_get_line (PangoLayoutIter *iter)
{
return iter->line;
}
* @iter: a #PangoLayoutIter
*
* Gets the current line.
+ *
+ * Use the faster pango_layout_iter_get_line_readonly() if you do not plan
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
*
* Return value: the current line.
**/
}
/**
+ * pango_layout_iter_get_line_readonly:
+ * @iter: a #PangoLayoutIter
+ *
+ * Gets the current line for read-only access.
+ *
+ * This is a faster alternative to pango_layout_iter_get_line(),
+ * but the user is not expected
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
+ *
+ * Return value: the current line, that should not be modified.
+ *
+ * Since: 1.16
+ **/
+PangoLayoutLine*
+pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
+{
+ if (ITER_IS_INVALID (iter))
+ return NULL;
+
+ return iter->line;
+}
+
+/**
* pango_layout_iter_at_last_line:
* @iter: a #PangoLayoutIter
*
projects / platform / upstream / pango.git / commitdiff