The Interface Kit: BView General Functions

The Interface Kit Table of Contents | The Interface Kit Index

# BView General Functions

###### Summary

This section describes BView functionality which is of general use, or which does not fit neatly into any of the other BView document sections describing the BView functions.

## Constructor and Destructor

### BView()

`BView(` BRect frame, const char *name, uint32 resizingMode, uint32 flags`)`
`BView(` BMessage *archive`)`

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_RI GHT`
`B_FOLLOW_H_CENT ER`

with one for vertical resizing:

`B_FOLLOW_TOP`
`B_FOLLOW_BOTTOM`
`B_FOLLOW_TOP_BOTT OM`
`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_SI DES`
`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:

`B_WILL_DRAW
` Indicates that the BView does some drawing of its own and therefore can't be ignored when the window is updated. If this flag isn't set, the BView won't receive update notifications—its `Draw()` function won't be called—and it won't be erased to its background view color if the color is other than white.

`B_PULSE_NEEDED
` Indicates that the BView should receive `Pulse()` notifications.

`B_FRAME_EVENTS
` Indicates that the BView should receive `FrameResized()` and `FrameMoved()` notifications when its frame rectangle changes—typically as a result of the automatic resizing behavior described above. `FrameResized()` is called when the dimensions of the view change; `FrameMoved()` is called when the position of its left top corner in its parent's coordinate system changes.

`B_FULL_UPDATE_ON_RESIZE
` Indicates that the entire view should be updated when it's resized. If this flag isn't set, only the portions that resizing adds to the view will be included in the clipping region. This doesn't affect the view's children; their own flags determine when updates will occur.

`B_NAVIGABLE
` Indicates that the BView can become the focus view for keyboard actions. This flag makes it possible for the user to navigate to the view and put it in focus by pressing the Tab key. See "Keyboard Navigation" at the beginning of this chapter.

`B_NAVIGABLE_JUMP
` Marks the position of a group of views for keyboard navigation. By pressing Control-Tab, the user can jump from group to group. The focus lands on the first BView in the group that has the `B_NAVIGABLE` flag set. This may be the same BView that has the `B_NAVIGABLE_JUMP` marker, or the `B_NAVIGABLE_JUMP` BView may be the parent of a group of `B_NAVIGABLE` views.

`B_SUBPIXEL_PRECISE
` Instructs the rendering methods to use subpixel precision when drawing. If you don't set this flag, coordinates are rounded to the nearest unit.

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

See also: `SetResizingMode()`, `SetFlags()`, `BHandler::SetName()`

### ~BView()

virtual `~BView() `

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.

See also: `RemoveChild()`

## Static Functions

### Instantiate()

static BArchivable *`Instantiate(` BMessage *archive`)`

Returns a new BView object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the message doesn't contain archived data for a BView, `Instantiate()` returns `NULL`.

See also: `BArchivable::Instantiate()`, `instantiate_object()`

## Member Functions

### Bounds()

BRect `Bounds(`void`)` const

Returns the BView's bounds rectangle.

### ConvertToParent() , ConvertFromParent()

BPoint `ConvertToParent(` BPoint localPoint`)` const
void `ConvertToParent(` BPoint *localPoint`)` const
BRect `ConvertToParent(` BRect localRect`)` const
void `ConvertToParent(` BRect *localRect`)` const
BPoint `ConvertFromParent(` BPoint parentPoint`)` const
void `ConvertFromParent(` BPoint *parentPoint`)` const
BRect `ConvertFromParent(` BRect parentRect`)` const
void `ConvertFromParent(` BRect *parentRect`)` const

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() , ConvertFromScreen()

BPoint `ConvertToScreen(` BPoint localPoint`)` const
void `ConvertToScreen(` BPoint *localPoint`)` const
BRect `ConvertToScreen(` BRect localRect`)` const
void `ConvertToScreen(` BRect *localRect`)` const
BPoint `ConvertFromScreen(` BPoint screenPoint`)` const
void `ConvertFromScreen(` BPoint *screenPoint`)` const
BRect `ConvertFromScreen(` BRect screenRect`)` const
void `ConvertFromScreen(` BRect *screenRect`)` const

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

### Flags() see SetFlags()

### Frame()

BRect `Frame(`void`)` const

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.

### Hide() , Show()

virtual void `Hide(`void`) `
virtual void `Show(`void`) `

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

### IsFocus()

bool `IsFocus(`void`)` const

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()`, `MakeFocus()`

### IsHidden()

bool `IsHidden(`void`)` const

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.

See also: `Hide()`

### IsPrinting()

bool `IsPrinting(`void`)` const

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

| You should avoid calling this function from outside `Draw()` and `DrawChildren()`; 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, `Draw()` , `DrawChildren()`

### LeftTop()

BPoint `LeftTop(`void`)` const

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

### Origin() see SetOrigin()

### ResizeBy() , ResizeTo()

void `ResizeBy(`float horizontal, float vertical`) `
void `ResizeTo(`float width, float height`) `

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.

| 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()`, `BRect::Width()`, `Frame()`

### ResizingMode() see SetResizingMode()

### SetFlags() , Flags()

virtual void `SetFlags(`uint32 mask`) `
uint32 `Flags(`void`)` const

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

### SetOrigin() , Origin()

void `SetOrigin(` BPoint pt`) `
void `SetOrigin(`float x, float y`) `
BPoint `Origin(`void`)` const

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).

### SetResizingMode() , ResizingMode()

virtual void `SetResizingMode(`uint32 mode`) `
uint32 `ResizingMode(`void`)` const

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: the BView constructor, `SetFlags()`

### SetViewCursor()

void `SetViewCursor(`const BCursor *cursor, bool sync=true`)` const

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.

### Show() see Hide()

### Sync() see Flush()

### Window()

BWindow *`Window(`void`)` const

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

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..