Blitz:IntuitionGadgets
The standard Intuition gadgets are quite old and have many restrictions, including looking quite old on newer versions of the OS, and being quite low level to program. Their use should be avoided unless compatibility with OS 1.x is required.
Contents
Using Intuition Gadgets
Intuition gadgets are defined individually by using a specific command and providing the required parameters, such as size, position, label text, modifier flags and a unique ID for each gadget.
Intuition gadgets produce standard Intuition events when used which can be identified by the gadget ID number.
Defining Intuition Gadgets
Intuition gadgets are defined using a separate command for each gadget. Most gadget types are variations on the basic text gadget, which is actually a button, not a string entry gadget as the name might imply. Intuition gadgets do not include specific cycle, radio or checkmark gadgets; these are merely normal buttons with the relevant properties applied, and do not show any visual differences to indicate their differing behaviour.
Flags
Each gadget accepts a flags parameter to set certain properties of the gadget. General flags that apply to most gadgets are listed below, and can be ORed together to combine options. Common flags are contained within the AmigaLibs.res resident file. Unfortunately, these flags don't seem to tally with the values described in the Blitz Basic 2 manual section on Intuition gadgets, so I am unsure whether these flags can be used or if you have to use the "magic numbers" from the Blitz manual. More testing to be done here...
General Parameters
Most Intuition gadget definitions require a set of broadly similar parameters, with some specific parameters required for certain gadgets. The common parameters are described below:
- GadgetList
- This is the ID of the GadgetList to which the gadget will belong
- 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
- Flags
- This is a flag value based on the required values from the flags listed above, andsets many of the properties of the gadget
- Id
- This is the unique ID of the new gadget
- Text$
- This is a string containing the label to be used for the gadget
Text Gadget
As pointed out before, this is actually a button containing text and not a string entry gadget. The command for creating a text gadget is as follows:
TextGadget GadgetList, X, Y, Flags, Id, Text$
The gadget's size will be determined by the Text$ string used, which will be rendered within the gadget in the standard Amiga Topaz font. See above for some comments on the flags parameter. The Blitz manual contains values that can be added together here, including flags for making this button into a toggle, cycle or radio gadget.
Toggle Gadget
This is a normal text gadget as above, but will toggle on and off as the user clicks it. A button becomes a toggle gadget by adding 1 to the flags parameter.
Cycle Gadget
Again, this is a normal text gadget as above, but with multiple options specified in the Text$ field, separated by pipe characters (|). These options should be evenly spaced within the strings as shown in this example:
TextGadget 0, 20, 30, 0, #sizegadget, " Small|Medium| Large| Huge "
Where #sizegadget is the unique ID defined for this gadget. Note each option is spaced to 6 characters.
Radio Buttons
These are mutually exclusive buttons - selecting one will deselect all other buttons in the group. Again, these are normal text gadgets from above that have been placed in a group, just with the 9th flag bit set (512 added to the flags value). By default, all buttons belong to the one group, so any radio buttons created will mutually exclusive to all others. The ButtonGroup command can be used for setting up different groups. Simply use the ButtonGroup command with a group number to start a new group. Every gadget created after that point will belong to the new group number until another ButtonGroup instruction is encountered. For example:
ButtonGroup 2 TextGadget 0, 20, 30, 512, #sizesmall, "Small" TextGadget 0, 20, 50, 512, #sizemedium, "Medium" TextGadget 0, 20, 70, 512, #sizelarge, "Large" TextGadget 0, 20, 90, 512, #sizehuge, "Huge"
This will create a column of 4 mutually exclusive buttons in their own separate group (group 2). By default, all buttons are created in group 1. Group number must be greater than 0.
String Gadget
This is a gadget that allows the user to enter some text. Its usage is as follows:
StringGadget GadgetList, X, Y, Flags, Id, Maxlen, Width
Most of these parameters are the same as they are for other gadgets above. The Maxlen parameter specifies the maximum number of characters to accept. Width specifies the width of the gadget in pixels.
Proportional Gadget
This is a slider gadget used to set or show a proportional value, such as a scrollbar or volume control. They can be either horizontal or vertical, and their usage template is as follows:
PropGadget GadgetList, X, Y, Flags, Id, Width, Height
Again, most of the parameters are as they are for the other gadgets. Width and Height set the size of the gadget in pixels. Flags sets some special properties for the gadget, and there are some flags that particularly apply to this type of gadget:
- Add 8 to the Flags value to make the width of the gadget proportional to the window size
- Add 16 to the Flags value to make the height of the gadget proportional to the window size
- Add 64 to the Flags value to make a horizontal moving gadget
- Add 128 to the Flags value to make a vertical moving gadget
- Add 256 to the Flags value to suppress drawing a border around the gadget
Gadget Appearance Settings
Most gadgets have a number of properties that can be set using various commands prior to gadget creation.
BorderPens
This sets the pens to use for the highlight and shadow areas of the gadget borders. By default the gadgets use pen 1 for highlight and pen 2 for shadow, however this is only suitable under OS 1.x. For OS 2.0 and above it is recommended to use pen 2 for highlight and pen 1 for shadow so the borders still create a raised look with the standard palette:
BorderPens 2, 1 ; Use pen 2 for highlight and pen 1 for shadow as per the OS2.0+ palette
This command must be used before the creation of gadgets to have any effect.
Borders
This command can be used to turn on and off the automatic creation of gadget borders by specifying the On or Off argument:
Borders Off
Turns off automatic boarders. The default is to create borders. This command can also be used to specify the border spacing around the gadget:
Borders 5, 2
This specifies that 5 pixels of space be left between the left and right edges of the gadget and the border, and 2 pixels between the top and bottom edges and the border.
Note that only button and string gadgets can have borders automatically created.
Manually Drawing Gadget Borders
The GadgetBorder command can be used to manually draw a gadget border on the window. This can be used to surround an area, or to apply a border to gadgets that don't automatically have their own borders created, such as sliders.
GadgetBorder 10, 15, 50, 12
This draws a border starting at coordinates 10x15 in the current window, and draws it 50 pixels wide and 12 pixels tall. Note that this border doesn't behave like a gadget and will need to be redrawn manually if corrupted.
Controlling Gadgets
A number of commands are available for controlling and manipulating gadgets which are already created or displayed.
Redraw
This is used for redrawing a gadget which has been modified, such as changing the proportions of a slider gadget when it's already displayed, or when modifying the contents of a text gadget.
Redraw 0, 5
This will redraw Gadget ID 5 in Window ID 0.
Enable/Disable
These commands allow you to disable or enable gadgets. By default, all gadgets are enabled, but can be disabled to prevent their use. Disabling gadgets gives them a "ghosted" look to show the user that they're not available. Usage is simple:
Disable 0, 2 ; Makes Gadget ID 2 in Gadgetlist ID 0 disabled Enable 0, 3 ; Enables Gadget ID 3 in Gadgetlist ID 0
Toggle
This command will toggle the selected status of the given gadget. Optionally, an On or Off keyword can be given to switch the gadget to that status instead of toggling it:
Toggle 0, 3 ; Toggle the state of Gadget ID 3 from Gadgetlist ID 0 Toggle 0, 4, On ; Set the status of Gadget ID 4 from Gadgetlist ID 0 to selected Toggle 0, 5, Off ; Set the status of Gadget ID 5 from Gadgetlist ID 0 to unselected
ClearString/SetString
These commands let you clear the contents of a string gadget, and set the contents to a string:
ClearString 0, 6 SetString 0, 8, "Test String" Redraw 0, 6 Redraw 0, 8
This clears the contents from Gadget ID 6 in Gadgetlist 0, sets the contents of Gadget ID 8 in Gadgetlist ID 0, and then redraws both gadgets to make their new contents visible.
SetHProp/SetVProp
These commands are used to set the size and position of the handle of the slider gadget. Two properties are involved: pot (short for potentiometer) is the position of the handle along the length of the slider, and body is the proportion of the length that the handle takes up. Both are a quick or floating point number from 0 to 1 (though never actually 1), and are both set at the same time. For example, if your slider is to move from 1 to 10, to position it half way you would set the pot value to 0.5, and to set it to 2, set the pot value to 0.1 (0.0 being the first position). In both cases, the handle represents one tenth of the value possible, so the body should be set to 0.1. If the slider went from 1 to 100, the body value should be set to 0.01. SetHProp is used to set sliders with a horizontal track, and SetVProp is used to set vertical sliders.
SetHProp 0, 2, 0.5, 0.1 Redraw 0, 2
This sets horizontal slider Gadget ID 2 in Gadgetlist 0 to half way, with a body size of 1/10 of the full length (suitable for 10 values). After modifying a slider's properties with these commands, you will need to redraw it with the Redraw command as shown.
Reading Gadget Properties
The properties of most gadgets can be read to determine their current value, status or contents.
GadgetStatus
This function returns the current selected status of the given gadget:
result = GadgetStatus(0, 5)
Sets the result variable to True (-1) if the gadget is selected, or False (0) if not selected.
ButtonID
This function will return the ID of the currently selected gadget within a button group of mutually exclusive gadgets:
result = ButtonID(0, 2)
This returns the ID of the selected gadget in Gadgetlist ID 0, Button Group ID 2.
StringText$
This function returns the string contents of the specified string gadget:
result$ = StringText$(0, 4)
The result$ variable now contains the string contents of String Gadget ID 4 in Gadgetlist ID 0.
HPropPot/VPropPot
These commands get the current pot setting of slider gadgets, effectively reading their selected position. HPropPot is used for horizontal sliders, VPropPot is used for vertical. The value will be a float between 0 and 1 (but never actually 1).
value.f = VPropPot(0, 3)
Sets the contents of the value variable to the positional value of vertical slider Gadget ID 3 in Gadgetlist 0.
HPropBody/VPropBody
Similar to HPropPot & VPropPot above, these commands get the current body setting of slider gadgets, returning a value between 0 and 1 that reflects the handle's size in proportion to the overall size of the gadget. For a slider with 20 possible values, this will be 0.05. Again, HPropBody is for horizontal sliders and VPropBody is for vertical sliders.
