This section describes three simple dialog boxes that you can use to query for user input. The three examples in this section are part of a single program that simulates rolling two six-sided dice a user-determined number of times, and enables you to display a graph that shows the distribution of the values for the dice rolls.

The simplest dialog box is a message box. This dialog box presents the user with information and then waits until the user clicks OK. The following statements use the DoMessageBoxOK module to display a message box with an OK button:

title = "Rolling Dice";
message = "This game simulates rolling two six-sided dice.";
run DoMessageBoxOK(title, message);

The message box is displayed in Figure 16.7. The DoMessageBoxOK has two arguments. The first is a string that appears in the title bar of the window. The second is the message that is displayed to the user.

Figure 16.7. A Message Box That Contains an OK Button

Another simple dialog box is one that contains a single edit field, as shown in Figure 16.8. The DoDialogModifyDouble module takes a default numerical value and enables the user to accept or modify that value, as shown in the following statements:

/* prompt user for a value to use in an algorithm */
message = "Please enter the number of times to roll the dice:";
N = 100;                            /* default number of rolls */
rc = DoDialogModifyDouble(N, title, message);
if rc & N>1 then do;         /* valid specification?           */
    N = int(N);                     /* truncate value to integer      */
    d = j(N, 2);                    /* allocate Nx2 vector (2 dice)   */
    call randgen(d, "uniform");     /* fill with values in (0,1)      */
    d = ceil(6*d);                  /* convert to integers in 1-6     */
    sum = d[,+];                    /* values of the N rolls          */
end;
else
   print "Good-bye";                /* canceled or invalid value      */

For this part of the program, the value 100 is the default number of dice rolls. The user can modify that value. When the user clicks OK, the value in the dialog box is copied into the scalar matrix N. The value returned by the module (called the return code) is stored in the rc matrix. The return code indicates whether the user entered a valid number and clicked OK. A value of 0 indicates that you should not use the value of n; a nonzero value indicates a successful return from the dialog box module.

Figure 16.8. A Dialog Box with a Numerical Input Field

The program uses the value from the dialog box to simulate rolling two dice N number of times. The RANDGEN function returns an N × 2 matrix of values in the range (0,1). If you call this matrix t, then 6t is a matrix with values in the range (0, 6). The CEIL function returns the closest integer greater than a given value, which results in uniformly distributed integers with values one through six. Finally, the subscript operator (+) sums the two columns of the matrix, as described in the section "Writing Efficient SAS/IML Programs" on page 79.

The vector d contains the values of the simulated dice rolls. The following statements use the DoMessageBoxYesNo module to ask the user whether the program should display a bar chart that shows the distribution of the values:

/* prompt user to determine the behavior of an algorithm */
message = "Would you like to see the distribution of the results?";

rc = DoMessageBoxYesNo(title, message);
if rc then do;                             /* create the bar chart */
   declare BarChart bar;
   bar = BarChart.Create(title, sum);
   bar.SetAxisLabel(XAXIS, "Sum");
   bar.SetQtherThreshold(0);
end;

The dialog box is shown in Figure 16.9. If the user clicks Yes, the program creates and displays a bar chart similar to the one shown in Figure 16.10. As the number of simulated rolls gets larger, the distribution of the sample approaches a triangular distribution.

Figure 16.9. A Message Box That Contains Yes and No Buttons

Figure 16.10. Possible Results from a Simulation of Rolling Dice

When you want to present the user with a list of possible choices, you can use the DoDialogGet-ListItem or DoDialogGetListItems modules. The DoDialogGetListItem module enables the user to choose a single item from the list, whereas the DoDialogGetListItems module enables the user to select one or more items from a list.

The two modules have a similar syntax. The first argument is a matrix that serves as an output argument. When the module returns, the matrix contains the indices of the items that the user selected. The second and third arguments are the title and message for the dialog box; these arguments are identical to the arguments for the DoMessageBoxOK dialog box. The fourth argument is a character matrix; each row contains the text for the list. The last argument is a character matrix that labels the columns in the list.

The following statements present the user with a list of all the numeric variables in a data set, and then run a correlation analysis on the variables that the user selects:

/* prompt user to choose variables for an analysis */
declare DataObject dobj;
dobj = DataObject.CreateFromServerDataSet("Sasuser.Vehicles");

/* get vector of numeric variables */
do i = 1 to dobj.GetNumVar();             /* 1 */
   name = dobj.GetVarName(i);             /* get the name              */
   if dobj.IsNumeric(name) then           /* if variable is numeric    */
      varNames = varNames // name;        /*    add it to the vector   */
