Message Constants

Container Messages

• B_MIME_DATA

• B_SIMPLE_DATA

A few constants identify messages as data containers. The system currently uses the B_MIME_DATA and B_SIMPLE_DATA constants to mark the containers it constructs for drag-and-drop operations.

B_MIME_DATA

This message constant indicates that all the data in the message is identified by MIME type names. The type code of every data field is B_MIME_TYPE and the name of each field is the MIME type string.

As an example, a BTextView object puts together a B_MIME_DATA message for drag-and-drop operations. The message has the text itself in a field named “text/plain”; the text_run_array structure that describes the character formats of the text is in a field named “application/x-vnd.Be-text_run_array”.

B_SIMPLE_DATA

This message is a package for a single data element. If there are multiple data fields in the message, they present the same data in various formats.

For example, when the user drags selected files and directories from a Tracker window, the Tracker packages entry_ref references to them in a B_SIMPLE_DATA message. The references are in a refs array with a type code of B_REF_TYPE. In other words, the message has the same structure as a B_REFS_RECEIVED message, but a different what constant.

Selection Messages

• B_CUT

• B_COPY

• B_PASTE

• B_SELECT_ALL

Declared in: app/AppDefs.h

These messages are sent to BTextView and BWindow classes (which normally passes the message to a BTextView instance) to cut, copy, paste and select all items respectively.

B_CUT

Removes the selected items and moves it to the clipboard.

The Command+X key combination is normally mapped to B_CUT

B_COPY

Copies the selected items to the clipboard.

The Command+C key combination is normally mapped to B_COPY

B_PASTE

Pastes items stored in the clipboard into the view.

The Command+V key combination is normally mapped to B_PASTE

B_SELECT_ALL

Selects all the items in the clipboard into the view.

The Command+A key combination is normally mapped to B_SELECT_ALL

Status Bar Messages

B_UPDATE_STATUS_BAR

Purpose:	Deliverable
Source:	Your app.
Target:	The BStatusBar you’re updating.
Hook:	BStatusBar::Update()

You construct and send this message to a BStatusBar object to tell it to (asynchronously) update its progress. To send the message, invoke BWindow’s PostMessage() naming the target BStatusBar as the handler:

statusBar->Window()->PostMessage(theMessage, statusBar);

Field	Type code	Description
delta	B_FLOAT_TYPE	An increment to the object’s current value.
text	B_STRING_TYPE	The object’s new text (NULL-terminated).
trailing_text	B_STRING_TYPE	The object’s new trailing text (NULL-terminated)..

B_RESET_STATUS_BAR

Purpose:	Deliverable
Source:	Your app.
Target:	Reset()
Hook:	The BStatusBar you’re resetting.

You construct and send this message to a BStatusBar object to tell it to (asynchronously) reset itself. The message also lets you reset the object’s labels. To send the message, invoke BWindow’s PostMessage() naming the target BStatusBar as the handler:

statusBar->Window()->PostMessage(theMessage, statusBar);

Field	Type code	Description
label	B_STRING_TYPE	The object’s new label (NULL-terminated).
trailing_label	B_STRING_TYPE	The object’s new trailing label (NULL-terminated)..

General Constants

B_CONTROL_INVOKED

Purpose:	Deliverable
Source:	A BControl.
Target:	Selected BMessenger.

This message is sent to the targeted messenger when a BControl-derived object is invoked.

Keyboard Messages

B_KEY_DOWN

Purpose:	Deliverable
Source:	The system.
Target:	The focus view’s BWindow.
Hook:	BView::KeyDown() (B_KEY_DOWN) BView::KeyUp() (B_KEY_UP) (The …UNMAPPED… messages don’t map to hook functions.)

B_KEY_DOWN is sent when the user presses (or holds down) a key that’s mapped to a character; B_KEY_UP is sent when the user releases the key. B_UNMAPPED_KEY_DOWN and B_UNMAPPED_KEY_UP are sent if the key isn’t mapped to a character. This doesn’t include modifier keys, which are reported in the B_MODIFIERS_CHANGED message.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
key	B_INT32_TYPE	The code for the physical key that was pressed. See for the key map.
be:key_repeat (B_KEY_DOWN only)	B_INT32_TYPE	The “iteration number” of this key down. When the user holds the key down, successive messages are sent with increasing key repeat values. This field isn’t present in the initial event; the first repeat message (i.e., the second key down message) has a key repeat value of 1.
modifiers	B_INT32_TYPE	The modifier keys that were in effect at the time of the event. See for a list of values.
states	B_UINT8_TYPE	The state of all keys at the time of the event. See .
byte [3] (B_KEY_DOWN and B_KEY_UP only)	B_INT8_TYPE	The UTF8 data that’s generated
bytes (B_KEY_DOWN and B_KEY_UP only)	B_STRING_TYPE	The string that’s generated. (The string usually contains a single character.)
raw_char (B_KEY_DOWN and B_KEY_UP only)	B_INT32_TYPE	Modifier-independent ASCII code for the character.

B_MODIFIERS_CHANGED

Purpose:	Deliverable
Source:	The system.
Target:	The focus view’s window.
Hook:

