12 filereq (File Requester, File Dialogs)

The object filereq (file requester) is a modal file selection window. It distinguishes three modes:

choosing a file to open
specification for saving a file and
choosing a directory.

In addition, selectable files and directories can be restricted by a pattern, or the selection can be limited to existing files or directories.

Definition

{ export | reexport } { model } filereq { <Identifier> }
{
  <object-specific attributes>
}

Events

Children

Parents

None

12.1 Attributes

12.2 Specific Attributes

Please also take note of the subsequent chapters, especially chapter “Description of the filereq Object”.

Attribute	Description
.changedir	Controls whether the attribute .directory shall be set to the directory that last had been used in a file dialog in which the user actually did a selection.
.directory	Initial directory when the file dialog is opened with the querybox function.
.extension	Defines a file extension that is appended to file names without an extension.
multisel	Controls whether multiple files may be selected (Microsoft Windows only; with the styles fr_load and fr_save only).
.mustexist	Ensures that only existing files or directories can be selected; otherwise paths and file names are not checked.
.navigable	Sets if the object can receive the focus and therefore be navigated by keyboard.
options[enum]	Options of the filereq object; please refer to the “Attribute Reference” for details. Allowed indexes: fro_createprompt, fro_overwriteprompt, fro_relativepath
.pattern	Definition of a pattern for file and directory names to restrict which files or directories are selectable.
startsel	With the value true, the path from the attribute .value is taken as initial value. The default value is false.
.style	Sets the filereq object to a certain mode so that it can be used to pick a file, save a file or choose a directory. Possible values are: fr_load, fr_save and fr_directory
.text[enum]	Sets the labels for several dialog elements (Motif only).
.title	Text displayed in the titlebar of the file dialog.
value	Contains the full path of the file or directory that the user has selected.
.value[integer]	List with the paths of the selected files or directories when multi-selection was turned on.

12.3 Description of the filereq Object

The filereq object has no attribute .visible. File dialogs can be opened in the Rule Language with the built-in function querybox() and in the application with the interface functions DM_QueryBox() or DMcob_QueryBox().

The start-up position of the file dialog can be influenced through the parent parameter of these functions. The table below shows the effect of the parent parameter on different window systems.

Parent Parameter	Start-up Position of the File Dialog
	Motif	Microsoft Windows
	Motif	File Selection	Directory Selection
Not specified or Null	Upper left corner of the desktop	Upper left corner of the desktop when no application window is visible, or in the upper left corner of the last application window	Upper left corner of the desktop
Window Object	Centered in the window	Upper left corner of the desktop

During selection, no input is possible in other windows of the application. The user can navigate through the directory tree and select files with the mouse or keyboard. The file dialogs can be closed by aborting the selection with the “Cancel” Button, confirming it with the “OK” button or selecting by double clicking the left mouse button. The corresponding return values are:

button_ok

The user actually selected something. The full paths of the selected files or directories are contained in .value in case of single-selection or .value[] in case of multi-selection. If the attribute .changedir had been set to true, the attribute .directory contains the path to the parent directory of the selected files or directories.
button_cancel

The user aborted the selection.
nobutton

An error occurred that prevented the file dialog from being opened.

The selection options for the user can be limited by indicating an initial directory in the .directory attribute and by a pattern given in the .pattern attribute that determines which items are displayed and selectable by the user. The file extension set in the .extension attribute will be appended to the input name if the name does not already have an extension.

Depending on the window system and the mode specified in the .style attribute, the file dialogs appear differently:

Microsoft Windows	Motif
Figure 13-9: Selecting a file to be loaded	Figure 13-10: Selecting a file to be opened
Figure 13-11: Selecting files to be saved (with multi-selection)	Figure 13-12: Selecting a file to be saved (relative path, Motif 2.1)
Figure 13-13: Selecting a directory	Figure 13-14: Selection of a directory

Some attributes (.options[enum], .multisel, .text[enum]) enable the use of system-specific functions, offer additional functionality, or configure the selection. They are not available on all platforms or have no effect on some platforms.

12.4 Notes

The filereq object is mapped to the file and directory dialogs offered by the systems. Therefore there are different appearances and feature sets available on the different systems. On the other hand, one automatically benefits from improvements of the systems.

The feature to provide a “Help” button, which all systems would offer, is not supported.

The filereq object does not affect the current working directory of the application.

12.4.1 Motif

Most of the appearance (font, color, texts) is controlled by the Window Manager; only the font and some texts can be overwritten by the application.

The same dialog is used for all modes of the filereq object. Therefore its concrete function must be conveyed by the dialog title and the labels of dialog elements. Some labels in the file dialogs can be defined through the .text[enum] attribute of the filereq object.

The IDM assumes checking the existence of files and directories and attaching a file extension if it is not present.

12.4.2 Microsoft Windows

The appearance (font, color, texts) is completely controlled by Windows system settings with the exception of the dialog title.

Multi-selection is provided for choosing files and directories. Clicking the mouse button while holding down Shift, Ctrl, or both, allows for selecting a range of items or toggling the activation of items.

Selection of directories is, in contrast to Motif, limited to existing directories and does not offer the possibility to use patterns. Additionally in IDM versions below A.05.01.e, giving an initial directory limits the selection to the tree beneath this directory. This restriction has been omitted since version A.05.01.e.

Another feature of Microsoft Windows is that the user is prompted with confirmation dialogs before files are created or overwritten.

12.4.3 How to Increase Portability

To achieve a high level of consistency for functionality and appearance, adhere to the following rules:

Do not use multi-selection.
Set the .title attribute to a value that clearly describes the action (open, save, select…).
For consistency of language, the language of your texts must comply with the system language.
Use various patterns (attribute .pattern). Avoid using patterns for directory selection.
Use the directory selection without an initial directory.
Unix and Microsoft Windows use different path separators. This should be taken into account when processing paths.
The attribute .opsys_type of the setup object can be used to query the system.

12.5 Example

A file dialog can be displayed like this:

!! Example for Microsoft Windows
filereq Fr
{
  .style fr_load;
  .title "Show GIF image";
  .directory "c:\";  /* Motif: "/" */
  .pattern "GIF File\t*.gif\tAll\t*.*";  /* Motif: "*.gif"; */
  .extension "gif";
}
rule void OpenFile()
{
  if button_ok = querybox(Fr) then
    ViewGif(Fr.value);
  endif
}