end;

rc = DoDialogGetListItems(selections,     /* 2 */
        "Correlation Analysis",
        "Please select variables for correlation analysis.",
        varNames, "Name");

if rc then do;                            /* 3 */
   vars = varNames[selections];           /* 4 */
   dobj.WriteVarsToServerDataSet(vars,    /* 5 */
                    "Work", "In", true);

   submit vars;                           /* 6 */
      proc corr data=In nosimple noprob;
         var &vars;                       /* analyze selected vars */
      run;
   endsubmit;
end;

This example uses a data object to read the Vehicles data. The main steps of the program are as follows:

Figure 16.12. Results of a Correlation Analysis on Selected Variables

If you need more control over the number of items the user can select or if you want to supply a default set of values, use the DoDialogGetListItemsEx module.

The preceding example creates a vector by concatenating character strings within a loop. However, Section 2.9 advises that you avoid doing this. In the example, the loop is over variables in a data set. When the number of variables is small (say, less than 100), the inefficiency does not affect the overall performance of the program. However, if your data contain thousands of variables, you should avoid concatenating character strings within a loop. The following code gives an alternative formulation:

/* get vector of numeric variables (more efficient) */
k = dobj.GetNumVar();                 /* number of variables          */
blank32 = subpad("", 1, 32);          /* string with 32 blanks        */
varNames = j(k, 1, blank32);          /* allocate result vector       */
count = 0;                            /* keep count of numeric vars   */
do i = 1 to k;                        /* for each variable...         */
   name = dobj.GetVarName(i);         /* get the name                 */
   if dobj.IsNumeric(name) then do;   /* if the variable is numeric   */
      count = count + 1;              /*    increment the counter     */
      varNames[count] = name;         /*    add name to the vector    */
   end;
end;
varNames = strip(varNames[1:count]);  /* shrink & strip blanks        */

Analyzing the logic of the alternative formulation is left as an exercise for the reader.

Suppose you want to enable the user to choose some option that is associated with an analysis. The default value for the option is off, which is encoded by 0, but the user can turn the option on, which is encoded by 1. You can create a dialog box in R so that the user can select a value for the option. The dialog box records the choice in an R variable, which can be transferred to a SAS/IML matrix. The following statements implement this idea without creating the dialog box:

/* send default value to R; retrieve new value */
x = 0;
run ExportMatrixToR(x, "Value");
submit / R;
   # The user's choice is recorded in the Value variable.
   Value <- 1
endsubmit;
run ImportMatrixFromR(x, "Value");
print x;

The main idea is to create one or more R variables that contain the chosen options. These variables are then imported into SAS/IML matrices, and the algorithm continues based on the chosen options.

Using the previous program as a template, the following program creates a button on a Tk window. The window is created as a modal dialog box, which means that the user must dismiss the window before the program continues. When the button on the window is pressed, the dialog box sets the Value variable to 1.

/* create modal dialog box in R */
x = 0;
run ExportMatrixToR(x, "Value");
submit / R;
   library(tcltk)
   win <- tktoplevel()                  # 1. create a container window
   tktitle(win) <- "Main Window"        #    set title for container

   OnButton <- function() {             # 2. define handler for button
      Value <<- 1                       #    set value at global scope
      tkdestroy(win)                    #    close the parent window
   }
   set.but <- tkbutton(                 # 3. create button
       win,                             #    specify parent window
       text = "Set Return Value",       #    button text
       command = OnButton               #    func to call upon button press
       )
   tkgrid(set.but)                      # 4. add button to window

   tkfocus(win)                         # 5. move the focus to window
   tkwait.window(win)                   #    wait until window is closed
endsubmit;
run ImportMatrixFromR(x, "Value");
print x;

The window created by the program is shown in Figure 16.15. The following list briefly describes the main R statements:

Figure 16.15. Modal Dialog Box Created in R

The flow of the program is as follows. The ExportMatrixToR module creates the Value variable with the value 0. The R statements create the dialog box in Figure 16.15 and wait until the window is dismissed. When you click Set Return Value, the Value variable is set to the value 1 and the window is destroyed. This causes the program to continue and to execute the statement immediately following the tkwait function call. The ImportMatrixToR module reads the value of the Value variable into the SAS/IML matrix x, and this value is printed.

