EViews offers the ability to construct several types of user-interface controls, or dialogs, within your program. These dialogs permit users to input variables or set options during the running of the program, and allow you to pass information back to users.

There are five different functions that create dialogs in EViews:

Each dialog function returns an integer indicating how the user exited the dialog:

Note that the only dialog types that can return exit conditions other than “Cancel” or “OK” are @uiprompt and @uidialog. If “Cancel” is pressed, the variables passed into the dialog will not be updated with whatever settings the user has chosen. If “OK” is pressed, then the dialog changes are accepted.

Each of the dialog functions accept arguments that are used to define what will be displayed by the dialog, and that will be used to store the user's inputs to the dialog. You may use string or a scalar arguments, where both the string and scalar can be a literal, a program variable, or a workfile object.

The @uiprompt(string prompt, string type) function creates a simple message/prompt box that displays a single piece of text, specified using the prompt argument, and lets the user click a button to indicate an action. The choices of action offered the user will depend upon the string specified in type.

For example, the command:

will display a simple dialog box with a simple welcome message and an “OK” button, while the command

displays a dialog asking the user if they would like to continue the program, with a “Yes” or “No” answer.

Note that the arguments to the function may be a program variable or string object rather than string literals. The following sets of commands give identical results to that above:

The return value of the control is determined by the user response: Cancel (-1), OK (0), Yes (1), No (2).

See @uiprompt for additional detail.

The @uiedit(string IOString, string prompt, scalar maxEditLen) function provides an edit control that lets the user enter text which is then stored in the string IOString. If IOString contains text before the @uiedit function is called, the edit box will be initialized with that text.

The string prompt is used to specify text to be displayed above the edit box, which may be used to provide a message or instructions to the user.

maxEditLen is an option integer scalar that specifies the maximum length that IOString can take. If the user tries to enter text longer than maxEditLen characters, the extra characters will be truncated. By default maxEditLen is set to 32.

Both prompt and maxEditLen may be written in-line using string literals, but IOString must be either a program variable or a string object in your workfile.

As an example,

will display the following dialog box and then create an equation object with a name equal to whatever was entered for %EQNAME.

The return value of the control is determined by the user response: Cancel (-1) or OK (0).

See @uiedit for additional detail.

This function creates a list box dialog, which lets the user select one item from a list. There are two forms of the @uilist function, one that returns the user's selection as a string IOString,

and one that stores it as an integer IOScalar representing the position of the selection in the list,

The string prompt is used to specify text to be displayed above the list box, providing a message or instructions to the user.

The string list is a space delimited list of items that will be displayed in the list box. To specify entries with spaces, you should enclose the entry in double-quotes using double-quote escape characters.

Both prompt and list may be provided using in-line text, but IOString or IOScalar must be either a program variable or an object in your workfile.

If the IO variable (IOString or IOScalar) is defined before the function is called, then the list box control will have the item defined by the variable pre-selected. If the IO variable does not match an item in the list box, or if it is not pre-defined, the first item in the list will be selected.

The following program lines provide the user with a choice of robust standard errors, and then displays that choice on the statusline:

Note that the above program could also be run with the following lines:

The return value of the control is determined by the user response: Cancel (-1) or OK (0).

See @uilist for details.

This function is similar to @uilist in that it creates a list box dialog, with a difference being that here multiple selections from the list may be made. The form of the @uimlist function is:

The string prompt is used to specify text to be displayed above the list box, providing a message or instructions to the user.

The string list is a space delimited list of items that will be displayed in the list box. To specify entries with spaces, you should enclose the entry in double-quotes using double-quote escape characters.

Both prompt and list may be provided using in-line text, but IOString or IOScalar must be either a program variable or an object in your workfile.

If the IO variable (IOVector) is defined before the function is called, then the list box control will have the items defined by the vector pre-selected. If the IO variable does not match an item in the list box, or if it is not pre-defined, the first item in the list will be selected.

The following program lines provide the user with a choice of robust standard errors, and then displays those choices on the statusline:

See @uimlist for details.

@uiradio(scalar IOScalar, string prompt, string list) is similar to @uilist in that it provides a dialog that lets the user select from a list of choices. However rather than selecting an item from a list box, the user must select the desired item using radio buttons. The @uiradio function will return the user's choice in IOScalar.

The string prompt should be used to specify a message or instructions to the user to be displayed above the set of radio buttons.

The string list is a space delimited list of items that contains the items for the radio buttons. To specify entries with spaces, you should enclose the entry in double-quotes using double-quote escape characters.

Both prompt and list may be specified using in-line text, but IOScalar must be either a program variable or an object in your workfile.

If IOScalar is defined and set equal to a valid integer before the function is called, the radio button associated with that integer will be the default selection when the dialog is shown. If IOScalar is not a valid choice, the first radio will be selected.

As an example, we replicate the standard error choice example from the @uilist function, but this time use radio buttons:

The return value of the control is determined by the user response: Cancel (-1) or OK (0).

See @uiradio for additional detail.

The @uidialog(control_spec1[, control_spec2, ….]) function displays a dialog which may be composed of different controls, including simple text, edit boxes, list boxes, radio buttons and check boxes. The dialog is specified using a list of control specifications passed into the function as arguments. Each control specification is a type keyword specifying the type of control, followed by a list of parameters for that control.

