Release Notes: The Application Kit

Release Notes Table of Contents | Release Notes Index

# The Application Kit

## BApplication

Declared in: app/Appplication.h

### SetCursor()

`void` `SetCursor(const BCursor *`cursor, `bool` sync = `true``) `

The new `SetCursor()` function sets the cursor as a BCursor object. If sync is `true`, the function doesn't return until the cursor has actually been changed; otherwise, the function returns immediately.

## BCursor

Declared in: app/Cursor.h and app/AppDefs.h

The new BCursor class and related API let you retrieve and set the cursor on an app-wide and view-specific basis. The two Be-defined cursors, which used to be identified by name, are now represented by global BCursor objects (from app/AppDefs.h):

- `B_CURSOR_SYSTEM_DEFAULT` is the "hand" cursor.

- `B_CURSOR_I_BEAM` is the insertion point cursor commonly used by text editors.

The functions that control the app-wide cursor (`SetCursor()`, `ShowCursor()`, etc) are, as before, defined by BApplication; the only protocol difference is that `SetCursor()` now takes a BCursor object as an argument.

To set the cursor for a specific BView, use the new `BView::SetViewCursor()` function. In addition to an initial BCursor* argument, the function takes an optional boolean argument that, when `true`, tells the function to call `Sync()` before returning. This sync argument is `true` by default. With this new API, the BView doesn't need to watch for mouse-entered and mouse-exited events; the cursor will change automatically as the mouse enters and exits the view.

The old `B_HAND_CURSOR` and `B_I_BEAM_CURSOR` constants (app/AppDefs.h) have been deprecated.

## BHandler

Declared in: app/Handler.h

BHandler has a new "observe-notify" system in which a handler (the "observer") can register itself to be sent notifications from some other handler (the "notifier"). To register as an observer, a BHandler calls `StartWatching()`. When the notifier wants to broadcast a message to its observers, it calls `SendNotices()`.

| The Beta 1 versions of these functions will change to match the protocol given here.

### StartWatching() , StartWatchingAll() , StopWatching() , StopWatchingAll()

`status_t` `StartWatching(BMessenger` notifier, `uint32` what`) `
`status_t` `StartWatchingAll(BMessenger` notifier`) `
`status_t` `StartWatching(BHandler *`notifier, `uint32` what`) `
`status_t` `StartWatchingAll(BHandler *`notifier`) `
`status_t` `StopWatching(BMessenger` notifier, `uint32` what`) `
`status_t` `StopWatchingAll(BMessenger` notifier`) `
`status_t` `StopWatching(BHandler *`notifier, `uint32` what`) `
`status_t` `StopWatchingAll(BHandler *`notifier`) `

`StartWatching[All]()` places this BHandler on notifier's list of observers. When the notifier broadcasts a notification, this object will receive a `B_OBSERVER_NOTICE_CHANGE` message.

The `StartWatching()` what argument lets the observer tell the notifier which sort of changes it wants to be notified about (where the values that what can take are defined by the notifier). A handler can register for multiple what notifications with the same notifier by calling `StartWatching()` multiple times. For example:

       /* It's assumed that notifier has defined the NEW_... values */
       handler->StartWatching(notifier, NEW_NAME);
       handler->StartWatching(notifier, NEW_LOCATION);
       handler->StartWatching(notifier, NEW_ATTITUDE);

To receive notifications of all changes (as defined by notifier), use the `StartWatchingAll()` functions.

The notifier-as-BMessenger version of `StartWatching()` lets you watch a notifier that's local or remote. The BHandler* version can only watch local notifiers, but it can be called it before notifier is attached to a BLooper.

`StopWatching()` unregisters an observer for a given notifier/what combination. `StopWatchingAll()` completely unregisters the observer for that notifier.

The what value(s) that an observer registers for here shows up in the notification message as the `B_OBSERVE_WHICH_CHANGE` field. The notification message itself has a `what` of `B_OBSERVER_NOTICE_CHANGE`. For example, the handler that registered for the "NEW_*" changes above would respond to notifications thus:

       void myHandler::MessageReceived(BMessage *msg)
       {
          uint32 change;
          switch (msg->what) {
          case B_OBSERVER_NOTICE_CHANGE:
             msg->FindField(B_OBSERVE_WHICH_CHANGE, &change);
             switch (change) {
             case NEW_NAME:
                ...
             case NEW_LOCATION:
                ...
             case NEW_ATTITUDE:
                ...
             ...
             }
          ...
          }
          ...
       }

