GadTools Library

GadTools Library

Originally, programming even straightforward user interfaces in Intuition could be rather complicated, and certainly difficult for first-time programmers. The GadTools toolkit was introduced in AmigaOS 2.x to simplify the task. It provided relatively easy-to-use, higher-level chunks to build GUIs from, and to help programmers through what used to be a difficult chore.

Note
As of AmigaOS 4.1 Final Edition, GadTools is basically a legacy toolkit retained for compatibility. Due to its inherent limitations, using GadTools in modern applications can no longer be recommended. Prefer using the object-oriented GUI programming framework based on BOOPSI.

Elements of GadTools

GadTools is the easy way to program gadgets and menus. With GadTools, the system handles the detail work required to control gadgets and menus so the application uses less code and simpler data structures.

Another key benefit of GadTools is its standardized and elegant look. All applications that use GadTools will share a similar appearance and behavior. Users will appreciate a sense of instant familiarity even the first time they use a product.

GadTools provides a significant degree of visual consistency across multiple applications that use it. There is also internal consistency between different elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" areas are informational only, and clicking in them has no effect.

GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result other than what GadTools currently offers. Software developers whose needs extend beyond the standard features of GadTools should create custom gadgets that share the look and feel of GadTools by using either BOOPSI or by directly programming gadgets at a lower level. See Intuition Gadgets and BOOPSI for more information.

GadTools Tags

Many of the GadTools functions use TagItem arrays or tag lists to pass information across the function interface. These tag-based functions come in two types, one that takes a pointer to an array of tag items and one that takes a variable number of tag item arguments directly in the function call. In general, the second form, often called the varargs form because the call takes a variable number of arguments, is provided for convenience and is internally converted to the first form. When looking through the Autodocs or other Amiga reference material, the documentation for both forms is usually available in the array-based function description.

All GadTools tags begin with a leading "GT". In general, they also have a two-letter mnemonic for the kind of gadget in question. For example, slider gadgets recognize tags such as "GTSL_Level". The GadTools tags are defined in <libraries/gadtools.h>. Certain GadTools gadgets also recognize other Intuition tags such as GA_Disabled and PGA_Freedom, which can be found in <intuition/gadgetclass.h>.

For more information on tags and tag-based functions, be sure to see the Utility Library.

GadTools Menus

GadTools menus are the preferred way to manage menus on AmigaOS.

See GadTools Menus for more information on how to use them.

GadTools Gadgets

GadTools gadgets are largely superseded by BOOPSI-based GUI systems are to be avoided.

See GadTools Gadgets for more information about this obsolete GUI system.

Function Reference

The following are brief descriptions of the Intuition functions discussed in this article. See the SDK for details on each function call.

Function	Description
CreateGadgetA() CreateGadget()	Allocate GadTools gadget.
FreeGadgets()	Free all GadTools gadgets.
GT_SetGadgetAttrsA() GT_SetGadgetAttrs()	Update gadget.
CreateContext()	Create a base for adding GadTools gadgets.
CreateMenusA() CreateMenus()	Allocate GadTools menu structures.
FreeMenus()	Free menus allocated with CreateMenus().
LayoutMenuItemsA() LayoutMenuItems()	Format GadTools menu items.
LayoutMenusA() LayoutMenus()	Format GadTools menus.
GT_GetIMsg()	GadTools gadget compatible version of GetMsg().
GT_ReplyIMsg()	GadTools gadget compatible version of ReplyMsg().
GT_FilterIMsg()	Process GadTools gadgets with GetMsg()/ReplyMsg().
GT_PostFilterIMsg()	Process GadTools gadgets with GetMsg()/ReplyMsg().
GT_RefreshWindow()	Display GadTools gadget imagery after creation.
GT_BeginRefresh()	GadTools gadget compatible version of BeginRefresh().
GT_EndRefresh()	GadTools gadget compatible version of EndRefresh().
DrawBevelBoxA() DrawBevelBox()	Draw a 3D box.
GetVisualInfoA() GetVisualInfo()	Get drawing information for GadTools.
FreeVisualInfo()	Free drawing information for GadTools.