Standard Dialogs

OS/2 Version 2.0 provides standard dialog boxes for handling the selection of files and fonts. These dialogs conform to SAA CUA guidelines, and are implemented within Presentation Manager. Applications are therefore not required to explicitly design and code such dialog functions, nor to modify them should the CUA guidelines change in the future.

The standard dialogs are displayed using two Presentation Manager functions new to OS/2 Version 2.0; these are the WinFileDlg() and WinFontDlg() functions.

File Dialog

The standard file dialog enables a user to specify a file to be opened or a file name under which current work is to be saved, including the ability to switch directories and logical drives. The file dialog provides basic capabilities, and is designed in such a way that it may be modified if additional function is required.

The file dialog is displayed using the WinFileDlg() function. The dialog may be displayed as either an "Open" dialog or a "Save as" dialog, depending upon the value of control flags specified in a FILEDLG structure passed as a parameter to the function call. The WinFileDlg() function is shown in Figure "Standard Dialogs - WinFileDlg() Function".

The appearance of the file dialog is controlled by the FDS_* style flags specified in the fl field in the FILEDLG structure. The fields in this structure are:

Field

Usage

Defines the size of the FILEDLG structure, and should be initialized using the sizeof() function.

Style flags of the form FDS_*, which control the attributes of the dialog. These flags are described in the IBM OS/2 Version 2.0 Presentation Manager Reference.

Used by applications to store their own state information if subclassing the dialog in order to modify its appearance or behavior.

Identifier of the button used to dismiss the dialog. This is typically DID_OK or DID_CANCEL, unless the application has subclassed the dialog and added its own buttons.

System return code which indicates the reason for dialog failure, if a failure has occurred. This field is used to assist in debugging.

Dialog title text. If set to NULL, the text will default to "Open" or "Save As", depending upon the FDS_* flags selected.

Text used for the OK pushbutton on the dialog. If set to NULL, the text defaults to "OK".

Pointer to custom dialog procedure, for custom dialogs with the FDS_CUSTOM style flag set.

String pointer to a string defining the initial Extended Attribute type filter to be applied to the file name field in the dialog.

Pointer to a table of string pointers. Each points to a null terminated string defining an Extended Attribute type filter. The filters are displayed in ascending order in the Type pull-down box.

Pointer to a string specifying the initial logical drive to be applied in the dialog.

Pointer to a table of string pointers. Each points to a null terminated string defining a valid logical drive.

If the FDS_CUSTOM style flag is set, this field defines the DLL module handle that contains the file dialog template to be used. If set to NULL, the dialog template is loaded from the application's EXE file.

On initialization, this field contains the initial fully qualified path and file name, and on completion of the dialog, contains the selected or user-specified fully qualified file name. Upon invocation of the dialog, all drive and path data is stripped from the name, and moved to the appropriate fields in the dialog box.

Pointer to a table of pointers. Each points to a null terminated string containing a fully qualified file name. This table is used by applications that require multiple files to be selected from within the file dialog (indicated by specifying FDS_MULTIPLESEL). The storage is allocated by the file dialog procedure, and must be freed after dialog completion using the WinFileFreeFileList() function.

Number of file names selected in the file dialog, for dialogs with multiple selection enabled.

Window identifier of the dialog window. If the FDS_CUSTOM style flag is set, this is also the resource identifier of the dialog template.

Position of the dialog, relative to its parent. These fields are automatically updated by the dialog procedure when the dialog is moved by the user, so that if the same FILEDLG procedure is used on subsequent invocations, the dialog will appear in the same location. The FDS_CENTER style flag overrides any settings specified.

Extended Attribute file type to be be assigned to the file. This field contains the returned value specified in the Type field in the dialog. This field is valid only for a "Save As" dialog; the value -1 is returned for an "Open" dialog.

For applications with specialized file handling requirements, the standard file dialog may be subclassed, allowing these requirements to be handled while retaining standard processing for the majority of events. This subclassing is invoked by specifying the address of an application-defined dialog procedure in the pfnDlgProc field in the FILEDLG structure, and by specifying the resource identifier of an application-defined dialog template if controls are to be added or removed from the dialog.

Note that application-defined dialog procedures should invoke the WinFileDlgProc() function as their default case for message processing, to ensure that messages not explicitly processed by the application are passed to the standard file dialog procedure for correct default processing.

Font Dialog

The standard font dialog enables a user to specify a choice of font names, styles, and sizes from the range available within a given application. The font dialog is intended to fit basic application needs, and is designed in such a way that additional function may be added by subclassing the dialog procedure.