The type keywords should be from the following list:

The “edit”, “list” and “radio” controls are similar to their individual dialog functions, and the specifications for those controls follow the same pattern. Thus the specification for an edit box would be (“edit”, string IOString, string prompt, scalar maxEditLen).

The “caption” control changes the title of the dialog, shown in the title bar. The caption keyword should be followed by a string containing the text to be used as the caption, yielding a specification of (“caption”, string caption).

The “text” control adds basic text to the dialog. Like the caption control, the text control keyword, “text”, should be followed by a string containing the text to be used, yielding a specification of (“text”, string text).

The “check box” control adds a check box to the dialog. The check keyword should be followed by a scalar, IOScalar, which stores the selection of the check box - 1 for checked, and 0 for unchecked, and then by a string prompt which contains the text to be used as a prompt/instructions for the check box. The specification for the check box control is then: (“check”, scalar IOScalar, string prompt).

The “button” and “buttonc” controls add a custom button to the dialog. The dialog will close after a button has been pressed. The behavior of the button will depend on the type of button —buttons of type “button” will behave in the same way as the “OK” button (i.e., all variables passed into the dialog will be updated to reflect changes made to their corresponding controls). Buttons of type “buttonc” will behave in the same way as the “Cancel” button (i.e., all variables will be reset to the values that were passed into the dialog).

The return value of the dialog will correspond to the order in which buttons are placed in the dialog. If only one button (apart from the standard “OK” and “Cancel”) is included in the dialog, the return value for that button will be “1”. If there is more than one button, then the first button will return a value of “1”, the second will return a value of “2” and so on. Note that the return value is independent of whether the button was of type “button” or “buttonc”. The specification for the button controls is (“button[c]”, “text”) where text specifies the text that will be on the button.

The column break control inserts a column break. By default, EViews will automatically choose the number of columns in the constructed dialog. There is still a maximum of only two columns allowed, but by adding a “colbreak” control, you can force the position of a break in the dialog.

“setoc” allows you to change the text of the “OK” and “Cancel” buttons on the dialog. You should supply two words, separated by a space as the text for “OK” and “Cancel”.

As an example, a dialog that offers a choice of covariance matrix options, plus a check box for degree of freedom adjustment, could be made with:

See @uidialog for details.

The @uifiledlg(string IO_Filespec, string filter, string style) displays a standard Windows file open or save dialog so that you may obtain the path and name of a file.

@uifiledlg function will return the user's specification in file_spec.

The string IO_Filespec should be used to specify an initial location and possibly the name for the file. IO_Filespec will also contain the file specified on return.

The string filter is used to specify the types of files to show in the dialog using the filter argument, with, for example, “” used to denote all files, and “prg” used to limit the display to files ending in “.prg”.

The type argument is used to determine whether the shown dialog has an “open” or a “save” prompt.

(Note that the clicking OK on the dialog does not actually open or save the selected file, it merely returns the name of the selected file. Thus, specifying the type argument is for cosmetic reasons only.)

Both filter and style may be specified using in-line text, but IO_Filespec must be either a program variable or an object in your workfile.

The displayed dialog will display both an OK and a Cancel button, and will return an integer representing the button clicked: Cancel (-1), OK (0).

These commands display a file open dialog style containing a list of all files with a “.prg” extension in the folder “c:\temp\”. The user can navigate through the file system and select another file, whose path and name will be returned in the string MYFILE.

Note that the slightly different set of commands

will instead display a save dialog that opens in the “c:\” folder with the filename initialized to “temp.prg” (MYFILE does not have the trailing “\”).

See also @uifiledlg.

This program creates a workfile and some series, then puts up dialogs asking the user to specify the dependent variable and the regressors to be used in a least-squares equation. Note that the part of the example program that generates the data could be replaced with a command to open up an existing workfile.

Three program variables are used in this program: %DEP, %REGS and !RESULT. %DEP is the string variable that will contain the user’s entry for the dependent variable. To begin, we set this equal to an empty string. %REGS is used to store the user’s entry for the list of regressors. We set this equal to “C” to begin with. This means that the default setting for the regressor list will be a constant. !RESULT will be used to track the completion of the dialogs. Every dialog returns an integer value depending on whether the user clicked OK or Cancel (or in some cases Yes or No). We initialize this value to 0.

Following the declaration of the variables, the first dialog is brought up using the @uiedit command. This will create an Edit dialog asking the user to “Enter the dependent variable.” The user’s response will be stored in %DEP. Following the dialog command, we check whether the value of !RESULT is equal to ‑1. A ‑1 indicates that the user pressed Cancel in the dialog. If this is the case, the program quits, using the stop command.

The second dialog command is similar to the first, but rather than asking for the dependent variable, it asks the user to “Enter the list of regressors,” and stores that list in %REGS. Note that since %REGS was set equal to “C” prior to the dialog being put up, the dialog will be pre-filled with the constant term. Users can still delete the constant or add extra regressors.

Finally, having obtained entries for both %DEP and %REGS, equation EQ1 is estimated via least squares with the specified variables.