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:
Add Item 2:
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 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 = '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.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::ItemExists() 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 = 'exst'
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.