Derived from: public BView
Declared in: <interface/TextView.h>
The BTextView class defines a view that displays text on-screen and supports a standard user interface for entering, selecting, and editing text from the keyboard and mouse. It also supports the principal editing commands--Cut, Copy, Paste, Delete, and Select All.
BTextView objects are suitable for displaying small amounts of text in the user interface and for creating textual data in ASCII format. Full-scale text editors and word processors will need to define their own objects to handle richer data formats.
A BTextView displays all its text in a single font, the font that it inherits as a BView graphics parameter. Multiple fonts are not supported. Paragraph properties--such as alignment and tab widths--are similarly uniform for all text displayed within the view.
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.
When a BTextView is the focus view for its window, it responds to these standard keyboard shortcuts for cutting, copying, and pasting text:
These shortcuts work even in the absence of Cut, Copy, and Paste menu items; they're implemented by the BWindow for any view that might be the focus view. All the focus view has to do is cooperate, as a BTextView does, by handling the messages the shortcuts generate.
The only trick is to set up menu items that are compatible with the shortcuts. Follow these guidelines if you put a menu with editing commands in a window that has a BTextView:
You can also set up menu items that trigger calls to other BTextView editing and layout functions. Simply create menu items like Select All or Align at Left that are targeted to the focus view of the window where the BTextView is located, or to the BTextView itself. The model messages assigned to these items can be structured with whatever command constants and data entries you wish; the BTextView class imposes no constraints.
Then, in a class derived from BTextView, implement a MessageReceived() function that responds to messages posted from the menu items by calling BTextView functions like SelectAll() and SetAlignment(). For example:
void myText::MessageReceived(BMessage *message) { switch ( message->what ) { case SELECT_ALL: SelectAll(); break; case ALIGN_AT_LEFT: SetAlignment(B_ALIGN_LEFT); break; case ALIGN_AT_RIGHT: SetAlignment(B_ALIGN_RIGHT); break; . . . default: BTextView::MessageReceived(message); break; } }
The MessageReceived() function you implement should be sure to call BTextView's version of the function, which already handles B_CUT, B_COPY, and B_PASTE messages.
A BTextView object treats newline characters ('\n', 0x0a) and carriage return characters ('\r', 0x0d) alike. It converts received return characters into newlines and stores them only as newlines. By default, none of keys on the BeBox is mapped to a carriage return. The B_ENTER character is a newline.
AcceptsChar() | Can be implemented to preview the characters the user types and either accept or reject them before they're added to the display. |
BreaksAtChar() | Breaks word selection on spaces, tabs, and other invisible characters, permitting all adjacent visible characters to be selected when the user double-clicks a word. This function can be augmented to break word selection on other characters in addition to the invisible ones. |
BTextView(BRect frame, const char *name, BRect textRect, ulong resizingMode, ulong flags)
Initializes the BTextView to the frame rectangle, stated in its eventual parent's coordinate system, assigns it an identifying name, sets its resizing behavior to resizingMode and its drawing behavior with flags. These four arguments --frame, name, resizingMode, and flags--are identical to those declared for the BView class and are passed unchanged to the BView constructor.
The text rectangle, textRect, is stated in the BTextView's coordinate system. It determines where text in placed within the view's bounds rectangle:
The bottom of the text rectangle is ignored; it doesn't limit the amount of text the view can contain. The text can be limited by the number of characters, but not by the number of lines.
The constructor establishes the following default properties for a new BTextView:
A BTextView isn't fully initialized until it's assigned to a window and it receives an AttachedToWindow() notification.
See also: AttachedToWindow() , the BView constructor
virtual ~BTextView(void)
Frees the memory the BTextView allocated to hold the text and to store information about it.
virtual bool AcceptsChar(ulong aChar) const
Implemented by derived classes to return TRUE if aChar designates a character that the BTextView can add to its text, and FALSE if not. By returning FALSE, this function prevents the character from being displayed or retained by the object.
AcceptsChar() is called for every character the user types (including those, like B_BACKSPACE and B_RIGHT_ARROW, that are used for editing the text). The default version of this function always returns TRUE, but it can be overridden in a derived class to restrict the text the user can enter. For example, a BTextView might reject uppercase letters, or permit only numbers, or allow only those characters that are valid in a pathname.
Sometimes, a character will be meaningful and trigger a response of some kind, even though it can't be displayed. For example, a B_TAB (0x09) might be rejected as a character to display, and instead shift the selection to another text field. Similarly, a BTextView that has room to display only a single line of text might return FALSE for the newline character (B_ENTER, 0x0a), yet take the occasion to simulate a click on a button.
When rejecting a character outright (not using it to take some other action), an application has an obligation to explain to the user why the character is unacceptable, perhaps by displaying an alert panel or dialog box.
As an alternative to implementing an AcceptsChar() function, you can simply inform the BTextView at the outset that certain characters should not be allowed. Call DisallowChar() when setting up the BTextView to tell it which characters won't be acceptable.
See also: KeyDown(), DisallowChar()
virtual void AttachedToWindow(void)
Completes the initialization of the BTextView object after it becomes attached to a window. This function sets up the object so that it can correctly format text and display it. It makes sure that all properties that were previously set--for example, word wrapping, tab width, and alignment--are correctly reflected in the display on-screen. In addition, it calls SetFontName() and SetFontSize() to set the font to the 9.0-point Erich bitmap font (no rotation, 90 degree shear).
Because the BTextView uses pulses to animate (or "blink") the caret, the vertical line that marks the current insertion point, it enables pulsing in the window and fixes the pulse rate at 2 per second (once every 500,000 microseconds).
This function is called for you when the BTextView becomes part a window's view hierarchy; you shouldn't call it yourself, though you can override it to set a different default font and do other graphics initialization. For more information on when it's called, see the BView class.
An AttachedToWindow() function that's implemented by a derived class should begin by incorporating the BTextView version:
void MyText::AttachedToWindow() { BTextView::AttachedToWindow() . . . }
If it doesn't, the BTextView won't be able to properly display the text.
See also: BView::AttachedToWindow(), SetFontName()
virtual bool BreaksAtChar(ulong aChar) const
Implemented by derived classes to return TRUE if the aChar character can break word selection, and FALSE if it cannot. The BTextView class calls this function when the user selects a word by double-clicking it. A return of TRUE means that the character breaks the selection--it cannot be selected as part of the word. A return of FALSE means that the character will be included in the selected word.
By default, BreaksAtChar() returns TRUE if the character is a B_SPACE (0x20), a B_TAB (0x09), a newline (B_ENTER, 0x0a), or some other character with an ASCII value less than that of a space, and FALSE otherwise.
It can be reimplemented to add hyphens to the list of characters that break word selection, as follows:
bool MyTextView::BreaksAtChar(ulong someChar) { if ( someChar == '-' ) return TRUE; return BTextView::BreaksAtChar(someChar); }
See also: Text()
virtual void Copy(BClipboard *clipboard)
Copies the current selection to the clipboard. The clipboard argument is identical to the global be_clipboard object.
virtual void Cut(BClipboard *clipboard)
Copies the current selection to the clipboard, deletes it from the BTextView's text, and removes it from the display. The clipboard argument is identical to the global be_clipboard object.
void Delete(void)
Deletes the current selection from the BTextView's text and removes it from the display, without copying it to the clipboard.
See also: Cut()
void DisallowChar(ulong aChar) void AllowChar(ulong aChar)
These functions inform the BTextView whether the user should be allowed to enter aChar into the text. By default, all characters are allowed. Call DisallowChar() for each character you want to prevent the BTextView from accepting, preferably when first setting up the object.
AllowChar() reverses the effect of DisallowChar() .
Alternatively, and for more control over the context in which characters are accepted or rejected, you can implement an AcceptsChar() function for the BTextView. AcceptsChar() is called for each key-down event that's reported to the object.
See also: AcceptsChar()
virtual void Draw(BRect updateRect)
Draws the text on-screen. The Interface Kit calls this function for you whenever the text display needs to be updated--for example, whenever the user edits the text, enters new characters, or scrolls the contents of the BTextView.
See also: BView::Draw()
virtual void FrameResized(float width, float height)
Overrides the BView version of this function to reset the ranges of the BTextView's scroll bars and to update the sizes of their proportional knobs whenever the size of the BTextView changes.
See also: BView::FrameResized()
void GetSelection(long *start, long *finish)
Provides the current selection by writing the offset before the first selected character into the variable referred to by start and the offset after the last selected character into the variable referred to by finish. If no characters are selected, both offsets will record the position of the current insertion point.
The offsets designate positions between characters. The position at the beginning of the text is offset 0, the position between the first and second characters is offset 1, and so on. If the 175th through the 202nd characters were selected, the start offset would be 174 and the finish offset would be 202.
If the text isn't selectable, both offsets will be 0.
See also: Select()
void GoToLine(long index) long CurrentLine(void) const inline long CountLines(void) const
GoToLine() moves the insertion point to the beginning of the line at index. The first line has an index of 0, the second line an index of 1, and so on. If the index is out-of-range, the insertion point is moved to the beginning of the line with the nearest in-range index --that is, to either the first or the last line.
CurrentLine() returns the index of the line where the first character of the selection --or the character following the insertion point--is currently located.
CountLines() returns how many lines of text the BTextView currently contains.
Like other functions that change the selection, GoToLine() doesn't automatically scroll the display to make the new selection visible. Call ScrollToSelection() to be sure that the user can see the start of the selection.
See also: ScrollToSelection()
void Highlight(long start, long finish)
Highlights the characters from start through finish, where start and finish are the same sort of offsets into the text array as are passed to Select().
Highlight() is the function that the BTextView calls to highlight the current selection. You don't need to call it yourself for this purpose. It's in the public API just in case you may need to highlight a range of text in some other circumstance.
See also: Select()
long IndexAtPoint(BPoint point) const long IndexAtPoint(float x, float y) const
Returns the index of the character displayed closest to point --or (x, y)--in the BTextView's coordinate system. The first character in the text array is at index 0.
If the point falls after the last line of text, the return value is the index of the last character in the last line. If the point falls before the first line of text, or if the BTextView doesn't contain any text, the return value is 0.
See also: Text()
void Insert(const char *text, long length) void Insert(const char *text)
Inserts length characters of text--or if a length isn't specified, all the characters of the text string up to the null character that terminates it --at the beginning of the current selection. The current selection is not deleted and the insertion is not selected.
See also: SetText()
virtual void KeyDown(ulong aChar)
Enters text at the current selection in response to the user's typing. This function is called from the window's message loop for every report of a key-down event--once for every character the user types. However, it does nothing unless the BTextView is the focus view and the text it contains is editable.
If aChar is one of the arrow keys (B_UP_ARROW, B_LEFT_ARROW, B_DOWN_ARROW, or B_RIGHT_ARROW), KeyDown() moves the insertion point in the appropriate direction. If aChar is the B_BACKSPACE character, it deletes the current selection (or one character at the current insertion point). Otherwise, it checks whether the character was registered as unacceptable (by DisallowChar()) and it calls the AcceptsChar() hook function to give the application a chance to reject the character or handle it in some other way. If the character isn't disallowed and AcceptsChar() returns TRUE, it's entered into the text and displayed.
See also: BView::KeyDown() , AcceptsChar(), DisallowChar()
inline float LineHeight(void) const
Returns the height of a single line of text, as measured from the baseline of one line of single-spaced text to the baseline of the line above or below it.
The height is stated in coordinate units and depends on the current font. It's the sum of how far characters can ascend above and descend below the baseline, plus the amount of leading that separates lines.
See also: BView::GetFontInfo()
float LineWidth(long index = 0) const
Returns the width of the line at index--or, if no index is given, the width of the first line. The value returned is the sum of the widths (in coordinate units) of all the characters in the line, from the first through the last, including tabs and spaces.
Line indices begin at 0.
If the index passed is out-of-range, it's reinterpreted to be the nearest in-range index --that is, as the index to the first or the last line.
void MakeEditable(bool flag = TRUE) bool IsEditable(void) const
The first of these functions sets whether the user can edit the text displayed by the BTextView; the second returns whether or not the text is currently editable. Text is editable by default.
To edit text, the user must be able to select it. Therefore, when MakeEditable() is called with an argument of TRUE (or with no argument), it makes the text both editable and selectable. Similarly, when IsEditable() returns TRUE, the text is selectable as well as editable; IsSelectable() will also return TRUE.
A value of FALSE means that the text can't be edited, but implies nothing about whether or not it can be selected.
See also: MakeSelectable()
virtual void MakeFocus(bool flag = TRUE)
Overrides the BView version of MakeFocus() to highlight the current selection when the BTextView becomes the focus view (when flag is TRUE) and to unhighlight it when the BTextView no longer is the focus view (when flag is FALSE ). However, the current selection is highlighted only if the BTextView's window is the current active window.
This function is called for you whenever the user's actions make the BTextView become the focus view, or force it to give up that status.
See also: BView::MakeFocus(), MouseDown()
void MakeResizable(BView *containerView)
Makes the BTextView's frame rectangle and text rectangle automatically grow and shrink to exactly enclose all the characters entered by the user. The containerView is a view that should be resized with the BTextView; typically it's a view that draws a border around the text (like a BScrollView object) and is the parent of the BTextView. This function won't work without a container view.
MakeResizable() is an alternative to the automatic resizing behavior provided in the BView class. It triggers resizing on the user's entry of text, not on a change in the parent view's size. The two schemes are incompatible; the BTextView and the container view should not automatically resize themselves when their parents are resized.
< This function currently requires the text to be either left aligned or center aligned; it doesn't work for text that's right aligned. >
See also: SetAlignment()
void MakeSelectable(bool flag = TRUE) bool IsSelectable(void) const
The first of these functions sets whether it's possible for the user to select text displayed by the BTextView; the second returns whether or not the text is currently selectable. Text is selectable by default.
When text is selectable but not editable, the user can select one or more characters to copy to the clipboard, but can't position the insertion point (an empty selection), enter characters from the keyboard, or paste new text into the view.
Since the user must be able to select text to edit it, calling MakeSelectable() with an argument of FALSE causes the text to become uneditable as well as unselectable. Similarly, if IsSelectable() returns FALSE, the user can neither select nor edit the text; IsEditable() will also return FALSE.
A value of TRUE means that the text is selectable, but says nothing about whether or not it's also editable.
See also: MakeEditable()
virtual void MessageReceived(BMessage *message)
Overrides the BHandler version of MessageReceived() to handle four messages.
If this function gets a B_SIMPLE_DATA message, it looks for a data named "text" registered as B_ASCII_TYPE . Failing that, it looks for a single character named "char" registered as B_LONG_TYPE . If successful, it assumes that the message was dragged and dropped on the view. It changes the current selection to the point of drop and inserts the text or character at that point.
This function handles B_CUT, B_COPY, and B_PASTE messages by calling the Cut() , Copy(), and Paste() virtual functions. For the BTextView to get these messages, Cut, Copy, and Paste menu items should be:
The BTextView, through this function, takes care of the rest.
To inherit this functionality, MessageReceived() functions implemented by derived classes should be sure to call the BTextView version.
See also: BMenuItem::SetMessage(), BMenuItem::SetTarget()
virtual void MouseDown(BPoint point)
Selects text and positions the insertion point in response to the user's mouse actions. If the BTextView isn't already the focus view for its window, this function calls MakeFocus() to make it the focus view.
MouseDown() is called for each mouse-down event that occurs inside the BTextView's frame rectangle.
See also: BView::MouseDown(), BView::MakeFocus()
virtual void MouseMoved(BPoint point, ulong transit, BMessage *message)
Responds to messages reporting mouse-moved events by changing the cursor to the standard I-beam image for editing text whenever the cursor enters the view and by resetting it to the standard hand image when the cursor exits the view.
The cursor is changed to an I-beam only for text that is selectable, and only if the BTextView is the current focus view in the active window.
See also: BView::MouseMoved()
virtual void Paste(BClipboard *clipboard)
Takes textual data from the clipboard and pastes it into the text. The new text replaces the current selection, or is placed at the site of the current insertion point.
The clipboard argument is identical to the global be_clipboard object.
virtual void Pulse(void)
Turns the caret marking the current insertion point on and off when the BTextView is the focus view in the active window. Pulse() is called by the system at regular intervals.
This function is first declared in the BView class.
See also: BView::Pulse()
void ScrollToSelection(void)
Scrolls the text so that the beginning of the current selection is within the visible region of the view, provided that the BTextView is equipped with a scroll bar that permits scrolling in the required direction (horizontal or vertical).
See also: BView::ScrollBy()
void Select(long start, long finish)
Selects the characters from start up to finish, where start and finish are offsets into the BTextView's text. The offsets designate positions between characters. For example,
Select(0, 2);
selects the first two characters of text,
Select(17, 18);
selects the eighteenth character, and
Select(0, TextLength());
selects the entire text just as the SelectAll() function does. If start and finish are the same, the selection will be empty (an insertion point).
Normally, the selection is changed by the user. This function provides a way to change it programmatically.
If the BTextView is the current focus view in the active window, Select() highlights the new selection (or displays a blinking caret at the insertion point). However, it doesn't automatically scroll the contents of the BTextView to make the new selection visible. Call ScrollToSelection() to be sure that the user can see the start of the selection.
See also: Text(), GetSelection(), ScrollToSelection(), GoToLine() , MouseDown()
void SelectAll(void)
Selects the entire text of the BTextView, and highlights it if the BTextView is the current focus view in the active window.
See also: Select()
void SetAlignment(alignment where) alignment Alignment(void) const
These functions set the way text is aligned within the text rectangle and return the current alignment. Three settings are possible:
B_ALIGN_LEFT | Each line is aligned at the left boundary of the text rectangle. |
B_ALIGN_RIGHT | Each line is aligned at the right boundary of the text rectangle. |
B_ALIGN_CENTER | Each line is centered between the left and right boundaries of the text rectangle. |
The default is B_ALIGN_LEFT.
void SetAutoindent(bool flag) bool DoesAutoindent(void) const
These functions set and return whether a new line of text is automatically indented the same as the preceding line. When set to TRUE and the user types Return at the end of a line that begins with tabs or spaces, the new line will automatically indent past those tabs and spaces to the position of the first visible character.
The default value is FALSE.
virtual void SetFontName(const char *name) virtual void SetFontSize(float points) virtual void SetFontRotation(float degrees) virtual void SetFontShear(float angle)
These functions override their BView counterparts to recalculate the layout of the text when the font changes, and to prevent the text displayed by a BTextView object from being rotated.
Font rotation is disabled; the BTextView version of SetFontRotation() does nothing. The other three functions invoke their BView counterparts to change the font, then make sure the entire text is recalculated and rewrapped for the new font. However, the text display is not updated.
SetFontName() and SetFontSize() are called by AttachedToWindow() to set the BTextView's default font to 9.0-point Erich.
See also: BView::SetFontName()
void SetMaxChars(long max)
Sets the maximum number of characters that the BTextView can accept. The default is the maximum number of characters that can be designated by a long integer, a number sufficiently large to accommodate all uses of a BTextView. Use this function only if you need to restrict the number of characters that the user can enter in a text field.
virtual void SetSymbolSet(const char *name)
Overrides its BView counterpart to recalculate the text layout when the symbol set changes.
See also: BView::SetSymbolSet()
void SetTabWidth(float width) float TabWidth(void) const
These functions set the distance between tab stops to width coordinate units and return the current tab width. Tabs cannot be removed nor can they be individually set; all tabs have a uniform width. The default tab width is 44.0 coordinate units.
void SetText(const char *text, long length) void SetText(const char *text)
Removes any text currently in the BTextView and copies length characters of text to replace it--or all the characters in the text string, up to the null character, if a length isn't specified. If text is NULL or length is 0, this function empties the BTextView. Otherwise, it copies the required number of text characters passed to it.
This function is typically used to set the text initially displayed in the view. If the BTextView is attached to a window, it's updated to show its new contents.
See also: Text(), TextLength()
void SetTextRect(BRect rect) inline BRect TextRect(void) const
SetTextRect() makes rect the BTextView's text rectangle --the rectangle that locates where text is placed within the view. This replaces the text rectangle originally set in the BTextView constructor. The layout of the text is recalculated to fit the new rectangle, and the text is redisplayed.
TextRect() returns the current text rectangle.
See also: the BTextView constructor
void SetWordWrap(bool flag) bool DoesWordWrap(void) const
These functions set and return whether the BTextView wraps lines on word boundaries, dropping entire words that don't fit at the end of a line to the next line. Words break on tabs, spaces, and other invisible characters; all adjacent visible characters wrap together.
By default, word wrapping is turned off (DoesWordWrap() returns FALSE). Lines break only on a newline character (where the user types return).
See also: SetTextRect()
const char *Text(void) const char *GetText(char *buffer, long index, long length) const char CharAt(long index) const
These functions reveal the text contained in the BTextView.
Text() returns a pointer to the text, which may be a pointer to an empty string if the BTextView is empty. The returned pointer can be used to read the text, but not to alter it (use SetText(), Insert(), Delete(), and other BTextView functions to do that).
GetText() copies up to length characters of the text into buffer, beginning with the character at index, and adds a null terminator ('\0'). The first character in the BTextView is at index 0, the second at index 1, and so on. Fewer than length characters are copied if there aren't that many between index and the end of the text. The results won't be reliable if the index is out-of-range.
CharAt() returns the specific character located at index.
The pointer that Text() returns is to the BTextView's internal representation of the text. When it returns, the text string is guaranteed to be null-terminated and without gaps. However, the BTextView may have had to manipulate the text to get it in that condition. Therefore, there may be a performance price to pay if Text() is called frequently. If you're going to copy the text, it's more efficient to have GetText() do it for you. If you're going to index into the text, it may be more efficient to call CharAt().
The pointer that Text() returns may no longer be valid after the user or the program next changes the text. Even if valid, the string may no longer be null-terminated and gaps may appear.
See also: TextLength()
long TextLength(void) const
Returns the number of characters the BTextView currently contains-- the number of characters that Text() returns (not counting the null terminator).
See also: Text(), SetMaxChars()
virtual void WindowActivated(bool flag)
Highlights the current selection when the BTextView's window becomes the active window (when flag is TRUE)--provided that the BTextView is the current focus view --and removes the highlighting when the window ceases to be the active window (when flag is FALSE).
If the current selection is empty (if it's an insertion point), it's highlighted by turning the caret on and off (blinking it).
The Interface Kit calls this function for you whenever the BTextView's window becomes the active window or it loses that status.
See also: BView::WindowActivated(), MakeFocus()
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.