General BView Functions

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

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.