Keep in mind that the notifications are broadcast at the discretion of the notifier, through its `SendNotices()` function.

RETURN CODES

- `B_OK`. Success.

- `B_BAD_PORT_ID`. notifier (as a BMessenger) is invalid.

- Other errors. ...

### SendNotices()

`virtual void` `SendNotices(uint32` what, `const BMessage *`msg = 0`) `

Sends a `B_OBSERVER_NOTICE_CHANGE` message to each BHandler object (or "observer") that's observing this handler (the "notifier"). To observe a notifier, the observer calls `StartWatching()`. The what argument describes the type of change that's prompting this notification; only those observers that have registered to be notified about what (or that are watching all changes) are sent notifications.

The `B_OBSERVER_NOTICE_CHANGE` messages that are sent are copied from msg with the what argument added as the "be:old_what" field. Note that msg's original `what` field is clobbered.

## BMessage

Declared in: app/Message.h

### BMessage()

The BMessage constructor that takes a (BMessage *) argument has been retired:

`BMessage(BMessage *`msg`)`; obsolete—do not use

To replace the constructor in your code, simply de-reference the argument. For example:

       /* OLD CODE: */
       void SomeFunc(BMessage *msg)
       {
          BMessage new_msg(msg);
          ...
       }

       /* NEW CODE: */
       void SomeFunc(BMessage *msg)
       {
          BMessage new_msg(*msg);
          ...
       }

This will cause msg to be copied into new_msg, but (to anticipate your objection) it won't incur a second (leaked) copy.

### FindInt8() , FindInt64()

`int8` `FindInt8(const char *`name, `int32` index = 0`)` `const `
`int64` `FindInt64(const char *`name, `int32` index = 0`)` `const `

New direct-return versions of these functions (previously you could only retrieve an `int8` or an `int64` by reference).

## BRoster

Declared in: app/Roster.h

BRoster now provides access to the system-wide "recent documents" and "recent applications" lists. Also, some versions of `Launch()` have been deprecated in favor of new heavily `const`'d versions.

### GetRecentDocuments() , GetRecentFolders() , GetRecentApps() , AddToRecentDocuments() , AddToFolders()

`void` `GetRecentDocuments(BMessage *`refList `int32` maxCount, `const char *`fileType = `NULL`, `const char *`appSig = `NULL``)` `const `

`void` `GetRecentDocuments(BMessage *`refList
`int32` maxCount,
`const char *`fileTypes[],
`int32` fileTypesCount,
`const char *`appSig = `NULL``)` `const

`

`void` `GetRecentFolders(BMessage *`refList `int32` maxCount, `const char *`appSig = `NULL``)` `const `
`void` `GetRecentApps(BMessage *`refList `int32` maxCount`)` `const `
`void` `AddToRecentDocuments(const entry_ref *`ref `const char *`appSig = `NULL``)` `const `
`void` `AddToRecentFolders(const entry_ref *`ref `const char *`appSig = `NULL``)` `const `

These functions access the system-wide "recently opened documents," "recently opened folders," and "recently launched apps" lists. These lists are displayed by file panels, Deskbar, and other parts of the system. You can add to the document and folder lists, but not the app list (it's updated by the system). You can't programatically delete items from these lists.

The`Get...` functions retrieve the items as `entry_ref`s which they add to the "refs" field of the refList BMessage argument (refList must be allocated by the caller). The items in "refs" are listed from most recent to least recent.

`GetRecentDocuments()` gets the `entry_ref`s for the first maxCount items in the recent documents list. The optional fileType and appSig arguments let you specify that you only want to see files of a certain type and/or that were opened by a particular app. The fileTypes/fileTypesCount version lets you specify a list of candidate file types.

`GetRecentFolders()` returns the first maxCount `entry_ref`s in the recent folders list. The optional appSig lets you ask for folders that were opened by a particular app (only).

`GetRecentApps()` returns the first maxCount `entry_ref`s in the recent apps list.

`AddToRecentDocuments()` and `AddToRecentFolders()` adds the argument ref to the named list. appSig, if supplied, is the signature of the application that opened the document or folder.

Release Notes Table of Contents | Release Notes Index

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

Copyright © 2000 Be, Inc. All rights reserved..