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 in nature, 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:

Flag	Effect
#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:

Tag	Effect
#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.

Getting and Setting Attributes

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 #GTCY_Active attributes:

GTSetAttrs #enableviewcheckbox, #GTCB_Checked, 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.

String and Integer Gadgets

String and integer gadgets allow the user to enter strings or numbers that can be read by your program. Both types of gadget look and work the same way, the only difference being that the number gadget will only accept numerical digits. They are set up as follows:

GTString GTList, id, X, Y, W, H, Text$, flags, MaxChars
GTInteger GTList, id, X, Y, W, H, Text$, flags, default

Most parameters are the same as for the button gadget, with the final parameter setting the maximum number of characters the string gadget will accept, or the default value of an integer gadget. The contents of the gadgets can be set using the GTSetString and GTSetInteger commands:

GTSetString #MyString, "This is the string!"
GTSetInteger #MyInteger, 42

Both gadgets will report a Gadget Up event when the user presses enter after typing in the gadget. Please note however, that no event will be triggered if the user clicks elsewhere with the mouse. Therefore it is important not to rely on the Gadget Up event to update your program's record of the value! (This causes a potentially dangerous bug in older versions of HDToolBox.)

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.

Radio Buttons

Radio buttons are similar to cycle gadgets in that they allow the used to select one option from a list. The difference is that radio buttons list all the options so they're all visible and let the user click an individual button next to the required option to select it. This automatically deselects any previously selected option.

Radio buttons are also known as mutually exclusive, or MX gadgets. Their use is as follows:

GTMX GTList, id, X, Y, W, H, Text$, flags, Options$

All parameters are identical to those for the cycle gadget above. The options provided in Options$ are displayed in a vertical list with a small round button beside each option. Selecting a new option will produce a gadget up event, and the currently selected option can be seen by reading the #GTMX_Active attribute. Similarly to the cycle gadget above, the current option can also be set by writing the relevant index to the #GTMX_Active attribute.

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.listitem(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)

If there is no selected item, or the list is empty, this function will return -1.

This tag can also be used to set the active item in the list:

GTSetAttrs #listview, #GTLV_Selected, 3

Sets the highlight to the fourth item in the list (0 being the first). Setting the current item to -1 will remove the highlight from all entries.

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. Most gadgets give a Gadget Up message whenever the user has selected an option, so you can look out for these events and then read the relevant attribute from the gadget that triggered the event.