C++ Syntax

__int32

MKI_DialogFileSelection(

HWND f_hWindow

const LPCWSTR f_pszCaption,

MKI_FILENAMEW& f_rFileName,

__int32 f_nFileMode,

const LPCWSTR f_pszFilterString,

__int32 f_nFilterIndex,

const LPCWSTR f_pszDefaultExtension,

MKI_CALLBACK_PROC f_fnHelpCallback,

void* f_pHelpData,

MKI_CALLBACK_PROC f_pnAboutCallback,

void* f_pAboutData,

MKI_CALLBACK_PROC f_pnOptionsCallback,

void* f_pOptionsData );

Shows and processes a dialog which allows the user to select a file name or path.

Parameters

Window

[HWND] Handle of the dialog window's parent window.

Caption

[const LPCWSTR] Title of the dialog window to be displayed. Be careful that the given title fits into the dialog window's caption.

FileName

[MKI_FILENAMEW&] Pointer to a buffer that contains a file name used to initialize the dialog. When the function returns successfully, this buffer contains the drive designator, path, file name, and extension of the selected file.

FileMode

[__int32] Contains the mode that is used for selecting a file name or path respectively. Possible values are:

MKI_FILESELECT_OPEN

An "open file" dialog is displayed. The specified file name and path must exist.

MKI_FILESELECT_SAVE

A "save file" dialog is displayed. If the specified file name already exists a warning is displayed. The specified path must exist.

MKI_FILESELECT_PATH

A "choose path" dialog is displayed. A possibly specified file name is ignored, the specified path must exist. AboutCallback and OptionsCallback are ignored.

FilterString

[const LPCWSTR] Pointer to a buffer containing pairs of null-terminated filter strings. The last string in the buffer must be terminated by two zero characters.

The first string in each pair is a display string that describes the filter (for example, "Text Files"), and the second string specifies the filter pattern (for example, "*.TXT"). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, "*.TXT;*.DOC;*.BAK"). A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string. Example: "Text File (*.txt)\0*.txt\0All Files (*.*)\0*.*\0\0".

The system does not change the order of the filters. It displays them in the "File Types" combo box in the order specified.

FilterIndex

[__int32] Specifies the index of the currently selected filter in the "File Types" control. The buffer pointed to by FilterString contains pairs of strings that define the filters. The first pair of strings has an index value of 1, the second pair 2, and so on.

DefaultExtension

[const LPCWSTR] Pointer to a buffer that contains the default extension. The function appends this extension to the file name if the user fails to type an extension. This string can be of any reasonable length and should not contain a period (.). If this member is nullptr and the user fails to type an extension, no extension is appended.

HelpCallback

[MKI_CALLBACK_PROC] Pointer to a callback function that is called if the "Help" button is applied. If nullptr is specified, the "Help" button displays default help on the file selection dialog.

HelpData

[void*] Pointer to a buffer containing user-defined data (or nullptr) to be passed on to the HelpCallback function.

AboutCallback

[MKI_CALLBACK_PROC] Pointer to a callback function that is called if the "Infos" button is applied. If nullptr is specified, the "Infos" button is used to display file information on the currently selected file.

AboutData

[void*] Pointer to a buffer containing user-defined data (or nullptr) to be passed on to the AboutCallback function.

OptionsCallback

[MKI_CALLBACK_PROC] Pointer to a callback function that is called if the "Options" button is applied. If nullptr is specified no "Options" button is displayed.

OptionsData

[void*] Pointer to a buffer containing user-defined data (or nullptr) to be passed on to the OptionsCallback function.

Return Value Changed in Version 6.41

If the user specifies a file name and clicks the "OK" button and the function is successful, the return value is the selected, non-zero filter index (see FilterIndex). The buffer pointed to by the FileName contains the full path and file name specified by the user (if MKI_FILESELECT_PATH is active only the path is returned).

If the users cancels or an error occurs (error handling is done by the function) the return value is 0.