Share via

OPENFILENAME

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This structure contains information the operating system uses to initialize the system-defined Open or Save As dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure.

Syntax

typedef struct tagOFN { /* ofn */
  DWORD lStructSize;
  HWND hwndOwner;
  HINSTANCE hInstance;
  LPCSTR lpstrFilter;
  LPSTR lpstrCustomFilter;
  DWORD nMaxCustFilter;
  DWORD nFilterIndex;
  LPSTR lpstrFile;
  DWORD nMaxFile;
  LPSTR lpstrFileTitle;
  DWORD nMaxFileTitle;
  LPSTR lpstrInitialDir;
  LPCSTR lpstrTitle;
  DWORD Flags;
  WORD nFileOffset;
  WORD nFileExtension;
  LPCSTR lpstrDefExt;
  DWORD lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCSTR lpTemplateName;
} OPENFILENAME;

Members

  • lStructSize
    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
    Not supported.

  • lpstrFilter
    Long pointer to a buffer that contains pairs of null-terminated filter strings. The last string in the buffer must be terminated by two NULL 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.

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

    If lpstrFilter is NULL, the dialog box does not display any filters.

  • lpstrCustomFilter
    Not supported.
  • nMaxCustFilter
    Not supported.

  • 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. 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, the system uses the first filter in the lpstrFilter buffer.

  • lpstrFile
    Long 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 GetOpenFileName or GetSaveFileName function returns successfully, this buffer contains the drive designator, path, file name, and extension of the selected file.

    If the buffer is too small, the function returns FALSE. In this case, the first two bytes of the lpstrFile buffer contain the required size, in bytes or characters.

  • nMaxFile
    Specifies the size, in bytes (ANSI version) or 16-bit characters (Unicode version), of the buffer pointed to by lpstrFile. The GetOpenFileName and 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
    Long 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 bytes (ANSI version) or 16-bit characters (Unicode version), of the buffer pointed to by lpstrFileTitle. This member is ignored if lpstrFileTitle is NULL.
  • lpstrInitialDir
    Long pointer to a string that specifies the initial file directory. If this member is NULL, the system uses the root directory.
  • lpstrTitle
    Long 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, SaveAs or Open).

  • Flags
    A bitmask of flags used 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.

    Value Description

    OFN_ALLOWMULTISELECT

    Not supported.

    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.

    OFN_ENABLEHOOK

    Not supported.

    OFN_ENABLESIZING

    Not supported.

    OFN_ENABLETEMPLATE

    Not supported.

    OFN_ENABLETEMPLATEHANDLE

    Not supported.

    OFN_EXPLORER

    Ignored. The Explorer user interface is always used.

    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.

    OFN_HIDEREADONLY

    Hides the Read Only check box.

    OFN_LONGNAMES

    Ignored. The Explorer user interface is always used.

    OFN_NOCHANGEDIR

    Not supported.

    OFN_NODEREFERENCELINKS

    Directs the dialog box to return the path and file name of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and file name of the file referenced by the shortcut

    OFN_NOLONGNAMES

    Not supported.

    OFN_NONETWORKBUTTON

    Not supported.

    OFN_NOREADONLYRETURN

    Not supported.

    OFN_NOTESTFILECREATE

    Not supported.

    OFN_NOVALIDATE

    Ignored. A file name is always validated.

    OFN_PROJECT

    For version 2.0, causes the GetOpenFileName function to open the Project dialog box.

    OFN_PROPERTY

    For version 2.0, causes the GetSaveFileName function to open the Property dialog box.

    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

    Not supported.

    OFN_SHAREAWARE

    Not supported.

    OFN_SHOW_ALL

    Specifies that if OFN_PROJECT is set, show the <All Folders> item.

    > [!NOTE] > This flag applies only to Windows Mobile devices.

    OFN_SHOWHELP

    Not supported.
  • nFileOffset
    Specifies the zero-based offset, in bytes (ANSI version) or 16-bit characters (Unicode version), from the beginning of the path to the file name in the string pointed to by lpstrFile. For example, if lpstrFile points to the following string, c:\dir1\dir2\file.ext, this member contains the value 13 to indicate the offset of the file.ext string.
  • nFileExtension
    Specifies the zero-based offset, in bytes (ANSI version) or 16-bit characters (Unicode version), from the beginning of the path to the file name extension in the string pointed to by lpstrFile. For example, if lpstrFile points to the following string, c:\dir1\dir2\file.ext, this member contains the value 18. If the user did not type an extension and lpstrDefExt is NULL, this member specifies an offset to the terminating null character. If the user typed "." as the last character in the file name, this member specifies zero.
  • lpstrDefExt
    Long pointer to a buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to the file name if the user fails to type an extension. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). If this member is NULL and the user fails to type an extension, no extension is appended.
  • lCustData
    Not supported.
  • lpfnHook
    Not supported.
  • lpTemplateName
    Not supported.

Requirements

Header commdlg.h
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

GetOpenFileName
GetSaveFileName