#143601: Felipe Heidrich

Fri Jul 16 07:43:04 2004  Owen Taylor  <otaylor@redhat.com>

        #143601: Felipe Heidrich

        * pango/pango-layout.c (pango_layout_line_x_to_index):
        Go into painful detail about the behavior for X positions
        outside the line.

        * pango/pango-layout.c (pango_layout_xy_to_index):
        Add some more details about handling of positions
        outside the layout, reference
        pango_layout_line_x_to_index().

1 files changed, 16 insertions, 7 deletions

diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 16765fbe..787bfe7b 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -1423,10 +1423,12 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
  *
  * Converts from X and Y position within a layout to the byte 
  * index to the character at that logical position. If the
- * position is not inside the layout, the closest position is chosen
- * (the x/y position will be clamped inside the layout).
- * If a closest position is chosen, then the function returns %FALSE;
- * on an exact hit, it returns %TRUE.
+ * Y position is not inside the layout, the closest position is chosen
+ * (the position will be clamped inside the layout). If the
+ * X position is not within the layout, then the start or the
+ * end of the line is chosen as  described for pango_layout_x_to_index().
+ * If either the X or Y positions were not inside the layout, then the
+ * function returns %FALSE; on an exact hit, it returns %TRUE.
  *
  * Return value: %TRUE if the coordinates were inside text
  **/
@@ -3246,16 +3248,23 @@ pango_layout_line_unref (PangoLayoutLine *line)
  * @line:      a #PangoLayoutLine
  * @x_pos:     the x offset (in #PangoGlyphUnit)
  *             from the left edge of the line.
- * @index_:    location to store calculated byte offset for
+ * @index_:    location to store calculated byte index for
  *             the grapheme in which the user clicked.
  * @trailing:  location to store a integer indicating where
  *             in the grapheme the user clicked. It will either
  *             be zero, or the number of characters in the
- *             grapheme. 0 represents the trailing edge of the cluster.
+ *             grapheme. 0 represents the trailing edge of the grapheme.
  *
  * Converts from x offset to the byte index of the corresponding
  * character within the text of the layout. If @x_pos is outside the line,
- * the start or end of the line will be stored at @index_.
+ * @index_ and @trailing will point to the very first or very last position
+ * in the line. This determination is based on the resolved direction
+ * of the paragraph; for example, if the resolved direction is
+ * right-to-left, then an X position to the right of the line (after it)
+ * results in 0 being stored in @index_ and @trailing. An X position to the
+ * left of the line results in @index_ pointing to the (logical) last
+ * grapheme in the line and @trailing being set to the number of characters
+ * in that grapheme. The reverse is true for a left-to-right line.
  *
  * Returns: %FALSE if @x_pos was outside the line, %TRUE if inside
  **/