The Interface Kit: BWindow

The Interface Kit Table of Contents | The Interface Kit Index

# BWindow

Derived from: BLooper > BHandler > BArchivable

Declared in: be/interface/Window.h

Library: libbe.so

Allocation: Constructor only

###### Summary

A BWindow object represents a window that can be displayed on the screen, and that can be the target of user events. You almost always create your own BWindow subclass(es) rather than use direct instances of BWindow.

BWindow objects draw windows by talking to the App Server. If you want to take over the entire screen or draw directly into the graphics card's frame buffer (by-passing the App Server), you should use a BDirectWindow or BWindowScreen object (both classes are defined in the Game Kit).

## Creating and Using a BWindow

You must create your BApplication object (`be_app`) before you create any windows. `be_app` needn't be running to construct—or even show—a window, but it must be running for the window to receive notifications of user events (mouse clicks, key presses, etc.).

Typically, the first thing you do with your BWindow is add BViews to it, through the `AddChild()` function. Again, `be_app` needn't be running at this point, nor must the window be showing.

Even though it inherits from BLooper, you never invoke `Run()` on a BWindow. Instead, you call `Show()`. In addition to putting the window on-screen, the first (and only the first) `Show()` invocation starts the BWindow's message loop. To remove a window from the screen without interrupting the object's message loop, use `Hide()`. Other message loop details (locking and quitting in particular) are handled as described in the BLooper class.

If you create a BWindow-derived class that uses multiple inheritance, make sure the first class your mixin class inherits from is BWindow; otherwise, you'll crash when you try to close the window. This happens because of an interaction between the window thread how C++ deletes objects of a multiply-inherited class. In other words:

`class myClass : public BWindow, public OtherClass`

is safe, while

`class myClass : public OtherClass, public BWindow`

is not.

## Hook Functions

`FrameMoved()`

FrameResized()

MenusBeginning()

`MenusEnded()`

`Minimize()`

ScreenChanged()

WindowActivated()

WorkspaceActivated()

WorkspacesChanged()

Zoom()

## Constructor and Destructor

### BWindow()

`BWindow(` BRect frame,
const char *title,
`window_type` type,
uint32 flags,
uint32 workspaces = `B_CURRENT_WORKSPACE``)`

`BWindow`(BRect frame,
const char *title,
`window_look` look,
`window_feel` feel,
uint32 flags,
uint32 workspace = `B_CURRENT_WORKSPACE`)

`BWindow(` BMessage *archive`)`

Creates a new window:

- frame is the window's content area rectangle given in screen coordinates. The window's border and title tab (if any) are wrapped around the content area. The frame's coordinates are rounded to the nearest whole number. You can further restrict the window's frame through `SetWindowAlignment()` and `SetSizeLimits()`.

- title is the string that's displayed in the window's title tab (if it has one). The string is also used, with the prefix "w>", as the name of the window's looper thread: "w>title". You can reset the title through `SetTitle()`.

- look/feel or type. The appearance and behavior of the window is defined by a combination of the look and feel arguments, or by a single type. See the `window_look`, `window_feel`, and `window_type` descriptions for a list of values. The look and feel can be reset through `SetLook()`, `SetFeel()`, and `SetType()`.

- The flags argument is a mask that defines the window's "user attributes"—whether the user can resize or close the window, whether the window avoids front when the user closes other windows, and so on. See "Window Flags" for a list of values.The flags can be reset through `SetFlags()`.

- workspaces is a mask that tells the window which of the 32 potential workspace(s) it should be displayed in (it can be displayed in more than one workspace at the same time). For example, a workspaces of (1<<2)+(1<<7) tells the window to display itself in workspaces 2 and 7. Instead of passing a bitmask, you can also use the `B_CURRENT_WORKSPACE` or `B_ALL_WORKSPACES` constant. By default, the window appears in the current (active) workspace. You can reset the workspaces through `SetWorkspaces()`.

A freshly-created window is hidden and locked. After construction, you add BViews to the BWindow through `AddChild()`, and then show the window (and start its message loop) by calling `Show()`.

### ~BWindow()

You never delete your BWindows; call `Quit()` instead.

## Static Functions

### Instantiate() see BArchivable::Instantiate()

## Member Functions

### Activate() , IsActive() , WindowActivated()

void `Activate(`bool flag = `true``) `
bool `IsActive(`void`)` const
virtual void `WindowActivated(`bool active`) `

`Activate()` makes the BWindow the active window (if flag is `true`), or causes it to relinquish that status (if flag is `false`). The active window is made frontmost, its title tab is highlighted, and it becomes the target of keyboard events. The `Show()` function automatically activates the window.

| You can't activate a hidden window.

| You rarely call `Activate()` yourself. Deciding which window to make active is the user's choice.

`IsActive()` returns `true` if the window is currently the active window, and `false` if it's not.

`WindowActivated()` is a hook function that's automatically invoked on the BWindow (and each of its BView children) when the window is activated or deactivated. If active is `true`, the window has just become the active window; if it's `false`, it's about to give up that status. You can implement `WindowActivated()` to do whatever you want; the default implementation does nothing.

See also: `BView::WindowActivated()`

### AddChild() , RemoveChild() , ChildAt() , CountChildren()

void `AddChild(` BView *aView, BView *sibling = NULL`) `
bool `RemoveChild(` BView *aView`) `
BView *`ChildAt(`int32 index`)` const
int32 `CountChildren(`void`)` const

`AddChild()` places aView (and its child views) in the window, adds it to the window's view list, and adds it to the window's list of handlers:

- Graphically, the view is placed in the window's coordinate system at the location defined by its the view's frame rectangle.

- In the window's view list, aView is inserted before sibling. If sibling is `NULL`, aView is added at the end of the list. Note, however, that window list order is of little significance; for example, it doesn't affect the order in which sibling views are drawn.

- aView and its children are added to the window's handler list; aView's next handler is set to this BWindow.

Each BView in aView's hierarchy is sent an `AttachedToWindow()` call. When they've all had a chance to respond, they're each sent an `AllAttached()` call.

If aView has already been added to a view hierarchy, or if sibling isn't in the window's view list, `AddChild()` fails.

`RemoveChild()` removes aView (and its children) from the window's display, view list, and handler list, and sets aView's next handler to `NULL`. `DetachedFromWindow()` and `AllDetached()` are invoked on aView and each of its children. If aView isn't in the window's view list, the function fails and returns `false`; it returns `true` upon success.

`ChildAt()` returns the index'th view in the window's view list, or `NULL` if index is out of bounds (you've reached the end of the list). The view list doesn't recurse; to build a full map of a window's view hierarchy, you call `BView::ChildAt()` iteratively on each of the window's views (and each of their children, etc.).

See also: `BView::Parent()`

### AddShortcut() , RemoveShortcut()

void `AddShortcut(`uint32 key, uint32 modifiers, BMessage *message`) `
void `AddShortcut(`uint32 key, uint32 modifiers, BMessage *message, BHandler *handler`) `
void `RemoveShortcut(`uint32 key, uint32 modifiers`) `

`AddShortcut()` creates a keyboard shortcut: When the user types Command+modifiers+key, message is sent to handler. If a shortcut already exists for modifiers+key, it's removed before the new shortcut is added.

`RemoveShortcut()` removes the shortcut for modifiers+key.

| Don't use these functions to create and remove menu shortcuts; use BMenuItem objects instead.

Notes on the arguments:

- key is a case-insensitive character value. If you want to map to an uppercase character, you have to include `B_SHIFT_KEY` in the modifiers mask.

- modifiers is an OR'd list of modifier key numbers. `B_COMMAND_KEY`, which is always assumed, needn't be added to the mask. See `modifiers()` for a list of modifier keys.

- message is a model of the BMessage you want sent when the user types the shortcut. The BWindow takes ownership of the message object and adds a "when" field to it:

Field name | Type code | Description
--- | --- | ---
"when" | `B_INT64_TYPE` | The time of the key-down, in microseconds since 01/01/70.

- handler must be in the window's handler list (or the message won't be sent). If you exclude the argument, this BWindow handles the message. If handler is (literally) `NULL`, the message is sent to the BWindow's focus view (or to the BWindow if no view is in focus).

As with all Command events, a `B_KEY_DOWN` message isn't sent when the user invokes a keyboard shortcut, but the subsequent `B_KEY_UP` is.

Every BWindow has five built-in shortcuts:

Shortcut | Message | Handler
--- | --- | ---
Command+x | `B_CUT` | the focus view
Command+c | `B_COPY` | the focus view
Command+v | `B_PASTE` | the focus view
Command+a | `B_SELECT_ALL` | the focus view
Command+w (closable windows only) | `B_QUIT_REQUESTED` | the BWindow

In addition, BWindows respond to Command+q by posting `B_QUIT_REQUESTED` to `be_app`.

### AddToSubset() , RemoveFromSubset()

status_t `AddToSubset(`BWindow *window`) `
status_t `RemoveFromSubset(`BWindow *window`) `

Adds windows to and removes them from this window's subset. This affects modal and floating windows with a subset feel only (i.e. `B_MODAL_SUBSET_WINDOW_FEEL` or `B_FLOATING_SUBSET_WINDOW_FEEL)`. A subset feel window blocks or floats above only those windows in its subset. To set the window's feel, use `SetFeel()`.

For more information on this subject, see "Creating a Window" in the BeUIG.

### Archive()

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

### Bounds() , Frame()

BRect `Bounds(`void`)` const
BRect `Frame(`void`)` const

These functions return the rectangle that encloses the window's content area. The bounds rectangle (`Bounds()`) is expressed in the window's coordinate system; the frame rectangle (`Frame()`) is expressed in the screen's coordinate system.

The rectangles are cached by the BWindow itself—calling these functions doesn't incur a trip to the App Server.

### ChildAt() see AddChild()

### CountChildren() see AddChild()

### CommitViewTransaction() see OpenViewTransaction()

### ConvertToScreen() , ConvertFromScreen()

BPoint `ConvertToScreen(` BPoint windowPoint`)` const
void `ConvertToScreen(` BPoint *windowPoint`)` const
BRect `ConvertToScreen(` BRect windowRect`)` const
void `ConvertToScreen(` BRect *windowRect`)` const
BPoint `ConvertFromScreen(` BPoint screenPoint`)` const
void `ConvertFromScreen(` BPoint *screenPoint`)` const
BRect `ConvertFromScreen(` BRect screenRect`)` const
void `ConvertFromScreen(` BRect *screenRect`)` const

Converts the argument from window coordinates to screen coordinates or vice versa. The point or rect needn't fall within this BWindow's bounds.

If the argument is passed by value, the function returns the converted value; if it's by pointer, the conversion is done in-place.

The BWindow must be locked.

### CurrentFocus()

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 is the target for keyboard messages directed at this BWindow. The focus view is set through `BView::MakeFocus()`.

The BWindow sets its preferred handler to be the focus view, so the inherited `PreferredHandler()` function will return this same object (but as a BHandler).

### DefaultButton() see SetDefaultButton()

### DisableUpdates() , EnableUpdates()

void `DisableUpdates(`void`) `
void `EnableUpdates(`void`) `

These functions disable automatic updating within the window, and re-enable it again. Any drawing that's done while updates are disabled is suppressed until updates are re-enabled. If you're doing a lot of drawing within the window, and you want the results of the drawing to appear all at once, you should disable updates, draw, and then re-enable updates.

See also: `BView::Invalidate()`, `UpdateIfNeeded()`

### DispatchMessage()

Implementation detail; see `BLooper::DispatchMessage()`.

| You shouldn't override this function in a BWindow subclass; if you want to augment the window's message-dispatching mechanism, override `MessageReceived()`.

### EnableUpdates() see DisableUpdates()

### Feel() see SetFeel()

### Flags() see SetFlags()

### FindView()

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 functions returns `NULL` if no view is found.

### Flush() , Sync()

void `Flush(`void`)` const
void `Sync(`void`)` const

Both of these functions cause this window's App Server-bound messages to be sent immediately. `Flush()` sends the messages and returns immediately; `Sync()` send the messages and waits for the App Server to respond. In other words, when `Sync()` returns you're guaranteed that all of the flushed messages have been processed.

See also: `BView::Flush()`

### Frame() see Bounds()

### FrameMoved() , FrameResized()

virtual void `FrameMoved(` BPoint origin`) `
virtual void `FrameResized(`float width, float height`) `

These hook functions are invoked just after the window's frame is moved or resized, whether by the user or programatically. The arguments give the window's new origin (in screen coordinates) or dimensions. The default implementations do nothing.

See also: `B_WINDOW_MOVED`, `B_WINDOW_RESIZED`.

### GetSizeLimits() see SetSizeLimits()

### GetSupportedSuites()

virtual status_t `GetSupportedSuites(` BMessage *message`)`

Adds the name "suite/vnd.Be-window" to the message.

See also: `BHandler::GetSupportedSuites()`

### GetWindowAlignment() see SetWindowAlignment()

### Hide() see Show()

### IsFloating() see IsFront()

### IsFront() , IsFloating() , IsModal()

bool `IsFront(`void`)` const
bool `IsFloating(`void`)` const
bool `IsModal(`void`)` const

These functions return `true` if the window is frontmost on screen, if it has a floating window feel, and if it has a modal window feel, respectively.

| A floating window can never be the frontmost window.

### IsMinimized() see Show()

### IsModal() see IsFront()

### KeyMenuBar() see SetKeyMenuBar()

### LastMouseMovedView()

BView *`LastMouseMovedView(`void`) `

Returns a pointer to the view in this window that most recently received a `B_MOUSE_MOVED` message.

### Look() see SetLook()

### MenusBeginning() , MenusEnded()

virtual void `MenusBeginning(`void`)`
virtual void `MenusEnded(`void`)`

The `MenusBeginning()` hook function is called just before menus belonging to the window are about to be shown to the user. `MenusEnded()` is called when the menus have been removed from the screen. The default implementations do nothing. You can implement these functions to make sure the menus' states accurately reflect the state of the window.

| These hook functions are not invoked because of messages—don't go looking for a "menus beginning" or "menus ended" message.

### MessageReceived()

virtual void `MessageReceived(` BMessage *message`) `

Implementation detail. See `BHandler::MessageReceived()`.

### Minimize() see Show()

### MoveBy() , MoveTo()

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()`

### NeedsUpdate()

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.

### OpenViewTransaction() , CommitViewTransaction()

virtual void `OpenViewTransaction(`void`) `
virtual void `CommitViewTransaction(`void`) `

These two functions bracket a series of "batched" drawing instructions. After you call `OpenViewTransaction()`, everything you draw in the window is bundled up and then sent to the app server (and rendered) when you call `CommitViewTransaction()`. You can only perform one transaction (per window) at a time. The BWindow must be locked when you call `OpenViewTransaction()`, and must remain locked until after you call `CommitViewTransaction()`. Invocations of `Flush()` are ignored while a transaction is open (and locked).

### PreferredHandler() see CurrentFocus()

### PulseRate() see SetPulseRate()

### Quit()

virtual void `Quit(`void`) `

`Quit()` removes the window from the screen, deletes all the BViews in its view hierarchy, destroys the window thread, removes the window's connection to the Application Server, and deletes the BWindow object.

Use this function, rather than the `delete` operator, to destroy a window.

BWindow's `Quit()` works much like the BLooper function it overrides. When called from the BWindow's thread, it doesn't return. When called from another thread, it returns after all previously posted messages have been processed and the BWindow and its thread have been destroyed.

| The window must be locked when you call `Quit()`.

See also: `BLooper::QuitRequested()`, `BLooper::Quit()`, `BApplication::QuitRequested()`

### RemoveChild() see AddChild()

### RemoveShortcut() see AddShortcut()

### ResizeBy() , ResizeTo()

void `ResizeBy(`float horizontal, float vertical`) `
void `ResizeTo(`float width, float height`) `

These functions resize the window, while keeping its left top corner constant. `ResizeBy()` adds horizontal pixels to the width of the window's frame and vertical pixels to its height. `ResizeTo()` sets the frame absolutely to [width, height] pixels. Fractional components are rounded to the nearest whole number.

The `FrameResized()` hook function is called after the frame has been resized.

### ResolveSpecifier()

virtual BHandler *`ResolveSpecifier(` BMessage *message, int32 index, BMessage *specifier, int32 command, const char *property`) `

Resolves specifiers for the "Frame", "Title", and "View" properties. See "Scripting Support" in the class overview for more information.

See also: `BHandler::ResolveSpecifier()`

### ScreenChanged()

virtual void `ScreenChanged(` BRect frame, color_space mode`) `

Hook function that's called when the screen (on which this window is located) changes size or location in the screen coordinate system, or changes color space (depth). frame is the screen's new frame rectangle, and mode is its new color space.

See also: `BScreen::Frame()`

### SendBehind()

status_t `SendBehind(`const BWindow *window`) `

Relayers the windows on the screen so this window is behind window.

### SetDefaultButton() , DefaultButton()

void `SetDefaultButton(` BButton *button`) `
BButton *`DefaultButton(`void`)` const

Set and return the window's default button. This is the button that's mapped to the Enter key. The user can activate the default button at any time—even if another BView is the focus view (the focus view will not receive a `B_KEY_DOWN` message). To remove the current default (without promoting another button) call `SetDefaultButton(NULL)`. There can only be one default button at a time; `SetDefaultButton()` demotes the previous default.

When you promote or demote a default button, it's automatically redisplayed and receives a `BButton::MakeDefault()` call.

### SetFeel() , Feel()

status_t `SetFeel`(window_feel feel)
window_feel `Feel(`void`)` const

`SetFeel()` changes the window's feel to the specified value.

`Feel()` returns the current feel of the window.

See the BWindow constructor for a list of `window_feel` constants.

### SetFlags() , Flags()

status_t `SetFlags`(uint32 flags)
uint32 `Flags(`void`)` const

`SetFlags()` set the window's flags (or "user attributes") to the specified combination. `Flags()` returns the current flags.

See "Window Flags" for a list of the flag values. Also see "User Attributes" in the BeUIG for a detailed description.

### SetKeyMenuBar() , KeyMenuBar()

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.

### SetLook() , Look()

status_t `SetLook`(window_look look)
window_look `Look(`void`)` const

`SetLook()` changes the window's look to the specified value.

`Look()` returns the current look of the window.

See the BWindow constructor for a list of `window_look` constants.

### SetPulseRate() , PulseRate()

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

### SetSizeLimits() , GetSizeLimits() , SetZoomLimits()

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()`

### SetTitle() , Title()

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

### SetType() , Type()

status_t `SetType`(window_type type)
window_type `Type(`void`)` const

`SetType()` changes the type of the window to the specified value. `Type()` returns the type. You normally set the window's type when it's constructed. .

The type is set at construction (or by `SetType()`) as one of the following constants (full descriptions can be found in the discussion of the BWindow constructor):

B_UNTYPED_WINDOW
B_MODAL_WINDOW
B_BORDERED_WINDOW
B_TITLED_WINDOW
B_DOCUMENT_WINDOW
B_FLOATING_WINDOW

See also: the BWindow constructor

### SetWindowAlignment() , GetWindowAlignment()

status_t `SetWindowAlignment(`window_alignment mode, int32 h,
int32 hOffset = 0,
int32 width = 0,
int32 widthOffset = 0,
int32 v = 0,
int32 vOffset = 0,
int32 height = 0,
int32 heightOffset = 0`)

`

status_t `GetWindowAlignment(`window_alignment *mode = `NULL`,
int32 *h = `NULL`,
int32 *hOffset = `NULL`,
int32 *width = `NULL`,
int32 *widthOffset = NULL,
int32 *v = NULL,
int32 *vOffset = NULL,
int32 *height = NULL,
int32 *heightOffset = NULL`)` const

`SetWindowAlignment()` sets the current alignment of the window content on the screen. mode is either `B_PIXEL_ALIGNMENT` or `B_BYTE_ALIGNMENT`.

If mode is `B_PIXEL_ALIGNMENT`, `SetWindowAlignment()` aligns the window in pixel coordinates. h and hOffset together determine the horizontal alignment: h gives the horizontal origin step while hOffset is the horizontal offset. hOffset must be between 1 and h (as a convenience, 0 is taken to mean 1). For example, if h is 4 and hOffset is 1, valid horizontal origins would be ..., -7, -3, 1, 5, 9, ... Similarly, width/widthOffset, v/vOffset, height/heightOffset give you control over the other window parameters.

If mode is `B_BYTE_ALIGNMENT`, then the alignment is given in terms of frame buffer offsets. However, the setting only affects the horizontal origin and width. You can't align the right and bottom edges in `B_BYTE_ALIGNMENT` mode.

`GetWindowAlignment()` returns the current window alignment.

Both methods return `B_NO_ERROR` on success and `B_ERROR` otherwise.

### SetWorkspaces() , Workspaces()

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()`

### SetZoomLimits() see SetSizeLimits()

### Show() see Hide()

### Sync() see Flush()

### Title() see SetTitle()

### Type() see SetType()

### Show() , Hide() , IsHidden() , Minimize() , IsMinimized()

virtual void `Show(`void`) `
virtual void `Hide(`void`) `
bool `IsHidden(`void`)` const
virtual void `Minimize(`bool minimize`) `
bool `IsMinimized(`void`)` const

These functions hide and show the window.

`Show()` places the window frontmost on the screen (but behind any applicable floating or modal windows), places it on Deskbar's window list, and makes it the active window. If this is the BWindow's first `Show()`, the object's message loop is started, and the object is unlocked.

`Hide()` removes the window from the screen, removes it from Deskbar's window list, and passes active status to some other window (if this is the active window). 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.

`Minimize()` hides and shows the window (and passes active status), as minimize is `true` or `false`. The difference between this function and `Hide()`/`Show()` is that`Minimize()` dims (and undims) the window's entry in Deskbar's window list, but doesn't remove the entry altogether. Also, a single `Minimize(false)` "undoes" any number of `Minimize(true)` calls.

`Minimize()` also acts as a hook that's invoked when the user double-clicks the window's title tab or selects the window from DeskBar's window list. If minimize is `true`, the window is about to be hidden; if `false`, it's about to be shown. The `Minimize()` function itself does the hiding and showing—if you override `Minimize()` and you want to inherit the BWindow behaviour, you must call `BWindow::Minimize()` in your implementation.

`IsHidden()` returns `true` if the window is currently hidden (i.e. through `Hide()`). `IsMinimized()` returns `true` if the window is minimized. Hiding takes precendence over minimization. For example, in both of these sequences...

       window->Hide();
       window->Minimize(true);
       /* or */
       window->Minimize(true);
       window->Hide();

...the window is hidden but not minimized.

See also: `B_MINIMIZE`

### UpdateIfNeeded()

void `UpdateIfNeeded(`void`) `

Immediately and synchronously invokes `Draw()` on each child view that needs updating. This function is ignored if its called from any thread other than the BWindow's message loop. You call it as part of the implementation of a user interface hook function (`MouseMoved()`, `KeyDown()`, et. al.) to force invalid views to be immediately redrawn without having to wait for the hook function to finish. See "Forcing an Update while Responding to an Event" for details and an example.

### WindowActivated() see Activate()

### Workspaces() see SetWorkspaces()

### WorkspaceActivated()

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()`

