AmiDock and Dockies

Introduction

On every OS you can meet with panel launchers, tray bars, launch bars and so on, and AmigaOS4 is not exception. The realization of such thing on OS4 done via AmiDock commodity and while there can be another 3d party realization of toolbar systems, AmiDock start to be de-facto standard and provided with OS4 by default, and that is thing on which our article is based.

What is AmiDock

AmiDock for OS4 is a almost completely rewritten version of the former AmiDock from AmigaOS3.9. And while AmiDock is a single commodity, its more that just that as its provide you with necessary for today set of features like Arexx support and feature rich APIs by which your Dockies can control most of AmiDock's features and expand them.

You can follow to that article if you want to know user-kind details about, but there we will concentrate on technical details to help programmers to make their Dockies as best as it possible.

What are a Dock and a Docky?

Dock

A Dock is an area/a window (currently provided by the "AmiDock" commodity) where the user can put some icons and other stuff. Some may call it "Panels".

So, Docks can be used as Launcher Panels:

And as Tray Bar panels:

As anything else anyone can come up with: you can put everything inside of panels of any size, structure and design it as you wish.

Docky

A Docky is this item the user can place in the dock: a program icon or an interactive program. Dockies are able to control most of AmiDocks feature and provide a great way to expand AmiDocks features beyond its default features. Dockies may be invisible to the user or show static or dynamic (animated) content. You may change their behavior, size and look acording their current equirements. Dockies can be of 2 main types:

Standalone Dockies.

Is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common form of Dockies. This docky-type uses the shared library feature of AmigaOS4 as common interface to the internal properties and behavioral possibilities of a docky.

Application Dockies.

That second type of dockies are application dockies (short form 'AppDockies' or as some call it 'AppDockIcon Dockies'). An AppDocky is a docky which is introduced to the system during runtime by an application using application.library registration mechanism for applications. The biggest diference between the two docky types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.

To sum up in "standalone dockies" the docky itself is the application (the only reason of existence of the application is the docky) while for "AppDockIcon dockies" the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)

How to create and manipulate a simple docky

You write a docky just like you'd write a standard Exec library. In your code you must implement certain specifically-named functions like DockyGet(), DockyProcess(), DockySet() etc. The docky manager (AmiDock) calls these functions when it needs to.

See the datetime.docky source code (on os4depot.net) to get started.

One shortage of the current docky system is that AmiDock only provides your docky with a rastport pointer to render data into the dock. You get no window pointer, which makes it impossible to build your docky interface from Intuition gadgets.

How to make a right Docky

For tray-bar kind Docks

If you are a developer and you want to make your dockies to work in tray-bar kind docks, you need to make a docky more flexible, and you should follow some rules when you do it:

1. You should write Dockies more flexible when it comes to visual appearance like checking for the max. icon size of the Dock they appear.

2.

3.

For example, in QT port implementing of QSystemTrayIcon was done like an "application docky":

1. Open application.library. Note the interface is called "application" NOT "main".

2. Register your application using RegisterApplication()

3. Get the application.library port through GetApplicationsAttrs

4. Get events from that port in the usual fashion (the messages are detailed in the autodoc)

5. Unregister the application, close the library etc.

FAQ

Q: Is it possible to create an application docky and then update its content on the fly and how ?

A: (by ChrisY): Set the icon type to APPICONT_Docky; but you'll need to create a real docky as well then. If it doesn't need to be truly active it is possible just to change the icon's imagery (I think you have to unreg/re-reg to get it to change though, so no good for frequent changes)

Q: How are context menus created? I don't see any contextmenu example in the SDK examples, but DOCKYGET_ContextMenu takes en Object * as data. What kind of Object are we talking about?

A: (by Centaurz): Context menus are dynamically built in response to DOCKYGET_ContextMenu attribute :

BOOL DockyGet (struct DockyIFace *Self, uint32 msgType, uint32 *msgData) 
{ 
switch (msgType) 
{ 
/* ... */ 
 
case DOCKYGET_ContextMenu: 
{ 
Object *contextMenu = (Object *)msgData; 
 
Object *item1 = PopupMenuItemObject, 
        PMIA_Title, GetString(&li, LOCALE_ITEM_PREFS), 
        PMIA_ID, PMID_PREFS, 
    PopupMenuItemEnd; 
 
    Object *item2 = PopupMenuItemObject, 
        PMIA_Title, GetString(&li, LOCALE_ITEM_SAVEASDEFAULT), 
        PMIA_ID, PMID_SAVEASDEFAULT, 
    PopupMenuItemEnd; 
 
    Object *item3 = PopupMenuItemObject, 
        PMIA_Title, GetString(&li, LOCALE_ITEM_USEASDEFAULT), 
        PMIA_ID, PMID_USEASDEFAULT, 
    PopupMenuItemEnd; 
 
if (item1 && item2 && item3) 
    { 
        IIntuition->IDoMethod(contextMenu, OM_ADDMEMBER, item1); 
        IIntuition->IDoMethod(contextMenu, OM_ADDMEMBER, item2); 
        IIntuition->IDoMethod(contextMenu, OM_ADDMEMBER, item3); 
    } 
 
} 
break; 
 
/* ... */ 
}

Q: How to use Alpha layer for Docky ?

A: (by Centaurz): On non-composited screens, AmiDock uses a "fake" transparency effect (i.e. the bitmap is filled with the contents of the window behind the dock), meaning that you can only add things over the background but you cannot render half or totally transparent contents without doing the blending at the same time (or you'll lose background information).

So if you want to support this configuration you need to follow this rule or provide an alternate rendering if you want to do fancy stuff when compositing is enabled.

Now, what you are trying to do should work on composited screens, but you have to tell AmiDock that you are using composited mode (see DOCKYGET_SupportsComposite and DOCKYGET_CompositeMode) so that it does not try to de-multiply the docky bitmap. Also I'm not sure you can use legacy pens to fill alpha channel, you're better off with direct ARGB painting (see SetRPAttrs() with RPTAG_APenColor).

Q: Is there a way to trigger a redraw from outside the docky ?

A: Use DOCKYGET_NeedsAttention for this. This is how a docky can be notified from an external task by signaling AmiDock process. Quite straightforward, this is how e.g. winbar.docky is told to rethink its layout in response to a change in preferences, or Intuition windows list. A shared structure and a semaphore/mutex to protect the data.

Links

1. SDK:Documentation/AutoDocs/docky.doc

2. Sys:Documentation/Commodities/AmiDock_Arexx.doc