INFORMIX SOFTWARE, INC., LENEXA, KS Wingz Technical Support Bulletin Number 003 Title: Guidelines for the creation of dialog boxes Date: January 23, 1989 Dialog boxes are how Macintoshes obtain information from the user. One of Wingz' more powerful features is the ability to create and customize your own dialog boxes for use within an application. This bulletin will cover some of the basic guidelines that should be followed when designing your own boxes. Following is an abbreviated example format: define doit,vars function myfunc() new modal dialog box at (-1,-1) (3 inches,3 inches) add push button "OK","Cancel" at (.5 inches, 2.5 inches) +(2 inches,.5 inches) dialog cancel push button select control 1 dialog default push button script "filename:doit = 1 filename:vars = ctvalue(3,0)" add radio button "Yes","No" at (.5 inches,.5 inches) +(2 inches,1.5 inches) use dialog box if doit commands end if end function Step 1: Define your variables Your variables need to be defined before they can be used. This is accomplished with the DEFINE command. Wingz uses both local and global variables. Local means that when a function or event is finished, any space allocated for those variables within that function or event is deallocated and released. Global means that the variable will exist in memory as long as the script or worksheet in which they were defined from is in memory. Load scripts into memory with the GET SCRIPT command. Variables defined within sheet scripts are loaded as long as the sheet is open. The variables can then be accessed by a worksheet, another script, another event, or another function. Space is not deallocated when the function or event is finished. In the example above, they have been defined as global because the DEFINE statement is outside of the function. Depending on your application, they can be either way. Step 2: Create the box The line, NEW MODAL DIALOG BOX AT (-1,-1) (3 INCHES,3 INCHES) will start the creation of the box. There are two types of dialog boxes available in Wingz; modal and modeless. Modal dialog boxes are used when you do not want to allow the user to access any other commands or do anything else until they clear the dialog box from the screen. When they try to access a menu command, for example, their error message will play. With modeless dialog boxes, the menu commands are available for use and the user has access to the sheet. In many ways, it acts just like another open window. You can move it, leave it and go to another window, and close it with the close box. It cannot be resized. Our example here will deal with modal dialog boxes. The command for a modeless box is: NEW MODELESS DIALOG BOX "name" AT (-1,-1) (3 inches,3 inches) The coordinates (-1,-1) tells Wingz to center the box in the middle of your screen, no matter what type or size. The second set of coordinates specifies the size of the box itself. In this case, three inches by three inches. You can specify exact coordinates to place the box anywhere on your screen. The first set of coordinates places the top left corner of the box measured from the bottom of the menu bar on the left side of the screen. The second set places the bottom right corner of the box. If a "+" is used in front of the second set, then the second coordinates are measured in relation to the first set. If you do not use the "+", then the second coordinates are measured using the same origin point the first set is measured from. Step 3: Place the controls Once you have the dialog box location and size defined, then you need to place your controls such as radio buttons or check boxes. For placing controls, the point of origin is the upper left corner of the box and the "+" works the same way when used with the second coordinate set. In the first example presented, two buttons are placed in the box. The left point for the controls is placed a half inch from the left of the box and 2.5 inches down. Since the "+" is used, the ending point of the controls is 2 inches to the right and a half inch down from the starting point of the controls. If the "+" wasn't used, the ending point would be 2 inches from the left of the box and .5 inches down. Even though just one command line was used to place the two buttons, they are considered as two distinct controls. The "OK" button, the first one listed, is the first control, and "Cancel" the second. Since it was listed last, it is the currently selected control. Control 1 had to be selected in order to attach a script to it. DIALOG CANCEL PUSH BUTTON assigns certain attributes to the button that is selected when the command is executed. Whenever that button is pressed, it will clear the box from the screen and deallocate any memory assigned for that box. DIALOG DEFAULT PUSH BUTTON is a command that will make pressing the return perform the same action as clicking the "OK" button. It will also highlight that button. Any memory will be deallocated when the box is cleared from the screen. Both DIALOG DEFAULT PUSH BUTTON and DIALOG CANCEL PUSH BUTTON has the command QUIT DIALOG BOX inherent to them. If you do not use these commands, it would be necessary to use QUIT DIALOG BOX in your scripts attached to the "OK" and "Cancel" buttons. A third control is added in the above example. The control is a radio button with two choices, "Yes" and "No". Step 4: Use the box The command USE DIALOG BOX is the command that puts everything together and makes the box available to the user. Dialog boxes follow this procedure when they are created: 1) Memory is allocated for the dialog box when the NEW DIALOG BOX command is executed. 2) Additional memory is allocated for any controls in the dialog box. 3) The box is displayed on the screen with the USE DIALOG BOX command. 4) The user may or may not manipulate any of the controls. 5a) The user presses the "Cancel" button. If this happens, all memory is deallocated and control passes to the next command line after USE DIALOG BOX. If there is a script attached to the button it would be executed. 5b). The user clicks the "OK" button or presses the return key. When this happens, the script attached to this button is executed. This generally stores the control settings to variables and sets a flag. In the above example, the flag set is called "doit". All variables need to be referenced as external variables because the script attached to the button is considered a separate script. Control settings need to be stored to variables because when the box is cleared, the controls can no longer be referenced. Script control passes to the next line after USE DIALOG BOX. The use of a variable flag is not mandatory. It is used primarily to keep any commands from being executed when the "Cancel" button is pressed instead of the "Ok" button. If a flag like "doit" is not set, then any commands after USE DIALOG BOX would be executed and could potentially create errors.