BView

Introduction

BView objects are the agents for drawing and message handling within windows. Each object sets up and takes responsibility for a particular view, a rectangular area that's associated with at most one window at a time. The object draws within the view rectangle and responds to reports of events elicited by the images drawn.

Classes derived from BView implement the actual functions that draw and handle messages; BView merely provides the framework. For example, a BTextView object draws and edits text in response to the user's activity on the keyboard and mouse. A BButton draws the image of a button on-screen and responds when the button is clicked. BTextView and BButton inherit from the BView class—as do most classes in the Interface Kit.

Views and Windows

For a BView to do its work, you must attach it to a window. The views in a window are arranged in a hierarchy—there can be views within views—with those that are most directly responsible for drawing and message handling located at the terminal branches of the hierarchy and those that contain and organize other views situated closer to its trunk and root. A BView begins life unattached. You can add it to a hierarchy by calling the AddChild() function of the BWindow or of another BView.

Within the hierarchy, a BView object plays two roles:

• It's a BHandler for messages delivered to the window thread. BViews implement the functions that respond to the most common system messages—including those that report keyboard and mouse events. They can also be targeted to handle application-defined messages that affect what they view displays.

• It's an agent for drawing. Adding a BView to a window gives it an independent graphics environment. A BView draws on the initiative of the BWindow and the Application Server, whenever they determine that the appearance of any part of the view rectangle needs to be "updated." It also draws on its own initiative in response to events.

The relationship of BViews to BWindows and the framework for drawing and responding to the user were discussed in the opening sections of this chapter. The concepts and terminology presented there are assumed in this class description.

BViews can also be called upon to create bitmap images. See the BBitmap class for details.

Locking the Window

If a BView is attached to a window, any operation that affects the view might also affect the window and the BView's shadow counterpart in the Application Server. For this reason, any code that calls a BView function should first lock the window—so that one thread can't modify essential data structures while another thread is using them. A window can be locked by only one thread at a time.

Locking is accomplished through the BLooper Lock() and Unlock() functions inherited by BWindow:

   if ( Window()->Lock() ) {
       . . .
       Window()->Unlock();
   }

Before they do anything else, almost all BView functions check to be sure the caller has the window locked. If the window isn't properly locked, they print warning messages and fail.

Of course, a BView function can require the window to be locked only if the view has a window to lock; the requirement can't be enforced if the BView isn't attached to a window. However, as discussed in "Views and the Server" in the "Drawing" section of this chapter, some BView functions don't work at all unless the view is attached—in which case the window must be locked.

Whenever the system calls a BView function to notify it of something—whenever it calls WindowActivated(), Draw(), MessageReceived() or another hook function—it first locks the window thread. The application doesn't have to explicitly lock the window when responding to an update, an interface message, or some other notification; the window is already locked.

Focus

To facilitate keyboard navigation of views, BView provides integral support for the concept of focus. Only one view in a window can have the focus at any given time, and the view that has the focus is the one whose KeyDown() function is called to process keyboard events.

From the user's point-of-view, the tab key rotates the focus from one view to the next through the navigation group, cycling back to the first view if the tab key is pressed while the last targetable view in the group has the focus. The shift-tab keyboard combination cycles the focus backward. Holding down the control key while cycling groups causes the focus to jump from one navigation group to the next.

When a view has the focus, some sort of indicator should be drawn to inform the user that the view is the focus. Typically, this involves drawing a line under a label in teh view, or possibly drawing a box around the view or some portion of it. The global keyboard_navigation_color() function should be used to obtain the color used to draw the focus indicator.

The view's MakeFocus() function is called to specify whether or not the control has the focus; it's called with an argument of true if the control has the focus, and false if it's not the focus; MakeFocus() calls the previously-focused view's MakeFocus() function to inform that view that it's not the focus anymore. You can augment MakeFocus() is a subclass if you need to take notice when the view becomes the focus (or loses the focus). For example, you may need to draw or erase the keyboard navigation indicator.

Focus is used extensively by controls. For further information, see "Introduction to Controls."

Derived Classes

When it comes time for a BView to draw, its Draw() virtual function is called automatically. When it needs to respond to an event, a virtual function named after the kind of event is called—MouseMoved(), KeyDown(), and so on. Classes derived from BView implement these hook functions to do the particular kind of drawing and message handling characteristic of the derived class.

• Some classes derived from BView implement control devices—buttons, dials, selection lists, check boxes, and so on—that translate user actions on the keyboard and mouse into more explicit instructions for the application. In the Interface Kit, BMenu, BListView, BButton, BCheckBox, and BRadioButton are examples of control devices.

