# The Application Kit: BApplication

Derived from: public BLooper

Declared in: be/app/Application.h

Library: libbe.so

## Overview

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:

- It makes a connection to the Application Server. Any application that puts a window on-screen or relies on other system services needs this connection. It's made automatically when the BApplication object is constructed.

- It runs the application's main message loop. The BApplication object is a kind of BLooper, but instead of spawning an independent thread, it runs a message loop in the application's main thread (the thread that the `main()` function executes in). This loop receives and processes messages that affect the entire application, including the initial messages received from remote applications. It gets several messages from the Tracker (such as reports of what documents to open). Any application that's known to the Tracker or that cooperates with other applications needs a main message loop.

- It's the home for applicationwide elements of the user interface. For example, it's expected to put a panel on-screen with information about the application for the user, it keeps a list of the application's windows, and it also lets you set, hide, and show the application's cursor. The ability to define the look of the cursor is provided by BApplication's`SetCursor()` function.

  The user interface centers mainly 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.

### Derived Classes

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 applicationwide import. All of these messages and the hook functions that respond to them are discussed in the next section.

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.

### Application Messages

The BApplication object runs the main message loop where it receives application messages--system messages that are not the province of any particular window, but concern the application as a whole. For these messages, the BApplication object acts as both looper (receiving and dispatching the message) and handler (responding to the message).

All seven application messages report events. Two of them notify the application of a change in its status:

- The `B_READY_TO_RUN` message reports that the application has finished launching and configuring itself.

- The `B_APP_ACTIVATED` message is delivered when the application becomes the active application--the one that the user is currently engaged with--and when it relinquishes that status to another application.

Two of the messages are requests that the application typically makes of itself:

- A `B_QUIT_REQUESTED` message is taken by the BApplication object to be a request to shut the entire application down, not just one thread. An application that has a user interface usually interprets some user action (such as clicking a Quit menu item) as a request to quit and, in response, posts a `B_QUIT_REQUESTED` message to the BApplication object. An application that's the servant of other applications may get the request from a remote source.

- A `B_ABOUT_REQUESTED` message requests information about the application, usually through an About... menu item. The application should set up this item to deliver a `B_ABOUT_REQUESTED` message to the BApplication object. In response, the BApplication object should display a window with general information about the application.

Other application messages report information from remote sources:

- The `B_ARGV_RECEIVED` message is delivered either on-launch or after-launch when the application receives strings of characters the user typed on the command line, or when it's launched by another application and is passed a similar array of character strings.

- The `B_REFS_RECEIVED` message passes the application one or more references to entries (files or directories) in the file system. Typically, this means the user has chosen some files to open--by picking them in the file panel, double-clicking a document icon in a Tracker window, or dragging the icon and dropping it on the application icon.

The system is the source of one repeated message:

- Periodic `B_PULSE` messages are posted at regularly spaced intervals. They can be used to arrange repeated actions when precise timing is not critical.

All application messages are received by the BApplication object in the main thread. The object dispatches them all to itself; it doesn't delegate them to any other handler. The following chart lists the hook functions that are called to initiate the application's response to system messages and the base class where each function is declared:

Message type | Hook function | Class
`B_READY_TO_RUN` | `ReadyToRun()` | BApplication
`B_APP_ACTIVATED` | `AppActivated()` | BApplication
`B_QUIT_REQUESTED` | `QuitRequested()` | BLooper
`B_ABOUT_REQUESTED` | `AboutRequested()` | BApplication
`B_ARGV_RECEIVED` | `ArgvReceived()` | BApplication
`B_REFS_RECEIVED` | `RefsReceived()` | BApplication
`B_PULSE` | `Pulse()` | BApplication

`QuitRequested()` is first declared in the BLooper class. BApplication reinterprets it--and reimplements it--to mean a request to quit the whole application, not just one of its threads.

Only three application messages--`B_APP_ACTIVATED`, `B_ARGV_RECEIVED`, and `B_REFS_RECEIVED`--contain any data; the rest are empty. See "Application Messages" in the Message Protocols appendix for details on the content of these messages.

### Constructing the Object and Running the Message Loop

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.

