Sets up a view with the frame rectangle, which is specified in the coordinate system of its eventual parent, and assigns the BView an identifying name, which can be NULL.

When it's created, a BView doesn't belong to a window and has no parent. It's assigned a parent by having another BView adopt it with the AddChild() function. If the other view is in a window, the BView becomes part of that window's view hierarchy. A BView can be made a child of the window's top view by calling BWindow's version of the AddChild() function.

When the BView gains a parent, the values in frame are interpreted in the parent's coordinate system. The sides of the view must be aligned on screen pixels. Therefore, the frame rectangle should not contain coordinates with fractional values. Fractional coordinates will be rounded to the first lower whole number (for example 1.2 will be rounded down to 1.0).

The resizingMode mask determines the behavior of the view when its parent is resized. It should combine one constant for horizontal resizing,

• B_FOLLOW_LEFT

• B_FOLLOW_RIGHT

• B_FOLLOW_LEFT_RIGHT

• B_FOLLOW_H_CENTER

with one for vertical resizing:

• B_FOLLOW_TOP

• B_FOLLOW_BOTTOM

• B_FOLLOW_TOP_BOTTOM

• B_FOLLOW_V_CENTER

For example, if B_FOLLOW_LEFT is chosen, the margin between the left side of the view and the left side of its parent will remain constant—the view will "follow" the parent's left side. Similarly, if B_FOLLOW_RIGHT is chosen, the view will follow the parent's right side. If B_FOLLOW_H_CENTER is chosen, the view will maintain a constant relationship to the horizontal center of the parent.

If the constants name opposite sides of the view rectangle—left and right, or top and bottom—the view will necessarily be resized in that dimension when the parent is. For example, B_FOLLOW_LEFT_RIGHT means that the margin between the left side of the view and left side of the parent will remain constant, as will the margin between the right side of the view and the right side of the parent. As the parent is resized horizontally, the child will be resized with it. Note that B_FOLLOW_LEFT_RIGHT is not the same as combining B_FOLLOW_LEFT and B_FOLLOW_RIGHT, an illegal move. The resizingMode mask can contain only one horizontal constant and one vertical constant.

If a side is not mentioned in the mask, the distance between that side of the view and the corresponding side of the parent is free to fluctuate. This may mean that the view will move within its parent's coordinate system when the parent is resized. B_FOLLOW_RIGHT plus B_FOLLOW_BOTTOM, for example, would keep a view from being resized, but the view will move to follow the right bottom corner of its parent whenever the parent is resized. B_FOLLOW_LEFT plus B_FOLLOW_TOP prevents a view from being resized and from being moved.

In addition to the constants listed above, there are two other possibilities:

• B_FOLLOW_ALL_SIDES

• B_FOLLOW_NONE

B_FOLLOW_ALL_SIDES is a shorthand for B_FOLLOW_LEFT_RIGHT and B_FOLLOW_TOP_BOTTOM. It means that the view will be resized in tandem with its parent, both horizontally and vertically.

B_FOLLOW_NONE behaves just like B_FOLLOW_LEFT | B_FOLLOW_TOP; the view maintains the same position in its parent's coordinate system, but not in the screen coordinate system.

Typically, a parent view is resized because the user resizes the window it's in. When the window is resized, the top view is too. Depending on how the resizingMode flag is set for the top view's children and for the descendants of its children, automatic resizing can cascade down the view hierarchy. A view can also be resized programmatically by the ResizeTo() and ResizeBy() functions.

The resizing mode can be changed after construction with the SetResizingMode() function.

The flags mask determines what kinds of notifications the BView will receive. It can be any combination of the following constants:

If none of these constants apply, flags can be NULL. The flags can be reset after construction with the SetFlags() function.

See also: BHandler::SetName()

Frees all memory the BView allocated, and ensures that each of the BView's descendants in the view hierarchy is also destroyed.

It's an error to delete a BView while it remains attached to a window. Call RemoveChild() or RemoveSelf() before using the delete operator.

Implemented by derived classes to complete the initialization of the BView when it's assigned to a window. A BView is assigned to a window when it, or one of its ancestors in the view hierarchy, becomes a child of a view already attached to a window.

