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 is the program responsible for creating and controlling docks and dockies. AmiDock is implemented as a commodity but 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

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

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)

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?

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.

How are context menus created?

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; 
 
/* ... */ 
}

How do you use an alpha layer for a Docky?

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

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

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.

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.

How does DOCKYGET_SupportsComposite work?

When compositing is enabled, a docky receives a DOCKYGET_SupportsComposite query. If it returns TRUE, it will then receive a DOCKYGET_CompositeMode query to which it can reply either DOCKYCOMPMODE_PreblendedRGB (0) or DOCKYCOMPMODE_RawRGB (1). The former has no advantages over the previous method, but was included for backward compatibility. The latter, however, allows you to directly *copy* the source ARGB data to the destination bitmap (or buffer) rather than blend it yourself. This way, it will be AmiDock itself that does the blending (once) without the need to undo the previous blending to get the raw RGB data.

One thing to take into account when using this method, though, is that on a 16-bit screen you will get an actual 16-bit destination bitmap, not 32-bit as it happens when returning FALSE to DOCKYGET_SupportsComposite. In this case, you will need to write the alpha channel separately to the (8-bit) bitmap provided in the DockyRenderDestination's alpha.RP field.

Links

1. SDK:Documentation/AutoDocs/docky.doc

2. Sys:Documentation/Commodities/AmiDock_Arexx.doc

3. SDK:Examples/AmiDock/