Note: This function is deprecated and supported for backwards compatibility only. The Form() function supersedes ShowForm() and has enhanced capabilities. Future enhancements will be made to the Form() function only.
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.
Use the Boolean return value of ShowForm to determine how the user exits the form. That is, if he clicks on the red X button at the top of the form, the return value is False. Any other action that exits the form (clicking on a user created button) will return True.
You can create a form variable "on the fly" but the recommend way would be to use <data> <enddata> to create the form template, then use the EditForm() function to make any dynamic changes.
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.
Of no use, but the most simplistic code to create and show a blank form would be:
If ShowForm($form) # enter code here if X button not selected to exit else cancel msg="You clicked on the red x button at the top of the form to exit" EndIf <data> varname=$form Name=MyForm Type=Form <EndData> |
To change form values see the EditForm() function
Supported controls:
Button - A button that can be clicked on
Checkbox - A check box for yes/no type selection
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
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
Supported properties
As previously stated, only name and type are mandatory. All controls default to a different height and width, but you can alter the defaults by specifying your own values. All controls support the following 8 properties.
Container - The control container (see extra notes)
Height - Vertical height of the control in pixels
Left - Position from the Left, which is the number of pixels relative to the container
Name - The control name
Top - Position from the top, which is the number of pixels relative to the container
Type - The control type
Visible - Yes, No.
Width - Horizontal length of the control in pixels
Note: If you omit both the Top and Left properties for the form, it will default to being displayed in the center of your GSAK screen. All other controls default to 0,0 for Top and Left respectively.
Some properties can only be used with certain controls:
Caption - Used by Button, Form, Label, Groupbox. This is the text description that this control will show
Color - Used by label, memo, group, edit, file. This is a number (Use "Macro=>Color picker" to select the corresponding color number.
Container - Every control has a container, and each control defaults to having the form as its container. Only a named Groupbox can be specified for the Container property (or blank to default to the form). When using the properties Top and Left, they are always relative to the control's container. Groupbox containers can be used to group like controls together, but should especially be used with radiobuttons. As only one radio button can be selected per container, this allows you to have multiple groups of radio buttons on a form. Note: You must always define the container before any controls that use this container.
Delay - Used by Form only. Number of seconds before the form will automatically close
DirectInput - ComboBox only. Use to specify that the user can directly input any value at all in the combobox. Currently, when you add a combobox to a form you can only select from the list of values for that combo box. This property when set to Yes will allow the user to directly enter any value rather than only those listed. Basically it turns the control into a combination of edit/combobox.
Display - Use by Combobox only. Combo boxes on forms default to 8 entries before you see the scroll bars to access more than 8. This property allows you to control this value
Font - Used by label and memo only. Allows you to specify the font name to use for the label caption or memo details.
Enabled - Yes, No. Used by all controls except the form. The enabled property set to "No" will automatically show the control in the "gray ghost" outline and prevent the user moving focus to it and changing data.
Enter - Yes, No. Used by buttons only. If yes, then when you press "Enter" on the keyboard, this button is activated. (also see button note below)
Error - Form only. You can use the "Error" property on the form to give the user an error box when the form is displayed. The error property accepts the name of a variable, and any data in this variable will cause the error box to trigger. (see the editform() example) .
Escape - Yes, No. Used by buttons only. If yes, then when you press "Escape" on the keyboard, this button is activated (also see button note below).
ReadOnly - Yes, No. Used by Memo only. Set to Yes to prevent the user from updating the contents of the memo data. No allows the user to update.
Scrollbars - Vertical, Horizontal, Both. Used by Memo only. Specify to show the corresponding scroll bars
Size - Used by label and memo only. Allows you to specify the point size of the label caption. Note: Not all, but many fonts only support the smallest size of 8 regardless of the value you enter.
Spellcheck - Used by button only. You can only specify the name of a memo or edit control here. When there is a named control set, clicking the button will no longer exit the form and return control to the macro. The sole purpose of the button will now be to spell check the corresponding control.
Style - Used by label and memo only. Allows you to specify the caption style. Supported styles are bold, italic, underline, strikeout. You can allocate any combination of these values to the style. Just separate each value with a ; (semi colon)
Values - Combo box only. Specify the variable that will contain the values to populate the combo box. Each single value to show in the combo box should be separated by a ; (semi colon)
Wrap - Yes, No. Used by Memo only. Determines if the text will wrap within the memo control. Has no effect if you set the horizontal scroll bar to show.
Note: Buttons also support another common Windows/Form convention. When allocating the "Caption" property of a button if you precede any letter of the caption with &, that letter then becomes the Alt- hot key for that button. You will also notice the caption of the button shows this character with and underline so you can see this is the Alt- combination required to activate it. This hot key can then be used at any time from any control to action that button.
Default sizes for controls:
Control Width Height
Form 517 277
Button 75 25
Label 32 13
Edit 121 21
Checkbox 17 17
Radiobutton 17 17
GroupBox 185 105
Memo 185 89
Combobox 145 21
Forms and variables
You communicate with your form via variables. Except for the type Form, Group, 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" If ShowForm($form) # enter code here if X button not selected to exit else cancel msg="You clicked on the red x button at the top of the form to exit" EndIf <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:
Any changes you make to the form, will then be reflected in the corresponding variable $data.
Buttons
You can add any number of buttons to your form. When the user mouse clicks on a button, the form will close and the next instruction in your macro will run. You can test which button the user has clicked, simply by testing the Boolean variable with the same name as the button when created.
Example
Some times the easiest way to figure out how it all hangs together is to follow an example:
$g10 = true $chkInclude = true $dblist = SysInfo("databases") If ShowForm($form) If $ok cancel msg="User clicked on the OK button" EndIf If $cancel cancel msg="User clicked on the Cancel button" EndIf else cancel msg="form cancelled" endif <data> Varname=$form Name=Form1 Type=Form Caption=Cache Raid Height=400 Name=Label1 Type=Label Left=100 Top=5 Caption=Cache Raid Input Form color=255 style=bold size=13 Name=Label2 Type=Label Left=5 Top=40 Caption=Database to use Name=Database Type=Combobox left=120 top=40 values=$dblist Name=Label3 Type=Label Left=5 Top=70 Caption=Description for reports Name=Rptdes Type=Edit Left=120 Top=70 Name=Label4 Type=Label Left=5 Top=100 Caption=Distance name=grp1 Type=groupbox left=120 top=100 height=60 caption=Select a group Name=glab10 Type=Label Left=25 Top=20 Caption=10km container=grp1 name=g10 type=radiobutton top=20 left=5 container=grp1 Name=glab20 Type=Label Left=85 Top=20 Caption=20km container=grp1 name=g20 type=radiobutton top=20 left=65 container=grp1 Name=glab30 Type=Label Left=145 Top=20 Caption=30km container=grp1 name=g30 type=radiobutton top=20 left=125 container=grp1 Name=labInclude Type=Label Left=5 Top=170 Caption=Include "special" Name=chkInclude Type=CheckBox left=120 top=170 Name=labOut Type=Label Left=5 Top=190 Caption=Output File Name=OutFile Type=File left=120 top=190 width=200 Name=labNotes Type=Label Left=5 Top=220 Caption=Notes Name=notes Type=memo left=120 top=220 width=300 color=16777088 name=ok type=Button top=330 left=100 caption=OK name=cancel type=Button top=330 left=240 caption=Cancel <enddata> |
This will produce this form:
Note: In the above example I have indented the properties after each name. This is for clarity only. You can enter the properties any way you like, I just find it easier to read this way.
Summary