Derived from: public BLooper
Declared in: be/interface/Window.h
Library: libbe.so
The BWindow class defines an application interface to windows. Each BWindow object corresponds to a single window in the user interface.
It's the Application Server's responsibility to provide an application with the windows it needs. The server allocates the memory each window requires, renders images in the window on instructions from the application, and manages the user interface. It equips windows with all the accouterments that let users activate, move, resize, reorder, hide, and close them. These user actions are not mediated by the application; they're handled within the Application Server alone. However, the server sends the application messages notifying it of user actions that affect the window. A class derived from BWindow can implement virtual functions such as FrameResized(), QuitRequested(), and WindowActivated() to respond to these messages.
A BWindow object is the application's interface to a server window. Creating the object instructs the server to produce a window that can be displayed to the user. The BWindow constructor determines what kind of window it will be and how it will behave. The window is initially hidden; the Show() function makes it visible on-screen.
BWindow objects communicate directly with the Application Server. However, before this communication can take place, the constructor for the BApplication object must establish an initial connection to the server. You must construct the BApplication object before the first BWindow.
A window can display images, but it can't produce them. To draw within a window, an application needs a collection of various BView objects. For example, a window might have several check boxes or radio buttons, a list of names, some scroll bars, and a scrollable display of pictures or text--all provided by objects that inherit from the BView class.
These BViews are created by the application and are associated with the BWindow by arranging them in a hierarchy under a top view, a view that fills the entire content area of the window. Views are added to the hierarchy by making them children of views already in the hierarchy, which at the outset means children of the top view.
A BWindow doesn't reveal the identity of its top view, but it does have functions that act on the top view's behalf. For example, AddChild() adds a view to the hierarchy as a child of the top view; FindView() searches the view hierarchy beginning with the top view.
Every window runs in its own thread. 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. Typically, those actions are directed at something that's drawn within the content area of the window--so the object responsible for responding is usually one of the BViews in the window's view hierarchy. Views are notified of user actions through MouseDown(), KeyDown(), MouseMoved() and other virtual function calls. However, sometimes the responsible object is the BWindow itself. It handles FrameMoved(), QuitRequested(), WindowActivated() and other notifications.
Since all these functions are called from the window thread, that thread will execute the application's responses to user activity centering on the window. This, of course, includes operations spun off from the original message. For example, if the user clicks a button in a window and this initiates a series of calculations involving a variety of objects, those calculations will be executed in the thread of the window where the button is located (unless the calculation explicitly spawns other threads or sends messages to other BLoopers).
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.
To "close" a window is to remove the window from the screen, quit the message loop, kill the window thread, and delete the BWindow object. As is the case for other BLoopers, this process is initiated by a request to quit--a B_QUIT_REQUESTED message.
For a BWindow, a request to quit is an event that 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. It typically interacts with the user, asking, for example, whether recent changes to a document should be saved.
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)
Produces a new window with the frame content area, assigns it a title and a look and feel or type, sets its behavioral flags, and determines the workspaces where it can be displayed. However, the constructor does not spawn a new thread of execution for the window or begin running a message loop in that thread. The thread will be created and the loop begun when Show() is called to put the window on-screen for the first time.
The first argument, frame, determines where the window will be located on-screen and the size of its content area; it excludes the border and the title tab at the top. The window's top view will be exactly the same size and shape as its frame rectangle--though the top view is located in the window's coordinate system and the window's frame rectangle is specified in the screen coordinate system. The width and height of frame must both be greater than 0.0.
For the window to be visible on-screen, the frame rectangle you assign it must lie within the frame rectangle of the screen. You can get this information by constructing a BScreen object and asking for its Frame():
BRect r = BScreen(B_MAIN_SCREEN_ID).Frame();
Since a window is always aligned on screen pixels, the sides of its frame rectangle must have integral coordinate values. Any fractional coordinates passed in frame will be rounded to the nearest whole number.
The second argument, title, sets the title the window will display if it has a tab, and determines the name assigned to the window thread created when Show() is called. The thread name is a string that prefixes "w>" to the title in the following format:
"w>title"
If the title is long, only as many characters will be used as will fit within the limited length of a thread name. (Only the thread name is limited, not the window title.) The title (and thread name) can be changed with the SetTitle() function.
The title can be NULL or an empty string.
The appearance and behavior of the window can be defined in one of two ways: by an explicit look and feel or by a shorthand type. The look defines the appearance of the window while the feel governs its behavior.
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 as a normal window. |
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().
The flags argument is a mask that determines the behavior of the window. It's formed by combining constants from the following set:
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().
The final argument, workspaces, associates the window with a set of one or more workspaces. Each workspace is identified by a specific bit in a 32-bit integer; the workspaces mask can name up to 32 workspaces. The mask can include workspaces that don't yet exist. The window will live in those workspaces when and if the user creates them.
Two special values can be passed as the workspaces parameter:
B_CURRENT_WORKSPACE | Associates the window with the workspace that's currently displayed on-screen (the active workspace), whatever workspace that happens to be. This is the default choice. |
B_ALL_WORKSPACES | Associates the window with all workspaces. The window will show up in all workspaces the user has created and in all future workspaces that will be created. |
When created, the window is hidden and the BWindow object is locked; it must be locked when Show() is called for the first time.
See also: AddToSubset(), RemoveFromSubset(), SetFeel(), SetFlags(), SetLook(), SetTitle(), SetType(), Show()
virtual ~BWindow()
Frees all memory that the BWindow allocated for itself.
Call the Quit() function to destroy the BWindow object; don't use the delete operator. Quit() does everything that's necessary to shut down the window--such as remove its connection to the Application Server and get rid of its views--and invokes delete at the appropriate time.
See also: Quit()
static BWindow *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)
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.
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.
This function will not activate a window that's hidden.
See also: WindowActivated(), BView::WindowActivated()
void AddChild(BView *aView, BView *sibling = NULL) bool RemoveChild(BView *aView)
AddChild() adds aView to the hierarchy of views associated with the window, making it a child of the window's top view, and assigns the BWindow object as aView's next handler for unrecognized messages. The new child is inserted before the named sibling BView in the top view's list of children. If the sibling is NULL (as it is by default), aView is added to the end of the list.
However, AddChild() fails if sibling isn't a child of the top view. Moreover, if aView already has a parent, it won't be forcibly removed from that family and adopted into this one. A view can live with but one parent at a time.
If successful in adopting aView, AddChild() calls its AttachedToWindow() and AllAttached() functions to inform it that it now belongs to the BWindow. Every BView that descends from aView also becomes attached to the window and receives its own AttachedToWindow() and AllAttached() notifications. In addition, each newly attached BView is added to the BWindow's list of BHandler objects, making it eligible to receive messages the BWindow dispatches.
RemoveChild() removes aView from the BWindow's view hierarchy, but only if it was added to the hierarchy as a child of the window's top view (by calling the BWindow version of AddChild()). If it succeeds in removing aView, RemoveChild() returns true. If not, it returns false.
When a BView is removed from a window, all its descendant views are removed with it. Every removed BView receives a DetachedFromWindow() and an AllDetached() function call to notify it of the change and it's crossed off the BWindow's list of eligible message handlers.
See also: BView::AddChild(), BLooper::AddHandler(), BView::AttachedToWindow(), BView::DetachedFromWindow(), BHandler::SetNextHandler()
void AddShortcut(uint32 aChar, uint32 modifiers, BMessage *message) void AddShortcut(uint32 aChar, uint32 modifiers, BMessage *message, BHandler *handler) void RemoveShortcut(uint32 aChar, uint32 modifiers)
These functions set up, and tear down, keyboard shortcuts for the window. A shortcut is a character (aChar) that the user can type, in combination with the Command key and possibly one or more other modifiers to issue an instruction to the application. For example, Command-r might rotate what's displayed within a particular view. The instruction is issued by posting a message to the window thread.
Keyboard shortcuts are commonly associated with menu items. However, do not use these functions to set up shortcuts for menus; use the BMenuItem constructor instead. These BWindow functions are for shortcuts that aren't associated with a menu.
BWindows come with five built-in shortcuts:
Shortcut | Message | Target 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 | B_QUIT_REQUESTED | the BWindow |
(In addition, Command-q sends a B_QUIT_REQUESTED message to the BApplication object.)
AddShortcut() registers a new window-specific keyboard shortcut. The first two arguments, aChar and modifiers, specify the character and the modifier states that together will issue the instruction. modifiers is a mask that combines any of the usual modifier constants (see the modifiers() function for the full list). Typically, it's one or more of these four (or it's 0):
B_SHIFT_KEY |
B_CONTROL_KEY |
B_OPTION_KEY |
B_COMMAND_KEY |
B_COMMAND_KEY is assumed; it doesn't have to be specified. The character value that's passed as an argument should reflect the modifier keys that are required. For example, if the shortcut is Command-Shift-C, aChar should be 'C', not 'c'.
The instruction that the shortcut issues is embodied in a model message that the BWindow will copy and post to itself whenever it's notified of a key-down event matching the combination of aChar and modifiers (including B_COMMAND_KEY).
Before posting the message, it adds one data entry to the copy:
Data name | Type code | Description |
---|---|---|
"when" | B_INT64_TYPE | When the key-down event occurred, as measured by the number of microseconds from 12:00:00 AM January 1, 1970. |
The model message shouldn't contain an entry of the same name.
If a target handler is specified, the BWindow will dispatch the message to that BHandler object; the handler must be in the BWindow's list of eligible BHandlers. If the handler is NULL, the BWindow will dispatch the message to its preferred handler at the time, the view that's in focus when it gets the message (or to itself if no view is in focus). If a handler isn't specified at all, not even NULL, the BWindow will handle the message.
RemoveShortcut() unregisters a keyboard shortcut that was previously added.
See also: MessageReceived(), the BMenuItem constructor
status_t AddToSubset(BWindow *window) status_t RemoveFromSubset(BWindow *window)
Adds windows to or removes windows from the 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 the window is displayed. Windows with a feel of B_FLOATING_SUBSET_WINDOW_FEEL will float above only windows in its subset.
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
Returns the current bounds rectangle of the window. The bounds rectangle encloses the content area of the window and is stated in the window's coordinate system. It's exactly the same size as the frame rectangle, but its left and top sides are always 0.0.
See also: Frame()
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
These functions convert points and rectangles to and from the global screen coordinate system. ConvertToScreen() converts windowPoint or windowRect from the window coordinate system to the screen coordinate system. ConvertFromScreen() makes the opposite conversion; it converts screenPoint or screenRect from the screen coordinate system to the window 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 window coordinate system has its origin, (0.0, 0.0), at the left top corner of the window's content area. The origin of the screen coordinate system is at the left top corner of the main screen.
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()
BRect Frame(void) const
Asks the Application Server for the current frame rectangle for the window and returns it. The frame rectangle encloses the content area of the window and is stated in the screen coordinate system. It's first set by the BWindow constructor and is modified as the window is resized and moved.
See also: MoveBy(), ResizeBy(), the BWindow constructor
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) status_t ShowSync(void)
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.
ShowSync() does the same thing as Show(), but does it synchronously; the call doesn't return until the window is visible.
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.
See also: IsHidden()
bool IsActive(void) const
Returns true if the window is currently the active window, and false if it's not.
See also: Activate()
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.
bool IsHidden(void) const
Returns true if the window is currently hidden, and false if it isn't.
Windows are hidden at the outset. The Show() function puts them on-screen, and Hide() can be called to hide them again.
If Show() has been called to unhide the window, but the window is totally obscured by other windows or occupies coordinates that don't intersect with the physical screen, IsHidden() will nevertheless return false, even though the window isn't visible.
See also: Hide()
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 and replaces it with a token representation, if the minimize flag is true--or restores the window to the screen and removes the token, 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, and when the user double-clicks the token to restore the window. It can be reimplemented to provide a different minimal representation for the window.
The token representation is currently an item in the menu of windows associated with the application in the desk bar. The item remains in the menu as long as the BWindow exists, but its icon is dimmed when the window is minimized.
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) inline void Close(void)
Quit() gets rid of the window and all its views. This function 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, finally, deletes the BWindow object.
Use this function, rather than the delete operator, to destroy a window. Quit() applies the operator after it empties the BWindow of views and severs its connection to the application and server. It's dangerous to apply delete while these connections remain intact.
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 responded to and the BWindow and its thread have been destroyed.
Close() is a synonym of Quit(). It simply calls Quit() so if you override Quit(), you'll affect how both functions work.
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, without moving its left and top sides. ResizeBy() adds horizontal coordinate units to the width of the window and vertical units to its height. ResizeTo() makes the content area of the window width units wide and height units high. Both functions adjust the right and bottom components of the frame rectangle accordingly.
Since a BWindow's frame rectangle must line up with screen pixels, only integral values should be passed to these functions. Values with fractional components will be rounded to the nearest whole number.
When a window is resized, either programmatically by these functions or by the user, the BWindow's FrameResized() virtual function is called to notify it of the change.
See also: FrameResized()
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)
Implemented by derived classes to respond to a notification that the screen configuration has changed. This function is called for all affected windows when:
frame is the new frame rectangle of the screen, and mode is its new color space.
(Currently, there can be only one monitor per machine, so the screen can't change where it's located in the screen coordinate system.)
See also: BScreen::Frame(), "B_SCREEN_CHANGED" in the Message Protocols appendix
status_t SendBehind(const BWindow *window)
Adjusts the window so that it's behind the specified window. The window doesn't move, but simply shifts in depth.
void SetDefaultButton(BButton *button) BButton *DefaultButton(void) const
SetDefaultButton() makes button the default button for the window--the button that the user can operate by pressing the Enter key even if another BView is the focus view. DefaultButton() returns the button that currently has that status, or NULL if there is no default button.
At any given time, only one button in the window can be the default. SetDefaultButton() may, therefore, affect two buttons: the one that's forced to give up its status as the default button, and the one that acquires that status. Both buttons are redisplayed, so that the user can see which one is currently the default, and both are notified of their change in status through MakeDefault() virtual function calls.
If the argument passed to SetDefaultButton() is NULL, there will be no default button for the window. The current default button loses its status and is appropriately notified with a MakeDefault() function 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).
See also: BButton::MakeDefault()
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 right and bottom edges in B_BYTE_ALIGNMENT mode.
GetWindowAlignment() returns the current window alignment.
Both methods return B_NO_ERROR 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.
BView's Invalidate() function generates an update message that the BWindow receives just as it receives other messages. Although update messages take precedence over other kinds of messages the BWindow receives, the window thread can respond to only one message at a time. It will update the invalidated view as soon as possible, but it must finish responding to the current message before it can get the update message.
This may not be soon enough for a BView that's 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()
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 workspaces in which the window resides. 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 3.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified March 26, 1998.