Derived from: public BLooper
Declared in: <interface/Window.h>
The BWindow class defines an application interface to windows. Each BWindow object corresponds to one window in the user interface.
At the most basic level, 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--both in the Application Server and in the application. 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(BMessage *archive)
Produces a new window with the frame content area, assigns it a title and a 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 become 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():
BScreen screen(B_MAIN_SCREEN_ID); BRect r = screen.Frame();
Since a window is always aligned on screen pixels, the sides of its frame rectangle must have integral coordinate values. Any fractional coordinates that are passed in frame will be rounded to the nearest whole number.
The second argument, title, does two things: It sets the title the window will display if it has a tab, and it determines the name assigned to the window thread (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 type of window is set by one of the following constants:
| 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 tab to display a title. |
| B_BORDERED_WINDOW | An ordinary (nonmodal) window with a border but no title tab. |
| B_TITLED_WINDOW | A window with a tab that displays its title and a border that's the same on all sides. |
| B_DOCUMENT_WINDOW | A window with a title tab, a border, and a resize button in the bottom right corner. The border on the right and bottom sides is designed to look good next to vertical and horizontal scroll bars. The tab and border are drawn around the window's frame rectangle, but the resize button is located inside the content area of the window, in the corner where the scroll bars meet. It's drawn last and obscures whatever the application might draw in that corner. |
The fourth argument, flags, 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_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_WILL_FLOAT | Not implemented for the current release. |
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 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: Hide(), SetFlags(), SetTitle()
virtual ~BWindow(void)
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 <of its tier>, 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 <of its tier> 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 AddFloater(BWindow *floatingWindow)
void RemoveFloater(BWindow *floatingWindow)
These functions are not implemented for the current release.
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
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
Flushes the window's connection to the Application Server, sending whatever happens to be in the output buffer to the server. The buffer is automatically flushed on every update and after each message.
This function has the same effect as the Flush() function defined for the BView class.
See also: BView::Flush
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)
< Documentation on scripting and message suites will be available soon. >
virtual void Hide(void)
virtual void Show(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.
Calls to Hide() and Show() can be nested; if Hide() is called more than once, you'll need to call Show() 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() 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 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()
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)
< Documentation on scripting and specifiers will be available soon >
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
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()
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
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
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()
window_type WindowType(void) const
Returns what type of window it is. The type is set at construction as one of the following constants:
| B_MODAL_WINDOW
B_BORDERED_WINDOW B_TITLED_WINDOW B_DOCUMENT_WINDOW |
See also: the BWindow constructor
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 Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified June 28, 1997.