org.gnu.gtk
public class TextView extends Container
java-gnome has an extremely powerful framework for multiline text editing. The primary objects involved in the process are TextBuffer, which represents the text being edited, and TextView, a widget which can display a TextBuffer. Each buffer can be displayed by any number of views.
One of the important things to remember about text in java-gnome is that it's in the UTF-8 encoding. This means that one character can be encoded as multiple bytes. Character counts are usually referred to as offsets, while byte counts are called indexes. If you confuse these two, things will work fine with ASCII, but as soon as your buffer contains multibyte characters, bad things will happen.
Text in a buffer can be marked with tags. A tag is an attribute that can be applied to some range of text. For example, a tag might be called "bold" and make the text inside the tag bold. However, the tag concept is more general than that; tags don't have to affect appearance. They can instead affect the behavior of mouse and key presses, "lock" a range of text so the user can't edit it, or countless other things. A tag is represented by a TextTag object. One TextTag can be applied to any number of text ranges in any number of buffers.
Each tag is stored in a TextTagTable. A tag table defines a set of tags that can be used together. Each buffer has one tag table associated with it; only tags from that tag table can be used with the buffer. A single tag table can be shared between multiple buffers, however.
Tags can have names, which is convenient sometimes (for example, you can name your tag that makes things bold "bold"), but they can also be anonymous (which is convenient if you're creating tags on-the-fly).
Most text manipulation is accomplished with iterators, represented by a TextIter. An iterator represents a position between two characters in the text buffer. Iterators are not valid indefinitely; whenever the buffer is modified in a way that affects the number of characters in the buffer, all outstanding iterators become invalid. (Note that deleting 5 characters and then reinserting 5 still invalidates iterators, though you end up with the same number of characters you pass through a state with a different number).
Because of this, iterators can't be used to preserve positions across buffer modifications. To preserve a position, the TextMark object is ideal. You can think of a mark as an invisible cursor or insertion point; it floats in the buffer, saving a position. If the text surrounding the mark is deleted, the mark remains in the position the text once occupied; if text is inserted at the mark, the mark ends up either to the left or to the right of the new text, depending on its gravity. The standard text cursor in left-to-right languages is a mark with right gravity, because it stays to the right of inserted text.
Like tags, marks can be either named or anonymous. There are two marks built-in to TextBuffer; these are named "insert" and "selection_bound" and refer to the insertion point and the boundary of the selection which is not the insertion point, respectively. If no text is selected, these two marks will be in the same position. You can manipulate what is selected and where the cursor appears by moving these marks around.
Text buffers always contain at least one line, but may be empty (that is, buffers can contain zero characters). The last line in the text buffer never ends in a line separator (such as newline); the other lines in the buffer always end in a line separator. Line separators count as characters when computing character counts and character offsets. Note that some Unicode line separators are represented with multiple bytes in UTF-8, and the two-character sequence "\r\n" is also considered a line separator.
Nested Class Summary | |
---|---|
static class | TextView.VerticalLineRange
Class to handle returns from VerticalLineRange. |
Constructor Summary | |
---|---|
TextView()
Constructs a new TextView. | |
TextView(TextBuffer buffer)
Creates a new TextView widget displaying the buffer buffer. | |
TextView(Handle handle)
Construct a TextView from a handle to a native resource. |
Method Summary | |
---|---|
void | addChild(Widget child, TextChildAnchor anchor)
Adds a child widget in the text buffer, at the given anchor.
|
void | addListener(TextViewListener listener)
Register an object to receive text view event notification.
|
Point | bufferToWindowCoords(TextWindowType winType, int xCoord, int yCoord)
Converts coordinate (xCoord, yCoord) to coordinates for the window
winType . |
boolean | getAcceptsTab()
Returns whether pressing the Tab key inserts a tab characters.
|
int | getBorderWindowSize(TextWindowType type)
Gets the width of the specified border window.
|
TextBuffer | getBuffer()
Returns the buffer being used
|
boolean | getCursorVisible()
Find out whether the cursor is being displayed.
|
TextAttributes | getDefaultAttributes()
Obtains a copy of the default text attributes. |
boolean | getEditable()
Returns the default editability of the GtkTextView. |
Class | getEventListenerClass(String signal) |
EventType | getEventType(String signal) |
Adjustment | getHAdjustment() |
int | getIndent()
Gets the default indentation of paragraphs in text_view. |
TextIter | getIterAtLocation(int x, int y)
Returns an iterator for the location pointed to by the coordinates
x and y within the buffer. |
TextIter | getIterAtLocation(Point bufferCoords)
Returns an iterator for the location pointed to by bufferCoords,
representing coordinates within the buffer. |
Justification | getJustification()
Gets the default justification of text in this TextView. |
int | getLeftMargin()
Gets the default left margin size of paragraphs in the TextView. |
TextView.VerticalLineRange | getLineYRange(TextIter iter)
Gets the y coordinate of the top of the line containing iter ,
and the height of the line. |
boolean | getOverwrite()
Returns whether the TextView is in overwrite mode or not.
|
int | getPixelsAboveLines()
Gets the default number of pixels to put above paragraphs.
|
int | getPixelsBelowLines()
Gets the default number of pixels of blank space to put below paragraphs.
|
int | getPixelsInsideWrap()
Gets the default number of pixels of blank space to leave between
display/wrapped lines within a paragraph.
|
int | getRightMargin()
Gets the default right margin size of paragraphs in the TextView. |
TabArray | getTabs()
Gets the default tabs for text_view. |
static TextView | getTextView(Handle handle)
Internal static factory method to be used by Java-Gnome only. |
static Type | getType()
Retrieve the runtime type used by the GLib library. |
Adjustment | getVAdjustment() |
Rectangle | getVisibleRectangle()
Returns a Rectangle with the currently-visible region of the buffer, in
buffer coordinates. |
Window | getWindow(TextWindowType type)
Retrieves the Window corresponding to an area of the
text view; possible windows include the overall widget window, child
windows on the left, right, top, bottom, and the window that displays the
text buffer. |
TextWindowType | getWindowType(Window win)
Usually used to find out which window an event corresponds to.
|
WrapMode | getWrapMode()
Gets the line wrapping for the view.
|
boolean | moveCursorOnScreen()
Moves the cursor to the currently visible region of the buffer, it it
isn't there already.
|
boolean | moveMarkOnScreen(TextMark mark)
Moves a mark within the buffer so that it's located within the
currently-visible text area.
|
void | removeListener(TextViewListener listener)
Unregister an object that was receiving text view event notification.
|
void | scrollMarkOnScreen(TextMark mark)
Scrolls this the minimum distance such that mark is contained within the
visible area of the widget.
|
boolean | scrollToIter(TextIter iter, double withinMargin, double xAlign, double yAlign)
Scrolls text view so that iter is on the screen in the position indicated
by xalign and yalign. |
boolean | scrollToIter(TextIter iter, double withinMargin)
Scrolls text view so that iter is on the screen. |
void | scrollToMark(TextMark mark, double withinMargin, boolean useAlign, double xAlign, double yAlign)
Scrolls the view so that mark is on the screen in the position indicated
by xAlign and yAlign. |
void | scrollToMark(TextMark mark, double withinMargin)
Scrolls the view so that mark is on the screen. |
void | setAcceptsTab(boolean acceptsTab)
Sets the behavior of the text widget when the Tab key is pressed. |
void | setBorderWindowSize(TextWindowType type, int size) |
void | setBuffer(TextBuffer buffer)
Sets buffer as the buffer being displayed by the view.
|
void | setCursorVisible(boolean setting)
Toggles whether the insertion point is displayed. |
void | setEditable(boolean setting)
Sets the default editability of the GtkTextView. |
void | setIndent(int indent)
Sets the default indentation for paragraphs in text_view. |
void | setJustification(Justification justification)
Sets the default justification of text in text_view. |
void | setLeftMargin(int leftMargin)
Sets the default left margin for text in text_view. |
void | setOverwrite(boolean overwrite)
Changes the overwrite mode (whether text is overwritten)
|
void | setPixelsAboveLines(int pixelsAboveLines)
Sets the default number of blank pixels above paragraphs in text_view.
|
void | setPixelsBelowLine(int pixelsBelowLines)
Sets the default number of pixels of blank space to put below paragraphs
in text_view. |
void | setPixelsBelowLines(int pixelsBelowLines)
Sets the default number of pixels of blank space to put below paragraphs
in text_view. |
void | setPixelsInsideWrap(int pixelsInsideWrap)
Sets the default number of pixels of blank space to leave between
display/wrapped lines within a paragraph. |
void | setRightMargin(int rightMargin)
Sets the default right margin for text in text_view. |
void | setTabs(TabArray tabStops)
Sets the default tab stops for paragraphs in text_view. |
void | setWrapMode(WrapMode wrapMode)
Sets the line wrapping for the view.
|
Point | windowToBufferCoords(TextWindowType winType, int xCoord, int yCoord)
Converts coordinates on the window identified by the winType
to buffer coordinates.
|
Parameters: buffer Buffer to use
Parameters: child A Widget anchor A TextChildAnchor in the TextBuffer for his view
Parameters: listener The object that has implemented the TextViewListener interface that is to receive the text view events.
winType
. Note that you can't convert coordinates for a
non-existing window (see
TextView.
Parameters: winType a TextWindowType xCoord buffer X coordinate yCoord buffer Y coordinate
Returns: the corresponding window coordinates
Parameters: type The window to return size from
Returns: The size of the window
See Also: .
Returns: The buffer used in the widget.
Returns: Whether the insertion cursor is visible
Returns: The text attributes being used
Returns: true if the widget is editable.
Returns: The number of pixels of indentation
x
and y
within the buffer. Coordinates
obtained in relation to the widget must be converted to buffer
coordinates using windowToBufferCoords before passing them into this
method.
Parameters: x x buffer coordinate y y buffer coordinate
Returns: an iterator to a given x-y coordinate location
Parameters: bufferCoords a Point representing a pair of buffer coordinates
Returns: an iterator to a given x-y coordinate location
Returns: The default justification
Returns: The left margin, in pixels
iter
,
and the height of the line. The coordinate is a buffer coordinate;
convert to window coordinates with
TextView.
Parameters: iter A valid TextIter
Returns: The y-coordinate and Height of the line containing iter
Since: 2.4
See Also: TextView
Returns: the default number of pixels to put above paragraphs.
Returns: the default number of pixels of blank space to put below paragraphs
Returns: the default number of pixels of blank space to leave between display/wrapped lines within a paragraph.
Returns: The right margin, in pixels
Parameters: type The window to get
Returns: The window, or null
Parameters: win A window
Returns: The type of the window
Returns: the line wrap setting for the view.
Returns: TRUE if the cursor had to be moved.
Returns: TRUE if the mark had to be moved.
Parameters: listener The object that is to no longer receive text view events.
Parameters: mark a mark in the buffer of the TextView.
Parameters: iter a TextIter withinMargin Margin as a [0.0,0.5) fraction of screen size. xAlign : horizontal alignment of mark within visible area. yAlign : vertical alignment of mark within visible area
Returns: TRUE if scrolling occurred
Parameters: iter a TextIter withinMargin Margin as a [0.0,0.5) fraction of screen size.
Returns: TRUE if scrolling occurred
Parameters: mark A TextMark withinMargin Margin as a fraction of screen size useAlign Whether to use alignment arguments. xAlign Horizontal alignment of mark within visible area. yAlign : vertical alignment of mark within visible area
Parameters: mark A TextMark withinMargin Margin as a fraction of screen size
Parameters: acceptsTab TRUE if pressing the Tab key should insert a tab character, FALSE, if pressing the Tab key should move the keyboard focus
Since: 2.4
Parameters: type The window to affect size Width or height of the window
Parameters: buffer The new buffer to display
Parameters: setting Whether to show the insertion cursor
Parameters: setting Whether it's editable
Parameters: indent Indentation in pixels
Parameters: justification The justification to use.
Parameters: leftMargin Size of left margin, in pixels
Parameters: overwrite TRUE to turn on overwrite mode, FALSE to turn it off
Since: 2.4
Parameters: pixelsAboveLines Pixels above paragraphs
Deprecated: Use TextView instead.
Sets the default number of pixels of blank space to put below paragraphs in text_view. May be overridden by tags applied to text_view's buffer.Parameters: pixelsBelowLines Pixels below paragraphs
Parameters: pixelsBelowLines Pixels below paragraphs
Parameters: pixelsInsideWrap Default number of pixels between wrapped lines
Parameters: rightMargin Size of right margin, in pixels
Parameters: tabStops tabs as a PangoTabArray
Parameters: wrapMode A WrapMode
winType
to buffer coordinates.
Parameters: winType a TextWindowType. xCoord the x-coordinate in relation to the Window win yCoord the y-coordinate in relation to the Window win
Returns: a Point representing the buffer coordinates