The Application Kit

BApplication

Declared in:  be/app/Appplication.h
more...

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:  be/app/Cursor.hp/headers/be/app/Cursor.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:  be/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:  be/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:  be/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_refs 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_refs 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_refs 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_refs 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.