IconControlA

Set and get icon and icon.library options (V44)

This function is used to modify and query icon and icon.library options.

icon

Pointer to a struct DiskObject, or NULL if global options are to be modified/queried.

tags

Options to modify/query.

ICONCTRLA_SetGlobalScreen (struct Screen *)

Pointer to the screen to remap palette mapped icons to. This is commonly used by workbench.library after it has initialized itself and before/after screen open/close transitions. If the screen is set to NULL, the icon colour remapping strategy is changed: colours are no longer allocated from a screen and the colours to map to will come from a default colour colour table with four palette entries. Please note that once you select a screen to remap to, you cannot tell icon.library to use a different screen; you first need to tell icon.library to "let go" of the previously selected screen by passing a NULL ICONCTRLA_SetGlobalScreen parameter. You can set a different screen only after this is done.

ICONCTRLA_GetGlobalScreen (struct Screen **)

Pointer to the screen to remap palette mapped icons to.

ICONCTRLA_SetGlobalPrecision (LONG)

Set the global colour allocation precision used when remapping icons for display. Default is PRECISION_ICON.

OBP_Precision (LONG)

Can be used as an alias for the ICONCTRLA_SetGlobalPrecision tag.

ICONCTRLA_GetGlobalPrecision (LONG *)

Get the global colour allocation precision used when remapping icons for display.

ICONCTRLA_SetGlobalEmbossRect (struct Rectangle *)

Set the frame sizes used for drawing icons. The Rectangle must be initialized as follows:

Rectangle->MinX Width of left edge border (negative),

must be in the range [-255..-1]

Rectangle->MinY Height of top edge border (negative),

must be in the range [-255..-1]

Rectangle->MaxX Width of right edge border (positive),

must be in the range [1..255]

Rectangle->MaxY Height of bottom edge border (positive),

must be in the range [1..255]

ICONCTRLA_GetGlobalEmbossRect (struct Rectangle *)

Get the frame sizes used for drawing icons.

ICONCTRLA_SetGlobalFrameless (BOOL)

Select whether icons should always be drawn without a surrounding frame. This option defaults to FALSE.

ICONCTRLA_GetGlobalFrameless (LONG *)

Query whether icons are always drawn without a surrounding frame.

ICONCTRLA_SetGlobalIdentifyHook (struct Hook *)

Set the hook that is invoked when trying to find an icon for a file/drawer/volume that does not have an icon associated with it. If set to NULL, no hook will be called. The hook will be called with the following parameters:

hookFunc(hook,reserved,iim)

A0 A2 A1

VOID hookFunc(struct Hook *hook,APTR reserved,

struct IconIdentifyMsg *iim);

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

The icon identification message contents are as follows:

iim_SysBase

see next

iim_DOSBase

see next

iim_UtilityBase

see next

iim_IconBase

Library base pointers set up for your use.

iim_FileLock

A lock on the object to return an icon for. This lock is guaranteed to be non-NULL.

iim_ParentLock

A lock on the object's parent directory. This may be NULL if iim_FileLock points to a volume's root directory. In such a case you should return a WBDISK type icon instead of a WBDRAWER icon.

iim_FIB

An initialized FileInfoBlock structure; prior to passing iim_FIB to you, Examine(iim_FileLock,iim_FIB) was called. Unlike the other members of this data structure, you may modify the contents of iim_FIB.

iim_FileHandle

If the object to return an icon for is a file, this member will contain a file handle that can be used to Read() its contents. The file read position will be set to the beginning of the file. Note that this member can be NULL.

iim_Tags

A copy of the tag item list passed to GetIconTagList(); if you are going to call GetIconTagList() in your hook, be sure to include this list as part of the tag list you pass to it.

NOTE:

This list does not include the tag ICONA_FailIfUnavailable. Keep in mind that the use of this tag can trigger a recursion if the icon you tried to retrieve via GetIconTagList() does not exist: your hook code will be invoked again.