AttachedToWindow() is called immediately after the BView is formally made a part of the window's view hierarchy and after it has become known to the Application Server and its graphics parameters are set. The Window() function can identify which BWindow the BView belongs to.

All of the BView's children, if it has any, also become attached to the window and receive their own AttachedToWindow() notifications. Parents receive the notification before their children, but only after all views have become attached to the window and recognized as part of the window's view hierarchy. This function can therefore depend on all ancestor and descendant views being in place.

For example, AttachedToWindow() can be implemented to set a view's background color to the same color as its parent, something that can't be done before the view belongs to a window and knows who its parent is.

void MyView::AttachedToWindow()
{
   if ( Parent() )
      SetViewColor(Parent()->ViewColor());
   baseClass::AttachedToWindow();
}

The AllAttached() notification follows on the heels of AttachedToWindow(), but works its way up the view hierarchy rather than down. When AllAttached() is called for a BView, all its descendants have received both AttachedToWindow() and AllAttached() notifications. Therefore, parent views can depend on any calculations that their children make in either function. For example, a parent can resize itself to fit the size of its children, where their sizes depend on calculations done in AttachedToWindow().

The default (BView) version of both these functions are empty.

See also: AddChild()

Implemented by derived classes to make any adjustments necessary when the BView is about to be removed from a window's view hierarchy. These two functions parallel the more commonly implemented AttachedToWindow() and AllAttached() functions.

DetachedFromWindow() notifications work their way down the hierarchy of views being detached, followed by AllDetached() notifications, which work their way up the hierarchy. The second function call permits an ancestor view to take actions that depend on calculations a descendant might have to make when it's first notified of being detached.

The BView is still attached to the window when both functions are called.

Implemented by derived classes to draw the updateRect portion of the view. The update rectangle is stated in the BView's coordinate system.

Draw() is called as the result of update messages whenever the view needs to present itself on-screen. This may happen when:

• The window the view is in is first shown on-screen, or shown after being hidden (see the BWindow version of the Hide() function).

