Intuition Library Reference¶

intuition.library is the AmigaOS GUI subsystem — windows, screens, gadgets, menus, requesters, and the BOOPSI object system. It is the second most-used library after exec.

BOOPSI — the V36+ object model¶

BOOPSI (Basic Object Oriented Programming System for Intuition) is the foundation of all V36+ GUI objects. Windows, screens, and gadgets are all BOOPSI objects.

APTR  NewObjectA(struct IClass *classPtr, STRPTR classID, struct TagItem *tags);
void  DisposeObject(APTR object);
ULONG SetAttrsA(APTR object, struct TagItem *tags);
ULONG GetAttr(ULONG attrID, APTR object, ULONG *storage);

Custom classes — create your own BOOPSI classes (e.g., custom gadgets):

struct IClass *MakeClass(STRPTR classID, STRPTR superClassID,
                         struct IClass *superClassPtr, ULONG instanceDataSize, ULONG flags);
void AddClass(struct IClass *classPtr);     /* make public */
void RemoveClass(struct IClass *classPtr);
void FreeClass(struct IClass *classPtr);

Subclassing pattern: MakeClass() → implement OM_NEW, OM_DISPOSE, OM_SET, OM_GET, and your custom method IDs in a dispatcher function → AddClass() if public. Always call the superclass method first (DoSuperMethodA()), then add your behavior.

Opening windows and screens¶

V36+ uses tag-based APIs:

struct Window *OpenWindowTags(struct NewWindow *nw, Tag tag1, ...);
struct Screen *OpenScreenTags(struct NewScreen *ns, Tag tag1, ...);

Key window tags: WA_Left, WA_Top, WA_Width, WA_Height, WA_Title, WA_IDCMP (which input events), WA_Flags, WA_CustomScreen, WA_PubScreenName, WA_NewLookMenus (V39).

Key screen tags: SA_Left, SA_Top, SA_Width, SA_Height, SA_Title, SA_DisplayID (mode ID), SA_Depth, SA_Type (CUSTOMSCREEN, WBENCHSCREEN).

IDCMP — the input event model¶

Each window has an IDCMP port that delivers IntuiMessage events. You choose which events to receive via the WA_IDCMP flag:

IDCMP Flag	Event
`IDCMP_VANILLAKEY`	Keyboard (ASCII)
`IDCMP_RAWKEY`	Keyboard (raw scancode)
`IDCMP_MOUSEBUTTONS`	Mouse button up/down
`IDCMP_MOUSEMOVE`	Mouse movement
`IDCMP_GADGETUP` / `IDCMP_GADGETDOWN`	Gadget interaction
`IDCMP_MENUPICK`	Menu item selected
`IDCMP_CLOSEWINDOW`	Close gadget
`IDCMP_SIZEVERIFY` / `IDCMP_NEWSIZE`	Window resize
`IDCMP_REFRESHWINDOW`	Window needs redraw
`IDCMP_INTUITICKS`	Periodic timer (~every 0.5s)
`IDCMP_ACTIVEWINDOW` / `IDCMP_INACTIVEWINDOW`	Focus change

Event loop pattern:

struct IntuiMessage *msg;
while ((msg = (struct IntuiMessage *)GetMsg(win->UserPort)))
{
    switch (msg->Class)
    {
        case IDCMP_CLOSEWINDOW:  running = FALSE; break;
        case IDCMP_GADGETUP:     /* handle gadget */ break;
        case IDCMP_MENUPICK:     /* handle menu */ break;
    }
    ReplyMsg((struct Message *)msg);
}
Wait(1 << win->UserPort->mp_SigBit | ...);

Always ReplyMsg() every message you GetMsg().

Classic vs. BOOPSI gadgets¶

Classic gadgets (struct Gadget, pre-V36): AddGadget(), RemoveGadget(), ModifyProp(). Limited.
BOOPSI gadgets (V36+): created via NewObject() with a class pointer. Support methods, attributes, subclassing. The modern way.

GadTools (see GadTools Library Reference) provides higher-level gadget creation on top of BOOPSI.

Screens and public screens¶

A public screen (CUSTOMSCREEN with SA_PubSnap) can be shared by multiple applications. Other apps open windows on it via WA_PubScreenName. LockPubScreen(name) gets a reference; UnlockPubScreen() releases it.

GetScreenDrawInfo(screen) / FreeScreenDrawInfo() — get screen rendering info (pen colors, font, display mode). Always paired.

Status: Outdated (V47, AmigaOS 3.2) — DrawInfo version. DRI_VERSION is now 3 (was 2 for V39), NUMDRIPENS is 13 (was 12) with a new BARCONTOURPEN, and the struct gains a dri_Screen backpointer. Code that hard-codes NUMDRIPENS or assumes DRI_VERSION == 2 must be updated. See AmigaOS 3.2 — What Changed for Developers.

AmigaOS 3.2 (V47) intuition additions¶

For OS 3.2 targets, Intuition gained several features (full list in AmigaOS 3.2 — What Changed for Developers):

Iconify gadget: WA_IconifyGadget,TRUE (WA_Dummy + 0x60) adds a hide gadget; it sends IDCMP_CloseWindow with msg->Code == 1 (hide) vs 0 (close).
Native scrollwheel support (V47.26), shift-click zoom = maximize, GA_Underscore/GA_ActivateKey hotkeys, MIF_SHIFTCOMMSEQ (0x0800) shift-shortcuts.
SA_OpenBorder lets windows drag partly off-screen.
ShowWindow()/HideWindow() reimplemented (V50-derived); IntuitionControlA() is a new multi-purpose entry point.
New sysiclass images (MENUSUB, FRAME_PROPBORDER, etc.) and OSERR_NORTGBITMAP (10) from OpenScreen on RTG bitmap failure.

Window refresh¶

When a window is damaged (covered/uncovered), Intuition sends IDCMP_REFRESHWINDOW. Use BeginRefresh() / EndRefresh():

case IDCMP_REFRESHWINDOW:
    BeginRefresh(win);
    /* redraw damaged areas */
    EndRefresh(win, TRUE);
    break;

BeginRefresh() locks layers and sets up a restricted clip for efficient repainting. See Intuition Layer Locking — don't call Intuition functions inside BeginRefresh/EndRefresh (it holds a layer lock).

Screen buffers (double buffering)¶

struct ScreenBuffer *AllocScreenBuffer(screen, bitMap, flags);
ChangeScreenBuffer(screen, sb);
FreeScreenBuffer(sb);

Enables double-buffered screen display for flicker-free animation. DBUF_INFO from AllocDBufInfo() (graphics.library) for synchronized buffer swaps at vertical blank.

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