| Chapter 19. Common Dialogs and Other UI Utilities in SIMPOL | ||
|---|---|---|
 | Part VII. User-Interface Components |  |
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.
![[Note]](images/note.png) | Note |
|---|---|
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 savingwxdirectorydialog()— for getting the name of a directory, including allowing the user to create a new onewxmessagedialog()— 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) parentmessagedefaultdirectorydefaultfilenamewildcardstylefilenameresult
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.
| Note |
|---|---|
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.
| Note |
|---|---|
SBL programmers should note that this function corresponds to the REQUEST command in SBL for type 28. |