AddAppIconA

add an icon to Workbench's list of AppIcons. (V36)

Attempt to add an icon to Workbench's list of AppIcons. If successful, the icon is displayed on the Workbench backdrop (the same place disk icons are displayed).

This call is provided to allow applications to be notified when a graphical object (not neccessarely associated with a file) gets 'manipulated'.

The notification consists of an AppMessage (found in workbench.h/i) of type 'MTYPE_APPICON' arriving at the message port you specified.

The types of 'manipulation' that can occur are:

1. Double-clicking on the icon. am_NumArgs will be zero and

2. Dropping an icon or icons on your AppIcon. am_NumArgs will

3. Dropping your AppIcon on another icon. NOT SUPPORTED.

4. Invoking an "Icons" item with your icon selected. (V44)

id

this variable is strictly for your own use and is ignored by Workbench. Typical uses in C are in switch and case statements, and in assembly language table lookup.

userdata

this variable is strictly for your own use and is ignored by Workbench.

text

name of icon (char *)

lock

NULL (Currently unused)

msgport

pointer to message port Workbench will use to send you an AppMessage message of type 'MTYPE_APPICON' when your icon gets 'manipulated' (explained above).

diskobj

pointer to a DiskObject structure filled in as follows: do_Magic - NULL

do_Version

NULL

do_Gadget

a gadget structure filled in as follows: NextGadget - NULL

LeftEdge

NULL

TopEdge

NULL

Width

width of icon hit-box

Height

height of icon hit-box

Flags

NULL or GADGHIMAGE

Activation

NULL

GadgetType

NULL

GadgetRender

pointer to Image structure filled in as follows: LeftEdge - NULL

TopEdge

NULL

Width

width of image (must be <= Width of hit box)

Height

height of image (must be <= Height of hit box)

Depth

# of bit-planes in image

ImageData

pointer to actual word aligned bits (CHIP MEM)

PlanePick

Plane mask ((1 << depth) - 1)

PlaneOnOff

0

NextImage

NULL

SelectRender

pointer to alternate Image struct or NULL

GadgetText

NULL

MutualExclude

NULL

SpecialInfo

NULL

GadgetID

NULL

UserData

NULL

do_Type

NULL

do_DefaultTool

NULL

do_ToolTypes

NULL

do_CurrentX

NO_ICON_POSITION (recommended)

do_CurrentY

NO_ICON_POSITION (recommended)

do_DrawerData

NULL

do_ToolWindow

NULL

do_StackSize

NULL

(an easy way to create one of these (a DiskObject) is to create an icon

taglist

ptr to a list of tag items. Must be NULL for V2.0.

WBAPPICONA_SupportsOpen (BOOL)

Set this to TRUE if your AppIcon should respond to the "Open" menu, to FALSE otherwise. Note that with this attribute set to FALSE, users will still be able to double-click on your AppIcon and drop icons on it. This attribute solely controls whether the "Open" menu item will be available.

This tag defaults to TRUE. (V44)

WBAPPICONA_SupportsCopy (BOOL)

Set this to TRUE if your AppIcon should respond to the "Copy" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsRename (BOOL)

Set this to TRUE if your AppIcon should respond to the "Rename" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsInformation (BOOL)

Set this to TRUE if your AppIcon should respond to the "Information" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsSnapshot (BOOL)

Set this to TRUE if your AppIcon should respond to the "Snapshot" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsUnSnapshot (BOOL)

Set this to TRUE if your AppIcon should respond to the "UnSnapshot" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsLeaveOut (BOOL)

Set this to TRUE if your AppIcon should respond to the "Leave Out" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsPutAway (BOOL)

Set this to TRUE if your AppIcon should respond to the "Put Away" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsDelete (BOOL)

Set this to TRUE if your AppIcon should respond to the "Delete" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsFormatDisk (BOOL)

Set this to TRUE if your AppIcon should respond to the "Format Disk" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_SupportsEjectDisk (BOOL)

Set this to TRUE if your AppIcon should respond to the "Eject Disk" menu, to FALSE otherwise.

This tag defaults to FALSE. (V47)

WBAPPICONA_SupportsEmptyTrash (BOOL)

Set this to TRUE if your AppIcon should respond to the "Empty Trash" menu, to FALSE otherwise.

This tag defaults to FALSE. (V44)

WBAPPICONA_PropagatePosition (BOOL)

Set this to TRUE if you want the AppIcon's position to be propagated back to the original DiskObject you passed to this function. By default, Workbench will make a copy of that DiskObject's icon imagery, allowing you to free the DiskObject. But if you specify "WBAPPICONA_PropagatePosition,TRUE," Workbench will assume that you will not free it and that the AppIcon's current position should be stored in its do_CurrentX/do_CurrentY members.

This tag defaults to FALSE. (V44)

WBAPPICONA_RenderHook (struct Hook *)

Pointer to a hook that will be invoked when rendering your AppIcon. With this hook and WorkbenchControlA() you can create dynamic or animated AppIcons. Your hook will be called with the following parameters and has to return a result value:

result = hookFunc(hook,reserved,arm)

D0 A0 A2 A1

LONG hookFunc(struct Hook *hook,APTR reserved,

struct AppIconRenderMsg *arm);

The reserved parameter will be set to NULL (V44).

If your hook code returns TRUE, the AppIcon's regular image will be drawn. If your code returns FALSE, the regular image will not be drawn; this allows you to do all the icon's on-screen rendering with the exception of the icon image used when dragging the icon on the screen.

The render message contents are as follows:

arm_RastPort

A pointer to the RastPort to render into.

arm_Icon

A pointer to the Icon to be rendered.

arm_Label

A pointer to the label text to be printed below the icon.

arm_Tags

Further control tags which you should pass on to icon.library/DrawIconStateA, should you call this routine.

arm_Left

see next

arm_Top

Rendering origin; note that these coordinates DO NOT take the embossing border sizes into account.

arm_Width

see next

arm_Height

Size of the Icon's image area; you should limit your drawing to this area.

arm_State

An icon drawing state, such as used by icon.library/DrawIconStateA.

Note that all the data in the render message is read-only.

This tag defaults to NULL. (V44)

WBAPPICONA_NotifySelectState (BOOL)

Set this tag to TRUE if you want to be be notified whenever the AppIcon becomes selected or unselected. You will hear only state transitions, i.e. changes from selected to unselected state and the other way round. On a state transition you will receive AppMessages with the AppMessage->am_Class member set to AMCLASSICON_Selected or AMCLASSICON_Unselected, respectively.

This tag defaults to FALSE. (V44)

AppIcon

a pointer to an AppIcon structure which you pass to RemoveAppIcon when you want to remove the icon from Workbench's list of AppIcons. NULL if Workbench was unable to add your icon; typically happens when Workbench is not running or under low memory conditions.

For this function call to succeed, Workbench must be open. This means that the LoadWB command was executed and the Workbench screen has been opened.

RemoveAppIcon(), WorkbenchControlA(), icon.library/DrawIconStateA()

In workbench.library versions 36 through 40 Info cannot be obtained on appicons.