interface/usecases/BDeskbarUseCases.html

<HTML>
<!-- $Id: BDeskbarUseCases.html 1185 2002-09-26 02:21:31Z jrand $ -->
<HEAD>
<TITLE>BDeskbar Use Cases and Implementation Details</TITLE>
</HEAD>

<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF">

<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1">

<H1>BDeskbar Use Cases and Implementation Details:</H1>

<P>This document describes the BDeskbar interface and some basics of how it is implemented.
The document has the following sections:</P>

<OL>
<LI><A HREF="#interface">BDeskbar Interface</A></LI>
<LI><A HREF="#usecases">BDeskbar Use Cases</A></LI>
<LI><A HREF="#implement">BDeskbar Implementation</A></LI>
</OL>

<A NAME="interface"></A><H2>BDeskbar Interface:</H2>

<P>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
<A HREF="https://www.haiku-os.org/legacy-docs/bebook/BDeskbar.html">here in the Be Book</A>.
</P>

<A NAME="usecases"></A><H2>BDeskbar Use Cases:</H2>

<P>The following use cases cover the BDeskbar functionality:</P>

<OL>
<LI><P><B>Construction:</B> 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.</P></LI>

<LI><P><B>Destruction:</B> 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.</P></LI>

<LI><P><B>Add Item 1:</B> 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,
<A HREF="https://www.haiku-os.org/legacy-docs/benewsletter/Issue4-27.html#DevWorkshop4-27">this article</A>
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.</P></LI>

<LI><P><B>Add Item 2:</B> 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(float, float)".  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 <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
provided by the caller.<BR />
NOTE: The source code for the Deskbar found in
<A HREF="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/StatusView.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n625">TReplicantTray::LoadAddon()</A>
indicates that it also looks for a symbol called "BView *instantiate_deskbar_entry(image_id, entry_ref*, float, float)"
first, but there is no documentation on this.</P></LI>

<LI><P><B>Remove Item 1:</B> 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.</P></LI>

<LI><P><B>Remove Item 2:</B> 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.</P></LI>

<LI><P><B>Count Items:</B> 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.</P></LI>

<LI><P><B>Has Item 1:</B> 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.</P></LI>

<LI><P><B>Has Item 2:</B> 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".</P></LI>

<LI><P><B>Get Item Info 1:</B> 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.</P></LI>

<LI><P><B>Get Item Info 2:</B> 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.</P></LI>

<LI><P><B>Frame:</B> The Frame() member function returns a BRect which describes the location and
size of the deskbar on the screen.</P></LI>

<LI><P><B>Location:</B> 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.</P></LI>

<LI><P><B>Is Expanded:</B> 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.</P></LI>

<LI><P><B>Set Location:</B> 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.</P></LI>

<LI><P><B>Expand:</B> 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.</P></LI>

</OL>

<A NAME="implement"></A><H2>BDeskbar Implementation:</H2>

<P>Internally, the BDeskbar uses a BMessenger to communicate with the deskbar itself.<BR />
<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>


<H3>AddItem:</H3>

<P>The AddItem() member sends the following message to the deskbar to add an item from an
archived BView:</P>

<PRE>
BMessage theMsg;
BMessage viewMsg;
theView.Archive(&amp;viewMsg);              // This takes the target BView to place in the shelf and archives it into viewMsg
theMsg.what = 'icon'
theMsg.AddMessage("view", &amp;viewMsg);    // This puts the archived view in the viewMsg and puts it in the message to the deskbar
</PRE>

<P>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(float, float)" function:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'adon'
theMsg.AddRef("addon", &amp;theAddonRef);    // This is the addon which contains the hook function to get the view to add
</PRE>

<P>The /boot/app/Pulse application exports the necessary symbol for this mechanism to work and
is a good candidate to test with.</P>

<P>In either case, the deskbar responds with a message which looks like:</P>

<PRE>
BMessage theMsg;
theMsg.AddInt32("id", theID);         // This is the id of the new item
</PRE>

<P>Note that in both cases, the deskbar does not set the what code of the reply.  Checking the
source code for
<A href="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n571">TBarWindow::AddItem()</A>
confirms this.


<H3>HasItem:</H3>

<P>The HasItem() member sends the following message to the deskbar:</P>

<PRE>
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
</PRE>

<P>The deskbar responds with a message which looks like:</P>

<PRE>
BMessage theMsg;
theMsg.AddBool("exists", IDorNameExists());    // This is a true/false value which indicates whether or not the name/id exists in the shelf
</PRE>

<P>Note that the deskbar does not set the what code of the reply.  Checking the source code
for
<A href="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n513">TBarWindow::ItemExists()</A>
confirms this.</P>


<H3>GetItemInfo:</H3>

<P>The GetItemInfo() member sends the following message to the deskbar:</P>

<PRE>
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
</PRE>

<P>The deskbar responds with a message which looks like:</P>

<PRE>
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
</PRE>

<P>Note that the deskbar does not set the what code of the reply.  Checking the source code
for
<A href="https://git.haiku-os.org/haiku/tree/src/apps/deskbar/BarWindow.cpp?id=f10faf61aca9496c0c2cfa04deb1acf47164b650#n486">TBarWindow::ItemInfo()</A>
confirms this.</P>


<H3>CountItems:</H3>

<P>The CountItems() member sends the following message to the deskbar:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'cwnt'
</PRE>

<P>The deskbar responds with a message which looks like:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'rply';                     // This means reply
theMsg.AddInt32("count", ItemCount());    // This is the number of items in the deskbar shelf
</PRE>


<H3>RemoveItem:</H3>

<P>The RemoveItem() member sends the following message to the deskbar:</P>

<PRE>
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
</PRE>

<P>The deskbar does not send a response.</P>


<H3>Frame:</H3>

<P>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".</P>

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


<H3>Location:</H3>

<P>The Location() member sends the following message to the deskbar:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'gloc';    // This means get location
</PRE>

<P>The deskbar responds with a message which looks like:</P>

<PRE>
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
</PRE>


<H3>IsExpanded:</H3>

<P>The IsExpanded() member sends the following message to the deskbar:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'gexp';    // This means get expanded state
</PRE>

<P>The deskbar responds with a message which looks like:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'rply';                      // This means reply
theMsg.AddBool("expanded", Expanded());    // This is true if the deskbar is expanded, false otherwise
</PRE>


<H3>SetLocation:</H3>

<P>The SetLocation() member sends the following message to the deskbar:</P>

<PRE>
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
</PRE>

<P>The deskbar does not send a reply to this message.</P>


<H3>Expand:</H3>

<P>The Expand() member sends the following message to the deskbar:</P>

<PRE>
BMessage theMsg;
theMsg.what = 'sexp';                     // This means set expanded state
theMsg.AddBool("expand", isExpanded);     // This is true if the deskbar is expanded, false otherwise
</PRE>

<P>The deskbar does not send a reply to this message.</P>

</BODY>
</HTML>