OPENFILENAME Structure

Type OPENFILENAME
	lStructSize As Long
	hwndOwner As Long
	hInstance As Long
	lpstrFilter As String
	lpstrCustomFilter As String
	nMaxCustomFilter As Long
	nFilterIndex As Long
	lpstrFile As String
	nMaxFile As Long
	lpstrFileTitle As String
	nMaxFileTitle As Long
	lpstrInitialDir As String
	lpstrTitle As String
	flags As Long
	nFileOffset As Integer
	nFileExtension As Integer
	lpstrDefExt As String
	lCustData As Long
	lpfnHook As Long
	lpTemplateName As String
End Type

Description & Usage

The OPENFILENAME structure is used to pass data to and from the GetOpenFileName and GetSaveFileName API functions. It stores both settings used to create the dialog box and the results of the user's selection.

Visual Basic-Specific Issues

Windows NT, 2000: If you do not use a string in the structure, it is imperative that you not set it to an empty string (""). If you do not use a string, leave it alone entirely. Any strings you do use must be explicitly terminated by a null character (vbNullChar). Failure to do either of these will cause GetOpenFileName and GetSaveFileName to fail. See the examples for those two functions for a demonstration on how strings must be handled. Of course, following these guidelines still works under Windows 95 and 98, but it isn't necessary. Your best bet is to follow the NT/2000 requirements so your code works under all versions of Windows.

Data Members

lStructSize

The size in bytes of the structure.

hwndOwner

A handle to the window opening the file dialog box.

hInstance

If using a dialog box template, this is a handle to the memory block of the dialog box template to use. If using the default dialog box, set to 0.

lpstrFilter

The entries in the File Type drop box. The format of the string is "name of file type" & vbNullChar & "mask" & vbNullChar ... for as many types, where name of file type is the text that appears in the list and mask is the extension mask. The string must end with a double vbNullChar.

lpstrCustomFilter

Similar to lpstrFilter, but holds only one file type name/mask pair that specifies a user-defined file type. If unused, set to an empty string.

nMaxCustFilter

The size in bytes of the string contained in lpstrCustomFilter.

nFilterIndex

