Aros/Developer/Docs/Libraries/GadTools

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:

IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_MOUSEMOVE, IDCMP_MOUSEBUTTONS and IDCMP_INTUITICKS.

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 (LeftEdge, TopEdge, Width, Height, Flags). 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).

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.

void NewModifyProp( struct Gadget *gadget, struct Window *window, struct Requester *requester,                     unsigned long flags, unsigned long horizPot, unsigned long vertPot,                        unsigned long horizBody, unsigned long vertBody, long numGad );

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:

void GT_SetGadgetAttrs (struct Gadget *gad, struct Window *win,                           struct Requester *req, Tag tag1, ... ) void GT_SetGadgetAttrsA(struct Gadget *gad, struct Window *win,                           struct Requester *req, struct TagItem *taglist)

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 {WA_NewLookMenus, TRUE} tag to OpenWindowTags, and providing the {GTMN_NewLookMenus, TRUE} tag to LayoutMenus. 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.

LONG top = 0; LONG selected = 0; LONG result; result = GT_GetGadgetAttrs(listview_gad, win, NULL,                               GTLV_Top, &top,                                GTLV_Selected, &selected,                                TAG_DONE); if (result != 2) {        printf( "Something's wrong!" ); }

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

GetVisualInfo and FreeVisualInfo   CreateContext

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:

ng.ng_GadgetText = "Select _Font...";

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
Coder's Clinic 3

CCCC   OOOO   DDDD   EEEEEE    CCCC  L      IIIII N    N IIIII  CCCC C   C  O    O  D   D  E        C    C L        I   NN   N   I   C    C C       O      O D    D EEE     C       L        I   N NN N   I  C  C    C  O    O  D   D  E        C    C L        I   N   NN   I   C    C   CCCC    OOOO   DDDD   EEEEEE    CCCC  LLLLLL IIIII N    N IIIII  CCCC -- CODE CLINIC #3                                       I LUV GADGETS!!!

As promised, We will add a gadget to our window. First we have to       get some info on how to do this.

GADGETS:Two types of gadgets.

*FIRST TYPE OF GADGET:System System gadgets are those that you see in the windows and screens that you open. And we are not going to go much further than that. *SECOND TYPE OF GADGET:Application Application gadgets are the ones in which you create and use in your own programs. They can be placed at any location inside the window and can use any image. There are four basic types of application gadgets.

[1] Boolean   : OK buttons ect...                         [2] Proportion : Sound level ect...        [3] String     : Enter your name ect...                         [4] Custom     : New gadgets. *****--            * N *   I STRONGLY SUGGEST INVESTING IN THE COMPLETE  | * O *  SET OF AMIGA ROM KERNEL MANUALS... AT THE    | * T *  VERY LEAST YOU SHOULD TRY TO GET THE LIBRARIES| * E *  MANUAL ...THERE ARE MANY EXAMPLES/EXPLANATIONS| *****--                To create a gadget you simply fill in a Gadget structure. (see fig.�1). You may also use the Gadtools Library to create gadgets (which we will), As you can see the Gadget structure has many items and to cover all these would    struct Gadget consume a great deal of text   { as suggested before get the       struct Gadget *NextGadget ROM Kernel manual:Libraries       WORD LeftEdge, TopEdge; (at the very least) as there      WORD Width, Height; is detailed information on all    UWORD Flags; structures the amiga programmer   UWORD Activation; needs to understand. UWORD GadgetType; APTR GadgetRender; OK lets do something different    APTR SelectRender; like use the Gadtools Library     struct IntuiText *GadgetText; to put some gadgets up on the     LONG MutualExclude; window and let us know which one  APTR SpecialInfo; we selected. UWORD GadgetID; APTR UserData; Now that we know about the      }; Intuistion gadgets lets take a              FIG. 1 look at the Gadtools gadgets. There are 12 types of gadgets that the Gadtools library supports and they are: Button String Integer Checkboxes Mutually exclusive Cycle Sliders Scrollers Listviews Palette Text-display Numeric-display With all of these types of gads what couldnt you do? And as a real bonus there are several GUI buiders on aminet, just look in dev/gui and you will see several I personally like GadToolBox by Jan van den Baard. These programs take a great deal of coding off of your back and allow you to work on the inner workings of your own program. Lets take a look a the structure used to create a gadtools gadget: struct NewGadget {                                                             WORD ng_LeftEdge,ng_TopEdge; WORD ng_Width,ng_Height; UBYTE *ng_GadgetText; struct TextAttr *ng_TextAttr; UWORD ng_GadgetID; ULONG ng_Flags; APTR ng_VisualInfo; APTR ng_UserData; };                                                                   FIG 2 If you compare the Gadget (fig 1) and the NewGadget (fig 2) structures you will see some common items. The way you create a gadget using gadtools is the CreateGadget function, its prototype is: struct Gadget *CreateGadget(ULONG kind,                                   struct Gadget *prevgad,                                    struct NewGadget *newgad,                                    struct TagItem *taglist); so to create a single button gadget we would do it like this: ng.ng_TextAttr  = &Topaz80; ng,ng_VisualInfo = vi; ng.ng_LeftEdge  = 10; ng.ng_TopEdge   = 10; ng.ng_Width     = 60; ng.ng_Height    = 12; ng.ng_GadgetText = "CLICK"; ng.ng_GadgetID  = 1; ng.ng_Flags     = 0; gad = CreateGadget(BUTTON_KIND,gad,&ng,TAG_END); _____________________________      If you look at fig 2 you will        []hello__________________[][] see that we have filled the         |                           | structure and then made a call      |  CLICK  QUIT            | to CreateGadget. The nice         |                           | thing is that if you were to        |                           | add another gadget you now only     |                           | fill in the items that will         |                           | change, an example of this          |                           | is given below. Lets add a          |___________________________| gadget that has "QUIT" inside it. FIG 4 ng.LeftEdge     =80; ng.ng_GadgetText ="QUIT"; ng.ng_GadgetID  =2; gad = CreateGadget(BUTTON_KIND,gad,&ng,TAG_END);

and now we would have two gadgets that would look like fig�4 The example program was created using the example from the ROM Kernel Manual:Libraries in the chapter Gadtools Library pg.383-385. I would also like to mention that this layout was written by me and not by a GUI builder... and this is the GUI that we will use to       create our AddressBook program. There are several new items to this code and alot of it you will not understand, I will try to clear up any questions in the next issue as we will go line by line of this code and explain what is going on...      *****-  *****- * N *  ALL CODE IS INTENDED |  * N *   I COMPILED THIS CODE | * O *  FOR VERSION 2.0 OR   |  * O *   WITH SAS/C V6.0 AND  | * T *  ABOVE... | * T *   HAD NO ERRORS OR     | * E *                       |  * E *   WARNINGS             | *****- *****-

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