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