Blitz:GadTools

GadTools is an updated system of gadgets that was introduced in OS 2.0, and is supported in all versions from 2.0 on. It offers some large improvements over the standard Intuition gadgets and is the standard, familiar look from OS 2.0 to 3.1. It is quite low level meaning, and it lacks some more advanced features from the more modern toolkits such as MUI, but has a very low footprint and doesn't need any external toolkits installed to work.

How to Use GadTools

GadTools gadgets are defined using a unique ID to identify each object, and a GTList object number to which the gadgets belong. All gadgets require you to specify the size and position of the gadget. Once the gadgets are defined, the GTList containing them can be attached to a standard Intuition window for use. Only one GTList can be attached to a window at any one time, and a GTList can only be attached to one window at any one time. Once attached, the gadgets will trigger standard IDCMP events when used.

Defining GadTools Objects

GadTools objects are defined using straightforward commands for each gadget type. The specifics of each command vary from gadget to gadget, but many parameters are the same. Some properties can also be changed after gadget creation, such as the state of a checkbox or the selected item in a cycle gadget.

Flags and Tags

Most GadTools gadget setup commands accept a flags parameter to control certain aspects of its appearance or functionality. These flags are constant values that are defined in the amigalibs.res resident file and are listed in the Blitz documentation. Some important ones are as follows:

#PLACETEXT_IN

Places the text in the middle of the gadget

#PLACETEXT_LEFT

Places the text to the left of the gadget

#PLACETEXT_RIGHT

Places the text to the right of the gadget

#PLACETEXT_ABOVE

Places the text above gadget

#PLACETEXT_BELOW

Places the text below the gadget

Tags can also be set prior to gadget creation using the GTTags command. These set various attributes of the gadget to be created, and are listed in the official [GadTools Autodocs]. Many are specific to a certain type of gadget. Some useful ones are as follows:

#GA_Disabled

Gadget is initially disabled and ghosted if this is set to True

#GA_Immediate

Gadget reports button down events as well as the normal button up events if this is set to True

#GTCB_Checked

Checkbox gadget is initially checked if this is set to True, unchecked if set to False (default)

#GTCB_Scaled

Checkbox gadget is scaled to the dimensions given instead of simply fitting them (this is important for OS4 and any setups that offer a pixel ratio other than 1:2)

#GTCY_Active

The index of the currently selected option of a cycle gadget

The GTTags command applies to the next gadget creation command only. It can be used as follows: GTTags #GA_Disabled, True, #GTCY_Active, 3 This example will set the next gadget created (which should be a cycle gadget) to be disabled initially and to start with the 4th option selected (option indices start at 0). The tags must be in pairs of tag, value. Any number of pairs can be set using this command.

Certain tags can also be set after creation of the gadget using the GTSetAttrs command, and can be read from the gadget using the GTGetAttrs command. For example, the #GTCB_Checked and #GTGY_Active attributes: GTSetAttrs #enableviewcheckbox, True mychoice = GTGetAttrs(#cyclegadget1, #GTCY_Active)

Buttons

Buttons are set up using the GTButton command with the form: GTButton GTList, id, X, Y, W, H, Text$, flags Where GTList is the ID of the GTList to which the button will belong, id is the unique ID of the new button, X and Y are the co-ordinates of the top left corner of the gadget relative to the top left corner of the window. W and H are the width and height of the gadget in pixels. Text$ is the actual text to put in the button, and flags is a flag value based on the required values from the GT flags listed above. An example of use: GTButton #maingtlist, #continuebutton, 20, 20, 100, 20, "Continue", #PLACETEXT_IN The flag #PLACETEXT_IN is normal for a button since normally the text is in the middle of the button.

Checkboxes

Checkboxes are small boxes you can place a tick in, usually to turn an option on or off. The are created using the following command: GTCheckBox GTList#, id, X, Y, W, H, Text$, flags All parameters are as per the GTButton command above.

Attaching GadTools to Your Window

When you open a standard window, you can attach your gadgets to the window using the AttachGTList command. This command takes the ID of the GTList object and the ID of the window. Once complete, the gadgets will be drawn at their relevant locations and will be ready to use. For example: AttachGTList #maingtlist, #mainwindow