With the exception of iim_FIB, all members of the IconIdentifyMsg are read-only; you may pass them to functions like Read(), Examine(), etc. but you may not Close() files, UnLock() locks or perform other functions that may result in the data structures getting deallocated or trashed.

When you manage to find the right icon type for the object to be examined, you should return a pointer to a struct DiskObject that can be freed using FreeDiskObject() lateron. Note that you cannot just return a pointer to a statically initialized data structure in your code, you must return a pointer to a DiskObject allocated by icon.library itself, such as through GetIconTagList(), DupDiskObjectA() or NewDiskObject().

The icon you return will be checked to make sure that its type matches the corresponding object. For example, returning a WBDRAWER icon for a volume root directory will cause that icon to be released and to be ignored.

ICONCTRLA_GetGlobalIdentifyHook (struct Hook **)

Get the hook that is invoked when trying to find an icon for a file/drawer/volume that does not have an icon associated with it.

ICONCTRLA_SetGlobalMaxNameLength (LONG)

icon.library has a built-in file name length limit that affects whether icon files are read and written. Currently, the default for this value is 25 characters. This is sufficient for an icon file name acceptable with the ROM filing system. This limit has two effects: if an icon file is to be written whose name would be longer than the limit, icon.library will silently abort the write attempt and pretend that the icon file has been written; this is done in order to avoid overwriting the original data file with the icon file. If an icon file was read that turns out to contain invalid icon data, another test is done in order to find out whether the file name was longer than the limit. If this is the case, it is assumed that the data was read from the original file rather than from the icon file. The library then pretends that the icon file was not found.

This tag can be used to set this length limit. The limit must be in the range [8..255].

ICONCTRLA_GetGlobalMaxNameLength (LONG *)

Retrieve the file name length limit used by icon.library.

ICONCTRLA_SetGlobalNewIconsSupport (BOOL)

Select whether icon.libray should read and return coloured icon images stored in NewIcons format. This option defaults to TRUE.

ICONCTRLA_GetGlobalNewIconsSupport (LONG *)

Query whether icon.library will read and return coloured icon images stored in NewIcons format.

ICONCTRLA_SetGlobalColorIconSupport (BOOL)

Select whether icon.libray should read and return coloured icon images. This option defaults to TRUE.

ICONCTRLA_GetGlobalColorIconSupport (LONG *)

Query whether icon.library will read and return coloured icon images.

ICONA_ErrorCode (LONG *)

Pointer to a LONG word variable to store error codes in. Note that this variable will be initialized regardless of whether an error occured or not. Thus, you can check for an error condition by comparing the variable contents against 0; 0 indicates success, all other values are error codes as defined by dos.library.

ICONA_ErrorTagItem (struct TagItem **)

When an error occurs whilst processing the tag item list passed to IconControl(), you can have a pointer to the item that caused the error passed back via the ICONA_ErrorTagItem tag. Note that for TagItem lists allocated from the stack the address passed back to you may no longer be valid when control returns from IconControl().

The following tags need a valid icon parameter to operate on. If the parameter is missing or invalid, it will be registered as an error.

ICONCTRLA_GetImageMask1 (PLANEPTR *)

Pointer to the mask plane for the regular icon image (icon->do_Gadget.GadgetRender). Note that this may be NULL.

ICONCTRLA_GetImageMask2 (PLANEPTR *)

Pointer to the mask plane for the alternate icon image (icon->do_Gadget.SelectRender). Note that this may be NULL.

ICONCTRLA_SetTransparentColor1 (LONG)

Set the transparent colour for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). The colour must be among the valid palette entries, e.g. for a 16 colour image, the transparent colour may not be larger than 15. To make the icon image opaque, set its transparent colour to -1.

ICONCTRLA_GetTransparentColor1 (LONG *)

Get the transparent colour for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). If the image is opaque, its "transparent colour" will be returned as -1. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result.

ICONCTRLA_SetTransparentColor2 (LONG)

