SIMPOL Documentation

Chapter 19. Common Dialogs and Other UI Utilities in SIMPOL

Common dialogs are typically provided by the operating system to perform commonly required tasks. Typical common dialogs would be those for picking a file to open or to save, for configuring the printer, or selecting a font or color. Currently SIMPOL provides support for the selecting of a file to open and to save, presenting a message to the user, and the selection of a directory (with or without a new directory button). Others will follow as we progress. The look and feel of these dialogs including largely the functionality that is provided is very operating system dependent, so it may be that certain capabilities are not provided that might otherwise be possible, in order to retain a common user-interface cross-platform. The message box is a good example. This may have a different name on different platforms but the functionality is fairly consistent: a dialog window is presented with a message to the user, possibly including an icon, and one or more buttons from which the user must choose.


Please come back and check this chapter regularly in each release. The common dialog support is a currently moving target. The older UTUI components that provided the initial common dialog support are now deprecated! Please migrate to the newer wxWidgets-based common dialog support.

Common Dialogs in SIMPOL

Common dialogs provide a method of accessing standard user-interface components that are provided to allow a common look and feel. These are implemented using functions rather than types in most cases. The following functions are currently implemented:

  • wxfiledialog() — for getting a file name for opening or saving

  • wxdirectorydialog() — for getting the name of a directory, including allowing the user to create a new one

  • wxmessagedialog() — for showing some information to the user and getting their response (one of "ok", "cancel", "yes", or "no")

The wxfiledialog() function implements the functionality that allows the user to select an existing file to be opened as well as that of selecting the path and then typing in a file name for a file to be saved. The behavior of the dialog depends on the purpose for which it is being used. If it is being used to select a file name for saving and the user selects a file that already exists, and if the style includes the value "overwriteprompt" then they will automatically be prompted for confirmation that they wish to overwrite the file that they have selected. In some operating systems, if the user enters the name of a file that does not exist when using this technology to open a file, they will be prompted with the question of whether they wish to create a new file. In other cases they may not be able to open a file that does not exist. The style value "mustexist" plays a role here.

The full syntax of this function is:

wxfiledialog ( type(wxdialogparent) parent, string message, string defaultdirectory, string defaultfilename, string wildcard, string style, string filename, string result )

Currently the style can contain either the value "open" or "save" to decide the basic type of file dialog. In addition to these two values, the style values "mustexist", "overwriteprompt", and "multiple" are provided to further influence how the dialog works. Generally, the viable combinations are: "open,mustexist", "open,multiple", "open,mustexist,multiple", and "save,overwriteprompt". The wildcard parameter provides the capability to have a number of different extensions and file descriptions on some platforms. However, not all platforms support this capability so an application should not rely on this ability in a cross-platform environment. A default value for the file name can be provided using the defaultfilename parameter. The starting directory is defined normally by the defaultdirectory parameter, but this is a fairly complicated issue, so check the description of this parameter in the "SIMPOL Language Reference" book. The filename and result parameters must be actual objects, since they will be filled with a value by the function. The result parameter will contain either "ok" or "cancel" indicating the action taken by the user. Although a number could have been chosen, the decision was taken that using strings for the return value is more programmer-friendly and that in the majority of places that they will be used, they would not be difficult strings for most programmers to understand. They can still be assigned to constants if desired by the programmer. For complete documentation on the features of this function, see the "wxWidgets" section of the "Components" chapter in the "SIMPOL Language Reference" book.


SBL programmers should note that this function corresponds to the REQUEST command in SBL for types 26 and 27.

The syntax and usage of the wxdirectorydialog() function is very similar to that of the preceding one. It is less complex, since the number of options is less. It is used to retrieve the name of a directory and can optionally provide the user with the ability to create a new directory.


SBL programmers should note that this function corresponds to the REQUEST command in SBL for type 28.