• The view is made visible after being hidden (see BView's Hide() function).

• Obscured parts of the view are revealed, as when a window is moved from in front of the view or an image is dragged across it.

• The view is resized.

• The contents of the view are scrolled (see ScrollBy()).

• A child view is added, removed, or resized.

• A rectangle has been invalidated that includes at least some of the view (see Invalidate()).

• CopyBits() can't completely fill a destination rectangle within the view.

Draw() is also called from a BPrintJob object's DrawView() function to draw the view on a printed page. IsPrinting() returns true when the BView is drawing for the printer and false when it's drawing to the screen. When printing, you may want to recalculate layouts, substitute fonts, turn antialiasing off, scale the size of a coordinate unit, or make other adjustments to ensure the quality of the printed image.

When drawing to the screen, the updateRect is the smallest rectangle that encloses the current clipping region for the view. Since the Application Server won't render anything on-screen that's outside the clipping region, an application will be more efficient if it avoids producing drawing instructions for images that don't intersect with the rectangle. For still more efficiency and precision, you can ask for the clipping region itself (by calling GetClippingRegion()) and confine drawing to images that intersect with it.

When printing, the updateRect matches the rectangle passed to DrawView() and may lie outside the clipping region. The clipping region is not enforced for printing, but the Print Server clips the BView's drawing to the specified rectangle.

See also: BWindow::UpdateIfNeeded()

This function is similar (in fact, almost identical) to Draw(). The only difference is that DrawAfterChildren() is called after all children have drawn during a screen update. This is in contrast to Draw(), which draws before any children have drawn. In general, Draw() will be used for almost all of your drawing needs; DrawAfterChildren() is intended for use in the rare circumstances where you wish a view to be able to draw on top of its child views.

Other details are as for Draw().

Implemented by derived classes to respond to a notification that the view has moved within its parent's coordinate system. newLocation gives the new location, within the coordinate system of the view's window, of the left top corner of the BView's frame rectangle.

FrameMoved() is called only if the B_FRAME_EVENTS flag is set and the BView is attached to a window.

If the view is both moved and resized, FrameMoved() is called before FrameResized(). This might happen, for example, if the BView's automatic resizing mode is a combination of B_FOLLOW_TOP_BOTTOM and B_FOLLOW_RIGHT and its parent is resized both horizontally and vertically.

BView's version of this function is empty.

Currently, FrameMoved() is also called when a hidden window is shown on-screen.

See also: MoveBy(), BWindow::FrameMoved(), SetFlags()

Implemented by derived classes to respond to a notification that the view has been resized. The arguments state the new width and height of the view. The resizing could have been the result of a user action (resizing the window) or of a programmatic one (calling ResizeTo() or ResizeBy()).

FrameResized() is called only if the B_FRAME_EVENTS flag is set and the BView is attached to a window.

BView's version of this function is empty.

See also: BWindow::FrameResized(), SetFlags()

GetPreferredSize() is implemented by derived classes to write the preferred width and height of the view into the variables the width and height arguments refer to. Derived classes generally make this calculation based on the view's contents. For example, a BButton object reports the optimal size for displaying the button border and label given the current font.

ResizeToPreferred() resizes the BView's frame rectangle to the preferred size, keeping its left and top sides constant.

See also: ResizeTo()

Implemented by derived classes to respond to a B_KEY_DOWN message reporting keyboard input. Whenever a BView is the focus view of the active window, it receives a KeyDown() notification for each character the user types, except for those that:

• Are produced while a Command key is held down. Command key events are interpreted as keyboard shortcuts.

• Are produced by the Tab key when an Option key is held down. Option+Tab events are invariably interpreted as instructions to change the focus view (for keyboard navigation); they work even where Tab alone does not.

• Can operate the default button in a window. The BButton object's KeyDown() function is called, rather than the focus view's.

The first argument, bytes, is an array that encodes the character mapped to the key the user pressed. The second argument, numBytes, tells how many bytes are in the array; there will always be at least one. The bytes value follows the character encoding of the BView's font. Typically, the encoding is Unicode UTF-8 (B_UNICODE_UTF8), so there may be more than one byte per character. The bytes array is not null-terminated; '0' is a valid character value.

The character value takes into account any modifier keys that were held down or keyboard locks that were on at the time of the keystroke. For example, Shift+i is reported as uppercase 'I' (0x49) and Control+i is reported as a B_TAB (0x09).

Single-byte characters can be tested against ASCII codes and these constants:

• B_BACKSPACE

• B_ENTER

• B_RETURN

• B_SPACE

• B_TAB

• B_ESCAPE

• B_LEFT_ARROW

• B_RIGHT_ARROW

• B_UP_ARROW

• B_DOWN_ARROW

• B_INSERT

• B_DELETE

• B_HOME

• B_END

• B_PAGE_UP

• B_PAGE_DOWN

• B_FUNCTION_KEY

B_ENTER and B_RETURN are the same character, a newline ('\n').

Only keys that generate characters produce key-down events; the modifier keys on their own do not.

You can determine which modifier keys were being held down at the time of the event by calling BLooper's CurrentMessage() function and looking up the "modifiers" entry in the BMessage it returns. If the bytes character is B_FUNCTION_KEY and you want to know which key produced the character, you can look up the "key" entry in the BMessage and test it against these constants:

• B_F1_KEY

• B_F1_KEY

• B_F2_KEY

• B_F3_KEY

• B_F4_KEY

• B_F5_KEY

• B_F6_KEY

• B_F7_KEY

• B_F8_KEY

• B_F9_KEY

• B_F10_KEY

• B_F11_KEY

• B_F12_KEY

• B_PRINT_KEY (Print Screen)

• B_SCROLL_KEY (Scroll Lock)

• B_PAUSE_KEY

For example:

if ( bytes[0] == B_FUNCTION_KEY ) {
   BMessage *msg = Window()->CurrentMessage();
   if ( msg ) {
      int32 key;
      msg->FindInt32("key", &key);
      switch ( key ) {
      case B_F1_KEY:
         . . .
         break;
      case B_F2_KEY:
         . . .
         break;
      . . .
      }
   }
}

The BView version of KeyDown() handles keyboard navigation from view to view through B_TAB characters. If the view you define is navigable, its KeyDown() function should permit B_SPACE characters to operate the object and perhaps allow the arrow keys to navigate inside the view. It should also call the inherited version of KeyDown() to enable between-view navigation. For example:

void MyView::KeyDown(const char *bytes, int32 numBytes)
{
   if ( numBytes == 1 ) {
      switch ( bytes[0] ) {
      case B_SPACE:
         /* mimic a click in the view*/
         break;
      case B_RIGHT_ARROW:
         /* move one position to the right in the view*/
         break;
      case B_LEFT_ARROW:
         /* move one position to the left in the view*/
         break;
      default:
         baseClass::KeyDown(bytes, numBytes);
         break;
      }
   }
}

If your BView is navigable but needs to respond to B_TAB characters—for example, if it permits users to insert tabs in a text string—its KeyDown() function should simply grab the characters and not pass them to the inherited function. Users will have to rely on the Option+Tab combination to navigate from your view.

See also: the Keyboard Information special topic, B_KEY_DOWN in the Keyboard Messages appendix, BWindow::SetDefaultButton(), modifiers()

Implemented by derived classes to respond to a B_KEY_UP message reporting that the user released a key on the keyboard. The same set of keys that produce B_KEY_DOWN messages when they're pressed produce B_KEY_UP messages when they're released. The bytes and numBytes arguments encode the character mapped to the key the user released; they work exactly like the same arguments passed to KeyDown().

Some B_KEY_DOWN messages are swallowed by the system and are never dispatched by calling KeyDown(); others are dispatched, but not to the focus view. In contrast, all B_KEY_UP messages are dispatched by calling KeyUp() for the focus view of the active window. Since the focus view and active window can change between the time a key is pressed and the time it's released, this may or may not be the same BView that was notified of the B_KEY_DOWN message.

Augments the BHandler version of MessageReceived() to handle scripting messages for the BView.

MouseDown() is a hook function that's invoked when the user depresses a mouse button (or other pointing device button, not including joysticks). The location of the cursor at the time of the event is given by point in the BView's coordinates. See B_MOUSE_DOWN for the message format. Also see SetMouseEventMask() for information on extending the view's event mask while the mouse is being held down.

The BView version of MouseDown() is empty.

Implemented by derived classes to respond to reports of mouse-moved events associated with the view. As the user moves the cursor over a window, the Application Server generates a continuous stream of messages reporting where the cursor is located.

The first argument, point, gives the cursor's new location in the BView's coordinate system. The second argument, transit, is one of four constants,

• B_ENTERED_VIEW

• B_INSIDE_VIEW

• B_EXITED_VIEW

• B_OUTSIDE_VIEW

which explains whether the cursor has just entered the visible region of the view, is now inside the visible region having previously entered, has just exited from the view, or is currently outside the visible region of the view. When the cursor passes from one view to another, MouseMoved() is called on each of the BViews, once with a transit code of B_EXITED_VIEW and the other with a code of B_ENTERED_VIEW.

If the user is dragging a bundle of information from one location to another, the final argument, message, is a pointer to the BMessage object that holds the information. If a message isn't being dragged, message is NULL.

The default version of MouseMoved() is empty.

Implemented by derived classes to respond to a message reporting a mouse-up event within the view. The location of the cursor at the time of the event is given by point in the BView's coordinates.

Implemented by derived classes to do something at regular intervals. Pulses are regularly timed events, like the tick of a clock or the beat of a steady pulse. A BView receives Pulse() notifications when no other messages are pending, but only if it asks for them with the B_PULSE_NEEDED flag.

The interval between Pulse() calls can be set with BWindow's SetPulseRate() function. The default interval is around 500 milliseconds. The pulse rate is the same for all views within a window, but can vary between windows.

Derived classes can implement a Pulse() function to do something that must be repeated continuously. However, for time-critical actions, you should implement your own timing mechanism.

The BView version of this function is empty.

See also: SetFlags() the BView constructor,

Implemented by derived classes to respond to a notification that the BView has become the target of the scroller BScrollView object. This function is called when the BScrollView sets its target, which it does on construction. The target is the object whose contents will be scrolled.

BView's implementation of this function is empty.

See also: The various scrolling-related functions in BView Input Related Functions.

Implemented by derived classes to take whatever steps are necessary when the BView's window becomes the active window, or when the window gives up that status. If active is true, the window has become active. If active is false, it no longer is the active window.

All objects in the view hierarchy receive WindowActivated() notifications when the status of the window changes.

BView's version of this function is empty.

See also: BWindow::WindowActivated()

Archives the BView in the BMessage archive.

See also: BArchivable::Archive(), Instantiate() static function

Returns the BView's bounds rectangle.

These functions convert points and rectangles to and from the coordinate system of the BView's parent. ConvertToParent() converts localPoint or localRect from the BView's coordinate system to the coordinate system of its parent BView. ConvertFromParent() does the opposite; it converts parentPoint or parentRect from the coordinate system of the BView's parent to the BView's own coordinate system.

If the point or rectangle is passed by value, the function returns the converted value. If a pointer is passed, the conversion is done in place.

Both functions fail if the BView isn't attached to a window.

See also: ConvertToScreen()

ConvertToScreen() converts localPoint or localRect from the BView's coordinate system to the global screen coordinate system. ConvertFromScreen() makes the opposite conversion; it converts screenPoint or screenRect from the screen coordinate system to the BView's local coordinate system.

If the point or rectangle is passed by value, the function returns the converted value. If a pointer is passed, the conversion is done in place.

The screen coordinate system has its origin, (0.0, 0.0), at the left top corner of the main screen.

Neither function will work if the BView isn't attached to a window.

See also: BWindow::ConvertToScreen(), ConvertToParent()

Returns the BView's frame rectangle. The frame rectangle is first set by the BView constructor and is altered only when the view is moved or resized. It's stated in the coordinate system of the BView's parent.

These functions hide a view and show it again.

Hide() makes the view invisible without removing it from the view hierarchy. The visible region of the view will be empty and the BView won't receive update messages. If the BView has children, they also are hidden.

Show() unhides a view that had been hidden. This function doesn't guarantee that the view will be visible to the user; it merely undoes the effects of Hide(). If the view didn't have any visible area before being hidden, it won't have any after being shown again (given the same conditions).

Calls to Hide() and Show() can be nested. For a hidden view to become visible again, the number of Hide() calls must be matched by an equal number of Show() calls.

However, Show() can only undo a previous Hide() call on the same view. If the view became hidden when Hide() was called to hide the window it's in or to hide one of its ancestors in the view hierarchy, calling Show() on the view will have no effect. For a view to come out of hiding, its window and all its ancestor views must be unhidden.

Hide() and Show() can affect a view before it's attached to a window. The view will reflect its proper state (hidden or not) when it becomes attached. Views are created in an unhidden state.

See also: BWindow::Hide(), IsHidden()

Returns true if the BView is the current focus view for its window, and false if it's not. The focus view changes as the user chooses one view to work in and then another—for example, as the user moves from one text field to another when filling out an on-screen form. The change is made programmatically through the MakeFocus() function.

See also: BWindow::CurrentFocus()

Returns true if the view has been hidden by the Hide() function, and false otherwise.

This function returns true whether Hide() was called to hide the BView itself, to hide an ancestor view, or to hide the BView's window. When a window is hidden, all its views are hidden with it. When a BView is hidden, all its descendants are hidden with it.

If the view has no visible region—perhaps because it lies outside its parent's frame rectangle or is obscured by a window in front—this function may nevertheless return false. It reports only whether the Hide() function has been called to hide the view, hide one of the view's ancestors in the view hierarchy, or hide the window where the view is located.

If the BView isn't attached to a window, IsHidden() returns the state that it will assume when it becomes attached. By default, views are not hidden.

Returns true if the BView is being asked to draw for the printer, and false if the drawing it produces will be rendered on-screen (or if the BView isn't being asked to draw at all).

This function's result is only reliable when called from within Draw() or DrawAfterChildren() to determine whether the drawing it does is destined for the printer or the screen. When drawing to the printer, the BView may choose different parameters—such as fonts, bitmap images, or colors—than when drawing to the screen.

Note

You should avoid calling this function from outside Draw() and DrawAfterChildren(); however, if you absolutely have to do it, lock the view first. Failure to do so may bring up the debugger—if not in BeOS 5, it may in future versions of BeOS.

See also: the BPrintJob class

Returns the coordinates of the left top corner of the view—the smallest x and y coordinate values within the bounds rectangle.

See also: BRect::LeftTop(), Bounds()

These functions move the view in its parent's coordinate system without altering its size.

MoveBy() adds horizontal coordinate units to the left and right components of the frame rectangle and vertical units to the top and bottom components. If horizontal and vertical are positive, the view moves downward and to the right. If they're negative, it moves upward and to the left.

MoveTo() moves the upper left corner of the view to point or to (x, y) in the parent view's coordinate system and adjusts all coordinates in the frame rectangle accordingly.

Neither function alters the BView's bounds rectangle or coordinate system.

None of the values passed to these functions should specify fractional coordinates; the sides of a view must line up on screen pixels. Fractional values will be rounded to the closest whole number.

If the BView is attached to a window, these functions cause its parent view to be updated, so the BView is immediately displayed in its new location. If it doesn't have a parent or isn't attached to a window, these functions merely alter its frame rectangle.

See also: FrameMoved(), ResizeBy(), Frame()

These functions resize the view, without moving its left and top sides. ResizeBy() adds horizontal coordinate units to the width of the view and vertical units to the height. ResizeTo() makes the view width units wide and height units high. Both functions adjust the right and bottom components of the frame rectangle accordingly.

Since a BView's frame rectangle must be aligned on screen pixels, only integral values should be passed to these functions. Values with fractional components will be rounded to the nearest whole integer.

If the BView is attached to a window, these functions cause its parent view to be updated, so the BView is immediately displayed in its new size. If it doesn't have a parent or isn't attached to a window, these functions merely alter its frame and bounds rectangles.

Note

If the view isn't attached to a window, its frame and bounds rectangles are adjusted, but its children, if any, don't get corresponding adjustments.

See also: FrameResized(), MoveBy(), Frame(), BRect::Width()

These functions set and return the flags that inform the Application Server about the kinds of notifications the BView should receive. The mask set by SetFlags() and the return value of Flags() is formed from combinations of the following constants:

• B_WILL_DRAW

• B_FULL_UPDATE_ON_RESIZE

• B_FRAME_EVENTS

• B_PULSE_NEEDED

• B_NAVIGABLE

• B_NAVIGABLE_JUMP

• B_SUBPIXEL_PRECISE

The flags are first set when the BView is constructed; they're explained in the description of the BView constructor. The mask can be 0.

To set just one of the flags, combine it with the current setting:

myView->SetFlags(Flags() | B_FRAME_EVENTS);

See also: The BView constructor, SetResizingMode()

Sets and retrieves the local origin of the BView's coordinate system.

The actual origin used by the Application Server is the sum of the local origin (as set by this method) and the origins stored on the state stack (properly scaled).

These functions set and return the BView's automatic resizing mode. The resizing mode is first set when the BView is constructed. The various possible modes are explained where the constructor is described.

See also: SetFlags()

Sets the specified cursor as the view's cursor; while the mouse is inside the view, this cursor will be displayed (unless of course the cursor is hidden or obscured).

If sync is true, the Application Server will be synchronized by this call, forcing the change to take place immediately. If sync is false, the change will take place when the Application Server naturally gets to the change in its queue of pending requests.

Returns the BWindow to which the BView belongs, or NULL if the BView isn't attached to a window. This function returns the same object that Looper() (inherited from the BHandler class) does—except that Window() returns it more specifically as a pointer to a BWindow and Looper() returns it more generally as a pointer to a BLooper.

See also: BHandler::Looper() in the Application Kit, AddChild(), BWindow::AddChild(), AttachedToWindow()

AddChild() makes aView a child of the BView, provided that aView doesn't already have a parent. The new child is added to the BView's list of children immediately before the named sibling BView. If the sibling is NULL (as it is by default), aView isn't added in front of any other view—in other words, it's added to the end of the list. If the BView is attached to a window, aView and all its descendants become attached to the same window. Each of them is notified of this change through AttachedToWindow() and AllAttached() function calls.

AddChild() fails if aView already belongs to a view hierarchy. A view can live with only one parent at a time. It also fails if sibling is not already a child of the BView.

RemoveChild() severs the link between the BView and aView, so that aView is no longer a child of the BView; aView retains all its own children and descendants, but they become an isolated fragment of a view hierarchy, unattached to a window. Each removed view is notified of this change through DetachedFromWindow() and AllDetached() function calls.

A BView must be removed from a window before it can be destroyed.

If it succeeds in removing aView, RemoveChild() returns true. If it fails, it returns false. It will fail if aView is not, in fact, a current child of the BView.

When a BView object becomes attached to a BWindow, two other connections are automatically established for it:

• The view is added to the BWindow's flat list of BHandler objects, making it an eligible target for messages the BWindow dispatches.

• The BView's parent view becomes its next handler. Messages that the BView doesn't recognize will be passed to its parent.

Removing a BView from a window's view hierarchy also removes it from the BWindow's flat list of BHandler objects; the BView will no longer be eligible to handle messages dispatched by the BWindow.

See also: BWindow::AddChild(), BLooper::AddHandler(), BHandler::SetNextHandler(), RemoveSelf(), AttachedToWindow(), DetachedFromWindow()

Returns the BView identified by name, or NULL if the view can't be found. Names are assigned by the BView constructor and can be modified by the SetName() function inherited from BHandler.

FindView() begins the search by checking whether the BView's name matches name. If not, it continues to search down the view hierarchy, among the BView's children and more distant descendants. To search the entire view hierarchy, use the BWindow version of this function.

These functions provide various ways of navigating the view hierarchy. Parent() returns the BView's parent view, unless the parent is the top view of the window, in which case it returns NULL. It also returns NULL if the BView doesn't belong to a view hierarchy and has no parent.

All the children of the same parent are arranged in a linked list. NextSibling() returns the next sibling of the BView in the list, or NULL if the BView is the last child of its parent. PreviousSibling() returns the previous sibling of the BView, or NULL if the BView is the first child of its parent.

ChildAt() returns the view at index in the list of the BView's children, or NULL if the BView has no such child. Indices begin at 0 and there are no gaps in the list. CountChildren() returns the number of children the BView has. If the BView has no children, CountChildren() returns NULL, as will ChildAt() for all indices, including 0.

To scan the list of a BView's children, you can increment the index passed to ChildAt() until it returns NULL. However, it's more efficient to ask for the first child and then use NextSibling() to walk down the sibling list. For example:

BView *child;
if ( child = myView->ChildAt(0) ) {
   while ( child ) {
      . . .
      child = child->NextSibling();
   }
}

Removes the BView from its parent and returns true, or returns false if the BView doesn't have a parent or for some reason can't be removed from the view hierarchy.

This function acts just like RemoveChild(), except that it removes the BView itself rather than one of its children.

See also: AddChild()

These functions instruct the Application Server to display a rectangular outline that will track the movement of the cursor. BeginRectTracking() puts the rectangle on-screen and initiates tracking; EndRectTracking() terminates tracking and removes the rectangle. The initial rectangle, rect, is specified in the BView's coordinate system.

This function supports two kinds of tracking, depending on the constant passed as the how argument:

Tracking is typically initiated from within a BView's MouseDown() function and is terminated in MouseUp()

Initiates a drag-and-drop session.

message, is a BMessage object that bundles the information that will be dragged and dropped on the destination view. The caller retains responsibility for this object and can delete it after DragMessage() returns (the BView makes a copy of the message).

image, is a bitmap that the user can drag. The bitmap is automatically freed when the message is dropped.

Note

1 bit-per-pixel bitmaps aren't supported; you should avoid using them.

point locates the hotspot within image (in the bitmap's coordinate system). This is the point that's aligned with the location passed to MouseDown() or returned by GetMouse().

rect defines the dimensions of an outline rectangle that you can instead of a bitmap. The rectangle is stated in the BView's coordinate system.

replyTarget, names the object that you want to handle a message that might be sent in reply to the dragged message. If replyTarget is NULL, as it is by default, any reply that's received will be directed to the BView object that initiated the drag-and-drop session.

dragMode defines the drawing_mode which will be used to draw image as the image is dragged around. This is provided primarily so that transparent or partially transparent images can be dragged around (using the B_OP_ALPHA drawing mode).

This function works only for BView objects that are attached to a window.

Provides the location of the cursor and the state of the mouse buttons. The position of the cursor is recorded in the variable referred to by cursor; it's provided in the BView's own coordinates. A bit is set in the variable referred to by buttons for each mouse button that's down. This mask may be 0 (if no buttons are down) or it may contain one or more of the following constants:

• B_PRIMARY_MOUSE_BUTTON

• B_SECONDARY_MOUSE_BUTTON

• B_TERTIARY_MOUSE_BUTTON

The cursor doesn't have to be located within the view for this function to work; it can be anywhere on-screen. However, the BView must be attached to a window.

If the checkQueue flag is set to false, GetMouse() provides information about the current state of the mouse buttons and the current location of the cursor.

If checkQueue is true, as it is by default, this function first looks in the message queue for any pending reports of mouse-moved or mouse-up events. If it finds any, it takes the one that has been in the queue the longest (the oldest message), removes it from the queue, and reports the cursor location and button states that were recorded in the message. Each GetMouse() call removes another message from the queue. If the queue doesn't hold any B_MOUSE_MOVED or B_MOUSE_UP messages, GetMouse() reports the current state of the mouse and cursor, just as if checkQueue were false.

If checkQueue is true, and the view's parent window has pending update events, GetMouse() causes those update events to be processed.

You shouldn't use this function to track the mouse; implement the MouseMoved() function instead.

See also: modifiers()

Makes the BView the current focus view for its window (if the focused flag is true), or causes it to give up that status (if focused is false). The focus view is the view that displays the current selection and is expected to handle reports of key-down events when the window is the active window. There can be no more than one focus view per window at a time.

When called to make a BView the focus view, this function invokes MakeFocus() for the previous focus view, passing it an argument of false. It's thus called twice—once for the new and once for the old focus view.

Calling MakeFocus() is the only way to make a view the focus view; the focus doesn't automatically change on mouse-down events. BViews that can display the current selection (including an insertion point) or that can accept pasted data should call MakeFocus()in their MouseDown() functions.

A derived class can override MakeFocus() to add code that takes note of the change in status. For example, a BView that displays selectable data may want to highlight the current selection when it becomes the focus view, and remove the highlighting when it's no longer the focus view. A BView that participates in the keyboard navigation system should visually indicate that it can be operated from the keyboard when it becomes the focus view, and remove that indication when the user navigates to another view and it's notified that it's no longer the focus view.

If the BView isn't attached to a window, this function has no effect.

See also: BWindow::CurrentFocus(), IsFocus()

Returns a BScrollBar object that scrolls the BView (that has the BView as its target). The requested scroll bar has the posture orientation—B_VERTICAL or B_HORIZONTAL. If the BView isn't the target of a scroll bar with the specified orientation, this function returns NULL.

See also: BScrollBar::SetTarget()

These functions scroll the contents of the view, provided that the BView is attached to a window.

ScrollBy() adds horizontal to the left and right components of the BView's bounds rectangle, and vertical to the top and bottom components. This serves to shift the display horizontal coordinate units to the left and vertical units upward. If horizontal and vertical are negative, the display shifts in the opposite direction.

ScrollTo() shifts the contents of the view as much as necessary to put point—or (x, y)—at the upper left corner of its bounds rectangle. The point is specified in the BView's coordinate system.

Anything in the view that was visible before scrolling and also visible afterwards is automatically redisplayed at its new location. The remainder of the view is invalidated, so the BView's Draw() function will be called to fill in those parts of the display that were previously invisible. The update rectangle passed to Draw() will be the smallest possible rectangle that encloses just these new areas. If the view is scrolled in only one direction, the update rectangle will be exactly the area that needs to be drawn.

If the BView is the target of scroll bars, ScrollBy() and ScrollTo() notify the BScrollBar objects of the change in the display so they can update themselves to match. If the contents were scrolled horizontally, they call the horizontal BScrollBar's SetValue() function and pass it the new value of the left side of the bounds rectangle. If they were scrolled vertically, they call SetValue() for the vertical BScrollBar and pass it the new value of the top of the bounds rectangle.

The inline version of ScrollTo() works by creating a BPoint object and passing it to the version that's declared virtual. Therefore, if you want to override either function, you should override the virtual version. (However, due to the peculiarities of C++, overriding any version of an overloaded function hides all versions of the function. For continued access to the nonvirtual version without explicitly specifying the "BView::" prefix, simply copy the inline code from interface/View.h into the derived class.)