Set the transparent colour for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). The colour must be among the valid palette entries, e.g. for a 16 colour image, the transparent colour may not be larger than 15. To make the icon image opaque, set its transparent colour to -1. Please note that you can set the alternate image transparent colour only if there is an alternate image.

ICONCTRLA_GetTransparentColor2 (LONG *)

Get the transparent colour for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). If the image is opaque, its "transparent colour" will be returned as -1. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. Likewise, if there is no alternate image, no information may be available.

ICONCTRLA_SetPalette1 (struct ColorRegister *)

Set the colour palette for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender).

ICONCTRLA_GetPalette1 (struct ColorRegister **)

Get the colour palette for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. Note that the number of palette entries in this table matches the number of colours in use when the icon was first created.

ICONCTRLA_SetPalette2 (struct ColorRegister *)

Set the colour palette for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender).

ICONCTRLA_GetPalette2 (struct ColorRegister **)

Get the colour palette for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. If there is no alternate image, no information may be available. Note that the number of palette entries in this table matches the number of colours in use when the icon was first created.

ICONCTRLA_SetPaletteSize1 (ULONG)

Set the size of the colour palette to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). This value must be in the range [1..256].

ICONCTRLA_GetPaletteSize1 (ULONG *)

Get the size of the colour palette to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result.

ICONCTRLA_SetPaletteSize2 (ULONG)

Set the size of the colour palette to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). This value must be in the range [1..256].

ICONCTRLA_GetPaletteSize2 (ULONG *)

Get the size of the colour palette to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. If there is no alternate image, no information may be available.

ICONCTRLA_SetImageData1 (UBYTE *)

Set the image data to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). There must be exactly as many bytes of image data as the image width multiplied by its height requires.

To drop the palette mapped image data associated with an icon, use "ICONCTRLA_SetImageData1,NULL,".

ICONCTRLA_GetImageData1 (UBYTE **)

Get the image data to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result.

ICONCTRLA_SetImageData2 (UBYTE *)

Set the image data to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). There must be exactly as many bytes of image data as the image width multiplied by its height requires.

To drop the palette mapped image data associated with the alternate image of an icon, use "ICONCTRLA_SetImageData2,NULL,".

ICONCTRLA_GetImageData2 (UBYTE **)

Get the image data to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. If there is no alternate image, no information may be available.

ICONCTRLA_SetFrameless (BOOL)

Select whether the icon should be drawn without a frame. This option defaults to FALSE.

ICONCTRLA_GetFrameless (LONG *)

Query whether the icon should be drawn without a frame.

ICONCTRLA_SetNewIconsSupport (BOOL)

Select whether palette mapped icon images that were originally stored in NewIcons format should be written back in the same format. This option defaults to TRUE.

ICONCTRLA_GetNewIconsSupport (LONG *)

Query whether palette mapped icon images that were originally stored in NewIcons format should be written back in the same format.

ICONCTRLA_SetAspectRatio (UBYTE)

Set the icon aspect ratio; this consists of a numerator and a denominator packed into a single byte (the PACK_ICON_ASPECT_RATIO() macro can be used for encoding this parameter). If the icon aspect ratio is unknown, ICON_ASPECT_RATIO_UNKNOWN should be used.

ICONCTRLA_GetAspectRatio (UBYTE *)

Get the icon aspect ratio; this consists of a numerator and a denominator packed into a single byte (the UNPACK_ICON_ASPECT_RATIO() macro can be used for decoding this value). If the icon aspect ratio is unknown, ICON_ASPECT_RATIO_UNKNOWN will be returned.

ICONCTRLA_SetWidth (ULONG)

Select the palette mapped icon image width. This value must be in the range [1..256].

ICONCTRLA_GetWidth (ULONG *)

Query the palette mapped icon image width. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result.

ICONCTRLA_SetHeight (ULONG)

Select the palette mapped icon image height. This value must be in the range [1..256].

