# Aros/Developer/Docs/Libraries/GadTools

* Navbar for the Aros wikibook
* Aros User
* Aros User Docs
* Aros User FAQs
* Aros User Applications
* Aros User DOS Shell
* Aros/User/AmigaLegacy
* Aros Dev Docs
* Aros Developer Docs
* Porting Software from AmigaOS/SDL
* For Zune Beginners
* Zune .MUI Classes
* For SDL Beginners
* Aros Developer BuildSystem
* Specific platforms
* Aros x86 Complete System HCL
* Aros x86 Audio/Video Support
* Aros x86 Network Support
* Aros Intel AMD x86 Installing
* Aros Storage Support IDE SATA etc
* Aros Poseidon USB Support
* x86-64 Support
* Motorola 68k Amiga Support
* Linux and FreeBSD Support
* Windows Mingw and MacOSX Support
* Android Support
* Arm Raspberry Pi Support
* PPC Power Architecture
* misc
* Aros Public License

## Introduction

* V34 - OS1.3x Gadtools did not exist but gadtools13.library was around
* V36 - OS2.0x First Introduction
* V37 - OS2.04 NewLook rendering scheme
* V39 - OS3.0x NewLook menus added - GT_GetGadgetAttrs added -
* V40 - OS3.1x Fixes
Until AmigaOS™ 2.0, there was no unified look and feel design standard — application developers had to write their own objects (buttons, requesters and menus), with Intuition providing minimal support. With AmigaOS™ 2.0 came gadtools.library, which provided standard widget sets, and the Interface Style Guide, which explained how applications could be laid out for consistency to the user.
    you should refer to the GadTools Library chapter and Amiga list.
Gadtools is a deprecated interface as it is limited and restrictive (which does have its advantages in certain cases). Try just using BOOPSI gadgets which leads to our MUI version called Zune. BOOPSI is the underpinning for MUI, bgui and others.
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.
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"
For most gadgets, the NewGadget structure is used to specify its common attributes. Additional attributes that are unique to specific kinds of gadgets are specified as tags sent to the CreateGadget function
The various GadTools gadget types require certain classes of IDCMP messages in order to work. Applications specify these IDCMP classes when the window is opened or later with ModifyIDCMP. Each kind of GadTools gadget requires one or more of these IDCMP classes:
After closing the window, the gadgets allocated using CreateGadget must be released.
A direct conversion of window coordinates to GadTools gadget coordinates. GaDTools user interfaces are easy to use except for gadget coordinates. Also need a draw rectangle function based on these coordinates to calibrate my drawing areas and erase rectangle coordinates.
There is a strict set of functions and operations that are permitted on GadTools gadgets.
Never selectively or forcibly refresh gadgets. The only gadget refresh that should ever be performed is the initial GT_RefreshWindow after a window is opened with GadTools gadgets attached. It is also possible to add gadgets after the window is opened by calling AddGlist and RefreshGlist followed by GT_RefreshWindow. These refresh functions should not be called at any other time.
GadTools gadgets may not overlap with each other, with other gadgets or with other elements. Doing this to modify the gadget’s appearance is not supported.
GadTools gadgets may not be selectively added or removed from a window. This has to do with the number of Intuition gadgets that each call to CreateGadget produces and with refresh constraints.
Never use OnGadget or OffGadget or directly modify the GFLG_DISABLED Flags bit. The only approved way to disable or enable a gadget is to use GT_SetGadgetAttrs and the GA_Disabled tag. Those kinds of GadTools gadgets that do not support GA_Disabled may not be disabled.
The application should never write into any of the fields of the Gadget structure or any of the structures that need it unless they are explicitly programmer fields (e.g. GadgetID and UserData) or if they are guaranteed meaningful
On occasion, the program is specifically invited to read a field, for example the StringInfo->Buffer field.
GadTools gadgets may not be made relative sized or relative positioned. This means that the gadget flags GFLG_RELWIDTH, GFLG_RELHEIGHT, GFLG_RELBOTTOM and GFLG_RELRIGHT may not be specified. The activation type of the gadget may not be modified (for example changing GACT_IMMEDIATE to GACT_RELVERIFY).

## Gadgets

| Gadget Type | Description or Example Usage |
| Button | Familiar action gadgets, such as "OK" or "Cancel". |
| String | For text entry. |
| Integer | For numeric entry. |
| Checkboxes | For on/off items. |
| Mutually exclusive | Radio buttons, select one choice among several. |
| Cycle | Multiple-choice, pick one of a small number of choices. |
| Sliders | To indicate a level within a range. |
| Scrollers | To indicate a position in a list or area. |
| Listviews | Scrolling lists of text. |
| Palette | Color selection. |
| Text-display | Read-only text. |
| Numeric-display | Read-only numbers. |

