Contains information information that the GetOpenFileName and GetSaveFileName functions use to initialize an Open or Save As dialog box
Global Const $tagOPENFILENAME = "dword StructSize;hwnd hwndOwner;hwnd hInstance;ptr lpstrFilter;ptr lpstrCustomFilter;" & _
"dword nMaxCustFilter;dword nFilterIndex;ptr lpstrFile;dword nMaxFile;ptr lpstrFileTitle;int nMaxFileTitle;" & _
"ptr lpstrInitialDir;ptr lpstrTitle;dword Flags;short nFileOffset;short nFileExtension;ptr lpstrDefExt;ptr lCustData;" & _
"ptr lpfnHook;ptr lpTemplateName;ptr pvReserved;dword dwReserved;dword FlagsEx"
| StructSize | Specifies the length, in bytes, of the structure. |
| hwndOwner | Handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner. |
| hInstance | If the $OFN_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance is a handle to a memory object containing a dialog box template. If the $OFN_ENABLETEMPLATE flag is set, hInstance is a handle to a module that contains a dialog box template named by the lpTemplateName member. If neither flag is set, this member is ignored. If the $OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the $OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box. |
| lpstrFilter | Pointer to a buffer containing pairs of null-terminated filter strings. The last string in the buffer must be terminated by two NULL characters. |
| lpstrCustomFilter | Pointer to a static buffer that contains a pair of null-terminated filter strings for preserving the filter pattern chosen by the user. The first string is your display string that describes the custom filter, and the second string is the filter pattern selected by the user. The first time your application creates the dialog box, you specify the first string, which can be any nonempty string. When the user selects a file, the dialog box copies the current filter pattern to the second string. The preserved filter pattern can be one of the patterns specified in the lpstrFilter buffer, or it can be a filter pattern typed by the user. The system uses the strings to initialize the user-defined file filter the next time the dialog box is created. If the nFilterIndex member is zero, the dialog box uses the custom filter. If this member is NULL, the dialog box does not preserve user-defined filter patterns. If this member is not NULL, the value of the nMaxCustFilter member must specify the size, in TCHARs, of the lpstrCustomFilter buffer. For the ANSI version, this is the number of bytes; for the Unicode version, this is the number of characters. |
| nMaxCustFilter | Specifies the size, in TCHARs, of the buffer identified by lpstrCustomFilter. For the ANSI version, this is the number of bytes; for the Unicode version, this is the number of characters. This buffer should be at least 40 characters long. This member is ignored if lpstrCustomFilter is NULL or points to a NULL string. |
| nFilterIndex | Specifies the index of the currently selected filter in the File Types control. The buffer pointed to by lpstrFilter 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. An index of zero indicates the custom filter specified by lpstrCustomFilter. You can specify an index on input to indicate the initial filter description and filter pattern for the dialog box. When the user selects a file, nFilterIndex returns the index of the currently displayed filter. If nFilterIndex is zero and lpstrCustomFilter is NULL, the system uses the first filter in the lpstrFilter buffer. If all three members are zero or NULL, the system does not use any filters and does not show any files in the file list control of the dialog box. |
| lpstrFile | Pointer to a buffer that contains a file name used to initialize the File Name edit control. The first character of this buffer must be NULL if initialization is not necessary. When the _WinAPI_GetOpenFileName or _WinAPI_GetSaveFileName function returns successfully, this buffer contains the drive designator, path, file name, and extension of the selected file. If the $OFN_ALLOWMULTISELECT flag is set and the user selects multiple files, the buffer contains the current directory followed by the file names of the selected files. For Explorer-style dialog boxes, the directory and file name strings are NULL separated, with an extra NULL character after the last file name. For old-style dialog boxes, the strings are space separated and the function uses short file names for file names with spaces. You can use the FindFirstFile function to convert between long and short file names. If the user selects only one file, the lpstrFile string does not have a separator between the path and file name. If the buffer is too small, the function returns False and the _WinAPI_CommDlgExtendedError() function returns $FNERR_BUFFERTOOSMALL. In this case, the first two bytes of the lpstrFile buffer contain the required size, in bytes or characters. |
| nMaxFile | Specifies the size, in TCHARs, of the buffer pointed to by lpstrFile. For the ANSI version, this is the number of bytes; for the Unicode version, this is the number of characters. The buffer must be large enough to store the path and file name string or strings, including the terminating NULL character. The _WinAPI_GetOpenFileName and _WinAPI_GetSaveFileName functions return False if the buffer is too small to contain the file information. The buffer should be at least 256 characters long. |
| lpstrFileTitle | Pointer to a buffer that receives the file name and extension (without path information) of the selected file. This member can be NULL. |
| nMaxFileTitle | Specifies the size, in TCHARs, of the buffer pointed to by lpstrFileTitle. For the ANSI version, this is the number of bytes; for the Unicode version, this is the number of characters. This member is ignored if lpstrFileTitle is NULL. |
| lpstrInitialDir | Pointer to a NULL terminated string that can specify the initial directory. |
| lpstrTitle | Pointer to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, Save As or Open). |
| Flags | A set of bit flags you can use to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user's input. This member can be a combination of the following flags. $OFN_ALLOWMULTISELECT - Specifies that the File Name list box allows multiple selections. If you also set the $OFN_EXPLORER flag, the dialog box uses the Explorer-style user interface; otherwise, it uses the old-style user interface. $OFN_CREATEPROMPT - If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name; otherwise, the dialog box remains open. If you use this flag with the $OFN_ALLOWMULTISELECT flag, the dialog box allows the user to specify only one nonexistent file. $OFN_DONTADDTORECENT - Prevents the system from adding a link to the selected file in the file system directory that contains the user's most recently used documents. $OFN_ENABLEHOOK - Enables the hook function specified in the lpfnHook member. $OFN_ENABLEINCLUDENOTIFY - Causes the dialog box to send CDN_INCLUDEITEM notification messages to your OFNHookProc hook procedure when the user opens a folder. The dialog box sends a notification for each item in the newly opened folder. These messages enable you to control which items the dialog box displays in the folder's item list. $OFN_ENABLESIZING - Enables the Explorer-style dialog box to be resized using either the mouse or the keyboard. By default, the Explorer-style Open and Save As dialog boxes allow the dialog box to be resized regardless of whether this flag is set. This flag is necessary only if you provide a hook procedure or custom template. The old-style dialog box does not permit resizing. $OFN_ENABLETEMPLATE - Indicates that the lpTemplateName member is a pointer to the name of a dialog template resource in the module identified by the hInstance member. If the $OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the $OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box. $OFN_ENABLETEMPLATEHANDLE - Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores lpTemplateName if this flag is specified. If the $OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the $OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box. $OFN_EXPLORER - Indicates that any customizations made to the Open or Save As dialog box use the new Explorer-style customization methods. By default, the Open and Save As dialog boxes use the Explorer-style user interface regardless of whether this flag is set. This flag is necessary only if you provide a hook procedure or custom template, or set the $OFN_ALLOWMULTISELECT flag. If you want the old-style user interface, omit the $OFN_EXPLORER flag and provide a replacement old-style template or hook procedure. If you want the old style but do not need a custom template or hook procedure, simply provide a hook procedure that always returns False. $OFN_EXTENSIONDIFFERENT - Specifies that the user typed a file name extension that differs from the extension specified by lpstrDefExt. The function does not use this flag if lpstrDefExt is NULL. $OFN_FILEMUSTEXIST - Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the $OFN_PATHMUSTEXIST flag is also used. This flag can be used in an Open dialog box. It cannot be used with a Save As dialog box. $OFN_FORCESHOWHIDDEN - Forces the showing of system and hidden files, thus overriding the user setting to show or not show hidden files. However, a file that is marked both system and hidden is not shown. $OFN_HIDEREADONLY - Hides the Read Only check box. $OFN_LONGNAMES - For old-style dialog boxes, this flag causes the dialog box to use long file names. If this flag is not specified, or if the $OFN_ALLOWMULTISELECT flag is also set, old-style dialog boxes use short file names (8.3 format) for file names with spaces. Explorer-style dialog boxes ignore this flag and always display long file names. $OFN_NOCHANGEDIR - Restores the current directory to its original value if the user changed the directory while searching for files. This flag is ineffective for GetOpenFileName. $OFN_NODEREFERENCELINKS - Directs the dialog box to return the path and file name of the selected shortcut (.LNK) file. If this value is not specified, the dialog box returns the path and file name of the file referenced by the shortcut. $OFN_NOLONGNAMES - For old-style dialog boxes, this flag causes the dialog box to use short file names (8.3 format). Explorer-style dialog boxes ignore this flag and always display long file names. $OFN_NONETWORKBUTTON - Hides and disables the Network button. $OFN_NOREADONLYRETURN - Specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory. $OFN_NOTESTFILECREATE - Specifies that the file is not created before the dialog box is closed. This flag should be specified if the application saves the file on a create-nonmodify network share. When an application specifies this flag, the library does not check for write protection, a full disk, an open drive door, or network protection. Applications using this flag must perform file operations carefully, because a file cannot be reopened once it is closed. $OFN_NOVALIDATE - Specifies that the common dialog boxes allow invalid characters in the returned file name. Typically, the calling application uses a hook procedure that checks the file name by using the FILEOKSTRING message. If the text box in the edit control is empty or contains nothing but spaces, the lists of files and directories are updated. If the text box in the edit control contains anything else, nFileOffset and nFileExtension are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the buffer specified by lpstrFileTitle. If the value specified by nFileOffset is less than zero, the file name is invalid. Otherwise, the file name is valid, and nFileExtension and nFileOffset can be used as if the $OFN_NOVALIDATE flag had not been specified. $OFN_OVERWRITEPROMPT - Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file. $OFN_PATHMUSTEXIST - Specifies that the user can type only valid paths and file names. If this flag is used and the user types an invalid path and file name in the File Name entry field, the dialog box function displays a warning in a message box. $OFN_READONLY - Causes the Read Only check box to be selected initially when the dialog box is created. This flag indicates the state of the Read Only check box when the dialog box is closed. $OFN_SHAREAWARE - Specifies that if a call to the OpenFile function fails because of a network sharing violation, the error is ignored and the dialog box returns the selected file name. If this flag is not set, the dialog box notifies your hook procedure when a network sharing violation occurs for the file name specified by the user. If you set the $OFN_EXPLORER flag, the dialog box sends the CDN_SHAREVIOLATION message to the hook procedure. If you do not set $OFN_EXPLORER, the dialog box sends the SHAREVISTRING registered message to the hook procedure. $OFN_SHOWHELP - Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button. An Explorer-style dialog box sends a CDN_HELP notification message to your hook procedure when the user clicks the Help button. $OFN_USESHELLITEM - Do not use. |
| nFileOffset | Specifies the 0-based offset, in TCHARs, from the beginning of the path to the file name in the string pointed to by lpstrFile. For the ANSI version, this is the number of bytes; for the Unicode version, this is the number of characters. |
| nFileExtension | Specifies the 0-based offset, in TCHARs, from the beginning of the path to the file name extension in the string pointed to by lpstrFile. For the ANSI version, this is the number of bytes; for the Unicode version, this is the number of characters. |
| lpstrDefExt | Pointer to a buffer that contains the default extension. |
| lCustData | Specifies application-defined data that the system passes to the hook procedure identified by the lpfnHook member. |
| lpfnHook | Pointer to a hook procedure. This member is ignored unless the Flags member includes the $OFN_ENABLEHOOK flag. |
| lpTemplateName | Pointer to a null-terminated string that names a dialog template resource in the module identified by the hInstance member. |
| pvReserved | Reserved. Must be set to NULL. |
| dwReserved | Reserved. Must be set to 0. |
| FlagsEx | A set of bit flags you can use to initialize the dialog box. Currently, this member can be zero or the following flag. $OFN_EX_NOPLACESBAR - If this flag is set, the places bar is not displayed. If this flag is not set, Explorer-style dialog boxes include a places bar containing icons for commonly-used folders, such as Favorites and Desktop. |