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. And while AmiDock is a single commodity, its more than 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.

What are a Dock and a Docky?

Dock

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

Docky

A Docky is a little program be place in a dock. 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 AmigaOS 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 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 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.

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/