Derived from: BLooper > BHandler > BArchivable
Declared in: be/interface/Window.h
Library: libbe.so
A BWindow object represents a window that can be displayed on the screen. You can use BWindow objects off-the-shelf although you almost always create your own BWindow subclass(es). The BAlert, BWindowScreen, and BDirectWindow classes are the only Be-defined classes that inherit from BWindow.
The on-screen window that a BWindow represents is created and managed by the Application Server. When you construct your BWindow, the server creates (but doesn't yet display) the on-screen version. Most functions that you invoke on your BWindow object are turned into messages that are sent to the Application Server and immediately applied to the on-screen window. Whenever a message is sent to (or delivered from) the server, the BWindow must be locked. Most of the BWindow functions lock the object for you; those that don't are noted in the descriptions below.
Because of the Application Server's role in the BWindow world, you must construct your BApplication object (be_app) before you construct any BWindows. be_app needn't be running during BWindow construction. (Actually, you can display a BWindow without ever telling be_app to Run(); however, the BWindow won't receive any event messages.)
Typically, the first thing you do with your BWindow is add BViews to it. Each BWindow contains a hierarchy of views, as explained in <>. Again, be_app needn't be running at this point, nor must the window be showing.
As a BLooper object, every BWindow spawns a thread (the window thread) where it receives messages from the Application Server (and executes certain drawing functions, as explained later). However, unlike other BLoopers, you never tell a BWindow to Run(); instead, you tell it to Show(). The first Show() invocation spawns and runs the looper thread and displays the window on-screen. You can then Hide() and Show() the window as often as you like--only the first Show() invocation spawns a thread.
When you're done with your window, you call Quit() which stops the window thread, removes the window from the screen, and disposes of the BWindow object (and all the BViews it contains). You never use the delete operator to destroy your BWindow objects.
A BWindow object is a kind of BLooper; it spawns a window thread where it runs a message loop. You don't have to call Run() to get the message loop going, as you do for other BLoopers; it's called for you when you first call Show() to put the window on-screen.
The window's message loop receives messages reporting user actions associated with the window. The BWindow object handles some messages--such as FrameMoved() and QuitRequested()--itself, and passes "view-specific" messages--MouseDown(), KeyDown(), MouseMoved(), etc--to the responsible view.
The message loop continues running until the window is told to quit and the BWindow object is deleted. Everything the window thread does is initiated by a message of some kind.
When you're done with a window, you need to remove it from the screen, quit the message loop, kill the window thread, and delete the BWindow object. This process is initiated by a request to quit--a B_QUIT_REQUESTED message.
For a BWindow, a request to quit might be reported from the Application Server (as when the user clicks a window's close button) or from within the application (as when the user operates a Close menu item).
To respond to quit-requested messages, classes derived from BWindow implement QuitRequested() functions. QuitRequested() can prevent the window from closing, or take whatever action is appropriate before the window is destroyed.
QuitRequested() is a hook function declared in the BLooper class; it's not documented here. See the BLooper class in the Application Kit for information on the function and on how classes derived from BWindow might implement it.
FrameMoved()
Can be implemented to take note of the fact that the window has moved.
FrameResized()
Can be implemented to take note of the fact that the window has been resized.
MenusBeginning()
Can be implemented to make sure menu data structures are up-to-date before the menus are displayed to the user.
MenusEnded()
Can be implemented to take note that menus are no longer being displayed. The BWindow will receive a MenusBeginning() notification before they're displayed again.
Minimize()
Removes the window from the screen and replaces it with its minimized representation, or restores the window if it was previously minimized; can be reimplemented to provide a different representation for a minimized window.
ScreenChanged()
Makes sure the window stays visible on-screen when the size of the pixel grid changes; can be implemented to make other adjustments when the screen changes its depth or dimensions.
WindowActivated()
Can be implemented to take whatever action is necessary when the window becomes the active window, or when it loses that status.
WorkspaceActivated()
Can be implemented to take remedial steps when the workspace where the window lives becomes the active workspace, or when it loses that status.
WorkspacesChanged()
Can be implemented to respond when the set of workspaces where the window can be displayed changes.
Zoom()
Zooms the window to a larger size, or from the larger size to its previous state; can be reimplemented to modify the target window size or make other adjustments.
BWindow(BRect frame,
const char *title,
window_type type,
uint32 flags,
uint32 workspaces = B_CURRENT_WORKSPACE)
BWindow(BRect frame,
const char *title,
window_look look,
window_feel feel,
uint32 flags,
uint32 workspace = B_CURRENT_WORKSPACE)
BWindow(BMessage *archive)
Creates a new window:
| B_CURRENT_WORKSPACE | The window is displayed in the workspace that's currently displayed on-screen (the active workspace). This is the default. |
| B_ALL_WORKSPACES | The window is displayed in all workspaces (current and future) |
| B_BORDERED_WINDOW_LOOK | This is a minimal window, with a thin border and little else. |
| B_TITLED_WINDOW_LOOK | A normal window with a border and title bar. |
| B_DOCUMENT_WINDOW_LOOK | Like a titled window, only with a resize dragger in the corner. The dragger, drawn inside the content area of the window, is designed to look good next to vertical and horizontal scroll bars. |
| B_MODAL_WINDOW_LOOK | A window with a border but no title bar. |
| B_FLOATING_WINDOW_LOOK | A titled window with a thin border and small title bar. |
| B_NORMAL_WINDOW_FEEL | Behaves like a normal window (non-modal, non-floating). |
| B_MODAL_SUBSET_WINDOW_FEEL | When displayed, blocks all windows in its subset. Visible only if a window in its subset is visible. |
| B_MODAL_APP_WINDOW_FEEL | When displayed, blocks all windows in its team. |
| B_MODAL_ALL_WINDOW_FEEL | When displayed, blocks all windows on the screen. |
| B_FLOATING_SUBSET_WINDOW_FEEL | Floats above all windows in its subset. Visible only if a window in its subset is frontmost. |
| B_FLOATING_APP_WINDOW_FEEL | Floats above all windows in its team. |
| B_FLOATING_ALL_WINDOW_FEEL | Floats above all windows on the screen. |
B_MODAL_SUBSET_WINDOW_FEEL and B_FLOATING_SUBSET_WINDOW_FEEL specify window subsets, a set of windows for which it exhibits either modal or floating behavior. Subsets can be specified with the AddToSubset() and RemoveFromSubset() methods.
A set of common combinations of looks and feels are defined and may be passed as the type parameter to the constructor. It may be any of the following constants:
| B_UNTYPED_WINDOW | A window of unknown or undefined type. |
| B_MODAL_WINDOW | A modal window, one that disables other activity in the application until the user dismisses it. It has a border but no title tab. Equivalent to B_MODAL_WINDOW_LOOK and B_MODAL_APP_WINDOW_FEEL. |
| B_BORDERED_WINDOW | An ordinary (nonmodal) window with a border but no title tab. Equivalent to B_BORDERED_WINDOW_LOOK and B_NORMAL_WINDOW_FEEL. |
| B_TITLED_WINDOW | A window with both a border and a title tab. Equivalent to B_TITLED_WINDOW_LOOK and B_NORMAL_WINDOW_FEEL. |
| B_DOCUMENT_WINDOW | A window with a title tab, a border, and a resize dragger in the bottom right corner. Equivalent to B_DOCUMENT_WINDOW_LOOK and B_NORMAL_WINDOW_FEEL. |
| B_FLOATING_WINDOW | A window that floats above other windows owned by the same application. Equivalent to B_FLOATING_WINDOW_LOOK and B_FLOATING_APP_WINDOW_FEEL. |
The look and feel of a window may be modified with the SetLook() and SetFeel() methods, while the type can be modified with SetType().
:
| B_NOT_MOVABLE | Prevents the user from being able to move the window. By default, a window with a tab at the top is movable. |
| B_NOT_H_RESIZABLE | Prevents the user from resizing the window horizontally. A window is horizontally resizable by default. |
| B_NOT_V_RESIZABLE | Prevents the user from resizing the window vertically. A window is vertically resizable by default. |
| B_NOT_RESIZABLE | Prevents the user from resizing the window in any direction. This constant is a shorthand that you can substitute for the combination of B_NOT_H_RESIZABLE and B_NOT_V_RESIZABLE. A window is resizable by default. |
| B_NOT_CLOSABLE | Prevents the user from closing the window (eliminates the close button from its tab). Windows with title tabs have a close button by default. |
| B_NOT_ZOOMABLE | Prevents the user from zooming the window larger or smaller (eliminates the zoom button from the window tab). Windows with tabs are zoomable by default. |
| B_NOT_MINIMIZABLE | Prevents the user from collapsing the window to its minimized form. Windows can be minimized by default. |
| B_AVOID_FRONT | Prevents the window from activating when the window above it is closed. |
| B_AVOID_FOCUS | Instructs the window to always reject the focus. |
| B_WILL_ACCEPT_FIRST_CLICK | Enables the BWindow to receive mouse-down and mouse-up messages even when it isn't the active window. By default, a click in a window that isn't the active window brings the window to the front and makes it active, but doesn't get reported to the application. If a BWindow accepts the first click, the event gets reported to the application, but it doesn't make the window active. The BView that responds to the mouse-down message must take responsibility for activating the window. |
| B_OUTLINE_RESIZE | Resizes with an outline view rather than full updates. |
| B_NO_WORKSPACE_ACTIVATION | When a window is first shown, the workspace normally switches to the one in which the window is displayed. Setting this flag keeps this from happening. |
| B_NOT_ANCHORED_ON_ACTIVATE | If the window with this flag is in a workspace other than the current when it is activated by the Deskbar, it will move to the current workspace. Activating a window without this flag will cause the workspace to switch to the one containing the window. |
If flags is 0, the window will be one the user can move, resize, close, and zoom. It won't float or accept the first click. The flags can be later modified with SetFlags().
When created, the window is hidden and the BWindow object is locked; it must be locked when Show() is called for the first time. The window's message loop is created when Show() is called to put the window on-screen for the first time.
See also: AddToSubset(), RemoveFromSubset(), SetFeel(), SetFlags(), SetLook(), SetTitle(), SetType(), Show()
Don't use this operator; call the Quit() function to destroy the BWindow object
static BArchivable *Instantiate(BMessage *archive)
Returns a new BWindow object, allocated by new and created with the version of the constructor that takes a BMessage archive. However, if the archive message doesn't contain data for a BWindow object, the return value will be NULL.
See also: BArchivable::Instantiate(), instantiate_object(), Archive()
void Activate(bool flag = true)
bool IsActive(void) const
Activate() makes the BWindow the active window (if flag is true), or causes it to relinquish that status (if flag is false). When this function activates a window, it reorders the window to the front, highlights its tab, and makes it the window responsible for handling subsequent keyboard messages. When it deactivates a window, it undoes all these things. It reorders the window to the back and removes the highlighting from its tab. Another window (the new active window) becomes the target for keyboard messages. This function will not activate a window that's hidden.
When a BWindow is activated or deactivated (whether programmatically through this function or by the user), it and all the BViews in its view hierarchy receive WindowActivated() notifications.
IsActive() returns true if the window is currently the active window, and false if it's not.
See also: WindowActivated(), BView::WindowActivated()
void AddChild(BView *aView, BView *sibling = NULL)
bool RemoveChild(BView *aView)
AddChild() adds aView (and the view hierarchy it represents) to the root of this window's view hierarchy. All the view's in aView's hierarchy are added to the window's handler list; aView's next handler is set to this BWindow. Each view in aView's hierarchy is sent an AttachedToWindow() and an AllAttached() call.
If the sibling argument identifies another view that's already at the root of this window's hierarchy (in other words, if it identifies a potential sibling), aView is inserted before sibling in the list of root views. If sibling is NULL (the default), aView is added to the end of the list. List order affects the view's ChildAt() index only; it doesn't affect drawing order, which is always indeterminant among siblings.
If aView is already part of a view hierarchy, or if sibling isn't at the root of this window's hierarchy, AddChild() fails.
RemoveChild() removes aView from the window's list of root views, removes aView (and its children) from the window's handler list, sets aView's next handler to NULL, and sends a DetachedFromWindow() and an AllDetached() call to aView and each of its children. If aView isn't a root view (of this window), the function fails and returns false; it returns true upon success.
When a BView is removed from a window, all its descendant views are removed with it. BView::AddChild(), BLooper::AddHandler(), BView::AttachedToWindow(), BView::DetachedFromWindow(), BHandler::SetNextHandler()
void AddShortcut(uint32 key,
uint32 modifiers,
BMessage *message)
void AddShortcut(uint32 key,
uint32 modifiers,
BMessage *message,
BHandler *handler)
void RemoveShortcut(uint32 key, uint32 modifiers)
AddShortcut() creates a keyboard shortcut: When the user types Command+modifiers+key, message is sent to handler. If a shortcut already exists for modifiers+key, it's removed before the new shortcut is added. Don't use this functions to assign menu shortcuts; use the BMenuItem constructor instead.
RemoveShortcut() removes the shortcut for modifiers+key.
The arguments are:
| Field name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | The time of the key-down, in microseconds since 12:00:00 AM January 1, 1970. |
As with all Command events, a B_KEY_DOWN message isn't sent when the user invokes a keyboard shortcut, but the subsequent B_KEY_UP is.
Every BWindow has five built-in shortcuts:
| Shortcut | Message | Handler |
|---|---|---|
| Command+x | B_CUT | the focus view |
| Command+c | B_COPY | the focus view |
| Command+v | B_PASTE | the focus view |
| Command+a | B_SELECT_ALL | the focus view |
| Command+w
(closable windows only) |
B_QUIT_REQUESTED | the BWindow |
In addition, BWindows respond to Command+q by posting B_QUIT_REQUESTED to be_app.
status_t AddToSubset(BWindow *window)
status_t RemoveFromSubset(BWindow *window)
Adds windows to and removes them from this window's subset. This affects the behavior of windows with a feel of either B_MODAL_SUBSET_WINDOW_FEEL or B_FLOATING_SUBSET_WINDOW_FEEL. In the B_MODAL_SUBSET_WINDOW_FEEL case, the subset determines the set of windows which are blocked when this window is displayed. A window with a feel of B_FLOATING_SUBSET_WINDOW_FEEL floats above the windows in its subset (only).
See also: The BWindow constructor, Feel(), SetFeel(),
virtual status_t Archive(BMessage *archive, bool deep = true) const
Archives the BWindow by recording its frame rectangle, title, type, and flags in the BMessage archive. If the deep flag is true, this function also archives all the views in the window's view hierarchy. If the flag is false, only the BWindow is archived.
See also: BArchivable::Archive(), Instantiate() static function
BRect Bounds(void) const
BRect Frame(void) const
Both functions return the rectangle that encloses the window's content area. The bounds rectangle (Bounds()) is expressed in the window's coordinate system; the frame rectangle (Frame()) is expressed in the screen's coordinate system.
Both functions autolock and incur a trip to the Application Server.
BView *ChildAt(int32 index) const
int32 CountChildren(void) const
The first of these functions returns the child BView at index, or NULL if there's no such child of the BWindow's top view. Indices begin at 0 and there are no gaps in the list. The second function returns how many children the top view has.
See also: BView::Parent()
BPoint ConvertToScreen(BPoint windowPoint) const
void ConvertToScreen(BPoint *windowPoint) const
BRect ConvertToScreen(BRect windowRect) const
void ConvertToScreen(BRect *windowRect) const
BPoint ConvertFromScreen(BPoint screenPoint) const
void ConvertFromScreen(BPoint *screenPoint) const
BRect ConvertFromScreen(BRect screenRect) const
void ConvertFromScreen(BRect *screenRect) const
Converts the argument from window coordinates to screen coordinates (ConvertToScreen()), or from screen to window coordinates (ConvertFromScreen()). If the argument is passed by value, the function returns the converted value; if it's by pointer, the conversion is done in-place.
The BWindow must be locked.
See also: BView::ConvertToScreen()
BView *CurrentFocus(void) const
Returns the current focus view for the BWindow, or NULL if no view is currently in focus. The focus view is the BView that's responsible for showing the current selection and handling keyboard messages when the window is the active window.
The BWindow sets its preferred handler to be the focus view, so the inherited PreferredHandler() function will return the same object. CurrentFocus() returns the focus view as a BView object; PreferredHandler() returns it as a BHandler.
See also: BView::MakeFocus(), BInvoker::SetTarget(), BLooper::SetPreferredHandler()
void DisableUpdates(void)
void EnableUpdates(void)
These functions disable automatic updating within the window, and re-enable it again. Updating is enabled by default, so every user action that changes a view and every program action that invalidates a view's contents causes the view to be automatically redrawn.
This may be inefficient when there are a number of changes to a view, or to a group of views within a window. In this case, you can temporarily disable the updating mechanism by calling DisableUpdates(), make the changes, then call EnableUpdates() to re-enable updating and have all the changes displayed at once.
See also: BView::Invalidate(), UpdateIfNeeded()
virtual void DispatchMessage(BMessage *message, BHandler *handler)
Overrides the BLooper function to dispatch messages as they're received by the window thread. This function is called for you each time the BWindow takes a message from its queue. It dispatches the message by calling the virtual function that's designated to begin the application's response.
Derived classes can override this function to make it dispatch specific kinds of messages in other ways. For example:
void MyWindow::DispatchMessage(BMessage *message)
{
if ( message->what == MAKE_PREDICTIONS )
predictor->GuessAbout(message);
else
BWindow::DispatchMessage(message);
}
However, much of the user interface depends on how the BWindow processes system messages. For example, for keyboard shortcuts and keyboard navigation to work, the BWindow object needs to get its hands on B_KEY_DOWN messages. You shouldn't implement a version of DispatchMessage() that denies these messages to the BWindow version. (Nor should you filter these messages so they never reach DispatchMessage().)
The BWindow is locked before DispatchMessage() is called. The lock remains in place until the window thread's response to the message is complete and DispatchMessage() returns. When it returns, the message loop deletes the message. You should not delete it in application code (unless DetachCurrentMessage() is first called to detach it from the message loop).
See also: the BMessage class, the BMessageFilter class, BLooper::DispatchMessage(), BLooper::CurrentMessage()
BView *FindView(BPoint point) const
BView *FindView(const char *name) const
Returns the view located at point within the window, or the view tagged with name. The point is specified in the window's coordinate system (the coordinate system of its top view), which has the origin at the upper left corner of the window's content area.
If no view is located at the point given, or no view within the window has the name given, this function returns NULL.
See also: BView::FindView()
void Flush(void) const
void Sync(void) const
For reasons of efficiency, the window's connection to the Application Server is buffered. Instructions destined for the server are placed in the buffer and dispatched as a group when the buffer becomes full. These methods empty the buffer, sending whatever it contains to the server, even if it's not yet full.
Flush() simply flushes the buffer and returns. This function has the same effect as the Flush() function defined for the BView class.
Sync() flushes the connection, then waits until the server has executed the last instruction that was in the buffer before returning. This alternative to Flush() prevents the application from getting ahead of the server and keeps both processes synchronized.
See also: BView::Flush(), BView::Sync()
virtual void FrameMoved(BPoint screenPoint)
Implemented by derived classes to respond to a notification that the window has moved. The move--which placed the left top corner of the window's content area at screenPoint in the screen coordinate system--could be the result of the user dragging the window or of the program calling MoveBy() or MoveTo(). If the user drags the window, FrameMoved() is called repeatedly as the window moves. If the program moves the window, it's called just once to report the new location.
The default version of this function does nothing.
See also: MoveBy(), "B_WINDOW_MOVED" in the Message Protocols appendix
virtual void FrameResized(float width, float height)
Implemented by derived classes to respond to a notification that the window's content area has been resized to a new width and height. The resizing could be the result of the program calling ResizeTo(), ResizeBy(), or Zoom()--in which case FrameResized() is called just once to report the window's new size. It could also be the result of a user action--in which case it's called repeatedly as the user drags a corner of the window to resize it.
The default version of this function does nothing.
See also: ResizeBy(), "B_WINDOW_RESIZED" in the Message Protocols appendix
virtual status_t GetSupportedSuites(BMessage *message)
Adds the name "suite/vnd.Be-window" to the message. See "Scripting Support" in the class overview for more information.
See also: BHandler::GetSupportedSuites()
virtual void Hide(void)
virtual void Show(void)
bool IsHidden(void) const
These functions hide the window so it won't be visible on-screen, and show it again.
Hide() removes the window from the screen. If it happens to be the active window, Hide() also deactivates it. Hiding a window hides all the views attached to the window. While the window is hidden, its BViews respond true to IsHidden() queries.
Show() puts the window back on-screen. It places the window in front of other windows and makes it the active window. Since a window is hidden when it's constructed, you must call Show() to bring it to life. That first call unlocks the window, spawns the window thread, and begins the message loop.
Calls to Hide() and Show() (or ShowSync()) can be nested; if Hide() is called more than once, you'll need to call Show() or ShowSync() an equal number of times for the window to become visible again.
A window begins life hidden (as if Hide() had been called once); it takes an initial call to Show() or ShowSync() to display it on-screen.
IsHidden() returns true if the window is currently hidden, and false if it isn't.
bool IsFloating(void) const
Returns true if the window is a floating window, and false if it's not.
bool IsFront(void) const
Returns true if the window is currently the frontmost window on-screen, and false if it's not.
|
A floating window can never be the frontmost window, so if the window is a floating window, this function will always return false. |
bool IsModal(void) const
Returns true if the window is modal, and false if it's not.
BView *LastMouseMovedView(void)
Returns a pointer to the window's child view in which the mouse last moved.
virtual void MenusBeginning(void)
virtual void MenusEnded(void)
These functions are implemented by derived classes to make sure menus are up-to-date when shown on-screen. MenusBeginning() is called just before menus belonging to the window are about to be shown to the user. It gives the BWindow a chance to make any required alterations--for example, disabling or enabling particular items--so that the menus accurately reflect the current state of the window. MenusEnded() is called when menus have been put away; the system will call MenusBeginning() before they're displayed again.
See also: the BMenu and BMenuItem classes
virtual void MessageReceived(BMessage *message)
Augments the BHandler version of MessageReceived() to ensure that B_KEY_DOWN messages that find their way to the BWindow object (in the absence of a focus view, for example), are not lost and can contribute to keyboard navigation.
This function also handles scripting messages for the window.
See also: BHandler::MessageReceived()
virtual void Minimize(bool minimize)
Removes the window from the screen if the minimize flag is true--or restores the window to the screen if minimize is false.
This function can be called to minimize or unminimize the window. It's also called by the BWindow to respond to B_MINIMIZE messages, which are posted automatically when the user double-clicks the window tab to minimize the window.
See also: "B_MINIMIZE" in the Message Protocols appendix, Zoom()
void MoveBy(float horizontal, float vertical)
void MoveTo(BPoint point)
void MoveTo(float x, float y)
These functions move the window without resizing it. MoveBy() adds horizontal coordinate units to the left and right components of the window's frame rectangle and vertical units to the frame's top and bottom. If horizontal and vertical are negative, the window moves upward and to the left. If they're positive, it moves downward and to the right. MoveTo() moves the left top corner of the window's content area to point--or (x, y)--in the screen coordinate system; it adjusts all coordinates in the frame rectangle accordingly.
None of the values passed to these functions should specify fractional coordinates; a window must be aligned on screen pixels. Fractional values will be rounded to the closest whole number.
Neither function alters the BWindow's coordinate system or bounds rectangle.
When these functions move a window, a window-moved event is reported to the window. This results in the BWindow's FrameMoved() function being called.
See also: FrameMoved()
bool NeedsUpdate(void) const
Returns true if any of the views within the window need to be updated, and false if they're all up-to-date.
See also: UpdateIfNeeded()
virtual void Quit(void)
Quit() removes the window from the screen, deletes all the BViews in its view hierarchy, destroys the window thread, removes the window's connection to the Application Server, and deletes the BWindow object.
Use this function, rather than the delete operator, to destroy a window.
BWindow's Quit() works much like the BLooper function it overrides. When called from the BWindow's thread, it doesn't return. When called from another thread, it returns after all previously posted messages have been processed and the BWindow and its thread have been destroyed.
See also: BLooper::QuitRequested(), BLooper::Quit(), BApplication::QuitRequested()
void ResizeBy(float horizontal, float vertical)
void ResizeTo(float width, float height)
These functions resize the window, while keeping its left top corner constant. ResizeBy() adds horizontal pixels to the width of the window's frame and vertical pixels to its height. ResizeTo() sets the frame absolutely to [width, height] pixels. Fractional components are rounded to the nearest whole number.
The FrameResized() hook function is called after the frame has been resized.
virtual BHandler *ResolveSpecifier(BMessage *message, int32 index, BMessage *specifier, int32 command, const char *property)
Resolves specifiers for the "Frame", "Title", and "View" properties. See "Scripting Support" in the class overview for more information.
See also: BHandler::ResolveSpecifier()
virtual void ScreenChanged(BRect frame, color_space mode)
Hook function that's called when the screen (on which this window is located) changes size or location in the screen coordinate system, or changes color space (depth). frame is the screen's new frame rectangle, and mode is its new color space.
See also: BScreen::Frame()
status_t SendBehind(const BWindow *window)
Relayers the windows on the screen so this window is behind window.
void SetDefaultButton(BButton *button)
BButton *DefaultButton(void) const
Set and return the window's default button. This is the button that's mapped to the Enter key even if another BView is the focus view. To remove the current default (without promoting another button) call SetDefaultButton(NULL). There can only be one default button at a time; SetDefaultButton() demotes the previous default.
When you promote or demote a default button, it's automatically redisplayed and receives a BButton::MakeDefault() call.
The Enter key can operate the default button only while the window is the active window. However, the BButton doesn't have to be the focus view. Normally, the focus view is notified of key-down messages the window receives. But if the character reported is B_ENTER, the default button is notified instead (provided there is a default button).
status_t SetFeel(window_feel feel)
window_feel Feel(void) const
SetFeel() changes the window's feel to the specified value.
Feel() returns the current feel of the window.
The feel is set at construction (or by SetFeel()) as one of the following constants (full descriptions can be found in the discussion of the BWindow constructor):
| B_NORMAL_WINDOW_FEEL |
| B_MODAL_SUBSET_WINDOW_FEEL |
| B_MODAL_APP_WINDOW_FEEL |
| B_MODAL_ALL_WINDOW_FEEL |
| B_FLOATING_SUBSET_WINDOW_FEEL |
| B_FLOATING_APP_WINDOW_FEEL |
| B_FLOATING_ALL_WINDOW_FEEL |
See also: the BWindow constructor
status_t SetFlags(uint32 flags)
uint32 Flags(void) const
SetFlags() changes the window's flags to the specified values.
Flags() returns the current flags of the window.
The flags are set at construction (or by SetFlags()), and may be any combination of the following values (full descriptions can be found in the discussion of the BWindow constructor):
See also: the BWindow constructor
void SetKeyMenuBar(BMenuBar *menuBar)
BMenuBar *KeyMenuBar(void) const
SetKeyMenuBar() makes the specified BMenuBar object the "key" menu bar for the window--the object that's at the root of the menu hierarchy that users can navigate using the keyboard. KeyMenuBar() returns the object with key status, or NULL if the window doesn't have a BMenuBar object in its view hierarchy.
If a window contains only one BMenuBar view, it's automatically designated the key menu bar. If there's more than one BMenuBar in the window, the last one added to the window's view hierarchy is considered to be the key one.
If there's a "true" menu bar displayed along the top of the window, its menu hierarchy is the one that users should be able to navigate with the keyboard. SetKeyMenuBar() can be called to make sure that the BMenuBar object at the root of that hierarchy is the "key" menu bar.
See also: the BMenuBar class
status_t SetLook(window_look look)
window_look Look(void) const
SetLook() changes the window's look to the specified value.
Look() returns the current look of the window.
The look is set at construction (or by SetLook()) as one of the following constants (full descriptions can be found in the discussion of the BWindow constructor):
| B_BORDERED_WINDOW_LOOK |
| B_TITLED_WINDOW_LOOK |
| B_DOCUMENT_WINDOW_LOOK |
| B_MODAL_WINDOW_LOOK |
| B_FLOATING_WINDOW_LOOK |
See also: the BWindow constructor
void SetPulseRate(bigtime_t microseconds)
bigtime_t PulseRate(void)
These functions set and return how often Pulse() is called for the BWindow's views (how often B_PULSE messages are posted to the window). All BViews attached to the same window share the same pulse rate.
By turning on the B_PULSE_NEEDED flag, a BView can request periodic Pulse() notifications. By default, B_PULSE messages are posted every 500,000 microseconds, as long as no other messages are pending. Each message causes Pulse() to be called once for every BView that requested the notification. There are no pulses if no BViews request them.
SetPulseRate() permits you to set a different interval. The interval set should not be less than 100,000 microseconds; differences less than 50,000 microseconds may not be noticeable. A finer granularity can't be guaranteed.
Setting the pulse rate to 0 disables pulsing for all views in the window.
See also: BView::Pulse(), the BView constructor
void SetSizeLimits(float minWidth, float maxWidth,
float minHeight, float maxHeight)
void GetSizeLimits(float *minWidth, float *maxWidth,
float *minHeight, float *maxHeight)
void SetZoomLimits(float maxWidth, float maxHeight)
These functions set and report limits on the size of the window. The user won't be able to resize the window beyond the limits set by SetSizeLimits()--to make it have a width less than minWidth or greater than maxWidth, nor a height less than minHeight or greater than maxHeight. By default, the minimums are sufficiently small and the maximums sufficiently large to accommodate any window within reason.
SetSizeLimits() constrains the user, not the programmer. It's legal for an application to set a window size that falls outside the permitted range. The limits are imposed only when the user attempts to resize the window; at that time, the window will jump to a size that's within range.
GetSizeLimits() writes the current limits to the variables provided.
SetZoomLimits() sets the maximum size that the window will zoom to (when the Zoom() function is called). The maximums set by SetSizeLimits() also apply to zooming; the window will zoom to the screen size or to the smaller of the maximums set by these two functions.
Since the sides of a window must line up on screen pixels, the values passed to both SetSizeLimits() and SetZoomLimits() should be whole numbers.
See also: the BWindow constructor, Zoom()
void SetTitle(const char *newTitle)
const char *Title(void) const
These functions set and return the window's title. SetTitle() replaces the current title with newTitle. It also renames the window thread in the following format:
"w>newTitle"
where as many characters of the newTitle are included in the thread name as will fit.
Title() returns a pointer to the current title. The returned string is null-terminated. It belongs to the BWindow object, which may alter the string or free the memory where it resides without notice. Applications should ask for the title each time it's needed and make a copy for their own purposes.
A window's title and thread name are originally set by an argument passed to the BWindow constructor.
See also: the BWindow constructor
status_t SetType(window_type type)
window_type Type(void) const
SetType() changes the type of the window to the specified value.
Type() returns what type the window currently is.
The type is set at construction (or by SetType()) as one of the following constants (full descriptions can be found in the discussion of the BWindow constructor):
| B_UNTYPED_WINDOW |
| B_MODAL_WINDOW |
| B_BORDERED_WINDOW |
| B_TITLED_WINDOW |
| B_DOCUMENT_WINDOW |
| B_FLOATING_WINDOW |
See also: the BWindow constructor
status_t SetWindowAlignment(window_alignment mode, int32 h,
int32 hOffset = 0,
int32 width = 0,
int32 widthOffset = 0,
int32 v = 0,
int32 vOffset = 0,
int32 height = 0,
int32 heightOffset = 0)
status_t GetWindowAlignment(window_alignment *mode = NULL,
int32 *h = NULL,
int32 *hOffset = NULL,
int32 *width = NULL,
int32 *widthOffset = NULL,
int32 *v = NULL,
int32 *vOffset = NULL,
int32 *height = NULL,
int32 *heightOffset = NULL) const
SetWindowAlignment() sets the current alignment of the window content on the screen. mode is either B_PIXEL_ALIGNMENT or B_BYTE_ALIGNMENT.
If mode is B_PIXEL_ALIGNMENT, SetWindowAlignment() aligns the window in pixel coordinates. h and hOffset together determine the horizontal alignment: h gives the horizontal origin step while hOffset is the horizontal offset. hOffset must be between 1 and h (as a convenience, 0 is taken to mean 1). For example, if h is 4 and hOffset is 1, valid horizontal origins would be ..., -7, -3, 1, 5, 9, ... Similarly, width/widthOffset, v/vOffset, height/heightOffset give you control over the other window parameters.
If mode is B_BYTE_ALIGNMENT, then the alignment is given in terms of frame buffer offsets. However, the setting only affects the horizontal origin and width. You can't align the top and bottom edges in B_BYTE_ALIGNMENT mode.
GetWindowAlignment() returns the current window alignment.
Both methods return B_OK on success and B_ERROR otherwise.
void SetWorkspaces(uint32 workspaces)
uint32 Workspaces(void) const
These functions set and return the set of workspaces where the window can be displayed. The workspaces argument passed to SetWorkspaces() and the value returned by Workspaces() is a bitfield with one bit set for each workspace in which the window can appear. Usually a window appears in just one workspace.
SetWorkspaces() can associate a window with workspaces that don't exist yet. The window will appear in those workspaces if and when the user creates them.
You can pass B_CURRENT_WORKSPACE as the workspaces argument to place the window in the workspace that's currently displayed (the active workspace) and remove it from all others, or B_ALL_WORKSPACES to make sure the window shows up in all workspaces, including any new ones that the user might create. Workspaces() may return B_ALL_WORKSPACES, but will identify the current workspace rather than return B_CURRENT_WORKSPACE.
Changing a BWindow's set of workspaces causes it to be notified with a WorkspacesChanged() function call.
See also: the BWindow constructor, WorkspacesChanged()
void UpdateIfNeeded(void)
Causes the Draw() virtual function to be called immediately for each BView object that needs updating. If no views in the window's hierarchy need to be updated, this function does nothing.
|
That's not entirely true. If the UpdateIfNeeded() call is issued while processing a message (such as a keydown or pulse), sometimes things that need updating will be updated even if nothing has been invalidated. |
This is useful if a BView is engaged in a time-consuming response to the current message. UpdateIfNeeded() forces an immediate update, without waiting to return the BWindow's message loop. However, it works only if called from within the BWindow's thread.
(Because the message loop expedites the handling of update messages, they're never considered the current message and are never returned by BLooper's CurrentMessage() function.)
See also: BView::Draw(), BView::Invalidate(), NeedsUpdate()
virtual void WindowActivated(bool active)
Implemented by derived classes to make any changes necessary when the window becomes the active window, or when it ceases being the active window. If active is true, the window has just become the new active window, and if active is false, it's about to give up that status to another window.
The BWindow receives a WindowActivated() notification whenever its status as the active window changes. Each of its BViews is also notified.
See also: BView::WindowActivated()
virtual void WorkspaceActivated(int32 workspace, bool active)
Implemented by derived classes to respond to a notification that the workspace displayed on the screen has changed. All windows in the newly activated workspace as well as those in the one that was just deactivated get this notification.
The workspace argument is an index to the workspace in question and the active flag conveys its current status. If active is true, the workspace has just become the active workspace. If active is false, it has just stopped being the active workspace.
The default (BWindow) version of this function is empty.
See also: "B_WORKSPACE_ACTIVATED" in the Message Protocols appendix, activate_workspace()
virtual void WorkspacesChanged(uint32 oldWorkspaces, uint32 newWorkspaces)
Implemented by derived classes to respond to a notification the the window has just changed the set of workspaces in which it can be displayed from oldWorkspaces to newWorkspaces. This typically happens when the user moves a window from one workspace to another, but it may also happen when a programmatic change is made to the set of permitted workspaces. Each workspace is represented by a corresponding bit in the oldWorkspaces and newWorkspaces masks.
The default (BWindow) version of this function is empty.
See also: "B_WORKSPACES_CHANGED" in the Message Protocols appendix, SetWorkspaces()
void Zoom(void)
virtual void Zoom(BPoint leftTop, float width, float height)
Zooms the window to a larger size--or, if already zoomed larger, restores it to its previous size.
The simple version of this function can be called to simulate the user operating the zoom button in the window tab. It resizes the window to the full size of the screen, or to the size previously set by SetSizeLimits() and SetZoomLimits(). However, if the width and height of the window are both within five coordinate units of the fully zoomed size, it restores the window to the size it had before being zoomed.
To actually change the window's size, the simple version of Zoom() calls the virtual version. The virtual version is also called by the system in response to a B_ZOOM system message. The system generates this message when the user clicks the zoom button in the window's title tab.
The arguments to the virtual version propose a width and height for the window and a location for the left top corner of its content area in the screen coordinate system. It can be overridden to change these dimensions or to resize the window differently.
Zoom() may both move and resize the window, resulting in FrameMoved() and FrameResized() notifications.
See also: SetSizeLimits(), ResizeBy()
enum window_feel {
The BWindow class implements the suite called "suite/vnd.Be-window" consisting of the following messages:
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns the current feel of the window. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Sets the feel of the window. |
The "Feel" property represents the workspaces in which the window resides. The messages are equivalent to manipulating the window with the Feel() and SetFeel() methods.
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns the current flags of the window. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Sets the window flags. |
The "Flags" property represents the window flags. The messages are equivalent to manipulating the window with the Flags() and SetFlags() methods.
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns the window's frame rectangle. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Sets the window's frame rectangle. |
The "Frame" property represents the frame rectangle of the window. The frame is passed as a BRect (B_RECT_TYPE).
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns true if the window is hidden; false otherwise. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Hides or shows the window. |
The "Hidden" property determines the visibility of the window. The messages are equivalent to manipulating the window 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.
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns the current look of the window. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Sets the look of the window. |
The "Workspaces" property represents the workspaces in which the window resides. The messages are equivalent to manipulating the window with the Look() and SetLook() methods.
| Message | Specifiers | Meaning |
|---|---|---|
| any | B_DIRECT_SPECIFIER | Directs the scripting message to the key menu bar. |
The "MenuBar" property pops the current specifier off the specifier stack and then passes the scripting message to the key menu bar. If no such menu bar is present, then an error is returned.
| Message | Specifiers | Meaning |
|---|---|---|
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Minimizes the window if "data" is true; restores otherwise. |
The "Minimize" property controls the whether the window is minimized or not. The message is equivalent to manipulating the window with the Minimize() method.
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns a string containing the window title. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Sets the window title. |
The "Title" property represents the title of the window. The messages are equivalent to manipulating the window with the Title() and SetTitle() methods.
| Message | Specifiers | Meaning |
|---|---|---|
| any | any | Directs the scripting message to the top view without popping the current specifier. |
The "View" property simply redirects all requests to the window's top view without popping the specifier from the stack.
| Message | Specifiers | Meaning |
|---|---|---|
| B_GET_PROPERTY | B_DIRECT_SPECIFIER | Returns int32 bitfield of the workspaces in which the window appears. |
| B_SET_PROPERTY | B_DIRECT_SPECIFIER | Sets the workspaces in which the window appears. |
The "Workspaces" property represents the workspaces in which the window resides. The messages are equivalent to manipulating the window with the Workspaces() and SetWorkspaces() methods.
The Archive() function adds the following fields to its BMessage argument:
| Field | Type code | Meaning |
|---|---|---|
| "_frame" | B_RECT_TYPE | The frame rectangle. |
| "_title" | B_STRING_TYPE | The title of the BWindow. |
| "_wlook" | B_INT32_TYPE | The BWindow look. |
| "_wfeel" | B_INT32_TYPE | The BWindow feel. |
| "_type" | B_INT32_TYPE | The BWindow type (if one exists). |
| "_flags" | B_INT32_TYPE | The BWindow flags. |
| "_wspace" | B_INT32_TYPE | The workspaces in which the BWindow appears. |
| "_zoom" (array) | B_FLOAT_TYPE | The horizontal and vertical zoom limits, if any exist. |
| "_sizel" (array) | B_FLOAT_TYPE | The minimum horizontal and vertical and maximum horizontal and vertical size limits, if any exist. |
| "_pulse" | B_INT64_TYPE | The pulse rate, if not the default. |
In deep archives, the child views of the BWindow are additionally archived in the "_views" array of BMessages. See the description of the BView Archived Fields for more information on those fields.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified December 14, 1998.