The number (#1, #2, etc.) of data type specified lpstrFilter should be the default one.

lpstrFile

Set it as a series of blank spaces. If you want to specify a default filename, set this string to that default filename and pad it with spaces. Receives the complete path and filename of the file(s) the user selects. If multiple files are selected, each filename is separated by vbNullChar, and the entire string will end with a double vbNullChar.

nMaxFile

The length in characters of lpstrFile.

lpstrFileTitle

Very similar to lpstrFile, but only receives the filename of the selected file. If multiple files are selected, this is not set to any useful data.

nMaxFileTitle

The length in characters of lpstrFileTitle.

lpstrInitialDir

The default directory to look in.

lpstTitle

The text that appears in the dialog box's title bar.

flags

Zero or more of the following flags specifying how to create the file dialog box. Some of these flags will be set by the function after the call to reflect the user's selections.

OFN_ALLOWMULTISELECT: Allow the user to select multiple files (Open File dialog box only).
OFN_CREATEPROMPT: Prompt if a non-existing file is chosen.
OFN_ENABLEHOOK: Use the function specified by lpfnHook to process the dialog box's messages.
OFN_ENABLESIZING: Windows 98, 2000: Allow the dialog box to be resized. This is selected by default unless a hook function or custom template is specified.
OFN_ENABLETEMPLATE: Use the dialog box template specifed by hInstance and lpTemplateName.
OFN_ENABLETEMPLATEHANDLE: Use the preloaded dialog box template specified by hInstance.
OFN_EXPLORER: Use Windows Explorer-like additions to the file dialog box. This is selected by default unless a hook function or custom template is specified.
OFN_EXTENSIONDIFFERENT: The function sets this flag if the user selects a file with an extension different than the one specified by lpstrDefExt.
OFN_FILEMUSTEXIST: Only allow the selection of existing files.
OFN_HIDEREADONLY: Hide the Open As Read Only check box (Open File dialog box only).
OFN_LONGNAMES: Have the file dialog use long file names. This is automatically specified unless the Explorer-type extensions are not used.
OFN_NOCHANGEDIR: Don't change Windows's current directory to match the one chosen in the dialog box.
OFN_NODEREFERENCELINKS: If a shortcut file (.lnk or .pif) is chosen, return the shortcut file itself instead of the file or directory it points to.
OFN_NOLONGNAMES: Have the file dialog use short (8.3) file names. This is ignored unless a file dialog without Explorer-type extensions are not used.
OFN_NONETWORKBUTTON: Hide and disable the Network button in the dialog box.
OFN_NOREADONLYRETURN: The function sets this flag if the selected file is not read-only (Open File dialog box only).
OFN_NOTESTFILECREATE: Do not create a test file before the box closes. Normally, this check is done to verify that the disk exists, that there is sufficient disk space, etc. However, this check should not be used on a create-nonmodify network share. Specifying this flag prevents this test from being done.
OFN_NOVALIDATE: Don't check the filename for invalid characters.
OFN_OVERWRITEPROMPT: Prompt the user if the chosen file already exists (Save File dialog box only).
OFN_PATHMUSTEXIST: Only allow the selection of existing paths.
OFN_READONLY: Check the Open As Read Only box. This flag is set after the function call if the box is checked after the user clicks OK.
OFN_SHAREAWARE: Ignore any file sharing violations.
OFN_SHOWHELP: Show the Help button in the dialog box. The button sends the WM_HELP message to the hook function specified by the structure. If no hook function is used, the Help button will do nothing.

nFileOffet

Receives the zero-based index specifying where in lpstrFile the pathname ends and the filename begins.

nFileExtension

Receives the zero-based index specifying where in lpstrFile the file extension begins.

lpstrDefExt

The default extension of a file (only for the Save dialog box). If a file is chosen with the *.* mask, the file gets this extension. Don't include the period.

lCustData

Information to pass to the hook function specified by lpfnHook whenever it is called.

lpfnHook

A pointer to a hook function to use to processes the dialog box's messages. For file dialogs with Explorer-type extensions, this is a pointer to a OFNHookProc hook function. For file dialogs without those extensions, this is a pointer to a OFNHookProcOldStyle hook function. If not using a hook function, set to 0.

lpTemplateName

The name of the dialog box template specified by hInstance, if needed.

Constant Definitions

Const OFN_ALLOWMULTISELECT = &H200
Const OFN_CREATEPROMPT = &H2000
Const OFN_ENABLEHOOK = &H20
Const OFN_ENABLESIZING = &H800000
Const OFN_ENABLETEMPLATE = &H40
Const OFN_ENABLETEMPLATEHANDLE = &H80
Const OFN_EXPLORER = &H80000
Const OFN_EXTENSIONDIFFERENT = &H400
Const OFN_FILEMUSTEXIST = &H1000
Const OFN_HIDEREADONLY = &H4
Const OFN_LONGNAMES = &H200000
Const OFN_NOCHANGEDIR = &H8
Const OFN_NODEREFERENCELINKS = &H100000
Const OFN_NOLONGNAMES = &H40000
Const OFN_NONETWORKBUTTON = &H20000
Const OFN_NOREADONLYRETURN = &H8000
Const OFN_NOTESTFILECREATE = &H10000
Const OFN_NOVALIDATE = &H100
Const OFN_OVERWRITEPROMPT = &H2
Const OFN_PATHMUSTEXIST = &H800
Const OFN_READONLY = &H1
Const OFN_SHAREAWARE = &H4000
Const OFN_SHOWHELP = &H10

Used By

GetOpenFileName, GetSaveFileName

Go back to the Structure listing.
Go back to the Reference section index.

Last Modified: September 24, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information.
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/o/openfilename.html