Sent when the user presses or releases a modifier key.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
modifiers	B_INT32_TYPE	The current modifier keys.
be:old_modifiers	B_INT32_TYPE	The previous modifier keys.
states	B_UINT8_TYPE	The state of all keys at the time of the event. See .

Mouse Messages

B_MOUSE_DOWN

Purpose:	Deliverable
Source:	The system.
Target:	The BWindow of the view the mouse is pointing to.
Hook:	BView::MouseDown()

Sent when the user presses a mouse button. This message is only sent if no other mouse button is already down.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
where	B_POINT_TYPE	Mouse location in the view’s coordinate system.
modifiers	B_INT32_TYPE	The modifier keys that were in effect at the time of the event.
buttons	B_INT32_TYPE	The mouse button that was pressed, one of: B_PRIMARY_MOUSE_BUTTON, B_SECONDARY_MOUSE_BUTTON, B_TERTIARY_MOUSE_BUTTON
clicks	B_INT32_TYPE	1 for a single-click, 2 for double-click, 3 for triple-click, and so on. The counter is reset if the time between clicks exceeds the “Double-click speed” set by the user in the Mouse preferences. Note that the counter is not reset if the mouse moves between clicks.

B_MOUSE_MOVED

Purpose:	Deliverable
Source:	The system.
Target:	The BWindow of the view the mouse is pointing to.
Hook:	BView::MouseMoved()

Sent when the user moves the mouse.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
where	B_POINT_TYPE	The mouse’s new location in window coordinates.
buttons	B_INT32_TYPE	The mouse buttons that are down. Zero or more of: B_PRIMARY_MOUSE_BUTTON, B_SECONDARY_MOUSE_BUTTON, B_TERTIARY_MOUSE_BUTTON

B_MOUSE_UP

Purpose:	Deliverable
Source:	The system.
Target:	BWindow of the view the mouse is pointing to.
Hook:	BView::MouseUp()

Sent when the user releases a mouse button. It’s only sent if no other mouse button remains down.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
where	B_POINT_TYPE	Mouse location in the view’s coordinate system.
modifiers	B_INT32_TYPE	The modifier keys that were in effect at the time of the event.

B_MOUSE_WHEEL_CHANGED

Purpose:	Deliverable
Source:	The system.
Target:	The BWindow of the view the mouse is pointing to.
Hook:

Sent when the user moves the mouse wheel (on mice that have them).

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
be:wheel_delta_x	B_FLOAT_TYPE	How much the Y value of the wheel has changed.
be:wheel_delta_y	B_FLOAT_TYPE	How much the Y value of the wheel has changed.

The standard mouse driver that comes with BeOS only supports a Y-oriented wheel.

B_PRINTER_CHANGED

Purpose:	Deliverable
Source:	The Print Server.
Target:	Everyone.
Hook:

Sent whenever the user changes printers. Applications that support printing should watch for this message, and if they receive it, they should suggest that the user check their page setup the next time they choose to print.

B_SCREEN_CHANGED

Purpose:	Deliverable
Source:	The system.
Target:	Every BWindow in the screen that changed (even hidden windows).
Hook:	BWindow::ScreenChanged()

Sent when the screen’s dimensions or color space changes—because the user played with the Screen preferences app, for example.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
frame	B_RECT_TYPE	The screen’s dimensions.
mode	B_INT32_TYPE	The screen’s color space: B_CMAP8, B_RGB15, B_RGB15, or BRGB32.

B_VALUE_CHANGED

Purpose:	Deliverable
Source:	The system.
Target:	The manipulated scrollbar’s BWindow.
Hook:	BScrollBar::ValueChanged()

Sent when the user plays with a scrollbar.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
value	B_INT32_TYPE	The scrollbar’s new value.

View Messages

B_VIEW_MOVED

Purpose:	Deliverable
Source:	The system.
Target:	The moved view’s BWindow.
Hook:	BView::FrameMoved()

Sent when a view’s origin (left top corner) changes relative to the origin of its parent. The message isn’t sent if the view doesn’t have the B_FRAME_EVENTS flag set.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
where	B_POINT_TYPE	The view’s new origin in the coordinate system of its parent.

B_VIEW_RESIZED

Purpose:	Deliverable
Source:	The system.
Target:	The resized view’s BWindow.
Hook:	BView::FrameResized()

Sent when the size of the view’s frame changes. The message isn’t sent if the view doesn’t have the B_FRAME_EVENTS flag set.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
width	B_INT32_TYPE	The view’s new width.
height	B_INT32_TYPE	The view’s new height.
where	B_POINT_TYPE	The view’s new origin expressed in the coordinate system of its parent. This field is only included if the view actually moved while being resized, and can always be ignored: If the view did move, you’ll hear about it in a separate B_VIEW_MOVED BMessage.

Window Messages

B_WINDOW_ACTIVATED

Purpose:	Deliverable
Source:	The system.
Target:	The activated/deactivated BWindow.
Hook:	BWindow::WindowActivated() and BView::WindowActivated()

