org.gnome.gtk

## Class TextIter

- Object
- - org.freedesktop.bindings.Pointer
  - - org.gnome.glib.Boxed
    - - org.gnome.gtk.TextIter

-     public final class TextIter
      extends Boxed

  A TextIter defines a position inside a `TextBuffer` and allows you to manipulate it.

  TextIters are just used for immediate operations, and are invalidated any time when the TextBuffer's contents change. If you need to hold a reference to a specific position, convert this TextIter into a TextMark with TextBuffer's `createMark()`.

  ## Navigation

  Quite a number of methods on TextIter allow you to move the location of the pointer in the TextBuffer, including `forwardLine()`, `backwardChars()`, and many others. These are both imperative commands and a means of querying. The TreeIter will attempt to move as requested, while the boolean return value of the call will tell you whether the TreeIter changed location. This can be used to ascertain your position in a logical sense or to limit loops. Remeber, however, that (unless otherwise marked) any method which changes the TextBuffer invalidates the TextIters pointing into it.

  Since:
    4.0.9
  Author:
    Stefan Prelle, Andrew Cowie

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `backwardChar()` Reduce the character offset by 1.
    `boolean` | `backwardChars(int count)` Reduce the character offset by `count`.
    `boolean` | `backwardDisplayLine(TextView view)` Move backward one display line within a paragraph as displayed in this TextView.
    `boolean` | `backwardDisplayLineStart(TextView view)` Move backward to the start of this display line.
    `boolean` | `backwardLine()` Bump this TextIter backward to the start of the next line.
    `boolean` | `backwardLines(int count)` Bump this TextIter backward multiple lines and to the start of the next line.
    `boolean` | `beginsTag(TextTag tag)` Check whether a specific `TextTag` is started at exactly this point identified by the TextIter.
    `boolean` | `canInsert(boolean defaultEditability)` Check if text inserted at the current position would be editable.
    `TextIter` | `copy()` Creates an independent copy of the iterator.
    `boolean` | `endsLine()` Check if the current position marks the end of a line.
    `boolean` | `endsSentence()` Returns `true` if the TextIter points to the last sign that does not belong to the sentence - usually the first whitespace, since e.g. dots belong to a sentence.
    `boolean` | `endsTag(TextTag tag)` Check whether a specific `TextTag` is ended at exactly this point identified by the TextIter.
    `boolean` | `endsWord()` Returns if the current position marks the end of a word.
    `boolean` | `forwardChar()` Increase the character offset by 1.
    `boolean` | `forwardChars(int count)` Increase the character offset by `count`.
    `boolean` | `forwardDisplayLine(TextView view)` Movie forward one display line within a paragraph as displayed in a TextView.
    `boolean` | `forwardDisplayLineEnd(TextView view)` Move forward to the end of this display line.
    `boolean` | `forwardLine()` Bump this TextIter forward to the start of the next line.
    `boolean` | `forwardLines(int count)` Bump this TextIter forward multiple lines and to the start of the next line.
    `int` | `getChar()` Get the character immediately following the position this TextIter is pointing at.
    `int` | `getCharsInLine()` Counts the characters in the current text line, including the newline if present.
    `org.gnome.gtk.TextChildAnchor` | `getChildAnchor()` If there is a `TextChildAnchor` at the current position, return it.
    `int` | `getLine()` Get the line number of the TextBuffer that this TextIter points at.
    `int` | `getLineOffset()` Get the character offset of this TextIter, counting from the start of the line.
    `TextMark[]` | `getMarks()` Return the `TextMark`s that exists at the location the TextIter points to.
    `int` | `getOffset()` Returns the number of characters into the TextBuffer that this TextIter is pointing.
    `Pixbuf` | `getPixbuf()` If the element at this position is an image
    `String` | `getSlice(TextIter end)` Returns the text from the position defined by this TextIter to the position referenced by a given TextIter, including non character elements like widgets or pixbufs.
    `TextTag[]` | `getTags()` Returns all TextTags that apply to the current position.
    `String` | `getText(TextIter end)` Returns the text from the position defined by this TextIter to the position referenced by a given TextIter.
    `TextTag[]` | `getToggledTags(boolean state)` Return all the TextTags that are either turned on or off at this position.
    `int` | `getVisibleLineOffset()` Like `getLineOffset()` but not counting those characters that are tagged "invisible".
    `String` | `getVisibleSlice(TextIter end)` Like `getSlice(TextIter)` but returns only those parts that are not flagged invisible.
    `String` | `getVisibleText(TextIter end)` Like `getText(TextIter)` but returns only those parts that are not flagged invisible.
    `boolean` | `hasTag(TextTag tag)` Checks whether a specific `TextTag` is applied to the text at the current position.
    `boolean` | `insideSentence()` Checks whether or not the current position is inside a sentence.
    `boolean` | `insideWord()` Check if the current position is inside a word, including the first or last letter.
    `boolean` | `isCursorPosition()` Returns if the TextIter is identical with the GUIs cursor position inside the TextView.
    `boolean` | `isEditable(boolean defaultEditability)` Check if text at the current position is editable.
    `boolean` | `isEnd()` Checks if the TextIter points to the end of the buffer.
    `boolean` | `isStart()` Checks if the TextIter points to the start of the buffer.
    `void` | `setLine(int row)` Move this TextIter to the start of the given line.
    `void` | `setLineOffset(int column)` Move the iterator within the current TextBuffer line to the given character offset.
    `void` | `setOffset(int offset)` Change this TextIter so that it points to the given offset into the underlying TextBuffer.
    `void` | `setVisibleLineOffset(int column)` Move this TextIter into the current line at the given offset, but skipping characters that have been marked `invisible`.
    `boolean` | `startsDisplayLine(TextView view)` Does the position represented by this TextIter start a display line (within a paragraph) in the given TextView?
    `boolean` | `startsLine()` Check if the current position is at the start of a line.
    `boolean` | `startsSentence()` Returns `true` if the TextIter points to the first character of a sentence.
    `boolean` | `startsWord()` Returns if a word is beginning at the current position, which is the case when the TextIter points to the first letter of the word.
    `boolean` | `togglesTag(TextTag tag)` Check whether a specific `TextTag` is either started or ended at exactly this point identified by the TextIter.
    `String` | `toString()`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### backwardChar

          public boolean backwardChar()

      Reduce the character offset by 1. If already at the first character, remain there.
      Returns:
        `true`, if the offset was decreased or `false` if the TextIter already pointed to the start of the TextBuffer.
      Since:
        4.0.9

    - #### backwardChars

          public boolean backwardChars(int count)

      Reduce the character offset by `count`. If this would point to a negative offset, point to the start of the TextBuffer.
      Returns:
        `true` if the position changed because of this call.
      Since:
        4.0.9

    - #### backwardDisplayLine

          public boolean backwardDisplayLine(TextView view)

      Move backward one display line within a paragraph as displayed in this TextView. This is the complement of `forwardDisplayLine()`; see there for details.
      Since:
        4.0.9

    - #### backwardDisplayLineStart

          public boolean backwardDisplayLineStart(TextView view)

      Move backward to the start of this display line.
      Since:
        4.0.14

    - #### backwardLine

          public boolean backwardLine()

      Bump this TextIter backward to the start of the next line. As a special case, if you're already pointing at the first line of the TextBuffer, then you will be moved to the start of the line.
      Since:
        4.0.9

    - #### backwardLines

          public boolean backwardLines(int count)

      Bump this TextIter backward multiple lines and to the start of the next line. As a special case, if you're already pointing at the first line of the TextBuffer, then you will be moved to the start of the line.
      Since:
        4.0.9

    - #### beginsTag

          public boolean beginsTag(TextTag tag)

      Check whether a specific `TextTag` is started at exactly this point identified by the TextIter.
      Since:
        4.0.9

    - #### canInsert

          public boolean canInsert(boolean defaultEditability)

      Check if text inserted at the current position would be editable. This is the case if the TextIter is within the range of an editable block (including the start AND end position) or the default editability is `true`.
      Since:
        4.0.9

    - #### copy

          public TextIter copy()

      Creates an independent copy of the iterator.

      This is basically the same as a clone() on normal Java object would do, but in this case is passed on to the native GTK layer.

      Since:
        4.0.9

    - #### endsLine

          public boolean endsLine()

      Check if the current position marks the end of a line.
      Since:
        4.0.9

    - #### endsSentence

          public boolean endsSentence()

      Returns `true` if the TextIter points to the last sign that does not belong to the sentence - usually the first whitespace, since e.g. dots belong to a sentence.
      Since:
        4.0.9

    - #### endsTag

          public boolean endsTag(TextTag tag)

      Check whether a specific `TextTag` is ended at exactly this point identified by the TextIter.
      Since:
        4.0.9

    - #### endsWord

          public boolean endsWord()

      Returns if the current position marks the end of a word. Usually this means that you are at the first whitespace or sentence ending sign behind a word.
      Since:
        4.0.9

    - #### forwardChar

          public boolean forwardChar()

      Increase the character offset by 1. If already at the last character, remain there.

      The method returns `true`, if the offset was increased or `false` if the TextIter already pointed to the end of the TextBuffer or one character before the end.

      If iterating character by character over a TextBuffer, you probably want to use `isEnd()` and if not at the end call this (and ignore its return value).

      Since:
        4.0.9

    - #### forwardChars

          public boolean forwardChars(int count)

      Increase the character offset by `count`. If this would point to a position behind the buffers end, point to the end of the TextBuffer.
      Returns:
        `true` if the position changed because of this call.
      Since:
        4.0.9

    - #### forwardDisplayLine

          public boolean forwardDisplayLine(TextView view)

      Movie forward one display line within a paragraph as displayed in a TextView. A single line in a TextBuffer will be displayed as multiple lines (known to mere mortals as a "paragraph") in a TextView if word wrapping is enabled and something is acting to constrain the width of the TextView to less than the width of the lines.

      A given TextBuffer can be displayed by more than one TextView, so where the wrapping occurs is dependent on the width of that Widget, which is why you need to pass the view you are working in to this method.

      In the native library this is a method on TextView; however, we have exposed it here so that it is in the same completion space as all the other `forward...()` methods available on TextIter.

      Returns:
        `true` if the location the TextIter points at was changed; that is, if `pointer` is not yet at the end of the underlying TextBuffer.
      Since:
        4.0.9

    - #### forwardDisplayLineEnd

          public boolean forwardDisplayLineEnd(TextView view)

      Move forward to the end of this display line.
      Since:
        4.0.14

    - #### forwardLine

          public boolean forwardLine()

      Bump this TextIter forward to the start of the next line. As a special case, if you're already pointing at the last line of the TextBuffer, then you will be moved to the end of the line.

      Keep in mind that a line in the TextBuffer may well be wrapped when displayed onscreen in a TextView as the several lines comprising a paragraph; to move forward such a displayed line (ie within a paragraph) use `forwardDisplayLine()`.

      Since:
        4.0.9

    - #### forwardLines

          public boolean forwardLines(int count)

      Bump this TextIter forward multiple lines and to the start of the next line. As a special case, if you're already pointing at the last line of the TextBuffer, then you will be moved to the end of the line.
      Since:
        4.0.9

    - #### getChar

          public int getChar()

      Get the character immediately following the position this TextIter is pointing at.

      TextBuffers work in characters, and so this method too returns a Unicode codepoint. Beware, of course if you are used to working with Java's 2-byte `char` type that you have to use StringBuffer's appendCodePoint(int) instead of append(char).

      An `int` value of `OBJECT_REPLACEMENT_CHARACTER` indicates a non-character element (an embedded Pixbuf or Widget). You'll get `0` (ie `'\0'`, not `'0'`) if this TextIter is already at the TextBuffer's end.

      Since:
        4.0.13

    - #### getCharsInLine

          public int getCharsInLine()

      Counts the characters in the current text line, including the newline if present. Non-printable objects like images count as one character.
      Since:
        4.0.9

    - #### getChildAnchor

          public org.gnome.gtk.TextChildAnchor getChildAnchor()

      If there is a `TextChildAnchor` at the current position, return it. Otherwise return `null`.
      Since:
        4.0.9

    - #### getLine

          public int getLine()

      Get the line number of the TextBuffer that this TextIter points at. Lines in a TextBuffer are numbered from `0`.

      Be aware that this is the count of unwrapped lines in the TextBuffer, where lines are split by newline characters. Most of the time TextViews are set to wrap lines and thus a single very long line will be presented visually as a paragraph (there is no definition of paragraph in TextBuffer terms). If you're wondering about where a position (the cursor, say) is down into a TextView widget, then see `startsDisplayLine()` and other related "`display`" methods.

      Since:
        4.0.9

    - #### getLineOffset

          public int getLineOffset()

      Get the character offset of this TextIter, counting from the start of the line. The first character on the line has line offset `0`.

      This is, in essence, a `getColumn()` method, but beware that the number of characters you are into a given line in a TextBuffer will only correspond to the column position on screen if the presenting TextView is not wrapping lines.

      Since:
        4.0.9

    - #### getMarks

          public TextMark[] getMarks()

      Return the `TextMark`s that exists at the location the TextIter points to. If there are none present here then a zero length array will be returned.

      GTK maintains a number of TextMarks internally in each TextBuffer for its own purposes (even over and above selection-bound and insert), proxies of which will get returned along with any TextMarks you've put there. So this method isn't quite as useful as one might like it to be.

      Since:
        4.0.9

    - #### getOffset

          public int getOffset()

      Returns the number of characters into the TextBuffer that this TextIter is pointing. Offset counts are `0` origin.

      If you have a given offset, you can use the TextBuffer `getIter()` method taking an `int` to convert it into an TreeIter. If you want to move this TreeIter to a given offset, then call `setOffset()`.

      Returns:
        A character offset from the start of the TextBuffer.
      Since:
        4.0.9

    - #### getPixbuf

          public Pixbuf getPixbuf()

      If the element at this position is an image
      Returns:
        The `Pixbuf` object or `null` if there is no image at the current position of this TextIter.
      Since:
        4.0.9

    - #### getSlice

          public String getSlice(TextIter end)

      Returns the text from the position defined by this TextIter to the position referenced by a given TextIter, including non character elements like widgets or pixbufs.
      Since:
        4.0.9

    - #### getTags

          public TextTag[] getTags()

      Returns all TextTags that apply to the current position. If there are not any present here then a zero length array will be returned.
      Since:
        4.0.9

    - #### getText

          public String getText(TextIter end)

      Returns the text from the position defined by this TextIter to the position referenced by a given TextIter. Non-printable elements like Widgets and Pixbufs are not included in the returned string. If you need them use `getSlice(TextIter)`.
      Since:
        4.0.9

    - #### getToggledTags

          public TextTag[] getToggledTags(boolean state)

      Return all the TextTags that are either turned on or off at this position.
      Since:
        4.0.9

    - #### getVisibleLineOffset

          public int getVisibleLineOffset()

      Like `getLineOffset()` but not counting those characters that are tagged "invisible".
      Returns:
        Offset from start of line
      Since:
        4.0.9

    - #### getVisibleSlice

          public String getVisibleSlice(TextIter end)

      Like `getSlice(TextIter)` but returns only those parts that are not flagged invisible.
      Since:
        4.0.9

    - #### getVisibleText

          public String getVisibleText(TextIter end)

      Like `getText(TextIter)` but returns only those parts that are not flagged invisible.
      Since:
        4.0.9

    - #### hasTag

          public boolean hasTag(TextTag tag)

      Checks whether a specific `TextTag` is applied to the text at the current position. Or in other words if the current position is between start and end of the `TextTag`.
      Since:
        4.0.9

    - #### insideSentence

          public boolean insideSentence()

      Checks whether or not the current position is inside a sentence.
      Since:
        4.0.9

    - #### insideWord

          public boolean insideWord()

      Check if the current position is inside a word, including the first or last letter.
      Since:
        4.0.9

    - #### isCursorPosition

          public boolean isCursorPosition()

      Returns if the TextIter is identical with the GUIs cursor position inside the TextView.
      Since:
        4.0.9

    - #### isEditable

          public boolean isEditable(boolean defaultEditability)

      Check if text at the current position is editable. This is the case if the default editability is `true` or the TextIter is within or at the start of an editable block. If the TextIter is at the end of an editable block (which is also the star of a non-editable area), this method returns `false`.
      Since:
        4.0.9

    - #### isEnd

          public boolean isEnd()

      Checks if the TextIter points to the end of the buffer. This is the case if this TextIter has the same offset as the TextIter returned by `TextBuffer.getIterEnd()`
      Since:
        4.0.9

    - #### isStart

          public boolean isStart()

      Checks if the TextIter points to the start of the buffer. This is the case if this TextIter has the offset 0.
      Since:
        4.0.9

    - #### setLine

          public void setLine(int row)

      Move this TextIter to the start of the given line.

      If `num` is negative or larger than the number of lines in the TextBuffer, it moves the iterator to the start of the last line. Line numbers are `0` origin.

      Since:
        4.0.9

    - #### setLineOffset

          public void setLineOffset(int column)

      Move the iterator within the current TextBuffer line to the given character offset.
      Since:
        4.0.9

    - #### setOffset

          public void setOffset(int offset)

      Change this TextIter so that it points to the given offset into the underlying TextBuffer.
      Since:
        4.0.9

    - #### setVisibleLineOffset

          public void setVisibleLineOffset(int column)

      Move this TextIter into the current line at the given offset, but skipping characters that have been marked `invisible`.

      See `setLineOffset()` for the method that treats all characters normally.

      Since:
        4.0.9

    - #### startsDisplayLine

          public boolean startsDisplayLine(TextView view)

      Does the position represented by this TextIter start a display line (within a paragraph) in the given TextView?
      Since:
        4.0.9

    - #### startsLine

          public boolean startsLine()

      Check if the current position is at the start of a line.
      Since:
        4.0.9

    - #### startsSentence

          public boolean startsSentence()

      Returns `true` if the TextIter points to the first character of a sentence.
      Since:
        4.0.9

    - #### startsWord

          public boolean startsWord()

      Returns if a word is beginning at the current position, which is the case when the TextIter points to the first letter of the word.
      Since:
        4.0.9

    - #### togglesTag

          public boolean togglesTag(TextTag tag)

      Check whether a specific `TextTag` is either started or ended at exactly this point identified by the TextIter.
      Since:
        4.0.9

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `org.freedesktop.bindings.Pointer`