The previous section showed how to create a modal dialog box by using the tcltk package. This section extends the example by creating a checkbox and adding OK and Cancel buttons to the dialog box.

Suppose you want to call the CORR procedure to examine the relationships between several variables. The CORR procedure has several options, one of which is the COV option that specifies whether to compute the variance-covariance matrix of the variables. You can write a program that displays a dialog box with a checkbox that gives the user the option of computing the covariance matrix. The dialog box might look like Figure 16.16. When the user clicks OK, the state of the checkbox determines whether to specify the COV option in the PROC CORR statement.

Figure 16.16. Modal Dialog Box with Checkbox

The following statements use the tcltk package to create the dialog box in Figure 16.16. The state of the checkbox is recorded in the cov.option variable in R:

/* create dialog box in R; retrieve options that the user selects */
covOption = 0;
run ExportMatrixToR(covOption, "cov.option");
submit / R;
   require(tcltk)
   OK.pressed <- FALSE
   win <- tktoplevel()                     # 1. create a container window
   tktitle(win) <- "CORR Options"          #    set title for container
   tcl.cov.option <- tclVar(cov.option)    # 2. create Tcl var for widget

   cb.cov.option <- tkcheckbutton(win)     # 3. create checkbox for option
   label.cov.option <- tklabel(win, text="Show covariances")
   tkconfigure(cb.cov.option, variable=tcl.cov.option)

   tkgrid(cb.cov.option,                   # 4. arrange widgets
          label.cov.option, sticky="w")
   onOK <- function() {                    # 5. define handler for buttons
       cov.option <<- as.numeric(tclvalue(tcl.cov.option))
       OK.pressed <<- TRUE
       tkdestroy(win)
   }
   onCancel <- function() {
       tkdestroy(win)
   }

   buttonsFrame <- tkframe(win)            # 6. create and layout OK/Cancel
   OK.but <- tkbutton(buttonsFrame, text="OK",
                      command=onOK, default="active")
   cancel.but <- tkbutton(buttonsFrame, text="Cancel", command=onCancel)
   tkgrid(OK.but, tklabel(buttonsFrame, text=" "), cancel.but)
   tkgrid(buttonsFrame, columnspan=2)

   tkfocus(win)                            # 7. move the focus to window
   tkwait.window(win)                      # wait until window is closed
endsubmit;

The program begins by defining a default value (0, which means "off") for the covariance option. This value is exported to an R variable named cov.option. The following list briefly describes the main R statements:

After the dialog appears, the user must press either OK or Cancel. If OK is pressed, the onOK function is called, which sets the cov.option variable to reflect the state of the checkbox and then sets the OK.pressed variable to TRUE. If the window is closed by clicking Cancel or by clicking the close icon (X) in the window's title bar, then the value of the OK.pressed variable is FALSE.

The following statements continue the program by checking the value of the OK.pressed variable. If the variable indicates that OK was pressed, then the value of cov.option determines whether to set the COV option in the PROC CORR statement.

/* retrieve user's choices from R variables */
run ImportMatrixFromR(pressed, "OK.pressed");

if pressed then do;                       /* OK was pressed          */
   run ImportMatrixFromR(covOption, "cov.option");
   if covOption then
      covParam = "COV";                   /* checkbox was selected   */
   else
      covParam="";                        /* not selected            */
   submit covParam;                       /* pass option to CORR     */
      proc corr data=Sasuser.Movies noprob &covParam;
         var Sex Violence Profanity;
      run;
   endsubmit;
end;
else do;
   /* Cancel button was pressed */
end;

The previous section describes how to create a dialog box with a single checkbox that specifies whether to use the COV option in the PROC CORR statement. This section builds on the previous example by adding two more widgets to the dialog box. The first is another checkbox that determines whether to use the NOSIMPLE option. The second is a radio button group that specifies how the CORR procedure should handle missing values. By default, the CORR procedure computes the correlation for each pair of variables and deletes missing values in a pairwise fashion. Alternatively, the NOMISS option specifies that an entire observation be deleted if any variable has a missing value for that observation. This is called listwise deletion of missing values. The dialog box is shown in Figure 16.17.

Figure 16.17. Modal Dialog Box for a Correlation Analysis

The following statements define the default values for the various options and transfer these values to R:

/* define and display modal dialog box in R */
descOption = 1;
covOption = 0;
missOption = "pair";
run ExportMatrixToR(descOption, "desc.option");
run ExportMatrixToR(covOption,  "cov.option");
run ExportMatrixToR(missOption, "miss.option");

