Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "AmiDock and Dockies"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Introduction =
 
= 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.
+
AmiDock is a tool to maintain a graphical menu bars (Docks) at the Workbench screen that can be used or to execute other programs from a selection of icons (either in the main Dock or in sub-Docks as specified by the AmiDock preferences), or to handle special kind of application called "Dockies", which can provide different functionality: render different kind of data right into the dock, provide user with a menu related to the Docky of choice and so on.
   
  +
AmiDock implemented as commodity, and together with being responsible for creating and controlling Docks and Dockies it provide different functionality such as ARexx support and a rich API by which your Dockies can control most of AmiDock's features.
= What is AmiDock =
 
   
  +
= What is a Dock and a Docky? =
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 ==
 
== Dock ==
  +
A Dock is an area/a window where the user can put a program icon or an interactive program.
 
  +
A Dock is an area or window where the user can put a program icon or an interactive program.
   
 
[[File:Laucher_dock.png|center]]
 
[[File:Laucher_dock.png|center]]
Line 16: Line 15:
 
== Docky ==
 
== 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:
+
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'''.
+
=== 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.
+
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'''.
+
=== 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.
+
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)
 
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)
 
= AmiDock's API =
 
 
= Different types of Dockies =
 
 
== Standalone Dockies ==
 
 
== Application Dockies ==
 
   
 
= How to create and manipulate a simple docky =
 
= How to create and manipulate a simple docky =
Line 44: Line 35:
 
= FAQ =
 
= FAQ =
   
''Q: Is it possible to create an application docky and then update its content on the fly and how ?
+
== 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)
+
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.
''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 ?
 
   
  +
== How are context menus created? ==
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.
 
   
  +
Context menus are dynamically built in response to DOCKYGET_ContextMenu attribute:
 
''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:
 
   
 
<syntaxhighlight>
 
<syntaxhighlight>
Line 98: Line 87:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
  +
== 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).
''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.
 
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.
Line 107: Line 95:
 
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).
 
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. [http://os4depot.net/share/utility/docky/winbar-docky.lha winbar.docky] ([http://os4depot.net/share/utility/docky/winbar_docky_src.zip source code is here], prefsobjects_macro.h include file which is required [http://openamiga.org/attachment/project/29/prefsobjects_macros.h here]) is told to rethink its layout in response to a change in preferences, or Intuition windows list. A shared structure and [[Exec_Mutexes|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.
''Q: Is there a way to trigger a redraw from outside the docky ?
 
   
  +
== How does DOCKYGET_SupportsComposite work? ==
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 [[Exec_Mutexes|Mutex]] to protect the data.
 
   
  +
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
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.
 
  +
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
= Final Words =
 
  +
(8-bit) bitmap provided in the DockyRenderDestination's alpha.RP field.
   
= Links =
+
= See Also =
   
 
1. SDK:Documentation/AutoDocs/docky.doc
 
1. SDK:Documentation/AutoDocs/docky.doc
   
2. Sys:Documentation/Commodities/AmiDock_Arexx.doc
+
2. SYS:Documentation/Commodities/AmiDock_Arexx.doc
   
 
3. SDK:Examples/AmiDock/
 
3. SDK:Examples/AmiDock/

Latest revision as of 10:27, 1 May 2014

Introduction

AmiDock is a tool to maintain a graphical menu bars (Docks) at the Workbench screen that can be used or to execute other programs from a selection of icons (either in the main Dock or in sub-Docks as specified by the AmiDock preferences), or to handle special kind of application called "Dockies", which can provide different functionality: render different kind of data right into the dock, provide user with a menu related to the Docky of choice and so on.

AmiDock implemented as commodity, and together with being responsible for creating and controlling Docks and Dockies it provide different functionality such as 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.

Laucher dock.png

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.

See Also

1. SDK:Documentation/AutoDocs/docky.doc

2. SYS:Documentation/Commodities/AmiDock_Arexx.doc

3. SDK:Examples/AmiDock/