This document describes the BDeskbar interface and some basics of how it is implemented. The document has the following sections:
The BDeskbar class is a simple class for getting information from the deskbar and for modifying it from your application. The best source of source of information for the BDeskbar interface can be found here in the Be Book.
The following use cases cover the BDeskbar functionality:
Construction: A BDeskbar does not take any arguments when it is constructed. The BDeskbar instance creates a connection to the deskbar in order to get and change its state.
Destruction: When a BDeskbar is deconstructed, the application's connection to the deskbar is closed. However any change to the deskbar's state made through the BDeskbar instance persists.
Add Item 1: The AddItem() member function can be used to take a passed in pointer to a BView and send it to the deskbar for inclusion in its shelf. This BView must be archivable and must be exported by the application (for details on how to do this, this article may help). The item will be added and the id of the new item will be passed back to the caller through a pointer to an int32.
Add Item 2: The AddItem() member function can be used to add an item to the deskbar shelf by passing a pointer to an entry_ref. The file pointed to by this entry_ref should be an addon that exports the symbol "BView *instantiate_deskbar_item()". This entry point is used to get a BView which it can display in the shelf. More information on this mechanism can be found in the Deskbar Release Notes but not in the Be Book proper. The item id of the added item is passed back in an int32 pointer provided by the caller. NOTE: The source code for the deskbar found in TReplicantTray::LoadAddon() indicates that it also looks for a symbol called "BView *instantiate_deskbar_entry(image_id, entry_ref *)" first, but there is no documentation on this.
Remove Item 1: The RemoveItem() member function takes an integer id and removes it from the deskbar shelf if it exists. The member returns B_OK at all times (unless the deskbar is not running or some communication failure occurs). A B_OK result does not mean that an item was actually removed.
Remove Item 2: The RemoveItem() member function also takes a string name and removes it from the deskbar shelf if it exists. The member returns B_OK at all times (unless the deskbar is not running or some communication failure occurs). A B_OK result does not mean that an item was actually removed.
Count Items: The CountItems() member function takes no arguments. It returns the number of "items" in the deskbar shelf. For example, the small email icon often found in the deskbar is one such item.
Has Item 1: The HasItem() member function takes a integer id and returns a true or false value which indicates whether or not an item exists in the deskbar shelf on that id. For example, the small email icon often found in the deskbar is one such item.
Has Item 2: The HasItem() member function also takes a string name parameter and returns a true or false value which indicates whether or not an item by than name exists in the deskbar shelf. For example, the small email icon often found in the deskbar is named "mail".
Get Item Info 1: The GetItemInfo() member function takes an integer id and a pointer to a const char * (ie a string). It checks to see if the id passed in exists in the deskbar and sets the value of the const char * to point to a allocated buffer which contains the name of the item which corresponds to this id and the function returns B_OK. Ownership of this allocated buffer is assigned to the caller of this member function so it is up to the caller to free the memory. If the id doesn't exist, then it still returns B_OK but the pointer to the string is set to NULL. If the pointer to the string passed in is NULL, the function returns B_BAD_VALUE.
Get Item Info 2: The GetItemInfo() member also takes a string (const char *) name and a pointer to an int. If the name matches an item in the deskbar shelf, the id of this item is returned at the location pointed to by the integer pointer and the member returns B_OK. If the name doesn't match an item in the deskbar shelf, the id is set to -1. If the pointer passed in is NULL, the function returns B_BAD_VALUE.
Frame: The Frame() member function returns a BRect which describes the location and size of the deskbar on the screen.
Location: The Location() member function returns one of B_DESKBAR_TOP, B_DESKBAR_BOTTOM, B_DESKBAR_LEFT_BOTTOM, B_DESKBAR_RIGHT_BOTTOM, B_DESKBAR_LEFT_TOP or B_DESKBAR_RIGHT_TOP. The return value describes where the deskbar currently is located. Also, the Location() member function takes an optional argument which is a pointer to a boolean. If supplied, the boolean which is pointed to is set to true if the deskbar is expanded and false otherwise. A deskbar can only be contracted (ie not expanded) when in the left or right top position.
Is Expanded: The IsExpanded() member function returns true if the deskbar is expanded and false if it is contracted. Note, the deskbar can only be contracted when in left or right top position.
Set Location: The SetLocation() member function takes the same values returned by the Location() member. The value passed in the first argument sets the position of the deskbar. If the optional second argument is supplied, it is a boolean which indicates whether or not the deskbar is expanded (true) or contracted (false). Note, the deskbar can only be contracted when in left or right top position.
Expand: The Expand() member function takes a single boolean argument which sets the deskbar to expanded (true) or contracted (false) mode. Note, the deskbar can only be contracted when in left or right top position.
Internally, the BDeskbar uses a BMessenger to communicate with the deskbar itself. The source code from the OpenTracker project will be used as a reference for this effort. You can find the deskbar source code here:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/
Specifically, the code which handles communicating with the BDeskbar class can be found here:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/BarWindow.cpp?rev=1.2&content-type=text/vnd.viewcvs-markup
The following describes the messages used to communicate between BDeskbar and the deskbar itself.
The AddItem() member sends the following message to the deskbar to add an item from an archived BView:
BMessage theMsg;
BMessage viewMsg;
theView.Archive(&viewMsg); // This takes the target BView to place in the shelf and archives it into viewMsg
theMsg.what = 'icon'
theMsg.AddMessage("view", &viewMsg); // This puts the archived view in the viewMsg and puts it in the message to the deskbar
Or, the AddItem() member sends the following message to the deskbar to add an item from a file that exports the "BView *instantiate_deskbar_item(void)" function:
BMessage theMsg;
theMsg.what = 'adon'
theMsg.AddRef("addon", &theAddonRef); // This is the addon which contains the hook function to get the view to add
The /boot/app/Pulse application exports the necessary symbol for this mechanism to work and is a good candidate to test with.
In either case, the deskbar responds with a message which looks like:
BMessage theMsg;
theMsg.AddInt32("id", theID); // This is the id of the new item
Note that in both cases, the deskbar does not set the what code of the reply. Checking the source code for TBarWindow::AddItem() confirms this.
The HasItem() member sends the following message to the deskbar:
BMessage theMsg;
theMsg.what = 'exst'
theMsg.AddInt32("id", theID); // This is the id to check for
// OR, only one of id or name should be in the message
theMsg.AddString("name", theName); // This is the name to check for
The deskbar responds with a message which looks like:
BMessage theMsg;
theMsg.AddBool("exists", IDorNameExists()); // This is a true/false value which indicates whether or not the name/id exists in the shelf
Note that the deskbar does not set the what code of the reply. Checking the source code for TBarWindow::ItemExists() confirms this.
The GetItemInfo() member sends the following message to the deskbar:
BMessage theMsg;
theMsg.what = 'info'
theMsg.AddInt32("id", theID); // This is the id to check for
// OR, only one of id or name should be in the message
theMsg.AddString("name", theName); // This is the name to check for
The deskbar responds with a message which looks like:
BMessage theMsg;
theMsg.AddString("name", theName); // This is the name corresponding to the id of the original request
// OR, only one of id or name should be in the response message depending on the request sent
theMsg.AddInt32("id", theID); // This is the id corresponding to the name of the original request
Note that the deskbar does not set the what code of the reply. Checking the source code for TBarWindow::ItemInfo() confirms this.
The CountItems() member sends the following message to the deskbar:
BMessage theMsg; theMsg.what = 'cwnt'
The deskbar responds with a message which looks like:
BMessage theMsg;
theMsg.what = 'rply'; // This means reply
theMsg.AddInt32("count", ItemCount()); // This is the number of items in the deskbar shelf
The RemoveItem() member sends the following message to the deskbar:
BMessage theMsg;
theMsg.what = 'remv'
theMsg.AddInt32("id", theID); // This is the id to remove
// OR, only one of id or name should be in the message
theMsg.AddString("name", theName); // This is the name to remove
The deskbar does not send a response.
The Frame() member sends a standard scripting message to get the frame from the deskbar. It sends a B_GET_PROPERTY message to the deskbar asking for the "Frame" property specifying the window by name. The window name is "Deskbar".
The response from deskbar has a what code of B_REPLY and a BRect describing the frame in a value called "result". This is standard BeOS scripting.
The Location() member sends the following message to the deskbar:
BMessage theMsg; theMsg.what = 'gloc'; // This means get location
The deskbar responds with a message which looks like:
BMessage theMsg;
theMsg.what = 'rply'; // This means reply
theMsg.AddInt32("location", DeskbarLocation()); // This is the number which represents the location of the deskbar
theMsg.AddBool("expanded", Expanded()); // This is true if the deskbar is expanded, false otherwise
The IsExpanded() member sends the following message to the deskbar:
BMessage theMsg; theMsg.what = 'gexp'; // This means get expanded state
The deskbar responds with a message which looks like:
BMessage theMsg;
theMsg.what = 'rply'; // This means reply
theMsg.AddBool("expanded", Expanded()); // This is true if the deskbar is expanded, false otherwise
The SetLocation() member sends the following message to the deskbar:
BMessage theMsg;
theMsg.what = 'sloc'; // This means set location
theMsg.AddInt32("location", newLocation); // This is the number which represents the location of the deskbar
theMsg.AddBool("expand", isExpanded); // This is true if the deskbar is expanded, false otherwise
The deskbar does not send a reply to this message.
The Expand() member sends the following message to the deskbar:
BMessage theMsg;
theMsg.what = 'sexp'; // This means set expanded state
theMsg.AddBool("expand", isExpanded); // This is true if the deskbar is expanded, false otherwise
The deskbar does not send a reply to this message.