-------------------------
3]CREATING GADGETS IN BASIC
3]By Tom Beale, Pomona, CA
-------------------------

     Although Amiga Basic has no built-in functions for making gadgets, it
is well within the power of the language to create them. Surprisingly, if
the code is well written, they can work as well as their `C' counterparts.  
   There are example programs of a Boolean Gadget, a Proportional Gadget and
a Matrix Menu, which is a variation of a Boole Gadget. All examples
presented here are written entirely in Amiga Basic and rely solely on Basic
commands. No library calls are required.

3]IN GENERAL
     All gadgets have one property in common: the select area. This is a
rectangular area that when selected, causes the Gadget to be acted upon. In
all the examples here, the variables Gx1, Gx2, Gy1 and Gy2 represent the
left, right, top and bottom of the gadget area respectively, and the
variables mx and my contain the mouse coordinates at the time the gadget was
selected. The Gadget's selection can be detected by the following line of
code:

IF (mx>gx1) AND (mx<gx2) AND (my>gy1) AND (my<gy2) THEN . . .

     This line would be placed somewhere in your 'CHECK MOUSE' routine, and
the THEN statement is usually followed by a GOSUB statement or a block of
commands, depending on the gadget's purpose.

3]BOOLEAN GADGETS

3]Theory
     Boolean Gadgets are used for on/off/selections such as the window close
box, the front/back gadgets, etc. These are the easiest to create, since the
only real information your program needs to get is whether or not the
pointer was in the gadget area when the select button was clicked. The steps
are:
     1) Define the gadget area.
     2) Check if the gadget has been selected.
     3) If selected, gosub to whatever you want it to do.

3]Doing It
     The mechanics of this is simple and one solution is demonstrated in the
example program BOOLE. The program calls a subroutine named InitGadg and
containing the following variable definitions:

 gx1 = 180                   ' Left Edge of Gadget Area (in Pixels)
 gy1 = 30                    ' Top
 gw = 100                    ' Gadget Height
 gh = 50                     ' Gadget Width
 gx2 = gx1+gw                ' Right Edge
 gy2 = gy1+gh                ' Bottom
 LINE(gx1,gy1)-(gx2,gy2),1,b ' Draw the Gadget Outline

      This code defines four variables that describe the area of the gadget,
then uses those variables to draw the box around the area. Once defined, the
following routine will detect the area being selected:

 WHILE MOUSE(0)=0:WEND ' Wait for Mouse
 mx = MOUSE(1)         ' Get Mouse X
 my = MOUSE(2)         ' Get Mouse Y
 IF (mx>gx1) AND (mx<gx2) AND (my>gy1) AND (my<gy2) THEN . . .

     Note that if any or all of the variables defining the size and location
of the gadget are changed, it will still work. In fact it may be moved
anywhere on the screen you want to put it. Usually if the select is
detected, the program would GOSUB to a subroutine that would perform
whatever operation was associated with the gadget.

3]GANGING BOOLES (Matrix Menus)

3]Theory
     In some instance, there may be a need to define multiple Boole gadgets.
An example would include a menu bar for a drawing program, which has three
rows of eight selections. One solution would be to define each area as a
separate gadget and have your program check each one. Monitoring 24 gadgets,
however, would would slow your program down considerably. A better solution
us to define the entire menu as one gadget and if it is selected, use the
mouse coordinate (MOUSE(1) and MOUSE(2)) to calculate which menu selection
was made.

3]Doing It
     The mechanics of defining the Rows and Columns plus returning the
correct one selected is simple. First, the code defining the rows and
columns is added to the Gadget definition:

 Rows = (Number of Rows)
 Cols = (Number of Columns)

 Ri = gh/Rows' Height of Each Row
 Ci = gw/Cols' Width of each Column

 gx2 = gx1+gw ' Right Edge
 gy2 = gy1+gh ' Bottom

     Detecting the Gadget selection is the same. Once selected, your program
can get the row and column and act on the results. The following code will
yield the Row and Column:

 Row% = (my-gy1)\Ri ' Compute Which Row Was Selected
 Col% = (mx-gx1)\Ci ' Compute Which Col Was Selected

     Row% will contain the row that was selected and Col% will contain the
number of the column. Note the Integer Divide (\). Unlike other versions of
Basic, Amiga Basic rounds off numbers when converting them to integers.
Since we don't want that, using the \ will truncate (cut off) the remainder.
     Once you have the row and column, you could either use an ON GOSUB or
IF statements to call the appropriate subroutines.

3]PROPORTIONAL GADGETS (Sliders)
     Sliders are used when the user needs to select a number from a range.
Selecting the knob allows it to move with the Mouse and as it does, the
value of a variable (the pot variable) is recalculated. If you have looked
at the sample program SLIDER, you will notice this is more involved than the
other gadgets. A simplified breakdown of the steps would be:

3]SET-UP
 1. Define the gadget area.
 2. Define the upper and lower limits of the range.
 3. Assign default value to pot variable.
 4. Calculate the ratio between the range and height of the slider.
 5. Calculate the position of the knob.
 6. Draw the knob.

3]IF SELECTED
 1. Check if the gadget has been selected. If so . . .
 2. Save position of knob in temporary variable.
 3. Calculate new pot value.
 4. Erase old knob.
 5. Draw new Knob. These last two steps should be done together to prevent
the knob from flashing, unless you want it to flash.

3]IF THE POT VALUE IS CHANGED (by something other than the gadget)
 1. Save position of knob in temporary variable.
 2. Calculate new Knob position.
 3. Erase old knob.
 4. Draw new Knob. These last two steps should be done together to prevent
the knob from flashing, unless you want it to flash.

3]DOING IT
3]Set-Up
     In order to make the prop gadget work quickly when selected, it is
important to take care of as much as possible beforehand.
     The initial area is set up the same as other gadgets, along with the
size and position of the knob, the min and max values of the slider and the
conversion ratios between the length of the slider (in pixels) and the range
of values it controls.

GadgInit:                    ' -------------- Set Gadget up for First Time
Gx1 = 461: Gy1 = 30          ' Upper Left Hand Corner of Gadget
Gh = 96                      ' Height
Gw = 20                      ' Width
Gx2 = Gx1+Gw                 ' Right Side of Gadget
Gy2 = Gy1+Gh                 ' Bottom of Gadget
Px1 = Gx1+2                  ' Define width of Gadget Knob
Px2 = Gx2-2
GMin = 0                     ' Maximum(+1) and Minimum values of the Pot
GMax = 16
G2Val = (GMax-GMin)/Gh       ' Ratio for converting from Gadget to Value
Val2G = 1/G2Val              ' Ratio for converting from Value to Gadget
LINE(Gx1,Gy1)-(Gx2,Gy2),2,bf ' Draw Gadget Container
LINE(Gx1,Gy1)-(Gx2,Gy2),3,b  ' Draw Gadget Container Outline
GVal = INT(number*Val2G)+Gy1 ' Calculate Knob Position

3]If the Gadget is Selected
     From Basic, the prop gadget is handled at a low level, which begins by
getting the mouse position within the gadget area. This is done by
subtracting Gy1 from the mouse position. Next, multiply that by the
Gadget-to-Value conversion value (G2Val) to get the new pot value. Now erase
the old knob by drawing a filled box the same color as the inside of the
slider over it and redraw the knob in the mouse position.

3]If the Pot Value is Changed
     If the Pot value is changed, either by a key-in or some other function
of the program, then the new pot value is used to calculate the position of
the knob (in pixels) from the top of the gadget. This is done by multiplying
the pot value by the value-to-gadget conversion value (Val2G). This is then
added to the location of the top of the gadget (gy1), yielding the position
of the knob in relation to the screen.

3]HIGHLIGHTING THE GADGET AREA
     Gadgets are visual elements of a program and can be accented or blended
into the background, depending on the graphics used to define them. It
should be obvious when a gadget is selected, though, so some type of change
should happen in or around the gadget area when it's selected.
     In the Boole and Matrix example, I used a PUT command to reverse the
gadget area when it was selected, then used the same command to reverse it
back when released.

3]Theory
     The Basic GET statement is used to copy a rectangular image from the
screen and assign it to a variable. The PUT statement is used to place this
image back on the screen. If a rectangle of a solid color is copied using a
GET statement and PUT on top of an image using the XOR option, the colors in
the image will be reversed. Using PUT again in the same place will reverse
the colors again, leaving the image the way it originally was. This will
work on any image or text, so long as it is not changed between the two
PUTs.

3]Doing It
     Before the GET command can be used, a variable has to be dimensioned to
contain the graphic image. This is done in the program Boole with the
following line of code:

DIM Hilit%(6+((gy2-gy1+1)*2*INT((gx2-gx1+16)/16)*2))

     Next, a rectangle is drawn, using the gadget coordinates, and the GET
command is used to place this rectangle into the variable Hilit%.

 LINE(gx1,gy1)-(gx2,gy2),1,bf    ' Draw the Gadget (For Highlight)
 GET (gx1,gy1)-(gx2,gy2),Hilit%  ' Put Solid Rectangle into Hilit%

     Now we can reverse the colors of any graphics in the gadget area with
the following statement:

 PUT (gx1,gy1),Hilit%,XOR

     Note also that using the statement again will reverse the colors back
to their original form.
     The program MatrixMenu uses the same technique, but with some
modifications. Since the area to be highlighted is not the entire gadget,
but a small section, it is only necessary to store a highlight image of one
of the squares. The line that does this is:

 DIM Hilit%(6+((Ci+1)*2*INT((Ri+16)/16)*2))

     Note the variables defining the width and height of the rows and
columns are used, rather than the actual gadget coordinates.
     Another difference is in using the GET statement. This time, gx1 and
gx2 are used, but the width and height of the rows and columns are used to
locate the second point, placing a rectangle the size of one square into
Hilit%.

 LINE(gx1,gy1)-(gx2,gy2),1,bf          ' Draw the Gadget Solid White
 GET (gx1,gy1)-(gx1+Ci,gy1+Ri),Hilit%

     And of course, the final difference is in the PUT statement, as it is
now necessary to locate the upper left corner of the square you want to
highlight:

 PUT (gx1+(Ci*Col%),gy1+(Ri*Row%)),Hilit%,XOR ' Highlight Gadget

3]Variations
     The GET/PUT commands are powerful and can be used to place an alternate
image in the gadget area as well as just reversing the colors. A button may
appear to be actually pressed in when selected, a switch may appear to
toggle, the gadget may even explode. Since you decide how the highlighting
is done, you can have it flip through several images to make a smooth
animation. Backgrounds created in DPII or some other utility can be used to
create realistic surfaces and the alternate images. The only limits are your
imagination and how much time you can spend at your Amiga.

3]NOTES ABOUT STYLE
     If you look at the program ColorGadget, you will note that while there
are three sliders, there is only one routine to deal with them. This is done
by using a dimensioned variable to deal with the values they control.
     You may have noticed these programs contain relatively few constant
numbers. What constants exist, are placed into variables and the rest of the
variables are computed from them. While this admittedly does make for
cryptic-looking code, it also allows the program to be flexible if changes
need to be made.
     One of the axioms of computing is there are many ways to accomplish any
task. Each has its merit and each is valid, so long as it works. The
solutions I've presented here are only a few approaches to problems that
have many solutions. I sincerely hope they have provided you with a little
insight, a little inspiration and a little interest. Please feel free to
modify, mutilate or otherwise improve upon the examples I have provided.

4]END OF TEXT