Name
LoadIcon -- load icon into memory (V9.0)
Synopsis
APTR handle = LoadIcon(STRPTR filename, struct hwTagList *tags);
Function
This function has to open the specified filename, check if it is in a format that the plugin wants to handle, and, if it is, return a handle to the icon back to Hollywood. Otherwise it has to return NULL. The handle returned by LoadIcon() is an opaque datatype that only your plugin knows about. Hollywood will simply pass this handle back to your GetIconImages() function when it wants to get the individual images in your icon.

Hollywood may also pass a tag list to your LoadIcon() implementation. This list may contain the following tags:

HWLDICONTAG_ADAPTER:
If this tag is specified, Hollywood wants your plugin to use the file adapter specified by the string stored in the pData member to open the icon. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the icon file because the former doesn't support file adapters. See hw_FOpenExt for details.

HWLDICONTAG_AMIGAEXT:
If this tag is set, pData points to a struct hwIconAmigaExt that your plugin can initialize with metadata obtained from the icon. This is for compatibility with Amiga icons which contain metadata in addition to the image data. struct hwIconAmigaExt looks like this:

 
struct hwIconAmigaExt
{
    int Type;
    int ViewMode;
    int IconX;
    int IconY;
    int DrawerX;
    int DrawerY;
    int DrawerWidth;
    int DrawerHeight;
    int StackSize;
    STRPTR DefaultTool;
    STRPTR *ToolTypes;
    ULONG Flags;
};

Here's an explanation of the individual structure members:

Type:
This must be set to the icon's type. This can be one of the following predefined constants:

 
HWAMIGAICON_NONE
HWAMIGAICON_DISK
HWAMIGAICON_DRAWER
HWAMIGAICON_TOOL
HWAMIGAICON_PROJECT
HWAMIGAICON_GARBAGE
HWAMIGAICON_DEVICE
HWAMIGAICON_KICKSTART

ViewMode:
This must be set to the icon's view mode. This can be one of the following predefined constants:

 
HWAMIGAICONMODE_NONE
HWAMIGAICONMODE_ICONS
HWAMIGAICONMODE_NAME
HWAMIGAICONMODE_DATE
HWAMIGAICONMODE_SIZE
HWAMIGAICONMODE_TYPE

IconX:
The icon's x position on Workbench screen.

IconY:
The icon's y position on Workbench screen.

DrawerX:
In case Type is set to a container type like HWAMIGAICON_DRAWER, set this to the x position of the new window that will be opened when double-clicking the icon.

DrawerY:
In case Type is set to a container type like HWAMIGAICON_DRAWER, set this to the y position of the new window that will be opened when double-clicking the icon.

DrawerWidth:
In case Type is set to a container type like HWAMIGAICON_DRAWER, set this to the width of the new window that will be opened when double-clicking the icon.

DrawerHeight:
In case Type is set to a container type like HWAMIGAICON_DRAWER, set this to the height of the new window that will be opened when double-clicking the icon.

StackSize:
In case Type is set to HWAMIGAICON_TOOL or HWAMIGAICON_PROJECT, the desired stack size for the program to be launched.

DefaultTool:
In case Type is set to HWAMIGAICON_PROJECT, this must be set to a null-terminated string containing name (and optionally path) of the program to open the file with.

ToolTypes:
If the icon has tooltypes, store them in this field. If set, this must be an array of STRPTR, each array item containing a single tooltype stored as a null-terminated string. The array you pass here must be terminated by a NULL entry which must be the last one.

Flags:
This structure member may be set to a combination of the following flags:

HWAMIGAICONFLAGS_VIEWALL:
If this is set and Type is a container type like HWAMIGAICON_DRAWER, all files will be visible, not only those that have an icon.

HWLDICONTAG_USERTAGS:
If this is set, pData will point to a struct hwUserTagList containing a list of user tags passed by the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. Note that even if your plugin doesn't support any user tags, you should still look for this tag and pass the user tags to hw_FOpenExt because the user tags passed in UserTags could also be intended for another plugin, namely the file adapter plugin passed in Adapter. See User tags for details. (V10.0)

Please note that you should not use ANSI C functions like fopen() to open the file that is passed to this function because the filename that is passed to this function can also be a specially formatted filename specification that Hollywood uses to load files that have been linked to applets or executables. In order to be able to load these files correctly, you have to use special IO functions provided by Hollywood. See File IO information for details.

Inputs
filename
filename to open
tags
tag list containing further options or NULL
Results
handle
a handle that identifies this icon or NULL if plugin doesn't want to handle this icon
Show TOC