ICONCTRLA_GetHeight (ULONG *)

Query the palette mapped icon image height. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result.

ICONCTRLA_IsPaletteMapped (LONG *)

Query whether the icon is using palette mapped icon images.

ICONCTRLA_IsNewIcon (LONG *)

Query whether the icon is of the NewIcon type.

ICONCTRLA_IsNativeIcon (LONG *)

There is an important difference between struct DiskObject icons allocated by icon.library itself (these are the so-called "native" icons) and statically initialized icons which consist solely of a simple struct DiskObject which may be part of a program's static data area. For example, you can attach a palette mapped icon image to a "native" icon, which is something you cannot do with a statically allocated icon. To help you tell the two types apart, you can use the ICONCTRLA_IsNativeIcon query tag.

ICONGETA_IsDefaultIcon (LONG *)

Query whether this icon is associated with a file/drawer/volume or is a "fake" icon that was constructed for an object that has no icon associated with it.

ICONCTRLA_GetScreen (struct Screen **)

Get the screen this icon has been remapped to and whose colour map it uses. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result.

This tag may return NULL if the icon is not currently associated with a screen.

ICONCTRLA_HasRealImage2 (LONG *)

icon.library may generate an alternate image for palette mapped icons if there is no image data stored for this image. To find out whether an icon was generated or is part of the original icon image, use the ICONCTRLA_HasRealImage2 tag.

processed

Number of tags that were processed correctly, i.e. the number of tags whose parameters are in order, for which information could be returned, etc. If processing stops because of an error, the number returned by this function will be smaller than the number of tag items passed in. The same happens if the information you wanted to obtain is unavailable. In any case, check the error code this routine can set up for you.

Changing an icon's palette or image data does not automatically produce a different icon image you can use. To do this, you must re-layout it using LayoutIcon().

When querying parameters, make sure to always pass in a pointer to a LONG word variable to store the result in.

Some get/set operations may cause additional memory to be allocated. This may fail; be prepared.

IconControl() processes the tag item list in sequential order. This has consequences for several tags, such as the palette size and the transparent colour. For example, if you want to make colour #14 of an icon image transparent, make sure to have the palette size set to at least 15 colours before you try to change the transparent colour. Otherwise, IconControl() may refuse to set the transparent colour to #14 since it won't know that there should be more than 14 colours in that image at the time you try to set it. Therefore, if you wanted to change the palette size and the transparent colour in the same tag item list, make sure that the palette size change tag appears before the transparent colour change tag.

As described above, some of the operations on icons are not supported for DiskObjects not allocated through icon.library. In such cases you will receive an error code ERROR_ACTION_NOT_KNOWN.

When you set an icon's palette or image data (with one of the following tags: ICONCTRLA_SetPalette1, ICONCTRLA_SetPalette2, ICONCTRLA_SetImageData1, ICONCTRLA_SetImageData2), icon.library will only update the respective data pointers in the icon, it will not copy the data pointed to. This means that the palette and image data information must stay valid until the icon they are attached to is disposed of. If you want to play it safe and be able to release the palette and image data as soon as possible, make a copy of the icon with icon.library/DupDiskObjectA.

When you create a palette mapped icon from an old one, make sure that if your new icon should use only a single icon image the second image needs to be set to NULL. Otherwise, the image data the icon started with will remain attached to it. Since the new icon size may not match the old icon size the result may not look too pretty. To tell icon.library that the second image is not needed use "IconControl(icon,ICONCTRLA_SetImageData2,NULL,TAG_DONE);".

dos.library/IoErr(), icon.library/DupDiskObjectA(), icon.library/GetIconTagList(), icon.library/LayoutIcon(), icon.library/NewDiskObject(), graphics.library/BltMaskBitMapRastPort(), graphics.library/ObtainBestPenA(), utility.library/CallHookPkt(), <graphics/view.h>, <workbench/icon.h>, <workbench/workbench.h>