#### be_app

The BApplication constructor assigns the new object to a global variable, `be_app`. `be_app` is declared in 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).

#### main()

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.

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.

The `main()` function of a Be application typically looks something like this:

       #include <app/Application.h>

       main()
       {
           . . .
           new BApplication("application/x-vnd.ORA-app5");
           . . .
           be_app->Run();
           delete be_app;
       }

The string passed to the constructor ("application/x-vnd.ORA-app5") 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 as an attribute and resource. If there is a compile-time signature, it's 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.

#### Configuration Messages Received on Launch

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

#### Quitting

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.

#### Aborted Run

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.

### Locking

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 other functions--from BLooper. See that class for details.

## Hook Functions

`AboutRequested()
` Can be implemented to present the user with a window containing information about the application.

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

`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 files and directories. Typically, the references are to documents that the application is being asked to open.

## Constructor and Destructor

### BApplication()

          BApplication(const char *signature)
          BApplication(BMessage *archive)

Establishes a connection to the Application Server, assigns signature as the application identifier if one hasn't already been set, and initializes the applicationwide 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 as a resource or file-system attribute. It's preferable to assign the signature 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.

Like other BHandlers, the BApplication object is archivable and can be reconstructed from a BMessage archive.

### ~BApplication()

          virtual ~BApplication()

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

## Static Functions

### Instantiate()

          static BApplication *Instantiate(BMessage *archive)

Returns a new BApplication object, allocated by `new` and created with the version of the constructor that takes a BMessage archive.

See also: `BArchivable::Instantiate()`, `instantiate_object()`, `Archive()`

## Member Functions

### AboutRequested()

          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 an About... menu item and a `B_ABOUT_REQUESTED` message is delivered to the BApplication object 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 follows:

       BMenuItem *item;
       item = new BMenuItem("About application name" B_UTF8_ELLIPSIS,
                                    new BMessage(B_ABOUT_REQUESTED));
       item->SetTarget(be_app);
       menu->AddItem(item);

See also: the BMenu class in the Interface Kit

### AppActivated()

          virtual void AppActivated(bool active)

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 active flag is `true`, and just lost it if the flag is `false`. The active application is the one that owns the current active window.

This function is called only when the change in active application is a consequence of a window being activated. It will be called when an application is 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

### Archive()

          virtual status_t Archive(BMessage *archive, bool deep = true) const

Calls the inherited version of `Archive()`, then adds the application signature to the BMessage archive.

See also: `BArchivable::Archive()`, `Instantiate()` static function

### ArgvReceived()

          virtual void ArgvReceived(int32 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 file 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

### CountWindows()

          int32 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

### DispatchMessage()

          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" in the overview.

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.

See also: `BLooper::DispatchMessage()`, `BHandler::MessageReceived()`

### GetAppInfo()

          status_t 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 file system, and other information.

This function is the equivalent to the identically named BRoster function--or, more accurately, to BRoster's `GetRunningAppInfo()`--except that it provides information only about the current application. The following code

       app_info info;
       if ( be_app->GetAppInfo(&info) == B_OK )
           . . .

is a shorthand for:

       app_info info;
       if ( be_roster->GetRunningAppInfo(be_app->Team(), &info) == B_OK )
           . . .

`GetAppInfo()` returns `B_OK` 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()`

### HideCursor(), ShowCursor(), ObscureCursor()

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

### IsCursorHidden()

          bool IsCursorHidden(void) const

Returns `true` if the cursor is hidden (but not obscured), and `false` if not.

See also: `HideCursor()`

### IsLaunching()

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

### MessageReceived()

          virtual void MessageReceived(BMessage *message)

Augments the BHandler version of `MessageReceived()` to handle scripting requests delivered to the BApplication object.

See also: `BHandler::MessageReceived()`

### ObscureCursor() see HideCursor()

### Pulse()

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

### Quit()

          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:

- It doesn't kill the thread. It merely causes the message loop to exit after it finishes with the current message.

- It therefore always returns, even when called from within the main thread.

- It returns immediately. It doesn't wait for the message loop to exit.

