BTextView¶
A BTextView object displays text on-screen, and provides these manipulating features:
It lets the user enter, select, and edit text from the keyboard and mouse.
It supports standard Cut, Copy, Paste, Delete, and Select All editing commands.
It provides an Undo mechanism.
By default, a BTextView displays all its text in a single font and color. The
SetStylable() turns on support for multiple character formats.
Paragraph formats—such as alignment and tab widths—are uniform for all text the
BTextView displays. These properties can be set, but the setting always applies to the
entire text.
Warning
The BTextView class isn’t multi-thread safe; don’t issue BTextView calls
on a BTextView object from multiple threads, or you may see unusual behavior; in
general, only the thread that created the BTextView should issue calls on it.
Offsets¶
The BTextView locates particular characters in its text buffer by offsets from the
beginning of the data. The offsets count bytes, not characters, and begin at 0. A single character
is identified by the offset of the first byte of the character. A group of characters—the current
selection, for example—is delimited by the offsets that bound its first and last characters; all
characters beginning with the first offset up to, but not including, the last offset are part of the
group.
For example, suppose the BTextView contains the following text in UTF-8 encoding,
Haiku® is . . .
and “Haiku®” is selected. GetSelection() would return 4 and 12 as the
offsets that enclose the selection. The character ‘H’ occupies the fourth byte of text and the space
following the registered trademark symbol is the twelth byte of text. The characters in “Haiku” are
encoded in one byte, but ‘®’ takes up three bytes in UTF-8. Thus the five-character selection
occupies 7 bytes (and offsets) of text.
Although offsets count bytes, they can also be thought of as designating positions between characters. The position at the beginning of the text is offset 0, the position between the sapce and the ‘H’ in the example above is at offset 4, the position between the ‘®’ and the space is at offset 12, and so on. Thus, even if no characters are selected, the insertion point (and location of the caret) can still be designated by an offset.
Most BTextView functions expect the offsets they’re passed to mark positions between
characters; the results are not defined if a character-internal offset is specified instead.
Graphics Primitives¶
The BTextViews mechanism for formatting and drawing text uses the graphics primitives
it inherits from the BView class. However, it largely presents its own API for
determining the appearance of the text it draws. You should not attempt to affect the
BTextView by calling primitive BView functions like
MovePenTo(), SetFont(), or
SetHighColor(). Instead, use BTextView functions like
SetFontAndColor() and let the object take care of formatting and drawing the
text.
The one inherited function that can influence the BTextView is
SetViewColor(). This function determines the background against which the text
is drawn and the color that is used in antialiasing calculations.
Resizing¶
A BTextView can be made to resize itself to exactly fit the text that the user enters.
This is sometimes appropriate for small one-line text fields. See the
MakeResizable() function.
BTextView and BScrollBars¶
If you add scrollbars to control the position of the BTextView’s document—this
includes using a BTextView as the target of a BScrollView—the
BTextView will update the scrollbars for you. (Note that it doesn’t own the scrollbars;
you still have to delete them yourself if you created them.) When the BTextView is
first displayed and thereafter resized, the scrollbars’ ranges, step sizes, and scroller positions
and proportions are automatically reset to refelct the BTextView object’s bounds.
Attempts to set these parameters directly (through BScrollBar::SetRange() etc.), are worse than ignored; they're actually applied, and then (at some point) the {cpp:class}()BTextView`
will notice the change in the scrollbars and reset them. Looks like flicker to me.