AmiDock and Dockies

This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally.

Introduction

AmiDock is a tool to maintain a graphical menu bar at the bottom of the Workbench screen that can be used to execute other programs from a selection of icons, either in the main Dock or in sub-Docks as specified by the AmiDock preferences.

What is AmiDock

AmiDock for AmigaOS 4 is a rewritten version of the former AmiDock from AmigaOS 3.9. While AmiDock is a single commodity, it's more than just that and provides many features like ARexx support and a rich API by which your Dockies can control most of AmiDock's features.

What is a Dock and a Docky?

Dock

A Dock is an area or window where the user can put a program icon or an interactive program.

Docky

A Docky is a little program to be placed in a dock. Dockies are able to control most of AmiDock's features and provides a great way to expand AmiDock beyond its default functionality. Dockies may be invisible to the user or show static or dynamic (animated) content. You may change their behavior, size and look according to requirements. Dockies are one of two main types:

Standalone Dockies

A standalone Docky 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 type of Docky. This Docky type uses the standard shared library feature of AmigaOS as a common interface.

Application Dockies

The second type of Docky is an application Docky which may sometimes be known as an 'AppDocky' or 'AppDockIcon Docky'. An AppDocky is a Docky which is introduced to the system at run time by an application using the application.library registration mechanism for applications. The biggest difference between the two types of Dockies 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 to get started.

FAQ

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

A: 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 un-register/re-register to get it to change though, so no good for frequent changes)

Q: I have successfully drawn a datatype (a picture) in a Docky and the picture file has more than 256 colors, but it is rendered in 256 colors only. Why ?

A: Just add PDTA_DestMode, PMODE_V43 to the NewDTObject call. You might also want to add DTA_GroupID, GID_PICTURE in order to restrict the file type to pictures.

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: 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: 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 (source code is here, prefsobjects_macro.h include file which is required here) is told to rethink its layout in response to a change in preferences, or Intuition windows list. A shared structure and Mutex to protect the data. By the way, winbar.docky source code can be helpful not only for that, but for all other things such as adding context menus, firing requests to AmiDock or other of the many still undocumented features of the API.

I.e. you are notified about the task/bit to signal through DOCKYSET_DockyAttention (you would store it in the library base for an easy access by the main program). When your program signals AmiDock, every docky is sent the DOCKYGET_NeedsAttention message, so it is a good idea to use a flag to know if the notification really comes from your program.

Links

1. SDK:Documentation/AutoDocs/docky.doc

2. Sys:Documentation/Commodities/AmiDock_Arexx.doc

3. SDK:Examples/AmiDock/