- It doesn't delete the object. It's up to you to delete it after `Run()` returns. (However, for some reason, `Quit()` does delete the BApplication object if it's called when no message loop is running.)

Before shutting down, the BApplication object responds to every message it received prior to the `Quit()` call.

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

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

### ReadyToRun()

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

### RefsReceived()

          virtual void RefsReceived(BMessage *message)

Implemented by derived classes to do something with file system entries 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 field named "refs" that contains one or more `entry_ref` (`B_REF_TYPE`) items.

Typically, the entry refs are for documents that the application is requested to open. For example, when the user double-clicks a document icon in a Tracker window, the Tracker sends a `B_REFS_RECEIVED` message to the application that owns the document. The BApplication object dispatches the message by passing it to this function.

There are a number of things you can do with the `entry_ref` taken from the message. For example, you might create a BEntry object for it and inquire whether it refers to a file:

       BEntry entry(&ref);
       if ( entry.IsFile() )
           . . .

If you're sure it's a file reference, you might create a BFile object and open it. For example:

       void MyApplication::RefsReceived(BMessage *message)
       {
           uint32 type;
           int32 count;
           entry_ref ref;
           . . .
           message->GetInfo("refs", &type, &count);
           if ( type != B_REF_TYPE )
               return;
           for ( long i = --count; i >= 0; i-- ) {
               if ( message->FindRef("refs", i, &ref) == B_OK ) {
                   BFile file;
                   if ( file.SetTo(&ref, B_READ_WRITE) == B_OK )
                       . . .
               }
           }
           . . .
       }

`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: the BEntry class in the Storage Kit, `ArgvReceived()`, `ReadyToRun()`, `IsLaunching()`, "`B_REFS_RECEIVED`" in the Message Protocols appendix

### ResolveSpecifier()

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

Resolves specifiers for the "Name" and "Window" properties. See "Scripting Support" in the class overview and the "Scripting" section of this chapter for more information.

See also: `BHandler::ResolveSpecifier()`

### Run()

          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: `BLooper::Run()`, `ReadyToRun()`, `QuitRequested()`

### SetCursor()

          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, its current cursor is automatically restored.

The first four bytes of cursor data is a preamble that gives information about the image, as follows:

- The first byte sets the size of the cursor image. The cursor bitmap is a square, and this byte states the number of pixels on one side. Currently, only 16-pixel-by-16-pixel images are acceptable.

- The second byte specifies the depth of the cursor image, in bits per pixel. Currently, only monochrome one-bit-per-pixel images are acceptable.

- The third and fourth bytes set the hot spot, the pixel within the cursor image that's used to report the cursor's location. For example, if the cursor is located over a button on-screen so that the hot spot is within the button rectangle, the cursor is said to point to the button. However, if the hot spot lies outside the button rectangle, even if most of the cursor image is within the rectangle, the cursor doesn't point to the button.

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

### SetPulseRate()

          void SetPulseRate(bigtime_t microseconds)

Sets how often `Pulse()` is called (how often `B_PULSE` messages are posted). The interval set should be a multiple of 100,000 microseconds (0.1 second); differences less than 100,000 microseconds will not be noticeable. A finer granularity can't be guaranteed.

The default pulse rate is 0, which disables the pulsing mechanism. Setting a different rate enables it.

See also: `Pulse()`

### ShowCursor() see HideCursor()

### WindowAt()

          BWindow *WindowAt(int32 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;
       int32 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 and can be locked while it's being read.

See also: `CountWindows()`

## Scripting Support

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

### The Name Property

Message | Specifiers | Meaning
`B_GET_PROPERTY` | `B_DIRECT_SPECIFIER` | Returns the name of the application's main thread.

### The Window Property

Message | Specifiers | Meaning
`B_COUNT_PROPERTIES` | `B_DIRECT_SPECIFIER` | Returns the number of windows owned by the application as reported by `CountWindows()`.
any others | `B_NAME_SPECIFIER,` `B_INDEX_SPECIFIER,` B_REVERSE_INDEX_SPECIFIER | Directs the scripting message to the specified window, first popping the current specifier off the specifier stack.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.