|
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.
|
| The Interface Kit Table of Contents | The Interface Kit Index |
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.
|
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()
|
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()
|
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()
|
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(), MakeFocus()
|
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()
|
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.
|
See also: the BPrintJob class, Draw() , DrawChildren()
|
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 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.
|
See also: FrameResized(), MoveBy(), BRect::Width(), Frame()
|
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: the BView constructor, 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()
| The Interface Kit Table of Contents | The Interface Kit Index |
Copyright © 2000 Be, Inc. All rights reserved..