Sent just after a window is activated or deactivated. Note that the BWindow invokes WindowActivated() on each of its views.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
active	B_BOOL_TYPE	true if the window is now active; false if not.

B_WINDOW_MOVE_BY

Purpose:	Deliverable.
Source:	Your application.
Target:	The BWindow to be moved.
Hook:

You can send this message to a window to resize it by the specified deltas.

Field	Type code	Description
data	B_POINT_TYPE	The amount by which to move the window’s X and Y coordinates.

B_WINDOW_MOVE_TO

Purpose:	Deliverable.
Source:	Your application.
Target:	The BWindow to be moved.
Hook:

You can send this message to a window to resize it to the specified size.

Field	Type code	Description
data	B_POINT_TYPE	The width and height (in X and Y) to resize the window to.

B_WINDOW_MOVED

Purpose:	Deliverable
Source:	The system.
Target:	BWindow that moved.
Hook:	BWindow::FrameMoved()

Sent when a window’s origin (left top corner) changes within the screen coordinate system.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
where	B_POINT_TYPE	The window’s new origin in screen coordinates.

B_WINDOW_RESIZED

Purpose:	Deliverable
Source:	The system.
Target:	The resized BWindow.
Hook:	BWindow::FrameResized()

Sent when the size of the window’s frame changes. Note that the width and height fields measure the window’s content area—they don’t include the window border or window tab.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
width	B_INT32_TYPE	The width of the window’s content area.
height	B_INT32_TYPE	The height of the window’s content area.

B_WORKSPACE_ACTIVATED

Purpose:	Deliverable
Source:	The system.
Target:	Every BWindow in the activated and deactivated workspaces.
Hook:	BWindow::WorkspaceActivated()

Sent when the active workspace changes.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
workspace	B_INT32_TYPE	The index of the window’s workspace.
active	B_BOOL_TYPE	true if the workspace is now active; false if not.

B_WORKSPACES_CHANGED

Purpose:	Deliverable
Source:	The system.
Target:	The BWindow whose set of workspaces changed.
Hook:	BWindow::WorkspacesChanged()

Sent when there’s a change to the set of workspaces in which a window can appear.

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70
old	B_INT32_TYPE	The window’s old workspace set, given as a vector of workspace indices.
new	B_INT32_TYPE	The window’s new workspace set, given as a vector of workspace indices.

B_ZOOM

Purpose:	Deliverable
Source:	The system.
Target:	The BWindow that was zoomed.
Hook:	BWindow::Zoom()

Sent when the user clicks a window’s zoom button.

The message has just one data field:

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70

B_OPEN_IN_WORKSPACE

Purpose:	Deliverable
Source:	The system.
Target:	BApplication.
Hook:

Sent to an application when it’s first launched to tell it to open in a specific workspace. The message will be handled during the construction of the BApplication object.

Field	Type code	Description
be:workspace	B_INT32_TYPE	Workspace number into which the application should open.

B_MINIMIZE

Purpose:	Deliverable
Source:	The system or your app.
Target:	The BWindow that’s hidden/unhidden.
Hook:	BWindow::Minimize()

Sent when the user double-clicks a window’s title bar (to hide the window), or selects a window from the DeskBar’s window list (to unhide the window).

Field	Type code	Description
when	B_INT64_TYPE	Event time, in microseconds since 01/01/70.
minimize	B_BOOL_TYPE	true if the window is being hidden; false if it’s being unhidden.

BShelf Messages

B_ARCHIVED_OBJECT

Purpose:	Deliverable and format
Source:	A dragged replicant, or your app.
Target:	A (remote) application.
Hook:	BShelf::CanAcceptReplicantMessage()

As a deliverable:

The replicant system uses this message as a deliverable. If you’re using BDragger and BShelf objects, the message is created and delivered for you. You can also simulate a dragged replicant by archiving a view, setting the archive message’s command to B_ARCHIVED_OBJECT, and sending the message to a remote application. If the remote application has a BShelf object, the BShelf will pick up the message (through a BMessageFilter) and pass it to the hook function.

To create a simulated replicant message, you call Archive() on the view that you want to replicate, and add (at least) the add_on field to the archive message.

See BShelf and BDragger for more information about replicants.

As a format:

B_ARCHIVED_OBJECT should be used as the command constant for all archive messages. When you archive an object, the class field is automatically added to the archive message. All other fields must be added by your archiving code. See the BArchivable class for more information about archiving.

Field	Type code	Description
class [ ]	B_STRING_TYPE	An array of class names that gives the class hierarchy of the archived object.
add_on	B_STRING_TYPE	The signature of the library or application that knows how to create the archived object.
be:add_on_version	B_INT32_TYPE	The version of the add_on.
be:load_each_time	B_BOOL_TYPE	true: The add_on is loaded each time the object is unarchived. false: The add_on is loaded only if it isn’t already loaded.
be:unload_on_delete	B_BOOL_TYPE	Is the add_on unloaded when the unarchived object is deleted?
shelf_type (replicants only; optional)	B_STRING_TYPE	The type of shelf that you want to have display the replicant. A shelf’s type is its name, as assigned when it’s created.