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

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 TextMarks 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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD