Widget for displaying textual data.
Conceptual Overview
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.
addChild
public void addChild(Widget child,
TextChildAnchor anchor)
Adds a child widget in the text buffer, at the given anchor.
child
- A Widgetanchor
- A TextChildAnchor in the TextBuffer for his view
addListener
public void addListener(TextViewListener listener)
Register an object to receive text view event notification.
listener
- The object that has implemented the TextViewListener interface
that is to receive the text view events.
bufferToWindowCoords
public Point bufferToWindowCoords(TextWindowType winType,
int xCoord,
int yCoord)
winType
- a TextWindowType
xCoord
- buffer X coordinateyCoord
- buffer Y coordinate
- the corresponding window coordinates
getAcceptsTab
public boolean getAcceptsTab()
Returns whether pressing the Tab key inserts a tab characters.
getBorderWindowSize
public int getBorderWindowSize(TextWindowType type)
Gets the width of the specified border window.
type
- The window to return size from
getBuffer
public TextBuffer getBuffer()
Returns the buffer being used
- The buffer used in the widget.
getCursorVisible
public boolean getCursorVisible()
Find out whether the cursor is being displayed.
- Whether the insertion cursor is visible
getDefaultAttributes
public TextAttributes getDefaultAttributes()
Obtains a copy of the default text attributes. These are the attributes
used for text unless a tag overrides them.
- The text attributes being used
getEditable
public boolean getEditable()
Returns the default editability of the GtkTextView. Tags in the buffer
may override this setting for some ranges of text.
- true if the widget is editable.
getIndent
public int getIndent()
Gets the default indentation of paragraphs in text_view. Tags in the
view's buffer may override the default. The indentation may be negative.
- The number of pixels of indentation
getIterAtLocation
public TextIter getIterAtLocation(int x,
int y)
Returns an iterator for the location pointed to by the coordinates
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.
x
- x buffer coordinatey
- y buffer coordinate
- an iterator to a given x-y coordinate location
getIterAtLocation
public TextIter getIterAtLocation(Point bufferCoords)
Returns an iterator for the location pointed to by bufferCoords,
representing coordinates within the buffer. Coordinates obtained in
relation to the widget must be converted to buffer coordinates using
windowToBufferCoords.
bufferCoords
- a Point representing a pair of buffer coordinates
- an iterator to a given x-y coordinate location
getJustification
public Justification getJustification()
Gets the default justification of text in this TextView. Tags in the
buffer may override the default.
- The default justification
getLeftMargin
public int getLeftMargin()
Gets the default left margin size of paragraphs in the TextView. Tags in
the buffer may override the default.
- The left margin, in pixels
getOverwrite
public boolean getOverwrite()
Returns whether the TextView is in overwrite mode or not.
getPixelsAboveLines
public int getPixelsAboveLines()
Gets the default number of pixels to put above paragraphs.
- the default number of pixels to put above paragraphs.
getPixelsBelowLines
public int getPixelsBelowLines()
Gets the default number of pixels of blank space to put below paragraphs.
- the default number of pixels of blank space to put below
paragraphs
getPixelsInsideWrap
public int getPixelsInsideWrap()
Gets the default number of pixels of blank space to leave between
display/wrapped lines within a paragraph.
- the default number of pixels of blank space to leave between
display/wrapped lines within a paragraph.
getRightMargin
public int getRightMargin()
Gets the default right margin size of paragraphs in the TextView. Tags in
the buffer may override the default.
- The right margin, in pixels
getTabs
public TabArray getTabs()
Gets the default tabs for text_view. Tags in the buffer may override the
defaults. The returned array will be NULL if "standard" (8-space) tabs
are used.
getTextView
public static TextView getTextView(Handle handle)
Internal static factory method to be used by Java-Gnome only.
getType
public static Type getType()
Retrieve the runtime type used by the GLib library.
- getType in interface Container
getVisibleRectangle
public Rectangle getVisibleRectangle()
getWindow
public 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. Windows are null and nonexistent if their width or height is
0, and are nonexistent before the widget has been realized.
getWindowType
public TextWindowType getWindowType(Window win)
Usually used to find out which window an event corresponds to.
getWrapMode
public WrapMode getWrapMode()
Gets the line wrapping for the view.
- the line wrap setting for the view.
moveCursorOnScreen
public boolean moveCursorOnScreen()
Moves the cursor to the currently visible region of the buffer, it it
isn't there already.
- TRUE if the cursor had to be moved.
moveMarkOnScreen
public boolean moveMarkOnScreen(TextMark mark)
Moves a mark within the buffer so that it's located within the
currently-visible text area.
- TRUE if the mark had to be moved.
removeListener
public void removeListener(TextViewListener listener)
Unregister an object that was receiving text view event notification.
listener
- The object that is to no longer receive text view events.
scrollMarkOnScreen
public void scrollMarkOnScreen(TextMark mark)
Scrolls this the minimum distance such that mark is contained within the
visible area of the widget.
mark
- a mark in the buffer of the TextView.
scrollToIter
public boolean scrollToIter(TextIter iter,
double withinMargin)
Scrolls text view so that iter is on the screen. The effective screen for
purposes of this function is reduced by a margin of size within_margin.
NOTE: This function uses the currently-computed height of the lines in
the text buffer. Note that line heights are computed in an idle handler;
so this function may not have the desired effect if it's called before
the height computations. To avoid oddness, consider using
gtk_text_view_scroll_to_mark() which saves a point to be scrolled to
after line validation.
iter
- a TextIterwithinMargin
- Margin as a [0.0,0.5) fraction of screen size.
- TRUE if scrolling occurred
scrollToIter
public 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. An alignment of 0.0 indicates left or top, 1.0
indicates right or bottom, 0.5 means center. The effective screen for
purposes of this function is reduced by a margin of size within_margin.
NOTE: This function uses the currently-computed height of the lines in
the text buffer. Note that line heights are computed in an idle handler;
so this function may not have the desired effect if it's called before
the height computations. To avoid oddness, consider using
scrollToMark(TextMark,double,boolean,double,double)
which
saves a point to be scrolled to after line validation.
iter
- a TextIterwithinMargin
- 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
- TRUE if scrolling occurred
scrollToMark
public void scrollToMark(TextMark mark,
double withinMargin)
Scrolls the view so that mark is on the screen. The text scrolls the
minimal distance to get the mark onscreen, possibly not scrolling at all.
The effective screen for purposes of this function is reduced by a margin
of size withinMargin.
mark
- A TextMark
withinMargin
- Margin as a fraction of screen size
scrollToMark
public 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. An alignment of 0.0 indicates left or top, 1.0
indicates right or bottom, 0.5 means center.
mark
- A TextMark
withinMargin
- Margin as a fraction of screen sizeuseAlign
- Whether to use alignment arguments.xAlign
- Horizontal alignment of mark within visible area.yAlign
- :
vertical alignment of mark within visible area
setAcceptsTab
public void setAcceptsTab(boolean acceptsTab)
Sets the behavior of the text widget when the Tab key is pressed. If
TRUE, a tab character is inserted. If is FALSE, the keyboard focus is
moved to the next widget in the focus chain.
acceptsTab
- TRUE if pressing the Tab key should insert a tab character,
FALSE, if pressing the Tab key should move the keyboard focus
setBorderWindowSize
public void setBorderWindowSize(TextWindowType type,
int size)
type
- The window to affectsize
- Width or height of the window
setBuffer
public void setBuffer(TextBuffer buffer)
Sets buffer as the buffer being displayed by the view.
buffer
- The new buffer to display
setCursorVisible
public void setCursorVisible(boolean setting)
Toggles whether the insertion point is displayed. A buffer with no
editable text probably shouldn't have a visible cursor, so you may want
to turn the cursor off.
setting
- Whether to show the insertion cursor
setEditable
public void setEditable(boolean setting)
Sets the default editability of the GtkTextView. You can override this
default setting with tags in the buffer, using the "editable" attribute
of tags.
setting
- Whether it's editable
setIndent
public void setIndent(int indent)
Sets the default indentation for paragraphs in text_view. Tags in the
buffer may override the default.
indent
- Indentation in pixels
setJustification
public void setJustification(Justification justification)
Sets the default justification of text in text_view. Tags in the view's
buffer may override the default.
justification
- The justification to use.
setLeftMargin
public void setLeftMargin(int leftMargin)
Sets the default left margin for text in text_view. Tags in the buffer
may override the default.
leftMargin
- Size of left margin, in pixels
setOverwrite
public void setOverwrite(boolean overwrite)
Changes the overwrite mode (whether text is overwritten)
overwrite
- TRUE to turn on overwrite mode, FALSE to turn it off
setPixelsAboveLines
public void setPixelsAboveLines(int pixelsAboveLines)
Sets the default number of blank pixels above paragraphs in text_view.
Tags in the buffer for text_view may override the defaults.
pixelsAboveLines
- Pixels above paragraphs
setPixelsBelowLine
public void setPixelsBelowLine(int pixelsBelowLines)
Use setPixelsBelowLines(int)
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.
pixelsBelowLines
- Pixels below paragraphs
setPixelsBelowLines
public void setPixelsBelowLines(int pixelsBelowLines)
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.
pixelsBelowLines
- Pixels below paragraphs
setPixelsInsideWrap
public void setPixelsInsideWrap(int pixelsInsideWrap)
Sets the default number of pixels of blank space to leave between
display/wrapped lines within a paragraph. May be overridden by tags in
text_view's buffer.
pixelsInsideWrap
- Default number of pixels between wrapped lines
setRightMargin
public void setRightMargin(int rightMargin)
Sets the default right margin for text in text_view. Tags in the buffer
may override the default.
rightMargin
- Size of right margin, in pixels
setTabs
public void setTabs(TabArray tabStops)
Sets the default tab stops for paragraphs in text_view. Tags in the
buffer may override the default.
tabStops
- tabs as a PangoTabArray
setWrapMode
public void setWrapMode(WrapMode wrapMode)
Sets the line wrapping for the view.
windowToBufferCoords
public Point windowToBufferCoords(TextWindowType winType,
int xCoord,
int yCoord)
Converts coordinates on the window identified by the winType
to buffer coordinates.
winType
- a TextWindowType
.xCoord
- the x-coordinate in relation to the Window winyCoord
- the y-coordinate in relation to the Window win
- a Point representing the buffer coordinates