1<HTML> 2<!-- $Id: BDeskbarUseCases.html 1185 2002-09-26 02:21:31Z jrand $ --> 3<HEAD> 4<TITLE>BDeskbar Use Cases and Implementation Details</TITLE> 5</HEAD> 6 7<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF"> 8 9<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1"> 10 11<H1>BDeskbar Use Cases and Implementation Details:</H1> 12 13<P>This document describes the BDeskbar interface and some basics of how it is implemented. 14The document has the following sections:</P> 15 16<OL> 17<LI><A HREF="#interface">BDeskbar Interface</A></LI> 18<LI><A HREF="#usecases">BDeskbar Use Cases</A></LI> 19<LI><A HREF="#implement">BDeskbar Implementation</A></LI> 20</OL> 21 22<A NAME="interface"></A><H2>BDeskbar Interface:</H2> 23 24<P>The BDeskbar class is a simple class for getting information from the deskbar and for modifying 25it from your application. The best source of source of information for the BDeskbar interface can be found 26<A HREF="file:///boot/beos/documentation/Be%20Book/Deskbar/Deskbar.html">here in the Be Book</A>. 27</P> 28 29<A NAME="usecases"></A><H2>BDeskbar Use Cases:</H2> 30 31<P>The following use cases cover the BDeskbar functionality:</P> 32 33<OL> 34<LI><P><B>Construction:</B> A BDeskbar does not take any arguments when it is constructed. The 35BDeskbar instance creates a connection to the deskbar in order to get and change its state.</P></LI> 36 37<LI><P><B>Destruction:</B> When a BDeskbar is deconstructed, the application's connection to the 38deskbar is closed. However any change to the deskbar's state made through the BDeskbar instance 39persists.</P></LI> 40 41<LI><P><B>Add Item 1:</B> The AddItem() member function can be used to take a passed in pointer to 42a BView and send it to the deskbar for inclusion in its shelf. This BView must be archivable 43and must be exported by the application (for details on how to do this, 44<A HREF="http://bedriven.be-in.org/articles/replicant/III_027-stepping%20up%20to%20the%20deskbar.html">this article</A> 45may help). The item will be added and the id of the new item will be passed back to the caller 46through a pointer to an int32.</P></LI> 47 48<LI><P><B>Add Item 2:</B> The AddItem() member function can be used to add an item to the deskbar 49shelf by passing a pointer to an entry_ref. The file pointed to by this entry_ref should be 50an addon that exports the symbol "BView *instantiate_deskbar_item()". This entry point is used to 51get a BView which it can display in the shelf. More information on this mechanism can be found in 52the <A HREF="file:///boot/beos/documentation/Be%20Book/Release%20Notes/Deskbar.html">Deskbar Release Notes</A> 53but not in the Be Book proper. The item id of the added item is passed back in an int32 pointer 54provided by the caller. NOTE: The source code for the deskbar found in 55<A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/StatusView.cpp?rev=1.5&content-type=text/vnd.viewcvs-markup">TReplicantTray::LoadAddon()</A> 56indicates that it also looks for a symbol called "BView *instantiate_deskbar_entry(image_id, entry_ref *)" 57first, but there is no documentation on this.</P></LI> 58 59<LI><P><B>Remove Item 1:</B> The RemoveItem() member function takes an integer id and removes it 60from the deskbar shelf if it exists. The member returns B_OK at all times (unless the deskbar is 61not running or some communication failure occurs). A B_OK result does not mean that an item was 62actually removed.</P></LI> 63 64<LI><P><B>Remove Item 2:</B> The RemoveItem() member function also takes a string name and removes 65it from the deskbar shelf if it exists. The member returns B_OK at all times (unless the deskbar is 66not running or some communication failure occurs). A B_OK result does not mean that an item was 67actually removed.</P></LI> 68 69<LI><P><B>Count Items:</B> The CountItems() member function takes no arguments. It returns the 70number of "items" in the deskbar shelf. For example, the small email icon often found in the 71deskbar is one such item.</P></LI> 72 73<LI><P><B>Has Item 1:</B> The HasItem() member function takes a integer id and returns a true or 74false value which indicates whether or not an item exists in the deskbar shelf on that id. For 75example, the small email icon often found in the deskbar is one such item.</P></LI> 76 77<LI><P><B>Has Item 2:</B> The HasItem() member function also takes a string name parameter and 78returns a true or false value which indicates whether or not an item by than name exists in 79the deskbar shelf. For example, the small email icon often found in the deskbar is named 80"mail".</P></LI> 81 82<LI><P><B>Get Item Info 1:</B> The GetItemInfo() member function takes an integer id and a pointer 83to a const char * (ie a string). It checks to see if the id passed in exists in the deskbar and 84sets the value of the const char * to point to a allocated buffer which contains the name of the 85item which corresponds to this id and the function returns B_OK. Ownership of this allocated 86buffer is assigned to the caller of this member function so it is up to the caller to free the 87memory. If the id doesn't exist, then it still returns B_OK but the pointer to the string is set 88to NULL. If the pointer to the string passed in is NULL, the function returns B_BAD_VALUE.</P></LI> 89 90<LI><P><B>Get Item Info 2:</B> The GetItemInfo() member also takes a string (const char *) name 91and a pointer to an int. If the name matches an item in the deskbar shelf, the id of this 92item is returned at the location pointed to by the integer pointer and the member returns B_OK. 93If the name doesn't match an item in the deskbar shelf, the id is set to -1. If the pointer 94passed in is NULL, the function returns B_BAD_VALUE.</P></LI> 95 96<LI><P><B>Frame:</B> The Frame() member function returns a BRect which describes the location and 97size of the deskbar on the screen.</P></LI> 98 99<LI><P><B>Location:</B> The Location() member function returns one of B_DESKBAR_TOP, 100B_DESKBAR_BOTTOM, B_DESKBAR_LEFT_BOTTOM, B_DESKBAR_RIGHT_BOTTOM, B_DESKBAR_LEFT_TOP or 101B_DESKBAR_RIGHT_TOP. The return value describes where the deskbar currently is located. Also, 102the Location() member function takes an optional argument which is a pointer to a boolean. 103If supplied, the boolean which is pointed to is set to true if the deskbar is expanded and false 104otherwise. A deskbar can only be contracted (ie not expanded) when in the left or right top 105position.</P></LI> 106 107<LI><P><B>Is Expanded:</B> The IsExpanded() member function returns true if the deskbar is 108expanded and false if it is contracted. Note, the deskbar can only be contracted when in 109left or right top position.</P></LI> 110 111<LI><P><B>Set Location:</B> The SetLocation() member function takes the same values returned 112by the Location() member. The value passed in the first argument sets the position of the deskbar. 113If the optional second argument is supplied, it is a boolean which indicates whether or not the 114deskbar is expanded (true) or contracted (false). Note, the deskbar can only be contracted when in 115left or right top position.</P></LI> 116 117<LI><P><B>Expand:</B> The Expand() member function takes a single boolean argument which sets the 118deskbar to expanded (true) or contracted (false) mode. Note, the deskbar can only be contracted 119when in left or right top position.</P></LI> 120 121</OL> 122 123<A NAME="implement"></A><H2>BDeskbar Implementation:</H2> 124 125<P>Internally, the BDeskbar uses a BMessenger to communicate with the deskbar itself. 126The source code from the OpenTracker project will be used as a reference for this effort. 127You can find the deskbar source code here:</P> 128 129<BLOCKQUOTE> 130<A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/</A> 131</BLOCKQUOTE> 132 133<P>Specifically, the code which handles communicating with the BDeskbar class can be found 134here:</P> 135 136<BLOCKQUOTE> 137<A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/BarWindow.cpp?rev=1.2&content-type=text/vnd.viewcvs-markup">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/BarWindow.cpp?rev=1.2&content-type=text/vnd.viewcvs-markup</A> 138</BLOCKQUOTE> 139 140<P>The following describes the messages used to communicate between BDeskbar and the deskbar 141itself.</P> 142 143 144<H3>AddItem:</H3> 145 146<P>The AddItem() member sends the following message to the deskbar to add an item from an 147archived BView:</P> 148 149<PRE> 150BMessage theMsg; 151BMessage viewMsg; 152theView.Archive(&viewMsg); // This takes the target BView to place in the shelf and archives it into viewMsg 153theMsg.what = 'icon' 154theMsg.AddMessage("view", &viewMsg); // This puts the archived view in the viewMsg and puts it in the message to the deskbar 155</PRE> 156 157<P>Or, the AddItem() member sends the following message to the deskbar to add an item from a file 158that exports the "BView *instantiate_deskbar_item(void)" function:</P> 159 160<PRE> 161BMessage theMsg; 162theMsg.what = 'adon' 163theMsg.AddRef("addon", &theAddonRef); // This is the addon which contains the hook function to get the view to add 164</PRE> 165 166<P>The /boot/app/Pulse application exports the necessary symbol for this mechanism to work and 167is a good candidate to test with.</P> 168 169<P>In either case, the deskbar responds with a message which looks like:</P> 170 171<PRE> 172BMessage theMsg; 173theMsg.AddInt32("id", theID); // This is the id of the new item 174</PRE> 175 176<P>Note that in both cases, the deskbar does not set the what code of the reply. Checking the 177source code for 178<A href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/BarWindow.cpp?rev=1.2&content-type=text/vnd.viewcvs-markup">TBarWindow::AddItem()</A> 179confirms this. 180 181 182<H3>HasItem:</H3> 183 184<P>The HasItem() member sends the following message to the deskbar:</P> 185 186<PRE> 187BMessage theMsg; 188theMsg.what = 'exst' 189theMsg.AddInt32("id", theID); // This is the id to check for 190 // OR, only one of id or name should be in the message 191theMsg.AddString("name", theName); // This is the name to check for 192</PRE> 193 194<P>The deskbar responds with a message which looks like:</P> 195 196<PRE> 197BMessage theMsg; 198theMsg.AddBool("exists", IDorNameExists()); // This is a true/false value which indicates whether or not the name/id exists in the shelf 199</PRE> 200 201<P>Note that the deskbar does not set the what code of the reply. Checking the source code 202for 203<A href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/BarWindow.cpp?rev=1.2&content-type=text/vnd.viewcvs-markup">TBarWindow::ItemExists()</A> 204confirms this.</P> 205 206 207<H3>GetItemInfo:</H3> 208 209<P>The GetItemInfo() member sends the following message to the deskbar:</P> 210 211<PRE> 212BMessage theMsg; 213theMsg.what = 'info' 214theMsg.AddInt32("id", theID); // This is the id to check for 215 // OR, only one of id or name should be in the message 216theMsg.AddString("name", theName); // This is the name to check for 217</PRE> 218 219<P>The deskbar responds with a message which looks like:</P> 220 221<PRE> 222BMessage theMsg; 223theMsg.AddString("name", theName); // This is the name corresponding to the id of the original request 224 // OR, only one of id or name should be in the response message depending on the request sent 225theMsg.AddInt32("id", theID); // This is the id corresponding to the name of the original request 226</PRE> 227 228<P>Note that the deskbar does not set the what code of the reply. Checking the source code 229for 230<A href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/opentracker/opentracker/deskbar/BarWindow.cpp?rev=1.2&content-type=text/vnd.viewcvs-markup">TBarWindow::ItemInfo()</A> 231confirms this.</P> 232 233 234<H3>CountItems:</H3> 235 236<P>The CountItems() member sends the following message to the deskbar:</P> 237 238<PRE> 239BMessage theMsg; 240theMsg.what = 'cwnt' 241</PRE> 242 243<P>The deskbar responds with a message which looks like:</P> 244 245<PRE> 246BMessage theMsg; 247theMsg.what = 'rply'; // This means reply 248theMsg.AddInt32("count", ItemCount()); // This is the number of items in the deskbar shelf 249</PRE> 250 251 252<H3>RemoveItem:</H3> 253 254<P>The RemoveItem() member sends the following message to the deskbar:</P> 255 256<PRE> 257BMessage theMsg; 258theMsg.what = 'remv' 259theMsg.AddInt32("id", theID); // This is the id to remove 260 // OR, only one of id or name should be in the message 261theMsg.AddString("name", theName); // This is the name to remove 262</PRE> 263 264<P>The deskbar does not send a response.</P> 265 266 267<H3>Frame:</H3> 268 269<P>The Frame() member sends a standard scripting message to get the frame from the deskbar. It 270sends a B_GET_PROPERTY message to the deskbar asking for the "Frame" property specifying the 271window by name. The window name is "Deskbar".</P> 272 273<P>The response from deskbar has a what code of B_REPLY and a BRect describing the frame in a 274value called "result". This is standard BeOS scripting.</P> 275 276 277<H3>Location:</H3> 278 279<P>The Location() member sends the following message to the deskbar:</P> 280 281<PRE> 282BMessage theMsg; 283theMsg.what = 'gloc'; // This means get location 284</PRE> 285 286<P>The deskbar responds with a message which looks like:</P> 287 288<PRE> 289BMessage theMsg; 290theMsg.what = 'rply'; // This means reply 291theMsg.AddInt32("location", DeskbarLocation()); // This is the number which represents the location of the deskbar 292theMsg.AddBool("expanded", Expanded()); // This is true if the deskbar is expanded, false otherwise 293</PRE> 294 295 296<H3>IsExpanded:</H3> 297 298<P>The IsExpanded() member sends the following message to the deskbar:</P> 299 300<PRE> 301BMessage theMsg; 302theMsg.what = 'gexp'; // This means get expanded state 303</PRE> 304 305<P>The deskbar responds with a message which looks like:</P> 306 307<PRE> 308BMessage theMsg; 309theMsg.what = 'rply'; // This means reply 310theMsg.AddBool("expanded", Expanded()); // This is true if the deskbar is expanded, false otherwise 311</PRE> 312 313 314<H3>SetLocation:</H3> 315 316<P>The SetLocation() member sends the following message to the deskbar:</P> 317 318<PRE> 319BMessage theMsg; 320theMsg.what = 'sloc'; // This means set location 321theMsg.AddInt32("location", newLocation); // This is the number which represents the location of the deskbar 322theMsg.AddBool("expand", isExpanded); // This is true if the deskbar is expanded, false otherwise 323</PRE> 324 325<P>The deskbar does not send a reply to this message.</P> 326 327 328<H3>Expand:</H3> 329 330<P>The Expand() member sends the following message to the deskbar:</P> 331 332<PRE> 333BMessage theMsg; 334theMsg.what = 'sexp'; // This means set expanded state 335theMsg.AddBool("expand", isExpanded); // This is true if the deskbar is expanded, false otherwise 336</PRE> 337 338<P>The deskbar does not send a reply to this message.</P> 339 340</BODY> 341</HTML> 342