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 Unicode UTF-8 encoding,

The BeOS(TM) is . . .

and "BeOS(TM)" is selected. GetSelection() would return 4 and 11 as the offsets that enclose the selection. The character 'B' occupies the fourth byte of text and the space following the trademark symbol is the eleventh byte of text. The characters in "BeOS" are each encoded in one byte, but '(TM) ' 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 space and the 'B' in the example above is at offset 4, the position between the '(TM) ' and the space is at offset 11, 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.

The BTextView's 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.

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.

If you add scrollbars to control the position of the BTextView's document—this includes using a BTextView as the target of a BTextViewBScrollView—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 reflect 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 BTextView will notice the change in the scrollbars and reset them. Looks like flicker to me.

When it's the focus view for its window, a BTextView automatically responds to a set of keyboard shortcuts:

• Command+x cuts text and copies it to the clipboard

• Command+c copies text to the clipboard without cutting it

• Command+v pastes text taken from the clipboard

• Command+a selects all of the text in the BTextView

• Command+z undoes the previous action

If you create menu items for these actions, you have to assign the BMenuItem shortcuts and command constants yourself: