BWindow Class Reference

#include <Window.h>

Inheritance diagram for BWindow:

BLooper BHandler BArchivable BAlert BDirectWindow DocWindow BSimpleWindow PrintPanelWindow BWindowScreen BDirectGLWindow List of all members.

Detailed Description

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).

Using BWindow

Hook Functions


Public Member Functions

 BWindow (BRect frame, const char *title, window_type type, uint32 flags, uint32 workspace=B_CURRENT_WORKSPACE)
 BWindow (BRect frame, const char *title, window_look look, window_feel feel, uint32 flags, uint32 workspace=B_CURRENT_WORKSPACE)
virtual ~BWindow ()
 BWindow (BMessage *data)
virtual status_t Archive (BMessage *data, bool deep=true) const
virtual void Quit ()
void Close ()
BWindow * Parent ()
status_t AddChild (BWindow *window)
bool RemoveChild (BWindow *window)
bool RemoveSelf ()
void AddChild (BView *child, BView *before=NULL)
bool RemoveChild (BView *child)
int32 CountChildren () const
BView * ChildAt (int32 index) const
virtual void DispatchMessage (BMessage *message, BHandler *handler)
virtual void MessageReceived (BMessage *message)
virtual void FrameMoved (BPoint new_position)
virtual void WorkspacesChanged (uint32 old_ws, uint32 new_ws)
virtual void WorkspaceActivated (int32 ws, bool state)
virtual void FrameResized (float new_width, float new_height)
virtual void Minimize (bool minimize)
virtual void Zoom (BPoint rec_position, float rec_width, float rec_height)
void Zoom ()
void SetZoomLimits (float max_h, float max_v)
virtual void ScreenChanged (BRect screen_size, color_space depth)
void SetPulseRate (bigtime_t rate)
bigtime_t PulseRate () const
void AddShortcut (uint32 key, uint32 modifiers, BMessage *msg)
void AddShortcut (uint32 key, uint32 modifiers, BMessage *msg, BHandler *target)
void RemoveShortcut (uint32 key, uint32 modifiers)
void SetDefaultButton (BButton *button)
BButton * DefaultButton () const
virtual void MenusBeginning ()
virtual void MenusEnded ()
bool NeedsUpdate () const
void UpdateIfNeeded ()
BView * FindView (const char *view_name) const
BView * FindView (BPoint) const
BView * CurrentFocus () const
void ClearExplicitFocus ()
void Activate (bool=true)
virtual void WindowActivated (bool state)
void ConvertToScreen (BPoint *pt) const
BPoint ConvertToScreen (BPoint pt) const
void ConvertFromScreen (BPoint *pt) const
BPoint ConvertFromScreen (BPoint pt) const
void ConvertToScreen (BRect *rect) const
BRect ConvertToScreen (BRect rect) const
void ConvertFromScreen (BRect *rect) const
BRect ConvertFromScreen (BRect rect) const
void MoveBy (float dx, float dy)
void MoveTo (BPoint)
void MoveTo (float x, float y)
void ResizeBy (float dx, float dy)
void ResizeTo (float width, float height)
virtual void Show ()
virtual void Hide ()
bool IsHidden () const
bool IsMinimized () const
void SetWindowColor (rgb_color color)
rgb_color WindowColor () const
void Flush () const
void Sync () const
void SetCurrentBeep (const char *name)
const char * CurrentBeep () const
status_t SendBehind (const BWindow *window)
void DisableUpdates ()
void EnableUpdates ()
void BeginViewTransaction ()
void EndViewTransaction ()
status_t ClipWindowToPicture (BPicture *picture, BPoint offset, uint32 flags)
BRect Bounds () const
BRect Frame () const
const char * Title () const
void SetTitle (const char *title)
bool IsFront () const
bool IsActive () const
void SetKeyMenuBar (BMenuBar *bar)
BMenuBar * KeyMenuBar () const
void SetSizeLimits (float min_h, float max_h, float min_v, float max_v)
void GetSizeLimits (float *min_h, float *max_h, float *min_v, float *max_v)
uint32 Workspaces () const
void SetWorkspaces (uint32)
BView * LastMouseMovedView () const
virtual BHandler * ResolveSpecifier (BMessage *msg, int32 index, BMessage *specifier, int32 form, const char *property)
virtual status_t GetSupportedSuites (BMessage *data)
status_t AddToSubset (BWindow *window)
status_t RemoveFromSubset (BWindow *window)
virtual status_t Perform (perform_code d, void *arg)
status_t SetType (window_type type)
window_type Type () const
status_t SetLook (window_look look)
window_look Look () const
status_t SetFeel (window_feel feel)
window_feel Feel () const
status_t SetFlags (uint32)
uint32 Flags () const
bool IsModal () const
bool IsFloating () const
status_t GetFrameState (BMessage *dest) const
status_t UpdateFrameState (const BMessage &changes)
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
virtual bool QuitRequested ()
virtual thread_id Run ()
virtual status_t UISettingsChanged (const BMessage *changes, uint32 flags)
virtual BView * NextNavigableView (BView *currentFocus, uint32 flags)
void DequeueAll ()
bool find_token_and_handler (BMessage *msg, int32 *token, BHandler **handler)

Static Public Member Functions

static BArchivable * Instantiate (BMessage *data)

Friends

class BApplication
class BBitmap
class BControl
class BScrollBar
class BView
class BMenuItem
class BWindowScreen
class BDirectWindow
class BFilePanel
class _CEventPort_
void _set_menu_sem_ (BWindow *w, sem_id sem)
status_t _safe_get_server_token_ (const BLooper *, int32 *)

Constructor & Destructor Documentation

BWindow (  BRect  bound,
const char *  name,
window_type  type,
uint32  flags,
uint32  workspaces = B_CURRENT_WORKSPACE
) 
 

Creates a new window.

Parameters:
bound 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().
name 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().
type The appearance and behavior of the window is defined 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().
flags The 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 (  BRect  bound,
const char *  name,
window_look  look,
window_feel  feel,
uint32  flags,
uint32  workspaces = B_CURRENT_WORKSPACE
) 
 

Creates a new window.

Parameters:
look/feel The appearance and behavior of the window is defined by a combination of the look and feel arguments. 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().
For more parameters look above.

~BWindow (   )  [virtual]
 

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

BWindow (  BMessage *  data  ) 
 

Member Function Documentation

void Activate (  bool  bringFront = true  ) 
 

Makes the BWindow the active window (if bringFront is true), or causes it to relinquish that status (if bringFront 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.

Parameters:
bringFront Window status
Attention:
You can't activate a hidden window.
Note:
You rarely call Activate() yourself. Deciding which window to make active is the user's choice.

void AddChild (  BView *  child,
BView *  before = NULL
) 
 

Places child (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, child is inserted before before. If before is NULL, child 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.
  • child and its children are added to the window's handler list; child's next handler is set to this BWindow.

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

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

Parameters:
child BView to added
before The BView inserted before this (default = NULL)

status_t AddChild (  BWindow *  window  ) 
 

void AddShortcut (  uint32  key,
uint32  mods,
BMessage *  msg,
BHandler *  target
) 
 

See AddShortcut() above.

Notes on the arguments:

  • target 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 target is (literally) NULL, the message is sent to the BWindow's focus view (or to the BWindow if no view is in focus).

void AddShortcut (  uint32  key,
uint32  mods,
BMessage *  msg
) 
 

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.

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.

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.

status_t AddToSubset (  BWindow *  window  ) 
 

Adds windows to 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().

Parameters:
window Window to add to subset

status_t Archive (  BMessage *  data,
bool  deep = true
)  const [virtual]
 

Archives the BWindow by recording its frame rectangle, title, type, and flags in the BMessage data. 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

Reimplemented from BLooper.

Reimplemented in BDirectWindow, and BAlert.

void BeginViewTransaction (   ) 
 

BRect Bounds (   )  const
 

This function return the rectangle that encloses the window's content area. The bounds rectangle (Bounds()) is expressed in the window's coordinate system.

Parameters:
Rectangle that encloses the window's content area.
The rectangles are cached by the BWindow itself - calling these functions doesn't incur a trip to the App Server.

BView * ChildAt (  int32  index  )  const
 

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.).

Parameters:
index To window's view list
Returns:
Returns BView at index
See also:
BView::Parent()

void ClearExplicitFocus (   ) 
 

status_t ClipWindowToPicture (  BPicture *  picture,
BPoint  offset,
uint32  flags
) 
 

void Close (   )  [inline]
 

BRect ConvertFromScreen (  BRect  r  )  const
 

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

Parameters:
r Screen rectangle
Returns:
Window rectangle
If the argument is passed by value, the function returns the converted value.

The BWindow must be locked.

void ConvertFromScreen (  BRect *  r  )  const
 

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

Parameters:
r Screen rectangle
The conversion is done in-place.

The BWindow must be locked.

BPoint ConvertFromScreen (  BPoint  pt  )  const
 

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

Parameters:
pt Screen point
Returns:
Point in
If the argument is passed by value, the function returns the converted value.

The BWindow must be locked.

void ConvertFromScreen (  BPoint *  pt  )  const
 

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

Parameters:
pt Screen point
The conversion is done in-place.

The BWindow must be locked.

BRect ConvertToScreen (  BRect  r  )  const
 

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

Parameters:
r Window rectangle
Returns:
Screen rectangle
If the argument is passed by value, the function returns the converted value.

The BWindow must be locked.

void ConvertToScreen (  BRect *  r  )  const
 

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

Parameters:
pt Window rectangle
The conversion is done in-place.

The BWindow must be locked.

BPoint ConvertToScreen (  BPoint  pt  )  const
 

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

Parameters:
pt Window point
Returns:
Screen point
If the argument is passed by value, the function returns the converted value.

The BWindow must be locked.

void ConvertToScreen (  BPoint *  pt  )  const
 

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

Parameters:
pt Window point
The conversion is done in-place.

The BWindow must be locked.

int32 CountChildren (   )  const
 

const char * CurrentBeep (   )  const
 

BView * CurrentFocus (   )  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().

Returns:
The current focus view for the BWindow

NULL if no view is currently in focus

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).

BButton * DefaultButton (   )  const
 

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.

void DequeueAll (   ) 
 

void DisableUpdates (   ) 
 

This function disable automatic updating within the window

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

void DispatchMessage (  BMessage *  an_event,
BHandler *  handler
)  [virtual]
 

Implementation detail; see BLooper::DispatchMessage().

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

Reimplemented from BLooper.

Reimplemented in BDirectWindow, BAlert, and BDirectGLWindow.

void EnableUpdates (   ) 
 

This function enable automatic updating within the window

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

void EndViewTransaction (   ) 
 

window_feel Feel (   )  const
 

Returns:
the current feel of the window.
See the BWindow constructor for a list of window_feel constants.

bool find_token_and_handler (  BMessage *  msg,
int32 *  token,
BHandler **  handler
) 
 

BView * FindView (  BPoint  loc  )  const
 

Find a view located at the window.

Parameters:
loc Point on the View
Returns:
The view located at point within the window.

NULL if no view is found.

BView * FindView (  const char *  name  )  const
 

Find a view located at the window.

Parameters:
name View's name
Returns:
The view tagged with name.

NULL if no view is found.

uint32 Flags (   )  const
 

void Flush (   )  const
 

This function cause this window's App Server-bound messages to be sent immediately.

Flush() sends the messages and returns immediately;

See also:
BView::Flush()

BRect Frame (   )  const
 

This function return the rectangle that encloses the window's content area. The frame rectangle (Frame()) is expressed in the screen's coordinate system.

Parameters:
Rectangle that encloses the window's content area.
The rectangles are cached by the BWindow itself - calling these functions doesn't incur a trip to the App Server.

void FrameMoved (  BPoint  new_position  )  [virtual]
 

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

param origin New Window position

See also:
B_WINDOW_MOVED, B_WINDOW_RESIZED.

Reimplemented in BDirectWindow, and BDirectGLWindow.

void FrameResized (  float  new_width,
float  new_height
)  [virtual]
 

This hook function are invoked just after the window's frame is resized, whether by the user or programatically. The arguments give the window's new dimensions. The default implementations do nothing.

Parameters:
width New window width
height New windoe height
See also:
B_WINDOW_MOVED, B_WINDOW_RESIZED.

Reimplemented in BDirectWindow, BAlert, and BDirectGLWindow.

status_t GetFrameState (  BMessage *  dest  )  const
 

void GetSizeLimits (  float *  min_h,
float *  max_h,
float *  min_v,
float *  max_v
) 
 

These functions set 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 , 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.

GetSizeLimits() writes the current limits to the variables provided.

Parameters:
min_h minimum width
max_h maximum width
min_v minimum height
max_v maximum height
See also:
The BWindow constructor, Zoom()

virtual status_t GetSupportedSuites (  BMessage *  data  )  [virtual]
 

Reimplemented from BLooper.

Reimplemented in BDirectWindow, BAlert, and BDirectGLWindow.

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
 

Returns the current window alignment.

Parameters:
mode (default is NULL)
h (default is NULL)
hOffset (default is NULL)
width (default is NULL)
width (default is NULL)
widthOffset (default is NULL)
v (default is NULL)
vOffset (default is NULL)
height (default is NULL)
heightOffset (default is NULL)
Returns:
B_NO_ERROR on success

B_ERROR otherwise

See also:
SetWindowAlignment()

void Hide (   )  [virtual]
 

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.

Reimplemented in BDirectWindow, BWindowScreen, and BDirectGLWindow.

BArchivable * Instantiate (  BMessage *  data  )  [static]
 

Reimplemented from BLooper.

Reimplemented in BDirectWindow, and BAlert.

bool IsActive (   )  const
 

Returns:
true if the window is currently the active window, and false if it's not.

bool IsFloating (   )  const
 

This function return true if the window has a floating window feel.

Note:
A floating window can never be the frontmost window.

bool IsFront (   )  const
 

This function return true if the window is frontmost on screen.

bool IsHidden (   )  const
 

Returns:
true if the window is currently hidden.

bool IsMinimized (   )  const
 

Returns:
true if the window is minimized. Hiding takes precendence over minimization.

bool IsModal (   )  const
 

This function return true if the window has a modal window feel.

BMenuBar * KeyMenuBar (   )  const
 

BView * LastMouseMovedView (   )  const
 

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

window_look Look (   )  const
 

void MenusBeginning (   )  [virtual]
 

The MenusBeginning() hook function is called just before menus belonging to the window are about to be shown to the user. The default implementation do nothing. You can implement this function to make sure the menus' states accurately reflect the state of the window.

Note:
This hook function are not invoked because of messages - don't go looking for a "menus beginning" message.

Reimplemented in DocWindow, BDirectWindow, and BDirectGLWindow.

void MenusEnded (   )  [virtual]
 

MenusEnded() is called when the menus have been removed from the screen. The default implementation do nothing. You can implement this function to make sure the menus' states accurately reflect the state of the window.

Note:
This hook function are not invoked because of messages - don't go looking for a "menus ended" message.

Reimplemented in BDirectWindow, and BDirectGLWindow.

void MessageReceived (  BMessage *  msg  )  [virtual]
 

Implementation detail. See BHandler::MessageReceived().

Reimplemented from BLooper.

Reimplemented in DocWindow, BDirectWindow, BAlert, BDirectGLWindow, PrintPanelWindow, and BSimpleWindow.

void Minimize (  bool  minimize  )  [virtual]
 

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.

Reimplemented in BDirectWindow, and BDirectGLWindow.

void MoveBy (  float  dh,
float  dv
) 
 

This function move the window without resizing it. MoveBy() adds dh coordinate units to the left and right components of the window's frame rectangle and dv units to the frame's top and bottom. If dh and dv are negative, the window moves upward and to the left. If they're positive, it moves downward and to the right.

Parameters:
dh Delta for horizontal moving
dv Delta for vertical moving
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 this function 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()

void MoveTo (  float  x,
float  y
) 
 

This function move the window without resizing it. MoveTo() moves the left top corner of the window's content area to x, y in the screen coordinate system; it adjusts all coordinates in the frame rectangle accordingly.

Parameters:
x New window x position on screen
y New window y position on screen
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 this function 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()

void MoveTo (  BPoint  pt  ) 
 

This function move the window without resizing it. MoveTo() moves the left top corner of the window's content area to point in the screen coordinate system; it adjusts all coordinates in the frame rectangle accordingly.

Parameters:
pt New window position on screen
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 this function 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 (   )  const
 

Returns:
true if any of the views within the window need to be updated

false if they're all up-to-date.

BView * NextNavigableView (  BView *  currentFocus,
uint32  flags
)  [virtual]
 

BWindow * Parent (   ) 
 

status_t Perform (  perform_code  d,
void *  arg
)  [virtual]
 

Reimplemented from BLooper.

Reimplemented in BDirectWindow, BWindowScreen, BAlert, and BDirectGLWindow.

bigtime_t PulseRate (   )  const
 

These functions 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.

Returns:
Pulse rate
See also:
SetPulseRate()

void Quit (  void   )  [virtual]
 

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.

Note:
The window must be locked when you call Quit().
See also:
BLooper::QuitRequested(), BLooper::Quit(), BApplication::QuitRequested()

Reimplemented from BLooper.

Reimplemented in BDirectWindow, BWindowScreen, BAlert, and BDirectGLWindow.

bool QuitRequested (   )  [virtual]
 

Reimplemented from BLooper.

Reimplemented in DocWindow, BAlert, PrintPanelWindow, and BSimpleWindow.

bool RemoveChild (  BView *  aView  ) 
 

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.

Parameters:
aView BView to remove from BWindow

bool RemoveChild (  BWindow *  window  ) 
 

status_t RemoveFromSubset (  BWindow *  window  ) 
 

Removes windows 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().

Parameters:
window Window to remove from subset

bool RemoveSelf (   ) 
 

void RemoveShortcut (  uint32  key,
uint32  modifiers
) 
 

void ResizeBy (  float  dh,
float  dv
) 
 

Theis function resize the window, while keeping its left top corner constant. ResizeBy() adds dh pixels to the width of the window's frame and dv pixels to its height.

Parameters:
dh Delta for horizontal moving
dv.Delta for vertical moving
The FrameResized() hook function is called after the frame has been resized.

void ResizeTo (  float  h,
float  v
) 
 

Sets the frame absolutely to [h, v] pixels. Fractional components are rounded to the nearest whole number.

Parameters:
h New window width
v.New window height
The FrameResized() hook function is called after the frame has been resized.

virtual BHandler* ResolveSpecifier (  BMessage *  msg,
int32  index,
BMessage *  specifier,
int32  form,
const char *  property
)  [virtual]
 

Reimplemented from BLooper.

Reimplemented in BDirectWindow, BAlert, and BDirectGLWindow.

thread_id Run (   )  [virtual]
 

Reimplemented from BLooper.

void ScreenChanged (  BRect  screen_size,
color_space  depth
)  [virtual]
 

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.

Parameters:
frame New screen size
mode Screens color space
See also:
BScreen::Frame()

Reimplemented in BDirectWindow, BWindowScreen, and BDirectGLWindow.

status_t SendBehind (  const BWindow *  window  ) 
 

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

Parameters:
window Window to send behind

void SetCurrentBeep (  const char *  name  ) 
 

void SetDefaultButton (  BButton *  button  ) 
 

Set 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.

status_t SetFeel (  window_feel  feel  ) 
 

Changes the window's feel to the specified value.

Parameters:
feel New window feel value
See the BWindow constructor for a list of window_feel constants.

status_t SetFlags (  uint32   ) 
 

void SetKeyMenuBar (  BMenuBar *  bar  ) 
 

status_t SetLook (  window_look  look  ) 
 

void SetPulseRate (  bigtime_t  rate  ) 
 

This function set how often Pulse() is called for the BWindow's views (how often B_PULSE messages are posted to the window). All BViews attached to the same window share the same pulse rate.

By turning on the B_PULSE_NEEDED flag, a BView can request periodic Pulse() notifications. By default, B_PULSE messages are posted every 500,000 microseconds, as long as no other messages are pending. Each message causes Pulse() to be called once for every BView that requested the notification. There are no pulses if no BViews request them.

SetPulseRate() permits you to set a different interval. The interval set should not be less than 100,000 microseconds; differences less than 50,000 microseconds may not be noticeable. A finer granularity can't be guaranteed.

Setting the pulse rate to 0 disables pulsing for all views in the window.

See also: BView::Pulse(), the BView constructor

void SetSizeLimits (  float  min_h,
float  max_h,
float  min_v,
float  max_v
) 
 

These functions set 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 , 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.

Parameters:
min_h minimum width
max_h maximum width
min_v minimum height
max_v maximum height
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 *  new_title  ) 
 

Replaces the current title with new_title. It also renames the window thread in the following format:

"w>newTitle"

where as many characters of the new_title are included in the thread name as will fit.

Parameters:
new_title Window title text

status_t SetType (  window_type  type  ) 
 

Changes the type of the window to the specified value.

Parameters:
type Window type
See also:
window_type

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
) 
 

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.

Parameters:
mode 
h 
hOffset (default is 0)
width (default is 0)
width (default is 0)
widthOffset (default is 0)
v (default is 0)
vOffset (default is 0)
height (default is 0)
heightOffset (default is 0)
Returns:
B_NO_ERROR on success

B_ERROR otherwise

void SetWindowColor (  rgb_color  color  ) 
 

void SetWorkspaces (  uint32  space  ) 
 

This function set the set of workspaces where the window can be displayed. The space 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.

Parameters:
space Set of workspaces where the window can be displayed
You can pass B_CURRENT_WORKSPACE as the spaces 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 SetZoomLimits (  float  max_h,
float  max_v
) 
 

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 Show (   )  [virtual]
 

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.

Reimplemented in BDirectWindow, BWindowScreen, and BDirectGLWindow.

void Sync (   )  const
 

This function cause this window's App Server-bound messages to be sent 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.

const char * Title (   )  const
 

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.

window_type Type (   )  const
 

Returns:
The type of window. You normally set the window's type when it's constructed.

status_t UISettingsChanged (  const BMessage *  changes,
uint32  flags
)  [virtual]
 

status_t UpdateFrameState (  const BMessage &  changes  ) 
 

void UpdateIfNeeded (   ) 
 

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.

Forcing an Update while Responding to an Event for details and an example.

void WindowActivated (  bool  state  )  [virtual]
 

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

Reimplemented in BDirectWindow, BWindowScreen, and BDirectGLWindow.

rgb_color WindowColor (   )  const
 

void WorkspaceActivated (  int32  ws,
bool  state
)  [virtual]
 

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

Reimplemented in BDirectWindow, BWindowScreen, and BDirectGLWindow.

uint32 Workspaces (   )  const
 

This function return the set of workspaces where the window can be displayed.

Returns:
Set of workspaces

void WorkspacesChanged (  uint32  old_ws,
uint32  new_ws
)  [virtual]
 

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 old_ws to new_ws. 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 old_ws and new_ws masks.

Parameters:
old_ws Old workspace
new_ws New Workspace
The default (BWindow) version of this function is empty.

See also:
"B_WORKSPACES_CHANGED" in the Message Protocols appendix, SetWorkspaces()

Reimplemented in BDirectWindow, and BDirectGLWindow.

void Zoom (   ) 
 

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.

void Zoom (  BPoint  rec_pos,
float  rec_width,
float  rec_height
)  [virtual]
 

Hook function.

See also:
Zoom()

Reimplemented in BDirectWindow, and BDirectGLWindow.

Friends And Related Function Documentation

friend class _CEventPort_ [friend]
 

status_t _safe_get_server_token_ (  const BLooper *  l,
int32 *  token
)  [friend]
 

Reimplemented from BLooper.

void _set_menu_sem_ (  BWindow *  w,
sem_id  sem
)  [friend]
 

friend class BApplication [friend]
 

Reimplemented from BLooper.

friend class BBitmap [friend]
 

friend class BControl [friend]
 

friend class BDirectWindow [friend]
 

friend class BFilePanel [friend]
 

friend class BMenuItem [friend]
 

friend class BScrollBar [friend]
 

friend class BView [friend]
 

Reimplemented from BLooper.

friend class BWindowScreen [friend]
 

Copyright 2005 by yellowTAB GmbH, Be Inc., Palm Source Inc. and their respective legal successors
All rights reserved.