The next portion of the program is long, but only because the dialog box now contains five widgets: two checkboxes, a radio button group, and the OK and Cancel buttons. However, the main steps of the program are similar to the steps explained in the previous section.

submit / R;
   require(tcltk)
   OK.pressed <- FALSE

   # 1. create Tcl variables for each widget
   tcl.desc.option <- tclVar(desc.option)
   tcl.cov.option  <- tclVar(cov.option)
   tcl.miss.option <- tclVar(miss.option)

   # 2. create a container window; set window title
   win <- tktoplevel()
   tktitle(win) <- "CORR Options"

   # 3. create descriptive statistics checkbox
   cb.desc.option <- tkcheckbutton(win)
   label.desc.option <- tklabel(win, text="Descriptive statistics")
   tkconfigure(cb.desc.option, variable=tcl.desc.option)

   # 4. create covariance checkbox
   cb.cov.option <- tkcheckbutton(win)

   label.cov.option <- tklabel(win, text="Show covariances")
   tkconfigure(cb.cov.option, variable=tcl.cov.option)

   # 5. create radio button for handling missing values
   label.miss.option <- tklabel(win, text="-- Exclude missing values --")
   rb.miss.pair <- tkradiobutton(win)
   rb.miss.list <- tkradiobutton(win)
   label.miss.pair <- tklabel(win, text="Pairwise")
   label.miss.list <- tklabel(win, text="Listwise")
   tkconfigure(rb.miss.pair, variable=tcl.miss.option, value="pair")
   tkconfigure(rb.miss.list, variable=tcl.miss.option, value="list")

   # 6. all widgets created. Arrange them on window
   tkgrid(cb.desc.option, label.desc.option, sticky="w")
   tkgrid(cb.cov.option,  label.cov.option, sticky="w")
   tkgrid(label.miss.option, columnspan=2)
   tkgrid(rb.miss.pair, label.miss.pair, sticky="w")
   tkgrid(rb.miss.list, label.miss.list, sticky="w")

   # 7. define handler for buttons
   onOK <- function() {
       desc.option <<- as.numeric(tclvalue(tcl.desc.option))
       cov.option  <<- as.numeric(tclvalue(tcl.cov.option))
       miss.option <<- as.character(tclvalue(tcl.miss.option))
       OK.pressed  <<- TRUE
       tkdestroy(win)
   }
   onCancel <- function() {
       tkdestroy(win)
   }

   # 8. create and layout OK/Cancel buttons
   buttonsFrame <- tkframe(win)
   OK.but <- tkbutton(buttonsFrame, text="OK",
                      command=onOK, default="active")
   cancel.but <- tkbutton(buttonsFrame, text="Cancel", command=onCancel)
   tkgrid(OK.but, tklabel(buttonsFrame, text=" "), cancel.but)
   tkgrid(buttonsFrame, columnspan=2)

   # 9. move the focus to window and wait until window is closed
   tkfocus(win)
   tkwait.window(win)
endsubmit;

The only new step is the creation of the radio button group. Two radio buttons are created by using the tkradiobutton function. Both of them are configured to update the tcl.miss.option variable. The first radio button sets the value of that variable to the string "pair"; the other sets the value to "list."

The remainder of the program reads the variables that are set by the dialog box. The program checks whether the OK button was clicked and, if so, reads the relevant R variables into SAS/IML matrices. Their values determine whether the NOSIMPLE, COV, and NOMISS options are specified in the PROC CORR statement.

/* retrieve user's choices from R variables; call SAS procedure */
run ImportMatrixFromR(pressed, "OK.pressed");
if pressed then do;
   run ImportMatrixFromR(descOption, "desc.option");
   run ImportMatrixFromR(covOption,  "cov.option");
   run ImportMatrixFromR(missOption, "miss.option");
   descParam = choose(descOption, "", "NOSIMPLE");
   covParam  = choose(covOption,  "COV", "");
   missParam = choose(upcase(missOption)="PAIR", "", "NOMISS");

   submit descParam covParam missParam;
      proc corr data=Sasuser.Movies noprob
                &descParam &covParam &missParam;
         var Sex Violence Profanity;
      run;
   endsubmit;
end;
else do;
   /* Cancel button was pressed */
end;

The examples in this section have demonstrated that you can use R to construct a dialog box in an IMLPlus program. For more information on creating dialog boxes with the tcltk package, see the Web page of examples from Wettenhall (2004).