Forms

Contents - Index

Forms

Overview

The macro language supports the use of forms to communicate with the user via a GUI interface. A form consists of a series of form statements (similar to settings variables used in the MacroSet command). You can create a form in a text editor with the raw data elements, but it is recommended that you use the Forms Designer for the initial set up and any changes to the positioning of controls on the form. If you do make changes outside the forms designer, then make sure your form properties are in the same order as generated by the form designer.

Once you have created a form, you can display it in a macro via the Form() function. You can also change individual elements on the form before you display it via the EditForm() function.

Form Controls

Browser - Similar to Memo, but allows you to display any URL or HTML coded File. Update the URL property to force the browser to navigate to that URL
Button - A button that can be clicked on (doing so causes the form to exit)
Checkbox - A check box for yes/no type selection
CheckGroup - A check box for yes/no type selection
CheckListbox - A group of check boxes for multiple selections that are not mutually exclusive (use radio buttons in a group box if the choices are to be mutually exclusive)
Combobox - A box that provides a drop down list of choices
Date - A type of Edit control that allows input of Dates (with pop up calendar)
Edit - A text box allowing user input
File - A type of Edit control that allows browsing for a file
Folder - A type of Edit control that allows browsing for a folder
Form - The actual form you are about to create
Groupbox - A "container" to group other controls
Image - Add a graphic/image to a form
Label - A text label
Memo - Similar to Edit but allows for longer text input and display
Radiobutton - When one of a few options can be selected (options must be mutually exclusive)

Forms and variables

You communicate with your form via variables. Except for the type Form, Group, Image, Browser,and Label, an internal GSAK variable is allocated to each control to reflect the value of the control. Type CheckBox and Radiobutton are Boolean variables, date is date, and all others are string variables. To populate your form control with required data, just allocate a value to a variable with the same name as the control. For example, if you have an edit box and you want the default value to show as "Test" (without the quotes) the code would be:

$data = "Test"
$exit = Form($form,"")
<data> varname=$form
Name=MyForm
Type=Form

Name=data
Type=Edit
Top=50
Left=20
<EndData>

This will result in the following form being displayed:

The default value for a combobox will be the first value of the list. To change this, you may assign the initial value to the combobox variable name. Note that the value you assign is not checked against the list of valid choices. If it is not in the list, the first value will selected.

$Combobox1 = "Second"
$FormExit = Form($form, "")

<Data> VarName=$form
#********************************************************************
# Form generated by GSAK form designer on Fri 19-Feb-2010 14:15:33
Name = Form1
Type = Form
Height = 300
Width = 500

Name = Combobox1
Type = Combobox
Height = 21
Left = 88
Top = 32
Values = First;Second;Third;Fourth
Width = 145
Taborder = 8
<enddata>

Any changes you make to the form, will then be reflected in the corresponding variable $data.

Forms contain controls and controls have properties. Every control must have a name property and a type property and they must be specified in that order. Each property must be on a separate line. The name property is the unique name given to the form control for later reference (and declaration of variables for many controls), and the type property identifies the type of control on the form. All other properties are not mandatory and can be specified in any order.

Note also that forms support the use of system variables $_AppData and $_ExePath. For an example of where this might be useful see this topic

To change form values see the EditForm() function