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="https://www.haiku-os.org/legacy-docs/bebook/BDeskbar.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="https://www.haiku-os.org/legacy-docs/benewsletter/Issue4-27.html#DevWorkshop4-27">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(float, float)". 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="http://www.tycomsystems.com/beos/BeBook/Release%20Notes/Deskbar.html">Deskbar Release Notes</A> but not in the Be Book proper. The item id of the added item is passed back in an int32 pointer 53provided by the caller.<BR /> 54NOTE: The source code for the Deskbar found in 55<A HREF="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/StatusView.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n625">TReplicantTray::LoadAddon()</A> 56indicates that it also looks for a symbol called "BView *instantiate_deskbar_entry(image_id, entry_ref*, float, float)" 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.<BR /> 126<A HREF="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp">The code which handles communicating with the BDeskbar</A> is described below.</P> 127 128 129<H3>AddItem:</H3> 130 131<P>The AddItem() member sends the following message to the deskbar to add an item from an 132archived BView:</P> 133 134<PRE> 135BMessage theMsg; 136BMessage viewMsg; 137theView.Archive(&viewMsg); // This takes the target BView to place in the shelf and archives it into viewMsg 138theMsg.what = 'icon' 139theMsg.AddMessage("view", &viewMsg); // This puts the archived view in the viewMsg and puts it in the message to the deskbar 140</PRE> 141 142<P>Or, the AddItem() member sends the following message to the deskbar to add an item from a file 143that exports the "BView *instantiate_deskbar_item(float, float)" function:</P> 144 145<PRE> 146BMessage theMsg; 147theMsg.what = 'adon' 148theMsg.AddRef("addon", &theAddonRef); // This is the addon which contains the hook function to get the view to add 149</PRE> 150 151<P>The /boot/app/Pulse application exports the necessary symbol for this mechanism to work and 152is a good candidate to test with.</P> 153 154<P>In either case, the deskbar responds with a message which looks like:</P> 155 156<PRE> 157BMessage theMsg; 158theMsg.AddInt32("id", theID); // This is the id of the new item 159</PRE> 160 161<P>Note that in both cases, the deskbar does not set the what code of the reply. Checking the 162source code for 163<A href="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n571">TBarWindow::AddItem()</A> 164confirms this. 165 166 167<H3>HasItem:</H3> 168 169<P>The HasItem() member sends the following message to the deskbar:</P> 170 171<PRE> 172BMessage theMsg; 173theMsg.what = 'exst' 174theMsg.AddInt32("id", theID); // This is the id to check for 175 // OR, only one of id or name should be in the message 176theMsg.AddString("name", theName); // This is the name to check for 177</PRE> 178 179<P>The deskbar responds with a message which looks like:</P> 180 181<PRE> 182BMessage theMsg; 183theMsg.AddBool("exists", IDorNameExists()); // This is a true/false value which indicates whether or not the name/id exists in the shelf 184</PRE> 185 186<P>Note that the deskbar does not set the what code of the reply. Checking the source code 187for 188<A href="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n513">TBarWindow::ItemExists()</A> 189confirms this.</P> 190 191 192<H3>GetItemInfo:</H3> 193 194<P>The GetItemInfo() member sends the following message to the deskbar:</P> 195 196<PRE> 197BMessage theMsg; 198theMsg.what = 'info' 199theMsg.AddInt32("id", theID); // This is the id to check for 200 // OR, only one of id or name should be in the message 201theMsg.AddString("name", theName); // This is the name to check for 202</PRE> 203 204<P>The deskbar responds with a message which looks like:</P> 205 206<PRE> 207BMessage theMsg; 208theMsg.AddString("name", theName); // This is the name corresponding to the id of the original request 209 // OR, only one of id or name should be in the response message depending on the request sent 210theMsg.AddInt32("id", theID); // This is the id corresponding to the name of the original request 211</PRE> 212 213<P>Note that the deskbar does not set the what code of the reply. Checking the source code 214for 215<A href="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n486">TBarWindow::ItemInfo()</A> 216confirms this.</P> 217 218 219<H3>CountItems:</H3> 220 221<P>The CountItems() member sends the following message to the deskbar:</P> 222 223<PRE> 224BMessage theMsg; 225theMsg.what = 'cwnt' 226</PRE> 227 228<P>The deskbar responds with a message which looks like:</P> 229 230<PRE> 231BMessage theMsg; 232theMsg.what = 'rply'; // This means reply 233theMsg.AddInt32("count", ItemCount()); // This is the number of items in the deskbar shelf 234</PRE> 235 236 237<H3>RemoveItem:</H3> 238 239<P>The RemoveItem() member sends the following message to the deskbar:</P> 240 241<PRE> 242BMessage theMsg; 243theMsg.what = 'remv' 244theMsg.AddInt32("id", theID); // This is the id to remove 245 // OR, only one of id or name should be in the message 246theMsg.AddString("name", theName); // This is the name to remove 247</PRE> 248 249<P>The deskbar does not send a response.</P> 250 251 252<H3>Frame:</H3> 253 254<P>The Frame() member sends a standard scripting message to get the frame from the deskbar. It 255sends a B_GET_PROPERTY message to the deskbar asking for the "Frame" property specifying the 256window by name. The window name is "Deskbar".</P> 257 258<P>The response from deskbar has a what code of B_REPLY and a BRect describing the frame in a 259value called "result". This is standard BeOS scripting.</P> 260 261 262<H3>Location:</H3> 263 264<P>The Location() member sends the following message to the deskbar:</P> 265 266<PRE> 267BMessage theMsg; 268theMsg.what = 'gloc'; // This means get location 269</PRE> 270 271<P>The deskbar responds with a message which looks like:</P> 272 273<PRE> 274BMessage theMsg; 275theMsg.what = 'rply'; // This means reply 276theMsg.AddInt32("location", DeskbarLocation()); // This is the number which represents the location of the deskbar 277theMsg.AddBool("expanded", Expanded()); // This is true if the deskbar is expanded, false otherwise 278</PRE> 279 280 281<H3>IsExpanded:</H3> 282 283<P>The IsExpanded() member sends the following message to the deskbar:</P> 284 285<PRE> 286BMessage theMsg; 287theMsg.what = 'gexp'; // This means get expanded state 288</PRE> 289 290<P>The deskbar responds with a message which looks like:</P> 291 292<PRE> 293BMessage theMsg; 294theMsg.what = 'rply'; // This means reply 295theMsg.AddBool("expanded", Expanded()); // This is true if the deskbar is expanded, false otherwise 296</PRE> 297 298 299<H3>SetLocation:</H3> 300 301<P>The SetLocation() member sends the following message to the deskbar:</P> 302 303<PRE> 304BMessage theMsg; 305theMsg.what = 'sloc'; // This means set location 306theMsg.AddInt32("location", newLocation); // This is the number which represents the location of the deskbar 307theMsg.AddBool("expand", isExpanded); // This is true if the deskbar is expanded, false otherwise 308</PRE> 309 310<P>The deskbar does not send a reply to this message.</P> 311 312 313<H3>Expand:</H3> 314 315<P>The Expand() member sends the following message to the deskbar:</P> 316 317<PRE> 318BMessage theMsg; 319theMsg.what = 'sexp'; // This means set expanded state 320theMsg.AddBool("expand", isExpanded); // This is true if the deskbar is expanded, false otherwise 321</PRE> 322 323<P>The deskbar does not send a reply to this message.</P> 324 325</BODY> 326</HTML> 327