### Modify

Create http://thomas-rapp.homepage.t-online.de/examples/gadtools.c
To change the flags and the body variables after the gadget is displayed, the program can call Intuition's NewModifyProp.
The gadget's internal state will be recalculated and the imagery will be redisplayed to show the new state. When numGads (in the prototype above) is set to all ones, NewModifyProp will only update those parts that have changed, which is much faster than removing the gadget, changing values, adding the gadget back and refreshing.
Each kind of GadTools gadget requires one or more of these IDCMP classes: IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_MOUSEMOVE, IDCMP_MOUSEBUTTONS and IDCMP_INTUITICKS.
programs that use Gadgets always require notification about window refresh events. Even if the application performs no rendering of its own, it may not use the WFLG_NOCAREREFRESH window flag and must always set IDCMP_REFRESHWINDOW.
The attributes of a gadget are set up when the gadget is created. Some of these attributes can be changed later by using the GT_SetGadgetAttrs function:

### Button

Button gadgets (BUTTON_KIND) are perhaps the simplest kind of GadTools gadget.
Text-entry (STRING_KIND) and number-entry (INTEGER_KIND) gadgets are fairly typical Intuition string gadgets
Cycle gadgets (CYCLE_KIND) allow the user to choose exactly one option from among several
GadTools gadgets and menus need information about the screen on which they will appear. Before creating any GadTools gadgets or menus, the program must get this information using the GetVisualInfo call.
Menus. GadTools fully supports Intuition's NewLook menus. NewLook menus can be added to an application by providing the
and providing the
These two tags will give your application NewLook menus. The pens used to render these menus are controllable by the user through the Palette prefs editor.
You can now put an arbitrary command string in the right-hand side of a menu, where the Amiga-key equivalent normally goes. To do this, point the NewMenu.nm_CommKey field at the string (e.g., "Shift-Alt-F1), and set the new NM_COMMANDSTRING flag in NewMenu.nm_Flags.
GT_GetGadgetAttrs. GadTools now has a GT_GetGadgetAttrsA function which retrieves attributes of the specified gadget, according to the attributes chosen in the tag list. For each entry in the tag list, ti_Tag identifies the attribute, and ti_Data is a pointer to the long variable where you wish the result to be stored.

### String

Most regular Intuition string gadgets which default to FALSE

### Listviews

Listviews. GadTools listviews
The disappearance of the display box at the bottom of the scrolling list area. Instead of showing the selected item in the display box, the selected item remains highlighted within the scrolling list. This was done to prepare listviews for multi-select support. Multi-selection requires a highlighting scheme as a display box would not work. The removal of the display box has a slight impact on the size of the listview.
GTLV_CallBack. This tag allows a callback hook to be provided to gadtools for listview handling. Currently, the hook only gets called to render an individual item. Every time GadTools wishes to render an item in a listview, it invokes the call back function, which can do custom rendering. This allows GadTools listviews to be used to scroll complex items such as graphics and images.
Listviews can now be disabled using {GA_Disabled, TRUE}.

### Palettes

Palettes. GadTools palette gadgets no longer display a box filled with the selected color. The selected color is instead denoted by a box drawn around the color square in the main palette area. This change slightly impacts the size of palette gadgets.
Another change which can affect the size of the palette gadgets is the smarter layout of the color squares. An attempt is now made to keep the color squares as square as possible, based on the aspect ratio information obtained from the gfx database. As many color squares as possible are put on the screen, until things get too small in which case the upper colors are thrown away. The GTPA_ColorTable tag was added in support of sparce color tables. It lets you define arbitrary pens to be used to fill-in the color squares of the palette gadget.
The GTPA_NumColors tag lets you define the exact number of colors to display in the palette gadget. Under V37, the GTPA_Depth tag played the same role. The problem with GTPA_Depth is that only multiples of 2 in number of colors can be specified. GTPA_NumColors allows any number of colors.

### Menus

http://thomas-rapp.homepage.t-online.de/examples/gtmenu.c
To set up GadTools menus
The underscore character, `_' is the recommended marker-symbol. So, for example, to mark the letter "F" as the keyboard equivalent for a button labelled "Select Font...", create the gadget text:

### List

http://thomas-rapp.homepage.t-online.de/examples/lv.c
When CreateGadget is called multiple times (for each gadget), each new gadget is automatically linked to the previous gadget's NextGadget field, thus creating a gadget list. Second, if one of the gadget creations fails (usually due to low memory, but other causes are possible), then for the next call to CreateGadget, next_gad will be NULL and CreateGadget will fail immediately. This means that the program can perform several successive calls to CreateGadget and only have to check for failure at the end.
can not use GadTools scroller gadgets in window borders

### Scroll

http://thomas-rapp.homepage.t-online.de/examples/scroll.c http://thomas-rapp.homepage.t-online.de/examples/iconify.c
allocating an object containing the imageclass and then using this to draw the graphic into the button

## Examples

//.C..C.O.D.E..............................................................

## References

Some code relies on AOS implementation of gadtools library which uses fake (non-boopsi) gadgets where especially the more complex ones (listview) have most gadget (input) handling done in the GT_GetImsg/GT_FitlerImsg funcs. In AROS gadtools library uses real boopsi gadgets and therefore behaves differently.
The first few items in each option can be altered after being created.
GA_Immediate and GA_RelVerify are tags, GACT_IMMEDIATE and GACT_RELVERIFY are flags used for the Activation field of struct Gadget.
GT_Underscore - Indicates the symbol that precedes the character in the gadget label to be underscored. This can be to indicate keyboard equivalents for gadgets (note that GadTools does not process the keys - just displays the underscore).
BUTTON_OPTION (action buttons):
CHECKBOX_OPTION (on/off items):
CYCLEOPTION (multiple state selections):
INTEGER_OPTION (numeric entry):
LISTVIEW_OPTION (scrolling list):
MX_OPTION (mutually exclusive, radio buttons):
NUMBER_OPTION (read-only numeric):
PALETTE_OPTION (color selection):
SCROLLER_OPTION (for scrolling through areas or lists):
SLIDER_OPTION (to indicate level or intensity):
STRING_OPTION (text-entry):
TEXT_OPTION (read-only text):
LayoutGadgetTags
Trying to manually open gadtools in the console code (for menus). I need it to be opened manually, because it *will* fail for the boot shell (see below), so I need to handle the case where it's not available. It seems to me that auto-opening non-resident libraries during boot is a really bad idea... Will lots of stuff break if that's turned off? Alternatively, is there a method to prevent auto-opening on a case by case basis? IIRC you just need to declare the base pointer manually. This will prevent from getting it (and associated library opening code) from libautoinit. With programs it works. I think it works with residents. The autoinit code is linked in by the libbase variable. E.g. the autoinit code defined the global libbase variable of a library. If you define 'struct Library *GadToolsBase' somewhere in your code as a global variable the autoinit code won't be linked in. Please, only use it when really needed and put proper comments why it is needed. The specific case here is avoiding duplicating a bunch of menu-layout code from gadtools in the console code to add menus to the console windows without requiring gadtools to be linked into the kernel. It means the boot shell won't get the menu, but I think that's a fair enough trade off vs. making things really messy.
And it's only called in when global library bases are used at all, which shouldn't be the case with romable code, should it? That's something I didn't think about. Do I mess up stuff if I declare a global GadToolsBase, or are bss properly handled? If it messes things up, are there alternative ways of preventing the auto-opening? (committed a basic menu structure for the console handler that uses a global GadToolsBase).
It's non-optimal, actually, since on m68k the only 'know to always exist' memory for the .bss is in Chip RAM, which is both precious and dog slow (due to contention with video and audio operations). For this usage it's probably fine, but if you can find a way to allocate it in a structure that the console handler passes around (con_base?) and dereference it from there, it's probably a better way to do. AllocMem memory allocates from the highest priority first. See rom/devs/filesys/AmberRAM/handler.h's 'struct Handler', and the macros that immediately follow it for an example of how to do this. The console handler does already put lots of stuff in it's handler data structure, so if there is a way I can suppress auto-opening without a global variable, it's trivial enough to put it in there.
Is there a good reference somewhere on all the things I need to take care of during a NEWWINDOWSIZE event? You probably know this already, but NEWWINDOWSIZE doesn't block until ReplyMsg like SIZEVERIFY.
Endian issues
There may be method structs in the code which uses WORD for some of the (coord) fields and then when calling the method it does something like gDoClassMethod(... , (x << 16) | (y & 0xffff), ...). This relies on big endianess and therefore fails on x86.