Utility, Locale, ASL, IFFParse, DataTypes, and Commodities Libraries¶

These are the supporting libraries that most AmigaOS programs use alongside exec, dos, intuition, and graphics.

utility.library — TagItems, Hooks, strings¶

TagItems¶

TagItem is the central V36+ data structure — a flexible key-value list used by nearly every modern Amiga API:

struct TagItem { ULONG ti_Tag; ULONG ti_Data; };

Special tag values (top bits of ti_Tag): TAG_DONE (0, end of list), TAG_IGNORE, TAG_MORE (ti_Data points to another tag list), TAG_SKIP.

Key functions:

struct TagItem *FindTagItem(ULONG tag, struct TagItem *tagList);
ULONG GetTagData(ULONG tag, ULONG default, struct TagItem *tagList);
struct TagItem *NextTagItem(struct TagItem **tagPtr);
struct TagItem *AllocateTagItems(ULONG count);
void FreeTagItems(struct TagItem *tagList);
struct TagItem *CloneTagItems(struct TagItem *tagList);

Pattern: AllocateTagItems(n) → fill in tags → pass to API → FreeTagItems(). For varargs, use the ...Tags() stub (e.g., SetAttrs() wraps SetAttrsA()).

Hooks¶

Hooks are callback function pointers used throughout AmigaOS (gadtools callbacks, datatype triggers, commodity input handlers):

struct Hook {
    struct MinNode h_MinNode;
    ULONG (*h_Entry)();  /* dispatcher entry point */
    APTR  h_SubEntry;    /* secondary entry (optional) */
    APTR  h_Data;        /* user data */
};

Hook convention: h_Entry is called with a0 = hook, a2 = object, a1 = message packet. Return value in a0.

Call a hook:

ULONG CallHookPkt(struct Hook *hook, APTR object, APTR paramPacket);

locale.library — internationalization¶

struct Locale *OpenLocale(STRPTR name);   /* NULL = system default */
void CloseLocale(struct Locale *locale);

struct Catalog *OpenCatalog(struct Locale *locale, STRPTR name, struct TagItem *tags);
void CloseCatalog(struct Catalog *catalog);
STRPTR GetCatalogStr(struct Catalog *catalog, LONG num, STRPTR defaultStr);
STRPTR GetLocaleStr(struct Locale *locale, LONG num);  /* built-in strings: days, months */

Pattern: OpenLocale(NULL) for system locale → OpenCatalog() for your app's translations → GetCatalogStr(cat, stringNum, "English default") to get each translated string.

FormatDate() and FormatString() provide locale-aware date/string formatting. IsAlNum(), IsAlpha(), IsDigit() etc. are locale-aware character classifiers.

V40+: the Language environment variable contains the current system language name.

asl.library — requesters¶

APTR AllocAslRequest(ULONG type, struct TagItem *tags);
BOOL AslRequest(APTR requester, struct TagItem *tags);
void FreeAslRequest(APTR requester);

Types: ASL_FileRequest, ASL_FontRequest, ASL_ScreenModeRequest (V38+).

All requester structures are read-only — modify only through tags. Common file-requester tags: ASLFR_DrawersOnly, ASLFR_DoSaveMode, ASLFR_InitialFile, ASLFR_InitialDrawer, ASLFR_SleepWindow, ASLFR_FilterFunc.

iffparse.library — IFF file handling¶

IFF (Interchange File Format) is the native Amiga structured file format. iffparse.library provides a stream-based parser:

struct IFFHandle *iff = AllocIFF();
iff->iff_Stream = Open("file.ilbm", MODE_OLDFILE);
InitIFFasDOS(iff);                          /* use DOS stream */
OpenIFF(iff, IFFF_READ);                    /* open for reading */
PropChunk(iff, ID_ILBM, ID_BMHD);           /* collect BMHD property */
StopChunk(iff, ID_ILBM, ID_BODY);           /* stop at BODY */
ParseIFF(iff, IFFPARSE_SCAN);               /* parse */
ReadChunkBytes(iff, buffer, size);          /* read BODY data */
CloseIFF(iff);
FreeIFF(iff);

For writing: PushChunk(iff, ID_FORM, ID_ILBM) → write data → PopChunk(iff).

Clipboard I/O: InitIFFasClip(iff) instead of InitIFFasDOS. Units 0+.

datatypes.library — transparent data handling¶

DataTypes is an OO system built on BOOPSI for loading, displaying, and converting data formats (images, sound, text, animation). Each format is a class (shared library) under DEVS:DataTypes/.

APTR dtObj = NewDTObjectA("image.ilbm", tags);   /* load from file */
GetDTAttrsA(dtObj, PDTA_BitMap, &bitmap, TAG_DONE); /* get the bitmap */
AddDTObject(win, NULL, dtObj, CHILD_WINDOW);       /* embed in window */
DoDTMethodA(dtObj, win, NULL, DTM_PROCLIMETHOD, ...); /* invoke method */
DisposeDTObject(dtObj);

Key properties: - Embedded objects are BOOPSI gadgets — input handling is on Intuition's task. - Time-intensive operations (layout, printing, file read/write) are off-loaded to a sub-process — they're asynchronous. - Format conversion: read ILBM, write JPEG (both are PICTURE subclasses). - Classes: PICTURE (ILBM, JPEG, GIF, BMP), SOUND (8SVX, AIFF), TEXT, ANIMATION, AMIGAGUIDE.

commodities.library — input event system¶

Commodities intercept and transform keyboard/mouse input system-wide:

struct CxObj *broker = CxBroker(&cxb, NULL);  /* create broker */
AttachCxObj(broker, filter);                   /* build object tree */
ActivateCxObj(broker, TRUE);                   /* activate (brokers start inactive) */

Object types: CX_BROKER (root), CX_FILTER (match input events), CX_TYPE (classify), CX_SENDER (send message), CX_SIGNAL (send signal), CX_TRANSLATE (replace event), CX_DEBUG (log), CX_CUSTOM (custom hook).

Input expressions (IX): ParseIX("rawkey ctrl f1") creates an input filter. Qualifiers support synonyms: LAMIGA, LEFT_AMIGA, CTRL, CAPS_LOCK, etc.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search