The Interface Kit: BView

The Interface Kit Table of Contents | The Interface Kit Index

# BView

Derived from: BHandler

Declared in: be/interface/View.h

Library: libbe.so

###### Summary

BView is a huge class. This document provides an introduction to BView, and provides scripting and archival information. For information about a specific member function, click on the function name below:

- Constructor and destructor: `BView()`, `~BView()

  `
- `AddLine()`, `AllAttached()`, `AllDetached()`, `AppendToPicture()`, `AttachedToWindow()

  `
- `BeginLineArray()`, `BeginPicture()`, `Bounds()

  `
- `ClearViewBitmap()`, `ClearViewOverlay()`, `ClipToPicture()`, `ClipToInversePicture()`, `ConstrainClippingRegion()`, `ConvertFromParent()`, `ConvertFromScreen()`, `ConvertToParent()`, `ConvertToScreen()`, `CopyBits()

  `
- `DetachedFromWindow()`, `Draw()`, `DrawAfterChildren()`, `DrawBitmap()`, `DrawBitmapAsync()`, `DrawChar()`, `DrawingMode()`, `DrawPicture()`, `DrawPictureAsync()`, `DrawString()

  `
- `EndLineArray()`, `EndPicture()

  `
- `FillArc()`, `FillBezier()`, `FillEllipse()`, `FillPolygon()`, `FillRect()`, `FillRegion()`, `FillRoundRect()`, `FillShape()`, `FillTriangle()`, `Flags()`, `Flush()`, `ForceFontAliasing()`, `Frame()`, `FrameMoved()`, `FrameResized()

  `
- `GetClippingRegion()`, `GetFont()`, `GetFontHeight()`, `GetPreferredSize()`, `GetStringWidths()

  `
- `Hide()`, `HighColor()

  `
- `Invalidate()`, `InvertRect()`, `IsFocus()`, `IsHidden()`, `IsPrinting()

  `
- `KeyDown()`, `KeyUp()

  `
- `LeftTop()`, `LineCapMode()`, `LineJoinMode()`, `LineMiterLimit()`, `LowColor()

  `
- `MouseDown()`, `MouseMoved()`, `MouseUp()`, `MovePenBy()`, `MovePenTo()`

- `Origin()

  `
- `PenLocation()`, `PenSize()`, `PopState()`, `Pulse()`, `PushState()

  `
- `ResizeBy()`, `ResizeTo()`, `ResizeToPreferred()`, `ResizingMode()

  `
- `SetDrawingMode()`, `SetFlags()`, `SetFont()`, `SetFontSize()`, `SetHighColor()`, `SetLowColor()`, `SetViewColor()`, `SetLineMode()`, `SetOrigin()`, `SetPenSize()`, `SetResizingMode()`, `SetScale()`, `SetViewBitmap()`, `SetViewCursor()`, `SetViewOverlay()`, `Show()`, `StringWidth()`, `StrokeArc()`, `StrokeBezier()`, `StrokeEllipse()`, `StrokePolygon()`, `StrokeRect()`, `StrokeRegion()`, `StrokeRoundRect()`, `StrokeTriangle()`, `Sync()

  `
- `TargetedByScrollView()`, `TruncateString()

  `
- `ViewColor()

  `
- `Window()`, `WindowActivated()

  `

  ## 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()`).

  ## Archived Fields

  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.

  The Interface Kit Table of Contents | The Interface Kit Index

  The Be Book,
  ...in lovely HTML...
  for BeOS Release 5.

  Copyright © 2000 Be, Inc. All rights reserved..