From 9eb78d12d6e78c471f68fa09d9290d570537ca5a Mon Sep 17 00:00:00 2001 From: jrand Date: Tue, 10 Sep 2002 03:30:21 +0000 Subject: [PATCH] Add final use cases and implementation details for AddItem(). git-svn-id: file:///srv/svn/repos/haiku/trunk/current@1006 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- .../app/usecases/BDeskbarUseCases.html | 62 +++++++++++++++++-- 1 file changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/develop/app/usecases/BDeskbarUseCases.html b/docs/develop/app/usecases/BDeskbarUseCases.html index cb4cddd65d..0133327328 100644 --- a/docs/develop/app/usecases/BDeskbarUseCases.html +++ b/docs/develop/app/usecases/BDeskbarUseCases.html @@ -1,5 +1,5 @@ - + BDeskbar Use Cases and Implementation Details @@ -23,7 +23,7 @@ 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. +here in the Be Book.

BDeskbar Use Cases:

@@ -38,9 +38,23 @@ BDeskbar instance creates a connection to the deskbar in order to get and change deskbar is closed. However any change to the deskbar's state made through the BDeskbar instance persists.

-

  • Add Item 1:

    • +

  • 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:

    • +

  • 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 @@ -127,6 +141,44 @@ here:

    itself.

    +

    AddItem:

    + +

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

    HasItem:

    The HasItem() member sends the following message to the deskbar:

    @@ -175,7 +227,7 @@ theMsg.AddInt32("id", theID); // This is the id corresponding to the nam

    Note that the deskbar does not set the what code of the reply. Checking the source code for -TBarWindow::ItemExists() +TBarWindow::ItemInfo() confirms this.