This appendix details the formats for public messages produced and understood by Be system software. The list includes every system message, every Be-produced message that might find its way to your application (for example, through a drag and drop operation), and every kind of message that you can deliver to a Be application or a Be-defined class with a reasonable assurance that it will be understood.
For information on the messaging system, see Messaging in The Application Kit chapter.
Messages that are dispatched and handled in a message-specific manner are known as system messages. For the most part, these are messages that the system produces and that applications are expected to respond to (by implementing hook functions matched to the messages), but some are messages that applications must produce themselves. They can be grouped into two categories, based on the scope of the message and the kind of object that's expected to respond:
For information on the place of system messages in the messaging system, see System Messages in the introduction to The Application Kit chapter.
Application messages concern the application as a whole, rather than one specific window or thread. They're all received and handled by the BApplication object. See Application Messages in the BApplication class description for information on when they're produced and how they should be handled.
This message requests the BApplication object to put a window on-screen with information about the application. Every application should set up an About... menu item that will send the message to the BApplication object. The BApplication object dispatches the message by calling its own AboutRequested() function.
As defined, this message contains no data. However, since each application must initiate the message on its own and respond to it by implementing AboutRequested(), you can add information to it if it suits your purposes.
This message informs the application that it has become the active application, or that it has ceded that status to another application. The BApplication object dispatches the message by calling AppActivated().
It contains one data entry:
| Data name | Type code | Description |
|---|---|---|
| "active" | B_BOOL_TYPE | true if the application has just become the active application, and false if it just gave up that status. |
This message passes the BApplication object command-line strings, typically ones the user typed in a shell. The BApplication object dispatches it by calling ArgvReceived().
The message has the two expected data entries for command-line arguments:
| Data name | Type code | Description |
|---|---|---|
| "argc" | B_INT32_TYPE | The number of items in the "argv" array. This will be the same number that BMessage::GetInfo() for "argv" would report. |
| "argv" | B_STRING_TYPE | The command-line strings. Each argument is stored as an independent item under the "argv" name--that is, there's an array of data items, each of type char *, rather than a single item of type char **. |
This message contains no data. It's posted at regularly spaced intervals as a kind of timing mechanism. The BApplication object dispatches it by calling the Pulse() function declared in the BApplication class.
This message simply asks a BLooper object to quit its message loop and destroy itself. The BLooper dispatches it by calling its own QuitRequested() function. In other words, the generic dispatching of B_QUIT_REQUESTED messages is defined in the BLooper class.
When it gets the message, the BApplication object interprets it to be a request to shut the entire application down, not just one thread. Its QuitRequested() function consequently promulgates similar messages to all BWindow objects.
Typically a B_QUIT_REQUESTED message contains no data. However, if the source of the message is the Command-q shortcut, it will have one data entry:
| Data name | Type code | Description |
|---|---|---|
| "shortcut" | B_BOOL_TYPE | true, to indicate that the system produced the message when the user typed Command-q. If the message isn't the result of a shortcut, this entry will be absent, not false. |
This message contains no data entries. It's delivered to the BApplication object to mark the application's readiness to accept message input after being launched. The BApplication object dispatches it by calling ReadyToRun().
This message passes the application one or more references to entries in the file system. It's typically produced by the Tracker when the user chooses some files for the application to open. The BApplication object dispatches it by calling RefsReceived().
The message has one data entry, which might be an array of more than one item:
| Data name | Type code | Description |
|---|---|---|
| "refs" | B_REF_TYPE | One or more entry_ref items referring to files or directories. Typically, they're documents the application is expected to open. |
If a B_REFS_RECEIVED message is dropped on a Tracker window, the Tracker will deliver it to the preferred application for the documents in the "refs" array.
Interface messages inform BWindow objects and their BViews about activity in the user interface. Unlike application messages, most of which consist only of a command constant, almost all interface messages contain data fields describing an event. They're all delivered to a BWindow object, which dispatches some to itself but most to its BViews.
See Interface Messages in The Interface Kit chapter for a discussion of the events these messages report.
This message reports that the user pressed a character key on the keyboard. It's dispatched by calling the KeyDown() function of the target BView, generally the window's focus view. However, if a Command key is held down, the message performs a keyboard shortcut and is not dispatched. Most keys produce repeated B_KEY_DOWN messages--as long as the user keeps holding the key down and doesn't press another key.
Each message contains the following data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the key went down, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "key" | B_INT32_TYPE | The code for the key that was pressed. |
| "modifiers" | B_INT32_TYPE | A uint32 mask that identifies which modifier keys the user was holding down and which keyboard locks were on at the time of the event. |
| "byte" | B_INT8_TYPE | The character that's generated by the combination of the key and modifiers. The character encoding is Unicode UTF8, which may take from 1 to 3 bytes to represent the character. There's one uint8 item in the "byte" array for each byte in the representation. |
| "raw_char" | B_INT32_TYPE | A raw code for the character that's mapped to the key; it equals the ASCII code for the character, minus the effect of the modifier keys. |
| "states" | B_UINT8_TYPE | A bitfield that records the state of all keys and keyboard locks at the time of the event. Although declared as B_UINT8_TYPE, this is actually an array of 16 bytes entered into the message as a single item. |
For most applications, the "byte" character is sufficient to distinguish one sort of user action on the keyboard from another. It reflects both the key that was pressed and the effect that the modifiers have on the resulting character. For example, if the Shift key is down when the user presses the A key, or if Caps Lock is on, the "byte" produced will be uppercase 'A' rather than lowercase 'a'. If the Control key is down, it will be the B_HOME character. A later appendix, Keyboard Information, discusses the mapping of keys to characters in more detail.
Although the character is recorded as a UTF-8 array in the B_KEY_DOWN message, it's translated to the encoding of the BView's current font when passed to the KeyDown() function.
The "modifiers" mask explicitly identifies which modifier keys the user is holding down and which keyboard locks are on at the time of the event. The mask is formed from the following constants, which are explained under Modifier Keys in the Keyboard Information appendix.
The mask is empty if no keyboard locks are on and none of the modifiers keys are being held down.
The "key" code is an arbitrarily assigned number that identifies which character key the user pressed. All keys on the keyboard, including modifier keys, have key codes (but only character keys produce key-down events). The codes for the keys on a standard keyboard are shown in the Key Codes section of the Keyboard Information appendix.
The "states" bitfield captures the state of all keys and keyboard locks at the time of the key-down event. (At other times, you can obtain the same information through the Interface Kit's get_key_info() function.)
Although it's declared as B_UINT8_TYPE, the bitfield is really an array of 16 bytes,
uint8 states[16];
with one bit standing for each key on the keyboard. For most keys, the bit records whether the key is up or down. However, the bits corresponding to keys that toggle keyboard locks record the current state of the lock. To learn how to read the "states" array, see Key States in the Keyboard Information appendix.
This message reports that the user released a key on the keyboard. It's an exact reflection of a B_KEY_DOWN message. It has the same data fields as B_KEY_DOWN and is dispatched by calling the KeyUp() function of the BWindow's focus view. It most cases this will be the same BView that got the B_KEY_DOWN message, but not always. See Handling Keyboard Actions in The Interface Kit chapter for more detailed information on how both keyboard messages are dispatched.
This message instructs a BWindow to "minimize" itself--to remove the window from the screen so that it has only a minimal representation as an item in the application's desk bar menu--or to restore the full window to the screen. The message is produced when the user double-clicks the window tab or operates the menu item. It's dispatched by calling the BWindow's Minimize() function.
It contains the following data:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the user acted, as measured by the number of microseconds from the beginning of 1970. |
| "minimize" | B_BOOL_TYPE | A flag that's true if the window should be removed from the screen, and false if it should be restored to the screen from its minimized state. |
This message reports that the user pressed a mouse button while the cursor was over the content area of a window. It's produced only for the first button the user presses--that is, only if no other mouse buttons are down at the time. The BWindow dispatches it by calling the target BView's MouseDown() function.
The message contains the following information:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the mouse button went down, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "where" | B_POINT_TYPE | Where the cursor was located when the user pressed the mouse button, expressed in the coordinate system of the target BView--the view where the cursor was located at the time of the event. |
| "modifiers" | B_INT32_TYPE | A mask that identifies which modifier keys were down and which keyboard locks were on when the user pressed the mouse button. |
| "buttons" | B_INT32_TYPE | A mask that identifies which mouse button went down. |
| "clicks" | B_INT32_TYPE | An integer that counts the sequence of mouse-down events for multiple clicks. It will be 1 for a single-click, 2 for the second of a double-click, 3 for the third of a triple-click, and so on. |
The "modifiers" mask is the same as for key-down events and is described under Modifier Keys in the Keyboard Information appendix.
The "buttons" mask identifies mouse buttons by their roles in the user interface. It may be formed from one or more of the following constants:
| B_PRIMARY_MOUSE_BUTTON
B_SECONDARY_MOUSE_BUTTON B_TERTIARY_MOUSE_BUTTON |
Because a mouse-down event is reported only for the first button that goes down, the mask will usually contain just one constant.
The "clicks" integer counts clicks. It's incremented each time the user presses the mouse button within a specified interval of the previous mouse-down event, and is reset to 1 if the event falls outside that interval. The interval is a user preference that can be set with the Mouse preferences application.
Note that the only test for a multiple-click is one of timing between mouse-down events. There is no position test--whether the cursor is still in the vicinity of where it was at the time of the previous event. It's left to applications to impose such a test where appropriate.
This message is produced when the user moves the cursor into, within, or out of a window. Each message captures a small portion of that movement. Messages aren't produced if the cursor isn't over a window or isn't moving. The BWindow dispatches each message by calling the MouseMoved() function of every BView the cursor touched in its path from its last reported location.
The message contains the following data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the event occurred, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "where" | B_POINT_TYPE | The new location of the cursor, where it has moved to, expressed in window coordinates. |
| "buttons" | B_INT32_TYPE | Which mouse buttons, if any, are down. |
The "buttons" mask is formed from one or more of the following constants:
| B_PRIMARY_MOUSE_BUTTON
B_SECONDARY_MOUSE_BUTTON B_TERTIARY_MOUSE_BUTTON |
If no buttons are down, the mask is 0.
This message reports that the user released a mouse button. It's produced only for the last button the user releases--that is, only if no other mouse button remains down. The BWindow does not dispatch this message. However, you can look at it from a filter function or, indirectly, by calling BView's GetMouse().
The message contains the following data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the mouse button went up again, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "where" | B_POINT_TYPE | Where the cursor was located when the user released the mouse button, expressed in the coordinate system of the target BView--the view where the cursor was located when the button went up. |
| "modifiers" | B_INT32_TYPE | A mask that identifies which of the modifier keys were down and which keyboard locks were in effect when the user released the mouse button. |
The "modifiers" mask is the same as for key-down events and is described under Modifier Keys in the Keyboard Information appendix.
This message serves as a simple timing mechanism. It's posted at regularly spaced intervals and is dispatched by calling the Pulse() function of every BView that wants to participate.
The message typically lacks any data entries, but may contain this one:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the event occurred, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
This message is interpreted by a BWindow object as a request to close the window. It's dispatched by calling QuitRequested(), which is generally implemented by application classes derived from BWindow.
When the Application Server produces the message (for example, when the user clicks the window's close button), it adds the following data entry:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the event occurred, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
However, this information is not crucial to the interpretation of the event. You don't need to add it to B_QUIT_REQUESTED messages that are posted in application code.
This message reports that the screen configuration has changed. The BWindow dispatches it by calling its own ScreenChanged() function.
The message contains these data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the screen changed, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "frame" | B_RECT_TYPE | A rectangle with the same dimensions as the pixel grid the screen displays. |
| "mode" | B_INT32_TYPE | The color space of the screen--currently B_COLOR_8_BIT or B_RGB_32_BIT. |
This message reports that the Application Server changed a value associated with a scroll bar--something that will happen repeatedly as the user drags the scroll knob and presses the scroll buttons. The BWindow dispatches it by calling the BScrollBar object's ValueChanged() function.
The message has these data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the value changed, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "value" | B_INT32_TYPE | The new value of the object. For a horizontal scroll bar, this is the coordinate value that should be at the left side of the target view's bounds rectangle. For a vertical scroll bar, it's the value that should be at the top of the target's bounds rectangle. |
This message reports that a view moved within its parent's coordinate system. Repeated messages may be produced if the view is moving because its parent is being resized as an automatic consequence of the user resizing the window. The BWindow dispatches each message by calling its FrameMoved() function.
The message contains the following data:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the view moved, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "where" | B_POINT_TYPE | The new location of the left top corner of the view's frame rectangle, expressed in the coordinate system of its parent. |
A BView receives B_VIEW_MOVED notifications only if it asks for them with the B_FRAME_EVENTS flag.
This message reports that a view has been resized. Repeated messages are produced if the resizing is an automatic consequence of the window being resized. The BWindow dispatches each one by calling its FrameResized() function.
The message holds the following data.
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the view was resized, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "width" | B_INT32_TYPE | The new width of the view's frame rectangle. |
| "height" | B_INT32_TYPE | The new height of the view's frame rectangle. |
| "where" | B_POINT_TYPE | The new location of the left top corner of the view's frame rectangle, expressed in the coordinate system of its parent. (The message has a "where" entry only if resizing the view also served to move it. The new location of the view would first be reported in a B_VIEW_MOVED BMessage.) |
A BView receives B_VIEW_RESIZED notifications only if it asks for them with the B_FRAME_EVENTS flag.
This message reports that the window has become the active window or has relinquished that status. The BWindow dispatches the message by calling its WindowActivated() function, which notifies every BView with a similar function call.
The message contains two data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the window's status changed, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "active" | B_BOOL_TYPE | A flag that records the new status of the window. It's true if the window has become the active window, and false if it is giving up that status. |
This message reports that the window has been moved in the screen coordinate system. Repeated messages are generated when the user drags a window. The BWindow dispatches each one by calling its WindowMoved() function.
The message has the following entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the window moved, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "where" | B_POINT_TYPE | The new location of the left top corner of the window's content area, expressed in screen coordinates. |
This message reports that the window has been resized. It's generated repeatedly as the user moves a window border. The BWindow dispatches each message by calling WindowResized().
The message holds these data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the window was resized, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "width" | B_INT32_TYPE | The new width of the window's content area. |
| "height" | B_INT32_TYPE | The new height of the window's content area. |
This message reports that the active workspace has changed. It's delivered to all BWindow objects associated with the workspace that was previously active and with the one just activated. Each BWindow dispatches the message by calling its own WorkspaceActivated() function.
The message contains the following data:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the workspace was activated or deactivated, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "workspace" | B_INT32_TYPE | An index to the workspace that's the subject of the message. |
| "active" | B_BOOL_TYPE | A flag that records the new status of the workspace--true if it has become the active workspace, and false if it has ceased being the active workspace. |
This message informs a BWindow object that the set of workspaces with which it is associated has changed. The BWindow dispatches the message by calling its own WorkspacesChanged() function.
The message has three data entries:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the set of workspaces associated with the window changed, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
| "old" | B_INT32_TYPE | The set of workspaces where the window could appear before the change. |
| "new" | B_INT32_TYPE | The set of workspaces where the window can appear after the change. |
For this message, each workspace is identified by a bit in a 32-bit mask.
This message instructs the BWindow object to zoom the on-screen window to a larger size--or to return it to its normal size. The message is produced when the user operates the zoom button in the window's title tab. The BWindow dispatches it by calling Zoom(), declared in the BWindow class.
The message has just one data entry:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the zoom button was clicked, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
The operating system produces or understands a few standard messages that aren't system messages--that aren't matched to a specific hook function. They fall into several groups:
The following sections discuss each of these groups in turn.
The following three messages are sent as replies to other messages.
This message doesn't contain any data. The system sends it as a reply to a message that the receiving thread's chain of BHandlers does not recognize. See MessageReceived() in the BHandler class of the Application Kit.
This message doesn't contain any data. It's sent as a default reply to another message when the original message is about to be deleted. The default reply is sent only if a synchronous reply is expected and none has been sent. See the SendReply() function in the BMessage class of the Application Kit.
This constant merely identifies a message as a reply to a previous message. The data that's in the reply depends on the circumstances and, particularly, on the original message.
A handful of messages pass instructions to edit currently selected data or to alter the selection. Because BTextViews are the only kit-defined objects that know how to display editable data, they're the only ones that are set up to respond to these messages.
A BWindow posts these messages to its focus view (or to itself, if none of its views is currently in focus) when the user presses the Command-x, Command-c, Command-v, and Command-a shortcuts. It puts only one data entry in the message:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the user pressed the keyboard shortcut, as measured by the number of microseconds since 12:00:00 AM January 1, 1970. |
BTextView objects respond to these messages. See the BTextView class in the Interface Kit for details.
A few constants identify messages as data containers. The system currently uses these constants to mark the containers it constructs for drag-and-drop operations.
This message constant indicates that the message is an object archive. It contains data that captures the object's state at a particular time and that can be used to reconstruct the object. Among the data entries, there are two that system functions rely on:
| Data name | Type code | Description |
|---|---|---|
| "class" | B_STRING_TYPE | An array of class names, beginning with the name of the archived object's class. This information must be present in every archive. |
| "add_on" | B_STRING_TYPE | The signature for an add-on executable containing the code that defines the class of the archived object. This entry is optional. |
Note, however, that the Archive() functions that produce object archives don't set the what constant to B_ARCHIVED_OBJECT (or to anything at all). It's up to the caller to identify the archive message as appropriate. For example:
BMessage message(B_ARCHIVED_OBJECT); someObject->Archive(&message);
Typically, B_ARCHIVED_OBJECT is used when the message might be dragged and dropped. For example, when the BDragger and BShelf classes in the Interface Kit archive an object so that a "replicant" of it can be dragged, they add the B_ARCHIVED_OBJECT identifier.
See the Archive() function and the BArchivable class in the Support Kit for more information of archiving.
This message constant indicates that all the data in the message is identified by MIME type names. The type code of every data entry is B_MIME_TYPE and the name of each entry is the MIME type string.
A BTextView object puts together a B_MIME_DATA message for drag-and-drop operations. The message has the text itself in an entry named "text/plain"; the text_run_array structure that describes the character formats of the text is in an entry named "application/x-vnd.Be-text_run_array".
This message is a package for a single data element. If there are multiple data entries in the message, they present the same data in alternative formats.
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.
A BStatusBar object can be controlled synchronously by calling its Reset() and Update() functions. It can also be controlled asynchronously by sending it messages corresponding to the two functions; the object calls the function when it receives the message. Each standard message contains entries for the arguments passed to the function.
| Data name | Type code | Description |
|---|---|---|
| "label" | B_STRING_TYPE | A null-terminated string for the label displayed on the left. If this entry is omitted, a NULL label is passed to Reset(). |
| "trailing_label" | B_STRING_TYPE | A null-terminated string for the label displayed on the right. If this entry is omitted, a NULL trailing label is passed to Reset(). |
| Data name | Type code | Description |
|---|---|---|
| "delta" | B_FLOAT_TYPE | An increment to add to the current value of the object. The current value determines how much of the status bar is filled with the bar color. |
| "text" | B_STRING_TYPE | A null-terminated string for the text displayed on the left. If this entry is omitted, NULL is passed to Update() for the text. |
| "trailing_text" | B_STRING_TYPE | A null-terminated string for the text displayed on the right. If this entry is omitted, NULL is passed to Update() for the trailing text. |
This section of the documentation is not complete. See The Storage Kit chapter for information on the B_NODE_MONITOR and B_QUERY_UPDATE messages.
The file panel produces three messages: B_REFS_RECEIVED, B_SAVE_REQUESTED, and B_CANCEL. The first of these is a system message and was discussed under Application Messages above. It's produced when the user picks files to open from the panel. The other two messages are described below.
The file panel produces this message when the user requests the application to save a document. It has two data entries:
| Data name | Type code | Description |
|---|---|---|
| "directory" | B_REF_TYPE | An entry_ref referring to the directory where the document should be saved. |
| "name" | B_STRING_TYPE | The file name under which the document should be saved. |
This message is produced when the user hits the Cancel button in the panel. It contains the following two pieces of information:
| Data name | Type code | Description |
|---|---|---|
| "old_what" | B_INT32_TYPE | What the what data member of the BMessage would have been, had the user not canceled--either B_REFS_RECEIVED or B_SAVE_REQUESTED. |
| "source" | B_POINTER_TYPE | A pointer to the BFilePanel object. |
Applications are, of course, free to create B_CANCEL messages in other contexts and add whatever data to them the context demands.
See the BFilePanel class in The Storage Kit chapter for more information.
The scripting system defines four generic messages that can operate on the specific properties of an object--B_SET_PROPERTY, B_GET_PROPERTY, B_CREATE_PROPERTY, and B_DELETE_PROPERTY. The property is identified in the message as a B_STRING_TYPE entry named "property".
Scripting also uses another message, B_GET_SUPPORTED_SUITES, to request information about the set of messages an object responds to.
Full documentation on scripting and these messages is not complete, but will be available soon.
The messages that a user drags and drops on a view might have their source in any application, including applications (and objects) that come with the Be operating system. Currently, there are three sources for public, published messages that the user might drop on your application:
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified June 30, 1997.