### WorkspacesChanged()

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()`

### Zoom()

void `Zoom(`void`) `
virtual void `Zoom(` BPoint origin, float width, float height`) `

The non-virtual `Zoom()` (which is called when the user clicks the zoom button, but can also be called programatically) figures out a new size and location for the window (as described below), and then passes these dimensions to the virtual `Zoom()` hook function. It's hook `Zoom()`'s responsibility to actually resize and move the window; the default version applies the arguments explicitly by calling`MoveTo()` and`ResizeTo()`. You can re-implement hook `Zoom()` to create a new zooming algorithm that incorporates or ignores the arguments as you see fit.

The dimensions that non-virtual `Zoom()` passes to hook `Zoom()` are deduced from the smallest of three rectangles: 1) the screen rectangle, 2) the rectangle defined by `SetZoomLimits()`, 3) the rectangle defined by `SetSizeLimits()`. However, if the window's rectangle already matches these "zoom" dimensions (give or take a few pixels), `Zoom()` passes the window's previous ("non-zoomed") size and location.

You can effectively call `Zoom()` even if the window is `B_NOT_ZOOMABLE`.

`Zoom()` may both move and resize the window, resulting in `FrameMoved()` and `FrameResized()` notifications.

## Constants and Defined Types

### window_look

The `window_look` constants define the appearance of the window—the look of its title tab, border, and the type of "resize control" (in the bottom right corner of the window). The look is set in the constructor or in the `SetLook()` function. The table below lists and briefly describes the window_look values; for more information (and pictures) see "Window Looks" in the BeUIG.

Window Look | Meaning
--- | ---
`B_DOCUMENT_WINDOW_LOOK` | Large title bar, thick border, draggable "resize box" .
`B_TITLED_WINDOW_LOOK` | Same as the document window, but with a less substantial "resize corner".
`B_FLOATING_WINDOW_LOOK` | Small title bar, thin border, resize corner.
`B_MODAL_WINDOW_LOOK` | No title bar, thick border, no resize control (by convention; see the `B_NOT_RESIZABLE` window flag).
`B_BORDERED_WINDOW_LOOK` | No title bar, line border, no resize control.
`B_NO_BORDER_WINDOW_LOOK` | A borderless white rectangle. The user can't move or close this window.

### window_feel

The `window_feel` constants govern a window's behavior in relation to other windows. The feel is set in the BWindow constructor or in `SetFeel()`. The table below briefly describes the window feels. For a more detailed explanation, see "Window Feels" in the BeUIG.

Window Feel | Meaning
--- | ---
`B_NORMAL_WINDOW_FEEL` | Behaves like a normal window (non-modal, non-floating).
`B_MODAL_SUBSET_WINDOW_FEEL B_MODAL_APP_WINDOW_FEEL B_MODAL_ALL_WINDOW_FEEL` | When displayed, blocks all windows in its subset1, app, or across the entire system. A modal subset/app window is visible only if a window in its subset/app is visible. Modal all windows are always visible in all workspaces
`B_FLOATING_SUBSET_WINDOW_FEEL B_FLOATING_APP_WINDOW_FEEL B_FLOATING_ALL_WINDOW_FEEL` | Floats above all windows in its subset1, app, or across the entire system2. A floating subset/app window is visible only if a window in its subset/app is frontmost. Floating all windows are always visible in all workspaces.

1 To set a window's subset, use `AddToSubset()`.

2 Modal windows are drawn in front of floating windows.

### window_type

The `window_type` constants are pre-defined combinations of looks and feels. You set the type through the BWindow constructor or `SetType()`. For more information on the window types, see "Window Types" in the BeUIG.

Window Type | Look and Feel
--- | ---
`B_TITLED_WINDOW` | `B_TITLED_WINDOW_LOOK` and `B_NORMAL_WINDOW_FEEL`.
`B_DOCUMENT_WINDOW` | `B_DOCUMENT_WINDOW_LOOK` and `B_NORMAL_WINDOW_FEEL`.
`B_MODAL_WINDOW` | `B_MODAL_WINDOW_LOOK` and `B_MODAL_APP_WINDOW_FEEL`.
`B_FLOATING_WINDOW` | `B_FLOATING_WINDOW_LOOK` and `B_FLOATING_APP_WINDOW_FEEL`.
`B_BORDERED_WINDOW` | `B_BORDERED_WINDOW_LOOK` and `B_NORMAL_WINDOW_FEEL`.
`B_UNTYPED_WINDOW` | A window of unknown or undefined type.

### Window , Flags

The window flags (or "user attributes") define miscellaneous aspects of the window's interface, such as whether it can be moved or closed by the user. You combine the flags that you want and pass them to the BWindow constructor or `SetFlags()`. For more information on the window flags, see "User Attributes".

The default behavior is the inverse of all these flags—i.e. a window is normally movable, closable, resizable, and so on. However, some window looks and feels cause imply some of these flags. For example, a modal feel window can't be minimized (hidden). The "User Attributes" section lists these implications.

Window Flag | Meaning
--- | ---
`B_NOT_MOVABLE` | Prevents the user from being able to move the window.
`B_NOT_CLOSABLE` | Prevents the user from closing the window.
`B_NOT_ZOOMABLE` | Prevents the user from zooming the window.
`B_NOT_MINIMIZABLE` | Prevents the user from hiding the window by double-clicking the title tab.
`B_NOT_H_RESIZABLE B_NOT_V_RESIZABLE B_NOT_RESIZABLE` | Prevents the user from resizing the window horizontally and/or vertically (`B_NOT_RESIZABLE` is the same as the sum of the other two constants).
`B_OUTLINE_RESIZE` | The window draws only the outline of its new dimensions as it's being resized, and doesn't refresh its contents.
`B_WILL_ACCEPT_FIRST_CLICK` | Tells a non-active window to process an activating mouse click (the "first" mouse click) as if it were already active. The BView that responds to the mouse-down message must activate the window. By default, the first mouse click in a non-active window activates the window, and then the mouse click event is thrown away.
`B_AVOID_FRONT` | Prevents the window from becoming the frontmost window.
`B_AVOID_FOCUS` | Prevents the window from being the target of keyboard events.
`B_NO_WORKSPACE_ACTIVATION` | When a window is first shown, the workspace normally switches to the one in which the window is displayed. Setting this flag keeps this from happening.
`B_NOT_ANCHORED_ON_ACTIVATE` | Tells the system to bring the window to the current workspace when the window is selected from Deskbar's window list. Normally, selecting a window from the list activates the workspace that the window is currently in.
`B_ASYNCHRONOUS_CONTROLS` | Tells the window to allow controls to run asynchronously. All windows that contain controls should include this flag (it's off by default because of backwards compatibility).
`B_QUIT_ON_WINDOW_CLOSE` | Currently has no effect.

### Window , Workspaces

You tell a window which workspaces to appear through the constructor, or through the `SetWorkspaces()` function. In practice, the only two realistic settings are represented by these constants.

Workspace Constant | Meaning
--- | ---
`B_CURRENT_WORKSPACE` | Appear in the current workspace.
`B_ALL_WORKSPACES` | Appear in all workspaces.

## Scripting Support

The BWindow class implements the suite called "suite/vnd.Be-window" consisting of the following messages:

#### Window Position

Message | Meaning
--- | ---
`B_WINDOW_MOVE_BY` | Moves the window by the distance specified by the `B_POINT_TYPE` field "data".
`B_WINDOW_MOVE_TO` | Moves the window to the position specified by the `B_POINT_TYPE` field "data".

These two messages can be sent to a BWindow to move the window.

#### The Feel Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns the current feel of the window.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Sets the feel of the window.

The "Feel" property represents the workspaces in which the window resides. The messages are equivalent to manipulating the window with the `Feel()` and `SetFeel()` methods.

#### The Flags Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns the current flags of the window.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Sets the window flags.

The "Flags" property represents the window flags. The messages are equivalent to manipulating the window with the `Flags()` and `SetFlags()` methods.

#### The Frame Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns the window's frame rectangle.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Sets the window's frame rectangle.

The "Frame" property represents the frame rectangle of the window. The frame is passed as a BRect (`B_RECT_TYPE`).

#### The Hidden Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns `true` if the window is hidden; `false` otherwise.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Hides or shows the window.

The "Hidden" property determines the visibility of the window. The messages are equivalent to manipulating the window with the `IsHidden()`, `Hide()`, and `Show()` methods with one caveat: nested `Hide()` and `Show()` calls are disabled so that multiple scripting Hide commands may be undone with a single Show.

#### The Look Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns the current look of the window.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Sets the look of the window.

The "Workspaces" property represents the workspaces in which the window resides. The messages are equivalent to manipulating the window with the `Look()` and `SetLook()` methods.

#### The MenuBar Property

Message | Specifiers | Meaning
--- | --- | ---
any | `B_DIRECT_SPECIFIER` | Directs the scripting message to the key menu bar.

The "MenuBar" property pops the current specifier off the specifier stack and then passes the scripting message to the key menu bar. If no such menu bar is present, then an error is returned.

#### The Minimize Property

Message | Specifiers | Meaning
--- | --- | ---
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Minimizes the window if "data" is `true`; restores otherwise.

The "Minimize" property controls the whether the window is minimized or not. The message is equivalent to manipulating the window with the `Minimize()` method.

#### The Title Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns a string containing the window title.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Sets the window title.

The "Title" property represents the title of the window. The messages are equivalent to manipulating the window with the `Title()` and `SetTitle()` methods.

#### The View Property

Message | Specifiers | Meaning
--- | --- | ---
any | any | Directs the scripting message to the top view without popping the current specifier.

The "View" property simply redirects all requests to the window's top view without popping the specifier from the stack.

#### The Workspaces Property

Message | Specifiers | Meaning
--- | --- | ---
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns int32 bitfield of the workspaces in which the window appears.
`B_SET_PROPERTY` | `B_DIRECT_SPECIFIER` | Sets the workspaces in which the window appears.

The "Workspaces" property represents the workspaces in which the window resides. The messages are equivalent to manipulating the window with the `Workspaces()` and `SetWorkspaces()` methods.

## Archived Fields

Field | Type code | Meaning
--- | --- | ---
"_frame" | `B_RECT_TYPE` | The frame rectangle.
"_title" | `B_STRING_TYPE` | The title of the BWindow.
"_wlook" | `B_INT32_TYPE` | The BWindow look.
"_wfeel" | `B_INT32_TYPE` | The BWindow feel.
"_type" | `B_INT32_TYPE` | The BWindow type (if one exists).
"_flags" | `B_INT32_TYPE` | The BWindow flags.
"_wspace" | `B_INT32_TYPE` | The workspaces in which the BWindow appears.
"_zoom" (array) | `B_FLOAT_TYPE` | The horizontal and vertical zoom limits, if any exist.
"_sizel" (array) | `B_FLOAT_TYPE` | The minimum horizontal and vertical and maximum horizontal and vertical size limits, if any exist.
"_pulse" | `B_INT64_TYPE` | The pulse rate, if not the default.

"_views"
(array)

`B_MESSAGE_TYPE`

Child BViews. See

## Archived Fields [BView]

forthe BMessage format. (Deep archive only.)

The Interface Kit Table of Contents | The Interface Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..