GadTools Library Reference

gadtools.library (V36+) provides higher-level GUI gadget and menu creation on top of BOOPSI. It handles the tedious low-level gadget layout, bevel boxes, menu construction, and IDCMP message filtering that raw Intuition requires.

The GadTools pattern

Every GadTools program follows this sequence:

/* 1. Get visual info from the screen */
struct VisualInfo *vi = GetVisualInfoA(screen, NULL);

/* 2. Create a gadget context (anchor for all GadTools gadgets) */
struct Gadget *glist = NULL;
struct Gadget *gad = CreateContext(&glist);

/* 3. Create gadgets in a chain */
struct NewGadget ng = { left, top, width, height, "OK", vi, ... };
gad = CreateGadgetA(BUTTON_KIND, gad, &ng, tags);

/* 4. Create menus */
struct Menu *menu = CreateMenusA(newmenu_array, tags);
LayoutMenusA(menu, vi, GTMN_NewLookMenus, TRUE, TAG_DONE);

/* 5. Add gadgets/menus to window */
AddGList(win, glist, -1, -1, NULL);
SetMenuStrip(win, menu);

/* 6. Event loop using GT_GetIMsg/GT_ReplyIMsg */
struct IntuiMessage *msg = GT_GetIMsg(win->UserPort);
/* ... handle ... */
GT_ReplyIMsg(msg);

/* 7. Cleanup */
ClearMenuStrip(win);
RemoveGList(win, glist, -1);
FreeGadgets(glist);
FreeMenus(menu);
FreeVisualInfo(vi);

Gadget kinds

Kind constant Widget type
BUTTON_KIND Push button
CHECKBOX_KIND Checkbox
CYCLE_KIND Cycle gadget (radio group)
MX_KIND Mutual exclusion (radio buttons)
LISTVIEW_KIND Scrolling list
NUMBER_KIND Integer display
PALETTE_KIND Color palette
SCROLLER_KIND Scrollbar
SLIDER_KIND Slider
STRING_KIND Text input
TEXT_KIND Read-only text label

GT_GetIMsg / GT_ReplyIMsg — the message filter

Always use GT_GetIMsg()/GT_ReplyIMsg() instead of GetMsg()/ReplyMsg() in GadTools windows. GadTools filters and transforms raw Intuition messages (e.g., converting slider position to meaningful values, handling string gadget editing).

For advanced filtering, GT_FilterIMsg() / GT_PostFilterIMsg() allow custom pre/post-processing of messages.

V39 enhancements

  • NewLook menus — GTMN_NewLookMenus, TRUE in LayoutMenusA(), plus WA_NewLookMenus, TRUE in OpenWindowTags().
  • GT_GetGadgetAttrsA() — read gadget attributes (e.g., GTLV_Top, GTLV_Selected for listviews).
  • Listview callbacks — GTLV_CallBack tag provides a hook for custom listview item rendering (draw images, graphics instead of text).
  • Palette improvements — GTPA_NumColors (replaces GTPA_Depth), GTPA_ColorTable for sparse palettes.
  • Menu command strings — NM_COMMANDSTRING flag + nm_CommKey for arbitrary text in the Amiga-key column.

LayoutMenusA

BOOL LayoutMenusA(struct Menu *menu, struct VisualInfo *vi, struct TagItem *tags);

Computes menu dimensions based on screen font and resolution. Must be called after CreateMenusA() and before SetMenuStrip(). The GTMN_NewLookMenus tag enables the V39 menu look.

See Also

Sources: Commodore-Amiga / ESCOM AG, gadtools.library Autodoc (1985-1996). Raw: raw/utility/supporting-libraries.md Updated: 2026-08-04