The font dialog is displayed using the WinFontDlg() function, specifying the owner window for the dialog box, and a FONTDLG control structure. The use of the WinFontDlg() function is shown in Figure "WinFontDlg() Function - Sample Code".

The appearance of the dialog is determined by the FNTS_* flags specified in the fl field of the FONTDLG structure, and by the other fields in this structure. The fields in the FONTDLG structure are:

Field

Usage

Defines the size of the structure, and should be initialized using the sizeof() function.

If not NULL, this field specifies the screen presentation space, which the dialog procedure queries for available fonts.

If not NULL, this field specifies the printer presentation space, which the dialog procedure queries for available fonts.

Title text for the dialog box. If set to NULL, the default text "Font" is used.

Text to be displayed in the Preview field in the dialog box. If set to NULL, the default text "abcdABCD" is used.

String containing a list of numeric point sizes, to be displayed in the Point Size drop-down list in the dialog box. Point sizes within the string must be separated by spaces. If set to NULL, the defaults of 8, 10, 12, 14, 18, and 24 are used.

Pointer to custom dialog procedure, for dialogs with the FNTS_CUSTOM flag set.

Font family name to be used by an application to select a font. If set to NULL, the system default is used.

Vertical point size of the font.

Flags which specify the characteristics of the dialog box; these may be any combination of FNTS_CENTERED, FNTS_CUSTOM, FNTS_HELPBUTTON, FNTS_MULTIFONTSELECTION, and FNTS_MODELESS. Flags are combined using the "or" operator.

Flags; specifying FNTF_VIEWPRINTERFONTS specifies whether printer fonts should be included if both hpsScreen and hpsPrinter are non-NULL. FNTF_PRINTERFONTSELECTED is set upon return, if the user selects a printer font.

Specifies additional font attributes specified by the user, and may be used as the options field in a QFSATTRS structure for the GpiQueryFaceString() function.

Specifies which flags in the flType field are required to change. This is only relevant where selections may be for different types and styles when multiple fonts are being selected.

Specifies any additional selections, and may be used for the selection indicators in a FATTRS structure supplied to the GpiCreateLogFont() function.

Specifies which flags in the flStyle field are required to change. This is only relevant where selections may be for different types and styles when multiple fonts are being selected.

These are equivalent to the CHS_* option flags used by the GpiCharStringPos() and GpiCharStringPosAt() functions.

Similar to flStyleMask.

Foreground color for the font.

Background color for the font.

May be used by applications to pass information if subclassing the font dialog.

Identifier of the button used to dismiss the dialog. This is typically DID_OK or DID_CANCEL, unless the application has subclassed the dialog and added its own buttons.

System return code that indicates the reason for dialog failure, if a failure has occurred. This field is used to assist in debugging.

Value that may be used within a FONTMETRICS structure by applications.

As above.

As above.

Complete font attribute (FATTRS) structure for the selected font. Only the codepage field may be modified by the application prior to invoking the dialog.

Nominal point size of selected font.

Character thickness (for example, normal or bold). The returned value may be used in the weightclass field in the QFSATTRS structure for the GpiQueryFaceString() function.

Character width. The returned value may be used in the widthclass field in the QFSATTRS structure for the GpiQueryFaceString() function.

Position of the dialog relative to its parent. These fields are automatically updated by the dialog procedure when the dialog is moved by the user, so that if the same FONTDLG structure is used on subsequent invocations, the dialog will appear in the same location. The FNTS_CENTERED style flag overrides any settings specified.

Window identifier of the dialog window. If the FNTS_CUSTOM style flag is set, this is also the resource identifier of the dialog template.

If the FNTS_CUSTOM style flag is set, this field defines the DLL module handle that contains the file dialog template to be used. If set to NULL, the dialog template is loaded from the application's EXE file.

Applications may customize the font dialog through subclassing, by specifying the FNTS_CUSTOM style flag, giving the resource identifier and module handle of the application's customized font dialog template, and the address of an application-defined dialog procedure, in the FONTDLG structure. The WinFontDlg() function then performs the subclassing operation on the application's behalf.

Note that application-defined dialog procedures should invoke the WinFontDlgProc() function as their default case for message processing, to ensure that messages not explicitly processed by the application are passed to the standard font dialog procedure for correct default processing.

An application that uses its own dialog template must include all of the standard controls within the dialog box, in addition to its own customized controls. Those controls, which are not required, may be rendered invisible in order to provide the correct appearance.

Control window identifiers in the range 0x0000 to 0x0FFF are reserved for use by standard controls. The application's own controls should therefore use window identifiers greater than 0x0FFF.