Derived from: public BLooper
Declared in: <app/Application.h>
The BApplication class defines an object that represents and serves the entire application. Every Be application must have one (and only one) BApplication object. It's usually the first object the application constructs and the last one it deletes.
The BApplication object has these primary responsibilities:
The user interface mainly centers on windows and is defined in the Interface Kit. The BApplication object merely contains the elements that are common to all windows and specific to the application.
BApplication typically serves as the base class for a derived class that specializes it and extends it in ways that are appropriate for a particular application. It declares (and inherits declarations for) a number of hook functions that you can implement in a derived class to augment and fine-tune what it does.
For example, your application might implement a RefsReceived() function to open a document and display it in a window, or a ReadyToRun() function to finish initializing the application after it has been launched and has started to receive messages. These two functions, like a handful of others, are called in response to system messages that have application-wide import. Hook functions for application messages were discussed in the introduction on page 17.
If you expect your application to get messages from remote sources, or its main thread to get messages from other threads in the application, you should also implement a MessageReceived() function to sort through them as they arrive.
A derived class is also a good place to record the global properties of your application and to define functions that give other objects access to those properties.
The BApplication object must be constructed before the application can begin running or put a user interface on-screen. Other objects in other kits depend on the BApplication object and its connection to the Application Server. In particular, you can't construct BWindow objects in the Interface Kit until the BApplication object is in place.
Simply constructing the BApplication object forms the connection to the Server. The connection is severed when you quit the application and delete the object.
The BApplication constructor assigns the new object to a global variable, be_app. This assignment is made automatically--you don't have to create the variable or set its value yourself. be_app is declared in app/Application.h and can be used throughout the code you write (or, more accurately, all code that directly or indirectly includes Application.h).
The be_app variable is typed as a pointer to an instance of the BApplication class. If you use a derived class instead--as most applications do--you have to cast the be_app variable when you call a function that's implemented by the derived class.
((MyApplication *)be_app)->DoSomethingSpecial();
Casting isn't required to call functions defined in the BApplication class (or in the BHandler and BLooper classes it inherits from), nor is it required for virtual functions defined in a derived class but declared by BApplication (or by the classes it inherits from).
Because of its pivotal role, the BApplication object is one of the first objects, if not the very first object, the application creates. It's typically created in the main() function. The job of main() is to set up the application and turn over its operation to the various message loops run by particular objects, including the main message loop run by the BApplication object.
After constructing the BApplication object (and the other objects that your application initially needs), you tell it to begin running the message loop by calling its Run() function. Like the Run() function defined in the BLooper class, BApplication's Run() initiates a message loop and begins processing messages. However, unlike the BLooper function, it doesn't spawn a thread; rather, it takes over the main application thread. Because it runs the loop in the same thread in which it was called, Run() doesn't return until the application is told to quit.
At its simplest, the main() function of a Be application would look something like this:
#include <app/Application.h> main() { . . . new BApplication('abcd'); . . . be_app->Run(); delete be_app; }
The number passed to the constructor ('abcd') sets the application's signature. This is just a precautionary measure. It's more common (and much better) to set the signature at compile time in a resource. If there is a resource, that signature is used and the one passed to the constructor is ignored.
The main() function shown above doesn't allow for the usual command-line arguments, argc and argv. It would be possible to have main() parse the argv array, but these arguments are also packaged in a B_ARGV_RECEIVED message that the application gets immediately after Run() is called. Instead of handling them within main() , applications generally implement an ArgvReceived() function to do the job. This function can also handle command-line arguments that are passed to the application after it has been launched; it can be called at any time while the application is running.
When an application is launched, it may be passed messages that affect how it configures itself. These are the first messages that the BApplication object receives after Run() is called.
For example, when the user double-clicks a document icon to launch an application, the Browser passes the application a B_REFS_RECEIVED message with information about the document. When launched from the command line, the application gets a B_ARGV_RECEIVED message listing the command-line arguments. When launched by the BRoster object, it might receive an arbitrary set of configuration messages.
After all the messages passed on-launch have been received and responded to, the application gets a B_READY_TO_RUN message and its ReadyToRun() hook function is called. This is the appropriate place to finish initializing the application before it begins running in earnest. It's the application's last chance to present the user with its initial user interface. For example, if a document has not already been opened in response to an on- launch B_REFS_RECEIVED message, ReadyToRun() could be implemented to place a window with an empty document on-screen.
ReadyToRun() is always called to mark the transition from the initial period when the application is being launched to the period when it's up and running--even if it's launched without any configuration messages. The IsLaunching() function can let you know which period the application is in.
The main message loop terminates and Run() returns when Quit() is called. Because Run() doesn't spawn a thread, Quit() merely breaks the loop; it doesn't kill the thread or destroy the object (unlike BLooper's version of the function).
Quit() is usually called indirectly, as a byproduct of a B_QUIT_REQUESTED message posted to the BApplication object. The application is notified of the message through a QuitRequested() function call; it calls Quit() if QuitRequested() returns TRUE.
When Run() returns, the application is well down the path of terminating itself. main() simply deletes be_app, cleans up anything else that might need attention, and exits.
Applications with restricted launch behavior (B_EXCLUSIVE_LAUNCH and B_SINGLE_LAUNCH) may be launched anyway in violation of those restrictions. When this happens, the Run() function returns abruptly without processing any messages and the application quits as it normally does when Run() returns. Messages that carried on-launch information for the aborted application are redirected to the instance of the application that's already running.
Applications should be prepared for their main() functions to be executed in this abortive manner and guard against any undesired consequences.
You sometimes have to coordinate access to the BApplication object, since a single object serves the entire application and different parts of the application (windows, in particular) will be running in other threads. Locking ensures that one thread won't change the state of the application while another thread is changing the same aspect (or even just trying to examine it).
The BApplication object is locked automatically while the main thread is responding to a message, but it may have to be explicitly locked at other times.
This class inherits the locking mechanism--the Lock(), Unlock() , and LockOwner() functions--from BLooper. See that class for details.
AboutRequested() | Can be implemented to present the user with a window containing information about the application. |
Activate() | Activates the application by making one of its windows the active window; can be reimplemented to activate the application in some other way. |
AppActivated() | Can be implemented to do whatever is necessary when the application becomes the active application, or when it loses that status. |
ArgvReceived() | Can be implemented to parse the array of command-line arguments (or a similar array of argument strings). |
FilePanelClosed() | Can be implemented to take note when the file panel is closed. |
MenusWillShow() | Can be implemented to update the menus in the application's main menu hierarchy, just before they're shown on-screen. |
Pulse() | Can be implemented to do something over and over again. Pulse() is called repeatedly at roughly regular intervals in the absence of any other activity in the main thread. |
ReadyToRun() | Can be implemented to set up the application's running environment. This function is called after all messages the application receives on-launch have been responded to. |
RefsReceived() | Can be implemented to respond to a message that contains references to database records. Typically, the records are for documents that the application is being asked to open. |
VolumeMounted() | Can be implemented to take note when a new volume (a floppy disk, for example) is mounted. |
VolumeUnmounted() | Can be implemented to take whatever action is necessary just before a volume is unmounted. |
BApplication(ulong signature)
Establishes a connection to the Application Server, assigns signature as the application identifier if one hasn't already been set, and initializes the application-wide variable be_app to point to the new object.
The signature that's passed becomes the application identifier only if a signature hasn't been set in a resource file. It's preferable to assign the signature in a resource at compile time, since that enables the system to associate the signature with the application even when it's not running.
Every application must have one and only one BApplication object, typically an instance of a derived class. It's usually the first object that the application creates.
virtual ~BApplication(void)
Closes the application's windows, if it has any, without giving them a chance to disagree, kills the window threads, frees the BWindow objects and the BViews they contain, and severs the application's connection to the Application Server.
You can delete the BApplication object only after Run() has exited the main message loop. In the normal course of events, all the application's windows will already have been closed and freed by then.
See also: the BWindow class in the Interface Kit, QuitRequested()
virtual void AboutRequested(void)
Implemented by derived classes to put a window on-screen that provides the user with information about the application. The window typically displays copyright data, the version number, license restrictions, the names of the application's authors, a simple description of what the application is for, and similar information.
This function is called when the user operates the "About . . ." item in the main menu and a B_ABOUT_REQUESTED message is posted to the application as a result.
To set up the menu item, assign it a model message with B_ABOUT_REQUESTED as the command constant and the BApplication object as the target, as illustrated in the SetMainMenu() description on page 38 . The default main menu includes such an item.
See also: SetMainMenu() , the BMenu class in the Interface Kit
virtual void Activate(void)
Makes the application the active application by arbitrarily picking one of its windows and making it the active window. If the application doesn't have any windows, or if the chosen window happens to be hidden, the attempted activation will fail. < A surer method of activation will be provided in a future release. >
This function is called when the main thread receives a B_ACTIVATE message, which any application can send to any other application. The Browser uses this method to activate a running application when, for example, the user double-clicks its icon or selects it from the application menu.
However, Activate() is not called when the application is first launched or when the user makes one of its windows the active window. Therefore don't rely on it as a way of being notified that the application has become active. Rely on AppActivated() instead.
See also: activate_app() and BWindow::Activate() in the Interface Kit, AppActivated()
virtual void AppActivated(bool isActive)
Implemented by derived classes to take note when the application becomes --or ceases to be--the active application. The application has just attained that status if the isActive flag is TRUE, and just lost it if the flag is FALSE. The active application is the one that owns the current active window and whose main menu is accessible through the icon displayed at the left top corner of the screen.
< Currently, this function is called only when the change in active application is a consequence of a window being activated. It can be called while an application is being launched, provided that the application puts a window on-screen. However, it's always called after ReadyToRun(), not before. >
See also: BWindow::WindowActivated() in the Interface Kit, B_APP_ACTIVATED in the Message Protocols appendix
virtual void ArgvReceived(int argc, char **argv)
Implemented by derived classes to respond to a B_ARGV_RECEIVED message that passes the application an array of argument strings, typically arguments typed on the command line. argv is a pointer to the strings and argc is the number of strings in the array. These parameters are identical to those traditionally associated with the main() function.
When an application is launched from the command line, the command-line arguments are both passed to main() and packaged in a B_ARGV_RECEIVED message that's sent to the application on-launch (before ReadyToRun() is called). When BRoster's Launch() function is passed argc and argv parameters, they're similarly bundled in an on-launch message.
An application might also get B_ARGV_RECEIVED messages after it's launched. For example, imagine a graphics program called "Splotch" that can handle multiple documents and is therefore restricted so that it can't be launched more than once (it's a B_SINGLE_LAUNCH or a B_EXCLUSIVE_LAUNCH application). If the user types
Splotch myArtwork
in a shell, it launches the application and passes it an on-launch B_ARGV_RECEIVED message with the strings "Splotch" and "myArtwork". Then, if the user types
Splotch yourArtwork
the running application is again informed with a B_ARGV_RECEIVED message. In both cases, the BApplication object dispatches the message by calling this function.
To open either of the artwork files, the Splotch application will need to translate the document pathname into a database reference. It can do this most easily by calling get_ref_for_path() , defined in the Storage Kit.
See also: RefsReceived() , B_ARGV_RECEIVED in the Message Protocols appendix
long CountWindows(void) const
Returns the number of windows belonging to the application. The count includes only windows that the application explicitly created. It omits, for example, the private windows used by BBitmap objects.
See also: the BWindow class in the Interface Kit
virtual void DispatchMessage(BMessage *message, BHandler *target)
Augments the BLooper function to dispatch system messages by calling a specific hook function. The set of system messages that the BApplication object receives and the hook functions that it calls to respond to them are listed under Application Messages of the chapter introduction.
Other messages--those defined by the application rather than the Application Kit --are forwarded to the target BHandler's MessageReceived() function. Note that the target is ignored for most system messages.
DispatchMessage() locks the BApplication object and keeps it locked until the main thread has finished responding to the message.
You can override this function to dispatch your own messages differently.
See also: BLooper::DispatchMessage(), BHandler::MessageReceived()
virtual void FilePanelClosed(BMessage *message)
Implemented by derived classes to take note when the file panel is closed. The message argument contains information about how the panel was closed and its state at the time. It has B_PANEL_CLOSED as its what data member and may include entries under the names "frame" (the last frame rectangle of the panel), "directory" (the last directory it displayed), "marked" (the item that was marked in its list of filters), and "canceled" (whether the user closed the panel). Some of this information can be retained to configure the panel the next time it runs.
See also: B_PANEL_CLOSED in the Message Protocols appendix, RunFilePanel()
long GetAppInfo(app_info *theInfo) const
Writes information about the application into the app_info structure referred to by theInfo. The structure contains the application signature, the identifier for its main thread, a reference to its executable file in the database, and other information.
This function is the equivalent to the identically-named BRoster function --or, more accurately, to BRoster's GetRunningAppInfo()--except that it only provides information about the current application. The following code
app_info info; if ( be_app->GetAppInfo(&info) == B_NO_ERROR ) . . .
is simply a shorthand for:
app_info info; if ( be_roster->GetRunningAppInfo(be_app->Team(), &info) == B_NO_ERROR ) . . .
GetAppInfo() returns B_NO_ERROR if successful, and an error code if not.
See the BRoster function for the error codes and for a description of the information contained in an app_info structure.
See also: BRoster::GetAppInfo()
virtual void HandlersRequested(BMessage *message)
Responds to a B_HANDLERS_REQUESTED message by sending a B_HANDLERS_INFO reply. The reply supplies a BMessenger object for each requested BHandler that's associated with the BApplication object. The BMessengers are placed in the reply message under the name "handlers".
This version of HandlersRequested() interprets the request for handlers as a request for BLoopers belonging to the application. If the request message has an entry named "class" containing the string "BWindow", it limits the search for BLoopers to BWindow objects belonging to the application. If the BWindow class isn't specified, the search encompasses all BLoopers belonging to the BApplication, including BWindow objects.
If the message has an entry named "index", this function supplies a BMessenger for the BLooper at that index in the list of the application's BLoopers (or the BWindow at that index in the application's window list). If there's no "index" entry, but there is one labeled "name", it supplies a BMessenger for the BLooper (or BWindow) with the specified name.
If it can't find a BLooper (or BWindow) at the specified "index" or with the requested "name", this function doesn't supply any BMessengers, but rather puts the B_BAD_INDEX or B_NAME_NOT_FOUND error constant in the reply message in an entry named "error".
If neither an "index" nor a "name" is specified, it places BMessengers for all the application's BLoopers (or BWindows) in the "handlers" array. Failing that, it places B_ERROR in an "error" entry.
You can override this function to use a different protocol for requesting handlers, or to prevent the BApplication object from revealing information about any or all of its BLoopers.
See also: BLooper::HandlersRequested()
void HideCursor(void) void ShowCursor(void) void ObscureCursor(void)
HideCursor() removes the cursor from the screen. ShowCursor() restores it. ObscureCursor() hides it temporarily, until the user moves the mouse.
See also: SetCursor(), IsCursorHidden()
bool IsCursorHidden(void) const
Returns TRUE if the cursor is hidden (but not obscured), and FALSE if not.
See also: HideCursor()
bool IsLaunching(void) const
Returns TRUE if the application is in the process of launching --of getting itself ready to run--and FALSE once the ReadyToRun() function has been called.
IsLaunching() can be called while responding to a message to find out whether the message was received on-launch (to help the application configure itself) or after-launch as an ordinary message.
See also: ReadyToRun()
virtual void MenusWillShow(void) const
Implemented by derived classes to make any necessary changes to the menus in the hierarchy controlled by the application's main menu before any of them is shown to the user. MenusWillShow() is called each time the main menu is placed on-screen, just before it's made visible.
See also: BWindow::MenusWillShow() in the Interface Kit, SetMainMenu()
virtual void Pulse(void)
Implemented by derived classes to do something at regular intervals. Pulse() is called regularly as the result of B_PULSE messages, as long as no other messages are pending. By default, pulsing is disabled --the pulse rate is set to 0.0--but you can enable it by calling the SetPulseRate() function to set an actual rate.
You can implement Pulse() to do whatever you want. However, pulse events aren't accurate enough for actions that require precise timing.
The default version of this function is empty.
See also: BWindow::Pulse() in the Interface Kit, SetPulseRate()
virtual void Quit(void)
Kills the application by terminating the message loop and causing Run() to return. You rarely call this function directly; it's called for you when the application receives a B_QUIT_REQUESTED message and QuitRequested() returns TRUE to allow the application to shut down.
BApplication's Quit() differs from the BLooper function it overrides in four important respects:
Before shutting down, the BApplication object responds to every message it received prior to the Quit() call.
See also: BLooper::Quit() , QuitRequested()
virtual bool QuitRequested(void)
Overrides the BLooper function to decide whether the application should really quit when requested to do so.
BApplication's implementation of this function tries to get the permission of the application's windows before agreeing to quit. It works its way through the list of BWindow objects that belong to the application and forwards the QuitRequested() call to each one. If a BWindow agrees to quit (its QuitRequested() function returns TRUE), the BWindow version of Quit() is called to destroy the window. If the window refuses to quit (its QuitRequested() function returns FALSE), the attempt to destroy the window fails and no other windows are asked to quit.
If it's successful in terminating all the application's windows (or if the application didn't have any windows to begin with), this function returns TRUE to indicate that the application may quit; if not, it returns FALSE.
An application can replace this window-by-window test of whether the application should quit, or augment it by adding a more global test. It might, for example, put a modal window on-screen that gives the user the opportunity to save documents, terminate on- going operations, or cancel the quit request.
This hook function is called for you when the main thread receives a B_QUIT_REQUESTED message; you never call it yourself. However, you do have to post the B_QUIT_REQUESTED message. Typically, the application's main menu has an item labeled "Quit." When the user invokes the item, it should post a B_QUIT_REQUESTED message directly to the BApplication object.
See also: BLooper::QuitRequested(), Quit() , SetMainMenu()
virtual void ReadyToRun(void)
Implemented by derived classes to complete the initialization of the application. This is a hook function that's called after all messages that the application receives on-launch have been handled. It's called in response to a B_READY_TO_RUN message that's posted immediately after the last on-launch message. If the application isn't launched with any messages, B_READY_TO_RUN is the first message it receives.
This function is the application's last opportunity to put its initial user interface on-screen. If the application hasn't yet displayed a window to the user (for example, if it hasn't opened a document in response to an on-launch B_REFS_RECEIVED or B_ARGV_RECEIVED message), it should do so in ReadyToRun() .
The default version of ReadyToRun() is empty.
See also: Run(), IsLaunching()
virtual void RefsReceived(BMessage *message)
Implemented by derived classes to do something with one or more database records that have been referred to the application in a message. The message has B_REFS_RECEIVED as its what data member and a single data entry named "refs" that contains one or more record_ref ( B_REF_TYPE) items.
Typically, the records are for documents that the application is requested to open. For example, unless an alternative message is specified, the user's selections in the file panel are reported to the application in a B_REFS_RECEIVED message. Similarly, when the user double-clicks a document icon in a Browser window, the Browser sends a B_REFS_RECEIVED message to the application that owns the document. In each case, the BApplication object dispatches the message by passing it to this function.
You can use the Storage Kit's does_ref_conform() function to discover what kind of record each item in the "refs" entry refers to. For example:
void MyApplication::RefsReceived(BMessage *message) { ulong type; long count; . . . message->GetInfo("refs", &type, &count); for ( long i = --count; i >= 0; i-- ) { record_ref item = message->FindRef("refs", i); if ( item.database >= 0 && item.record >= 0 ) { if ( does_ref_conform(item, "File") ) { BFile file; file.SetRef(item); if ( file.Open() == B_NO_ERROR ) . . . } else { BRecord *record = new BRecord(item); . . . } } } . . . }
REFS_RECEIVED messages can be received both on-launch (while the application is configuring itself) or after-launch (as ordinary messages received while the application is running).
See also: does_ref_conform() in the Storage Kit, ArgvReceived(), ReadyToRun() , IsLaunching(), B_REFS_RECEIVED in the Message Protocols appendix
virtual thread_id Run(void)
Runs a message loop in the application's main thread. This function must be called from main() to start the application running. The loop is terminated and Run() returns when Quit() is called, or (potentially) when a QUIT_REQUESTED message is received. It returns the identifier for the main thread (not that it's of much use once the application has stopped running).
This function overrides BLooper's Run() function. Unlike that function, it doesn't spawn a thread for the message loop or return immediately.
See also: the "Overview" to this class above, BLooper::Run(), ReadyToRun(), QuitRequested()
long RunFilePanel(const char *windowTitle = NULL, const char *openButtonLabel = NULL, const char *cancelButtonLabel = NULL, bool directoriesOnly = FALSE, BMessage *message = NULL) void CloseFilePanel(void) bool IsFilePanelRunning(void)
RunFilePanel() requests the Browser to display a window that lets the user navigate the file system to find desired files and directories. Its arguments are all optional and are used to configure the panel:
WishMaker : Open
This title reflects the fact that the panel is typically used to find files the application should open and display to the user.
If the message has any of the following entries, they will be used to help set up the panel:
Data name | Type code | Description |
---|---|---|
"directory" | B_REF_TYPE | The record_ref for the directory that the panel should display when it first comes on-screen. If this entry is absent, the panel will initially display the current directory of the current volume. |
"frame" | B_RECT_TYPE | A BRect that sets the size and position of the panel in screen coordinates. If this entry is absent, the Browser will choose an appropriate frame rectangle for the panel. |
"filter" | B_STRING_TYPE | An array of labels for items that should be displayed in a Filters pop-up menu. The items will be listed in the menu in the same order that they're added to the array. If this item is absent, the file panel won't display a Filters list. |
"marked" | B_STRING_TYPE | The label that should be marked in the Filters menu. If this item is absent, the first item in the list will be marked. |
If the panel is to have a Filters menu, the message should have one additional entry for each label in the "filter" array. This entry should list the file types associated with the label and have the label as its name. For example:
BMessage *model = new BMessage(OPEN_THESE); model->AddString("filter", "All files"); model->AddString("filter", "Picture files only"); model->AddString("filter", "Text files only"); model->AddString("filter", "Picture & text files"); model->AddLong("All files", 0); model->AddLong("Picture files only", MY_IMAGE_A_FILE_TYPE); model->AddLong("Picture files only", MY_IMAGE_B_FILE_TYPE); model->AddLong("Text files only", MY_TEXT_FILE_TYPE); model->AddLong("Picture & text files", MY_IMAGE_A_FILE_TYPE); model->AddLong("Picture & text files", MY_IMAGE_B_FILE_TYPE); model->AddLong("Picture & text files", MY_TEXT_FILE_TYPE); be_app->RunFilePanel(NULL, NULL, FALSE, model);
When the user selects a particular filter item, the file panel eliminates files of other types from the display. It shows only files with types associated with the selected item (and directories).
If an item is associated with a file type of 0--as is "All files" in the example above --it won't restrict the display. When the item is selected, the file panel shows every file in the directory. Generally, "All files" should be the first item in the menu and the one that's initially marked.
When the user operates the "Open" (or openButtonLabel) button, the file panel sends a message to the BApplication object. If a customized message is provided, it's used as the model for the message that's sent. If a message isn't provided, a standard B_REFS_RECEIVED message is sent instead. It has one data entry:
Data name | Type code | Description |
---|---|---|
"refs" | B_REF_TYPE | References to the database records for the files or directories selected by the user. |
If the user selects more than one file or directory, there will be more than one record_ref item in the "refs" array.
A customized message works much like the model messages assigned to BControl objects and BMenuItems in the Interface Kit. The file panel makes a copy of the model, adds a "refs" entry (as described above) to the copy, and delivers the copy to the BApplication object. All other entries, including those used to configure the panel, remain unchanged. The message can have any command constant you choose, including B_REFS_RECEIVED.
The file panel automatically disappears when the user operates the "Open" (or openButtonLabel) button--provided that the message has B_REFS_RECEIVED as the command constant. If it has a customized constant, it remains on-screen until CloseFilePanel() is called (or until the application quits). You can choose to close the panel if the user makes a valid selection, or you can leave it on-screen so the user can continue making selections. IsFilePanelRunning() will report whether the file panel is currently displayed on-screen.
The user can close the file panel by operating the "Cancel" (or cancelButtonLabel) button. Whenever the panel is closed, by the user or the application, a B_PANEL_CLOSED message is sent to the application and the FilePanelClosed() hook function is called.
RunFilePanel() returns B_NO_ERROR if it succeeds in getting the Browser to put the file panel on-screen. If the Browser isn't running or the file panel is already on-screen, it returns B_ERROR. If the Browser is running but the application can't communicate with it, it returns an error code that indicates what went wrong; these codes are the same as those documented for BMessenger's Error() function.
See also: RefsReceived() , FilePanelClosed()
void SetMainMenu(BPopUpMenu *menu) BPopUpMenu *MainMenu(void)
These functions set and return the application's main menu, the menu that's accessible through the icon that the Browser displays at the left top corner of the screen while the application is the current active application. Because it isn't under the control of a BMenuBar, this menu must be a kind of BPopUpMenu (but one that doesn't operate in radio mode or mark the selected item).
The main menu contains items that affect the application as a whole, rather than ones that affect operations within a particular window. The first item in the menu should be labeled "About" plus the name of the application and the three dots of an ellipsis. The last item should be "Quit". A default main menu with just these two items is provided for every application. You can set up your own menu in the following manner:
BMenuItem *item; BPopUpMenu *menu = new BPopUpMenu("", FALSE, FALSE); item = new BMenuItem("About <application name>...", new BMessage(B_ABOUT_REQUESTED)); item->SetTarget(be_app); menu->AddItem(item); item = new BMenuItem("Preferences", new BMessage(SET_PREFERENCES)); item->SetTarget(be_app); menu->AddItem(item); item = new BMenuItem("Open", new BMessage(SHOW_FILE_PANEL)); item->SetTarget(be_app); menu->AddItem(item); item = new BMenuItem("Quit", new BMessage(B_QUIT_REQUESTED)); item->SetTarget(be_app); menu->AddItem(item); be_app->SetMainMenu(menu);
B_ABOUT_REQUESTED and B_QUIT_REQUESTED are system messages that are dispatched by calling the AboutRequested() and QuitRequested() hook functions. The other messages in this example would be dispatched by calling MessageReceived().
See also: AboutRequested() , QuitRequested()
void SetCursor(const void *cursor)
Sets the cursor image to the bitmap specified in cursor. Each application has control over its own cursor, and can set and reset it as often as necessary. The cursor on-screen will have the shape specified in cursor as long as the application remains the active application. If it loses that status and then regains it again, its current cursor is automatically restored.
The first four bytes of cursor data is a preamble that gives information about the image, as follows:
To locate the hot spot, assume that the pixel in the upper left corner of the cursor image is at (0, 0). Identify the vertical y coordinate first, then the horizontal x coordinate. For example, a hot spot 5 pixels to the right of the upper left corner and 8 pixels down--at (5, 8)--would be specified as "8, 5."
Image data follows these four bytes. Pixel values are specified from left to right in rows starting at the top of the image and working downward. First comes data specifying the color value of each pixel in the image. In a one-bit-per-pixel image, 1 means black and 0 means white.
Following the color data is a mask that indicates which pixels in the image square are transparent and which are opaque. Transparent pixels are marked 0; they let whatever is underneath that part of the cursor bitmap show through. Opaque pixels are marked 1.
The Application Kit defines two standard cursor images. Each is represented by a constant that you can pass to SetCursor():
B_HAND_CURSOR | The hand image that's seen when the computer is first turned on. This is the default cursor. |
B_I_BEAM_CURSOR | The standard I-beam image for selecting text. |
See also: HideCursor()
void SetPulseRate(double microseconds)
Sets how often Pulse() is called (how often B_PULSE messages are posted). The interval set should be a multiple of 100,000.0 microseconds (0.1 second); differences less than 100,000.0 microseconds will not be noticeable. A finer granularity can't be guaranteed.
The default pulse rate is 0.0, which disables the pulsing mechanism. Setting a different rate enables it.
See also: Pulse()
virtual void VolumeMounted(long volume) virtual void VolumeUnmounted(long volume)
Implemented by derived classes to take action when a volume (typically a floppy disk) is mounted or unmounted. The volume is mounted just before VolumeMounted() is called and unmounted just after VolumeUnmounted() returns.
The volume identifier can be passed to the BVolume constructor to get an object corresponding to the volume.
Currently, there's no way to prevent a volume from being mounted or unmounted.
See also: the BVolume class in the Storage Kit
BWindow *WindowAt(long index) const
Returns the BWindow object recorded in the list of the application's windows at index, or NULL if index is out-of-range. Indices begin at 0, and there are no gaps in the list. Windows aren't listed in any particular order (such as the order they appear on-screen), so the value of index has no ulterior meaning. The window list excludes the private windows used by BBitmaps and other objects, but it doesn't distinguish main windows that display documents from palettes, panels, and other supporting windows.
This function can be used to iterate through the window list:
BWindow *window; long i = 0; while ( window = be_app->WindowAt(i++) ) { if ( window->Lock() ) { . . . window->Unlock(); } }
This works as long as windows aren't being created or deleted while the list index is being incremented. Locking the BApplication object doesn't lock the window list.
It's best for an application to maintain its own window list, one that arranges windows in a logical order, keeps track of any contingencies among them, and can be locked while it's being read.
See also: CountWindows()
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.