GadTools Library

Code samples on this page are not yet updated to AmigaOS 4.x some of them may be obsolete or incompatible with AmigaOS 4.x.

GadTools Library

GadTools is designed to simplify the task of creating user interfaces with Intuition. GadTools offers a flexible and varied selection of gadgets and menus to help programmers through what used to be a difficult chore.

Intuition, the Amiga's graphical user interface, is a powerful and flexible environment. It allows a software designer a great degree of flexibility in creating dynamic and powerful user interfaces. However, the drawback of this flexibility is that programming even straightforward user interfaces can be complicated, and certainly difficult for first-time Intuition programmers.

What the Gadget Toolkit (GadTools) attempts to do is harness the power of Intuition by providing easy-to-use, high-level chunks of user interface. GadTools doesn't pretend to answer all possible user interface needs of every application but by meeting the user interface needs of most applications, GadTools greatly simplifies the problem of designing user-friendly software on the Amiga.

For applications with special needs, custom solutions can be created with Intuition's already-familiar gadgets or its new BOOPSI object-oriented custom gadget system; GadTools is compatible with these.

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. Follow the GadTools rules. Only in this way may GadTools grow and improve without hindrance, even allowing new features to automatically appear in future software when reasonable.

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 chapter. See the SDK for details on each function call.

Function	Description
CreateGadgetA()	Allocate GadTools gadget, tag array form.
CreateGadget()	Allocate GadTools gadget, varargs form.
FreeGadgets()	Free all GadTools gadgets.
GT_SetGadgetAttrsA()	Update gadget, tag array form.
GT_SetGadgetAttrs()	Update gadget, varargs form.
CreateContext()	Create a base for adding GadTools gadgets.
CreateMenusA()	Allocate GadTools menu structures, tag array form.
CreateMenus()	Allocate GadTools menu structures, varargs form.
FreeMenus()	Free menus allocated with CreateMenus().
LayoutMenuItemsA()	Format GadTools menu items, tag array form.
LayoutMenuItems()	Format GadTools menu items, varargs form.
LayoutMenusA()	Format GadTools menus, tag array form.
LayoutMenus()	Format GadTools menus, varargs form.
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()	Draw a 3D box, tag array form.
DrawBevelBox()	Draw a 3D box, varargs form.
GetVisualInfoA()	Get drawing information for GadTools, tag array form.
GetVisualInfo()	Get drawing information for GadTools, varargs form.
FreeVisualInfo()	Free drawing information for GadTools.