"SBase Personal - 41. N>COMMANDS AND CONTROLS IN FORMS" 41. N>COMMANDS AND CONTROLS IN FORMS (Only in Sbase Professional 4) Pushbuttons Editing Pushbuttons Using Pushbuttons Commands Without Pushbuttons Auto Execution When is a Command Executed? Interfacing to a DML Program Programmability: A Caution Check Boxes Defining a Check Box Editing a Check Box Radio Buttons Defining a Radio Button Editing a Radio Button Using Form Controls in DML 41. N>COMMANDS AND CONTROLS IN FORMS (Only in SBase Professional 4) The Form Designer Pro includes facilities for adding commands, pushbuttons, check boxes, and radio buttons to forms, enabling you to create sophisticated and complete applications without having to produce a full-scale SBase program suite. By placing pushbuttons on forms, you gain access to SBase's DML programming language, either in the form of self-contained command strings or by executing routines in a memory-resident DML program. Pushbuttons may be used for almost any purpose: for example, to trigger complex processing, to save changes after editing form data, or simply to switch to another form. Command strings do not have to be attached to pushbuttons. You may need some processing to be performed automatically during the course of data entry, and to achieve this you can hide a command object within a form so that its presence is not apparent to the user. A command is one or more DML statements entered as a single line. The command must follow DML syntax as defined in the DML Reference Guide. In addition to pushbuttons and commands, SBase provides two kinds of form control: radio buttons and check boxes. These controls are attached to fields or variable calculations. Pushbuttons A pushbutton is a graphic object that executes a command. Visually, a pushbutton is a rectangle containing a text string that indicates its purpose. Logically, a pushbutton is a sequence of DML commands. When the user clicks the pushbutton, SBase executes the command sequence. To define a pushbutton: 1. Select the Command object type (CMD) from the toolbox. 2. Click where you want the pushbutton to be placed. Form Designer Pro will display requester shown below for naming the command object. *** See Fig 41-1 *** 3. Enter a variable name such as comm1$. Click on the OK button to presnet the requester for entering the command statements. - Do not enter a numeric name such as x% unless you plan to give the button a numeric title such as `100.' An ordinary text title will not be displayed if the pushbutton has a numeric name. 4. Enter the DML statements that comprise the command into the requester shown below. *** See Fig 41-2 *** - If there is more than one statement in a command line, statements must be separated by colons. - The keywords LET, AFTER, and POST should not be used to begin commands; these keywords are used in form calculations. 5. Turn on the Pushbutton check box. 6. Unless the pushbutton command is intended to be executed automatically - that is, as part of the data entry process - turn on the Skip Entry Execution check box. 7. Enter the Button Title. This is the text that you want to appear in the Pushbutton. It is automatically centered. - The Button Title text may be varied while a form is being used, either by DML or by the execution of other form commands. 8. Click OK. Editing Pushbuttons You may alter the visual characteristics of a pushbutton control by selecting it in the usual way, then choosing the attributes you require, for example: - Size. The pushbutton may be any size. - Font and style. The Button Title is drawn in the current font and text style. - Color. You may vary the color of the border, and draw the Button Title text in any pen and/or paper colors. Borders may be turned off. - Read Only. Commands are automatically designated read only, but this attribute may be turned off. If you want to change the contents of the pushbutton command or its title, you must use the Command requester. 1. Select the Command object type from the toolbox. 2. Click the pushbutton to be edited. 3. Change the name of the command if required. 4. Make any changes to the command sequence or button title. Using Pushbuttons Pushbuttons may be used to control a form-based application, for example by allowing the user to switch from one form to another, call up lists of queries, and so on. In such a situation, the pushbutton is not part of the data entry process, and should be excluded from the data entry order by turning on Skip Entry Execution. On the other hand, a pushbutton could be used to assign predictable values to several fields in one go, as a way of speeding up the data entry process. In this case you would leave Skip Entry Execution turned off. To use a pushbutton when a form is open, you may click it directly. This executes the command whether the pushbutton is read only or not. If a pushbutton is part of the data entry process, and has been made not read only, you may tab to it and execute it by pressing SPACEBAR. ENTER is used to move to the next field or control. Read only pushbuttons are executed automatically if they are part of the data entry process. Commands Without Pushbuttons The procedure for setting up command strings that are to be executed automatically is almost the same as for pushbuttons. On the Command requester, make sure the Pushbutton check box and the Skip Entry Execution check box are turned off, and do not enter a title. After creating the command object, adjust its colors so that the text is not visible against the background. Auto Execution If a command both comes first in the data entry order sequence and has read only status, it will be executed automatically once only: the first time the form is opened during a database session. This feature may be used to load a DML program consisting of subroutines that are subsequently called by other commands. When is a Command Executed? Commands are executed when the insertion point passes through them. If the command is read only, the insertion point will never appear in it, but will pass through on its way from one editable object (field or calculation) to the next. This allows you to place a command that is to be used for validation right after the field to which it relates. Of course, you must ensure that the data entry order includes the command at the correct point. See Chapter 37 Defining Data Entry Order. Interfacing to a DML Program You may use the keywords RUN, CHAIN, LOAD, GOTO, and GOSUB. This allows you to construct an interface between a form and a set of DML subroutines that are called from the form. RUN Loads a program from disk and executes it. CHAIN Loads a program from disk with preservation of variable contents, and executes it. LOAD Loads a program from disk but does not execute it. This allows you to load a program consisting of subroutines and then access them individually with the following two commands. GOTO exits to a specified label, and starts executing from that label. It does not return to the form at all. GOSUB exits to a label, and starts executing the subroutine at the label. Control returns to the form command when a RETURN statement is encountered. - When control is returned to the form command after a GOSUB, it returns to the next executable statement in the command, assuming that the command has more than one statement. If the GOTO or GOSUB was the last statement in a command, control returns to the next command or field in the data entry order. END in a command terminates data entry and removes the insertion point from the form. ENTER in a command that is executed during data entry may be used to redirect data entry to a specific field. ENTER 5, for example, will place an insertion point in field number 5 in the data entry order. - You can use only literal numbers in this situation, as the use of numeric variables for calculation and command names conflicts with the use of them as arguments to ENTER. ENTER END in a command terminates data entry. If no DML program is running, the standard `Save This Form' requester is invoked. OPEN FORM may be attached to a pushbutton to allow the user to switch to another area of the application. CLOSE FORM may also be used to exit from a form. Programmability: A Caution Because this is a programmable feature, the form designer must be sure that the rules of programming are respected. In particular, if you call or exit to a subroutine in a DML program, you should avoid overly complex looping or branching structures that jump from one subroutine to another. You are advised to keep called subroutines simple and self- contained, and always to return to the form before calling another routine. If your requirements are inherently complex, you should consider fully controlling the use of the form from within an independent DML program. Check Boxes The check box object type provides the user with a way of controlling the values entered into a field or variable. *** See Fig 41-3 *** A check box has two possible states: selected or unselected. Each state has a specific value attached, such as `yes' or `no,' 0 or 1. When the user turns the check box on, the value for the selected state is assigned to the field; when the check box is turned off, the value for the unselected state is assigned. When used with variables, check boxes, like radio buttons, provide a way of indicating user choices, so that, for example, a DML program can perform selective processing based on those choices. Defining a Check Box You place a check box on a form by selecting the check box object type and clicking on the form. 1. Select the Check Box object type in the toolbox. 2. Click where you want the check box to appear. 3. Choose a field from the list shown in the field selection requester. - You may enter a variable manually. 4. Click OK. 5. In the Check Box Values requester, enter values for the selected and unselected states. - The data should match the data type of the field. - If a field has a validation formula attached, the values assigned to the field by a check box control must pass the validation. 6. Click OK. The Form Designer Pro places a check box object on the form, with a small dotted box extending to the right. This is the selection area for the check box. If you want to be able to turn the check box on and off by clicking the text that normally accompanies a check box, you should resize the selection area and type in the text in the usual way. During data entry, a check box acts like a field, so it appears in the normal data entry order. You can click it to turn it on or off, or tab to it and use the SPACEBAR. Editing a Check Box 1. Select the Check Box object type in the toolbox. 2. Click the check box to be edited. 3. Alter the values for the selected and unselected states. You may edit the accompanying text for a check box in the normal way, but you must first resize the selection box so that it does not overlay the text object, preventing you from selecting it. The text may appear in any color, font or text style. Radio Buttons A radio button is a type of form control. It allows you to attach a specific value to a field or variable, and assign that value by selecting the radio button. *** See Fig 41-3 *** If you define several radio buttons for a field, the buttons act as a group, allowing you to create effective multiple choice fields on a form. Used with variables, radio buttons, like check boxes, provide a way of indicating user choices, so that, for example, a DML program can perform selective processing based on those choices. Defining a Radio Button 1. Select the Radio Button object type from the toolbox. 2. Click where you want the radio button to appear. 3. Choose a field from the list shown in the field selection requester. - You may enter a variable manually. 4. Click OK. 5. In the Radio Button Value requester, enter the value to be assigned to the field when the radio button is selected. - The data should match the data type of the field. - If a field has a validation formula attached, the values assigned to the field by a radio button control must pass the validation. 6. Click OK. The Form Designer Pro places a radio button object on the form, with a small dotted box extending to the right. This is the selection area for the radio button. If you want to be able to turn the radio button on and off by clicking the text that normally accompanies a radio button, you should resize the selection area and type in the text in the usual way. During data entry, a radio button acts like a field, so it appears in the normal data entry order. You can click it on or off, or tab to it and use the SPACEBAR. If you want to be able to use the direction keys to move within a group of radio buttons, you must ensure that all the buttons in the group form a continuous sequence in the data entry order. Editing a Radio Button 1. Select the Radio Button object type in the toolbox. 2. Click the radio button to be edited. 3. Alter the value that is assigned to the field. You may edit the accompanying text for a radio button in the normal way, but you must first resize the selection box so that it does not overlay the text object, preventing you from selecting it. The text may appear in any color, font or text style. Using Form Controls in DML Your application may call for forms that are opened and processed entirely within a DML program environment. The DML WAIT MOUSE command allows you to detect a mouse click on a pushbutton, radio button or check box. Radio buttons and check boxes must be attached to variables rather than fields before they can be used in this way. A typical use for this command would be to wait for the user to make certain radio button selections and then click a pushbutton, which would direct control to the routine appropriate to the user's choices. When a program receives a click on a pushbutton, the pushbutton command may direct control anywhere for example, to another routine within the same program (GOTO labelname), or to a new DML module (CHAIN programname).