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.
BWindow objects are the application's interface to the Server's windows:
BWindow objects communicate directly with the 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, BWindow's AddChild() function adds a view to the hierarchy as a child of the top view. Its FindView() function searches the view hierarchy beginning with the top view.
Each window runs in its own thread--both in the Application Server and in the application. When it's constructed, a BWindow object spawns a window thread for the application and begins running a message loop where it receives reports of user actions associated with the window. You don't have to call Run() to get the message loop going, as you do for other BLoopers; Run() is called for you at construction time.
Actions initiated from a BWindow's message loop are executed in the window's thread. This, of course, includes all actions that are 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 posts messages to other BLoopers).
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 clicks 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. |
| MenusWillShow() | Can be implemented to make sure menu data structures are up-to-date before the menus are displayed to the user. |
| 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. |
| SavePanelClosed() | Can be implemented to take note when the window's save panel closes. |
| SaveRequested() | Can be implemented to save the document displayed in the window when the user requests it in the save panel. |
| 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, ulong flags,
ulong workspaces = B_CURRENT_WORKSPACE)
Produces a new window with the frame content area, spawns a new thread of execution for the window, and begins running a message loop in that thread.
The first argument, frame, measures only the content area of the window; 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.
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 find the current dimensions of the screen by calling get_screen_info() . In addition, both the width and height of frame must be greater than 0.
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 of the window thread. 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 narrow border that's the same on all sides. |
| B_DOCUMENT_WINDOW | A window with a title tab and a border. The border on the right and bottom sides is a thin line that's designed to look good with vertical and horizontal scroll bars. |
The tab and border are drawn around the window's frame rectangle.
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 | Causes the window to float in front of other windows. |
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 long integer; the workspaces mask can name up to 32 workspaces. The mask can even name 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. |
The window's message loop reads messages delivered to the window and dispatches them by calling a virtual function of the responsible object. The responsible object is usually one of the BViews in the window's view hierarchy. Views are notified of system messages 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.
The message loop begins to run when the BWindow is constructed and continues 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.
See also: 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()
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 events. 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 events.
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()
virtual void AddChild(BView *aView)
Adds aView to the hierarchy of views associated with the window, making it a child of the window's top view. However, 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.
This function calls aView's AttachedToWindow() function to inform it that it now belongs to the BWindow. Every view that descends from aView also becomes attached to the window and receives its own AttachedToWindow() notification.
When a BView is attached to a window, it also is added to the BWindow's list of BHandler objects, making it eligible to receive messages the BWindow dispatches. In addition, this function assigns the BWindow as aView's next handler.
See also: BView::AddChild() , BView::AttachedToWindow() , RemoveChild(), BHandler::SetNextHandler()
void AddShortcut(ulong aChar, ulong modifiers, BMessage *message)
void AddShortcut(ulong aChar, ulong modifiers, BMessage *message,
BHandler *target)
void RemoveShortcut(ulong aChar, ulong 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 BMessage 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.
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 whenever it's notified of a key-down event matching the aChar and modifiers combination (including B_COMMAND_KEY).
Before posting the message, it adds one data entry to the copy:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_DOUBLE_TYPE | When the key-down event occurred, as measured in microseconds from the time the machine was last booted. |
The model message shouldn't contain an entry of the same name.
The message is posted to the BWindow. If a target BHandler object is specified, it will be designated to respond to the message. If a target isn't specified, the current focus view will be designated to handle it. If there is no focus view, the BWindow will act as the handler.
The message is dispatched by calling the handler's MessageReceived() function. If you add a keyboard shortcut to a window, you must implement a MessageReceived() function that can respond to the message the shortcut generates.
(Note, however, that if the message has B_QUIT_REQUESTED or the constant for another interface message as its what data member, the target will be ignored and it will be dispatched by calling a specific function, like QuitRequested(), not MessageReceived() .)
RemoveShortcut() unregisters a keyboard shortcut that was previously added.
See also: MessageReceived() , FilterKeyDown(), the BMenuItem constructor
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(long index) const
long CountChildren(void) const
These 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 the number of 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
virtual BHandler *PreferredHandler(void) const
Both these functions return the current focus view for the BWindow, or NULL if no view is currently in focus. CurrentFocus() returns the object as a BView, and PreferredHandler() overrides the BLooper function to return it as a BHandler.
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.
Various other objects in the Interface Kit, such as BButtons and BMenuItems, call PreferredHandler() to discover where they should target messages posted to the BWindow when a specific target hasn't been designated. This mechanism permits these objects to name the current focus view. Thus, a menu item or a control device can be set up to always act on whatever BView happens to be displaying the current selection.
See also: BView::MakeFocus(), BControl::SetTarget(), BMenuItem::SetTarget(), BLooper::PreferredHandler()
void DisableUpdates(void)
void EnableUpdates(void)
These function 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.
Whenever it's called, DispatchMessage() locks the BWindow. The lock remains in place until the window thread's response to the message is complete.
Derived classes can override this function to make it dispatch specific kinds of messages in other ways. For example:
void MyWindow::DispatchMessage(BMessage *message)
{
Lock();
if ( message->what == MAKE_PREDICTIONS )
predictor->GuessAbout(message);
else
BWindow::DispatchMessage(message);
Unlock();
}
The message loop deletes every message it receives when the function that DispatchMessage() calls, and DispatchMessage() itself, return. The message should not be deleted in application code (unless DetachCurrentMessage() is first called to detach it from the message loop).
See also: the BMessage 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 out-going 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 --or 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 void HandlersRequested(BMessage *message)
Responds to a request for information identifying the BHandlers associated with the BWindow. This function sends a B_HANDLERS_INFO reply to the B_HANDLERS_REQUESTED message it's passed as an argument. The reply has an entry named "handlers" with BMessenger objects corresponding to the requested BHandlers, or one named "error" with an error code.
If the B_HANDLERS_REQUESTED message has an entry called "class" and that entry contains the string "BView", this function interprets the request as one that concerns the BView objects that are the children of its top view. It limits its search for BHandlers accordingly. Otherwise, the scope of the request is not limited and encompasses all BHandlers that have been added to the window, including all BViews (except the top view).
If the message asks for a particular BView with an entry named "index", the BWindow puts a BMessenger in the reply message for the child BView (or the associated BHandler) at the requested index. If not, and if the message asks for a particular BView with an entry labeled "name" and the string in the entry matches the name of one of the top view's children (or one of the window's BHandlers), it puts a BMessenger for that object in the reply message.
However, if the message doesn't specify a particular object, it supplies BMessengers for all the top view's children (or all the BWindow's BHandlers).
If this function can't supply BMessengers for the specified BHandlers, it doesn't add any BMessengers to the B_HANDLERS_INFO message, but places an appropriate error code--B_BAD_INDEX , B_NAME_NOT_FOUND, or B_ERROR--in the message under the name "error".
You can override this function to respond to different protocols for requesting handlers, or to prevent the BWindow's BViews (and BHandlers) from being revealed.
See also: BView::HandlersRequested(), BApplication::HandlersRequested()
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.
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 MenusWillShow(void)
Implemented by derived classes to make sure menus are up-to-date before they're placed on-screen. This function 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 are in synch with the current state of the window.
See also: the BMenu and BMenuItem classes
virtual bool 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.
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.
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()
virtual bool RemoveChild(BView *aView)
Removes aView from the BWindow's view hierarchy, but only if aView was added to the hierarchy as a child of the window's top view (by calling BWindow's version of the AddChild() function).
If aView is successfully removed, RemoveChild() returns TRUE. If not, it returns FALSE.
See also: AddChild()
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()
long RunSavePanel(const char *tentativeName = NULL,
const char *windowTitle = NULL,
const char *saveButtonLabel = NULL,
const char *cancelButtonLabel = NULL,
BMessage *message = NULL)
void CloseSavePanel(void)
bool IsSavePanelRunning(void)
RunSavePanel() requests the Browser to display a panel where the user can choose how to save the document displayed in the window. The panel permits the user to navigate the file system and type in file and directory names.
The arguments to this function are all optional. They're used to configure the panel:
WishMaker : Save "UNTITLED-3" As...
If a tentativeName isn't passed, the quotes will be empty.
If the message has one or both of the following entries, they will be used to help configure the panel:
| Data name | Type code | Description |
|---|---|---|
| "directory" | B_REF_TYPE | The record_ref for the directory that the panel should display when it first comes on-screen. If this entry is absent, the panel will initially display the current directory of the current volume. |
| "frame" | B_RECT_TYPE | A BRect that sets the size and position of the panel in screen coordinates. If this entry is absent, the Browser will choose an appropriate frame rectangle for the panel. |
When the user finishes choosing where to save the file and operates the "Save" (or saveButtonLabel) button, the file panel sends a message to the BWindow (through the BApplication object). If a customized message is provided, it's used as the model for the message that's sent. If a message isn't provided, a standard B_SAVE_REQUESTED message is sent instead. In either case, it has two data entries:
| Data name | Type code | Description |
|---|---|---|
| "name" | B_STRING_TYPE | The name of the file in which the document should be saved. |
| "directory" | B_REF_TYPE | A record_ref reference to the directory where the file should reside. |
A B_SAVE_REQUESTED message is dispatched by calling the SaveRequested() hook function; the "name" and "directory" are passed as arguments to SaveRequested(). This function should be implemented to create the file, if necessary, and save the document. RunSavePanel() doesn't do this work; it simply delivers a BMessage object with the information you need to do the job.
A customized message works much like the model messages assigned to BControl objects and BMenuItems. The save panel makes a copy of the model, adds the "name" and "directory" entries (as described above) to the copy, and delivers the copy to the BWindow. Other entries in the message remain unchanged.
The message can have any command constant you choose. If it's B_SAVE_REQUESTED , the "name" and "directory" will be extracted from the message and passed to SaveRequested(). Otherwise, nothing is extracted and the message is dispatched by calling MessageReceived().
The save panel disappears when the user operates the "Save" (or saveButtonLabel) button--provided that the message has B_SAVE_REQUESTED as the command constant. If it has a customized constant, it remains open until CloseSavePanel() is called (or until the application quits). You can choose to leave the panel on-screen if the user hasn't chosen a valid file name. IsSavePanelRunning() will report whether the save panel is currently displayed on-screen. A BWindow can run only one save panel at a time.
The save panel is automatically closed when user operates the "Cancel" (or cancelButtonLabel) button. Whenever it's closed, by the user or the application, a B_PANEL_CLOSED message is sent to the application and the SavePanelClosed() hook function is called.
RunSavePanel() returns B_NO_ERROR if it succeeds in getting the Browser to put the panel on-screen. If the Browser isn't running or the save panel already is, it returns B_ERROR. If the Browser is running but the application can't communicate with it, it returns an error code that indicates what went wrong; these codes are the same as those documented for the BMessenger class in the Application Kit.
See also: SaveRequested() , SavePanelClosed()
virtual void SavePanelClosed(BMessage *message)
Implemented by derived classes to take note when the save panel is closed. The message argument contains information about how the panel was closed and its state at the time it was closed. It has entries under the names "frame" (the panel's frame rectangle), "directory" (the directory the panel displayed), and "canceled" (whether the user closed the panel). Some of this information can be retained to configure the panel the next time it runs.
See also: B_PANEL_CLOSED in the Message Protocols appendix, RunSavePanel()
virtual void SaveRequested(record_ref directory, const char *filename)
Implemented by derived classes to save the document displayed in the window. This function is called when the BWindow receives a B_SAVE_REQUESTED message from the save panel. It reports that the user has asked for the file to be saved in the directory indicated and assigned the specified filename. The file may already exist, or the application may need to create it to carry out the request.
There's no guarantee that the directory and filename are valid.
If the file can be saved as requested, you may want this function to call CloseSavePanel() to remove the panel from the screen. If the file can't be saved, SaveRequested() should notify the user. In some cases, you may want to leave the panel on-screen so the user can try again with a different directory or file name.
See also: RunSavePanel()
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: set_screen_size(), 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 SetDiscipline(bool flag)
Sets a flag that determines how much programming discipline the system will enforce. When flag is TRUE, as it is by default, Kit functions will check to be sure various rules are adhered to. For example, most BView functions will require the caller to first lock the window. < Currently, this is the only rule that comes under the discipline flag. > When flag is FALSE, these rules are not enforced.
The discipline flag should be set to TRUE while an application is being developed. However, once it has matured, and it's clear that none of the rules are being disobeyed, the flag can be set to FALSE. This will eliminate various checking operations and improve performance.
See also: Locking the Window in the BView class overview
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(double microseconds)
double 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.0 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.0 microseconds; differences less than 50,000.0 microseconds may not be noticeable. A finer granularity can't be guaranteed.
Setting the pulse rate to 0.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(ulong workspaces)
ulong 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()
inline 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(long 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 identifies 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
virtual void WorkspacesChanged(ulong oldWorkspaces, ulong 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.
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, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.