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 used in a similar fashion to the standard Intuition gadgets. They are declared 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)

General Parameters

Many gadget commands require the same parameters, such as the following:

GTList

This is the ID of the GTList to which the button will belong

id

This is the unique ID of the new button

X and Y

These are the co-ordinates of the top left corner of the gadget relative to the top left corner of the window

W and H

These are the width and height of the gadget in pixels

Text$

This is a string containing the label to be used for the gadget

flags

This is a flag value based on the required values from the GadTools flags listed above, usually used for positioning the label.

Buttons

Buttons are set up using the GTButton command with the form: GTButton GTList, id, X, Y, W, H, Text$, flags All of the parameters are standard and explained 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 Again, all parameters are explained above. Unlike the button gadget, it's probably better to put the label to the left, right, or above or below the gadget... It's important to set the tag GTCB_Scaled to True at creation time if your program is going to be used on OS4 or some graphics card setups, otherwise the gadget may appear squashed.

Cycle Gadgets

Cycle gadgets allow the user to select one choice from a predetermined list of choices by cycling through them. Most modern implementations also include a drop-down menu that lists all the options available. To set up a cycle gadget, use the following: GTCycle GTList, id, X, Y, W, H, Text$, flags, Options$ All the parameters are as before except Options$. This is a string containing all the options you wish your gadget to contain, separated by a pipe character (|). For example: GTCycle #maingtlist, #cycle1, 100, 40, 100, 20, "Choose a size", #PLACETEXT_LEFT, "Tiny|Small|Medium|Large|Huge" This gadget contains the five size options given, with the label to the left of the gadget. The tag #GTCY_Active can be set to the index value of an option to set the currently selected option, starting at 0 for the first option. Similarly, the currently selected option can be read by reading the same tag.

Listviews

Listview gadgets offer the user a list of items in a scrollable box. Scrolling and display is all handled by the gadget, which takes a list array containing the items to display in the list. The list must be of a NewType with at least two fields, the first being a word type, and the second being a string containing the text of that item. For example: NEWTYPE .listitem

 dummy.w
 itemname.s

End NEWTYPE

Dim LIST MyListItems(0) Adding items to this list array builds up your list to display in the gadget. This list is attached to the gadget at gadget creation time, but can also be updated at any stage by your program. To create the gadget, the following command is used: GTListView GTList, id, X, Y, W, H, Text$, flags, list() All parameters are as described previously, with list() being the name of the array to attach to the listview. To add some items to the list and then create the gadget to display them, the following example can be used: If AddItem(MyListItems())

 MyListItems()\itemname = "First Item"

End If If AddItem(MyListItems())

 MyListItems()\itemname = "Second Item"

End If If AddItem(MyListItems())

 MyListItems()\itemname = "Third Item"

End If

GTListview #maingtlist, #listview, 20, 20, 100, 50, "List of Options", #PLACETEXT_ABOVE, MyListItems() Once the GTList object is attached to a window, the gadget will be displayed with the three items in the list. To modify the list, first detach the array from the gadget using the GTChangeList command: GTChangeList #maingtlist, #listview Giving the GTList and gadget IDs. You can then make the changes to the array as required, and then use the GTChangeList command again to reattach the array to the gadget: GTChangeList #maingtlist, #listview, MyListItems() Don't forget to reattach the list or you'll have problems!

The Listview gadget produces gadget clicked events list like a button gadget whenever the user clicks on one of the options. You can then find out what the currently selected item is using the GTGetAttrs function along with the appropriate tag: CurrentItem = GTGetAttrs(#listview, #GTLV_Selected)

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

Detecting Gadget Events

Gadget events are handled through the standard Intuition Events system, so no special consideration is needed. Examples are given in the Gadget section of the Events page.