• Other BViews visually organize the display—for example, a view that draws a border around and arranges other views, or one that splits a window into two or more resizable panels. The BBox, BScrollBar, and BScrollView classes fall into this category.

• Some BViews implement highly organized displays the user can manipulate, such as a game board or a scientific simulation.

• Perhaps the most important BViews are those that permit the user to create, organize, and edit data. These views display the current selection and are the focus of most user actions. They carry out the main work of an application. BTextView is the only Interface Kit example of such a view.

Almost all the BView classes defined in the Interface Kit fall into the first two of these groups. Control devices and organizational views can serve a variety of different kinds of applications, and therefore can be implemented in a kit that's common to all applications.

However, the BViews that will be central to most applications fall into the last two groups. Of particular importance are the BViews that manage editable data. Unfortunately, these are not views that can be easily implemented in a common kit. Just as most applications devise their own data formats, most applications will need to define their own data-handling views.

Nevertheless, the BView class structures and simplifies the task of developing application-specific objects that draw in windows and interact with the user. It takes care of the lower-level details and manages the view's relationship to the window and other views in the hierarchy. You should make yourself familiar with this class before implementing your own application-specific BViews.

Scripting Support

The BView class implements the two suites "suite/vnd.Be-view" and "suite/vnd.Be-container-view." "suite/vnd.Be-container-view" is only implemented if the view contains a shelf; the suite consists of the single property "Shelf."

The Frame Property

Message	Specifiers	Meaning
B_GET_PROPERTY	B_DIRECT_SPECIFIER	Returns the view's frame rectangle.
B_SET_PROPERTY	B_DIRECT_SPECIFIER	Sets the view's frame rectangle.

The "Frame" property represents the frame rectangle of the view. The frame is passed as a BRect (B_RECT_TYPE).

The Hidden Property

Message	Specifiers	Meaning
B_GET_PROPERTY	B_DIRECT_SPECIFIER	Returns true if the view is hidden; false otherwise.
B_SET_PROPERTY	B_DIRECT_SPECIFIER	Hides or shows the view.

The "Hidden" property determines the visibility of the view. The messages are equivalent to manipulating the view with the IsHidden(), Hide(), and Show(). Note that this differs slightly from BWindow's "Hidden" property, where multiple hides or shows are not nested.

The "Hidden" property determines the visibility of the view. The messages are equivalent to manipulating the view with the IsHidden(), Hide(), and Show() methods with one caveat: nested Hide() and Show() calls are disabled so that multiple scripting Hide commands may be undone with a single Show.

The Shelf Property

Message	Specifiers	Meaning
any	B_DIRECT_SPECIFIER	Directs the scripting message to the shelf.

The "Shelf" property pops the current specifier off the specifier stack and then passes the scripting message to the shelf. If no shelf is present, an error is returned.

The View Property

Message	Specifiers	Meaning
B_COUNT_PROPERTIES	B_DIRECT_SPECIFIER	Returns the number of of child views.
any	B_INDEX_SPECIFIER, B_REVERSE_INDEX_SPECIFIER, B_NAME_SPECIFIER	Directs the scripting message to the specified view.

The "View" property represents the child views of the current view. For all messages except B_COUNT_PROPERTIES, the current specifier is popped off the specifier stack before the scripting message is passed to the target view. Views can be specified either by index (as found by ChildAt()), or name (as found by FindView()).

The Archive() function adds the following fields to its BMessage argument:

Field	Type code	Meaning
"_frame"	B_RECT_TYPE	The view's frame rectangle.
"_resize_mode"	B_INT32_TYPE	Resizing mode.
"_flags"	B_INT32_TYPE	View flags.
"_fname" (array)	B_STRING_TYPE	Font family and style.
"_fflt" (array)	B_FLOAT_TYPE	Font size, shear, and rotation (-1 if default).
"_color" (array)	B_INT32_TYPE	High, low, and view colors.
"_evmask" (array)	B_INT32_TYPE	Event mask and options.
"_dbuf"	B_INT32_TYPE	Double buffering flag.
"_origin"	B_POINT_TYPE	Origin.
"_psize"	B_FLOAT_TYPE	Pen size.
"_ploc"	B_POINT_TYPE	Pen location.
"_lmcapjoin" (array)	B_INT16_TYPE	Line cap mode and join mode.
"_lmmiter"	B_FLOAT_TYPE	Line mode miter value.
"_blend" (array)	B_INT16_TYPE	Blending alpha and mode.
"_dmod"	B_INT32_TYPE	Drawing mode.
"_views"	B_MESSAGE_TYPE	Archived child views (deep copy only).

Some of these fields may not be present if the setting they represent isn't used, or is the default value. For example, if the font's family and style were not changed, the "_fname" field won't be found in the archive.