GetUIFileNameForWrite()

std::basic_string<wchar_t, traits_t, alloc_t> Chusov::Win32::GDI::GetUIFileNameForWrite	(	HWND	hParent = NULL,
		LPCWSTR	lpszDialogTitle = NULL,
		LPCWSTR	lpszFilter = NULL,
		LPCWSTR	lpszDefExt = NULL,
		LPCWSTR	lpszInitialDir = NULL,
		bool	fAddToRecent = true,
		bool	fShowReadOnlyFiles = false,
		bool	fDenyWriteProtectedFiles = true,
		bool	fOverwritePrompt = true,
		bool	fNoTestCreate = false
	)

Displays standard explorer-style Windows dialog box offering a user to input or choose a name of a file to be created or overwritten.

Template Parameters

traits_t	is a type implementing character traits class of the returned wide string. The default value of the template parameter is std::char_traits<wchar_t>.
alloc_t	is a type of an allocator used by the returned string object. The default template argument is the default allocator instantiated for the wide character type - std::allocator<wchar_t>.

Parameters

[in]	hParent	is an optional handle of a window to be assigned as a parent of the created dialog box window. If a value of the handle is NULL, the dialog box will not have a parent window.
[in]	lpszDialogTitle	is an optional pointer to a wide string specifying a title of the dialog box. If the pointer is NULL, the default "Save As" title is used.
[in]	lpszFilter	is an optional pointer to a buffer containing pairs of zero-terminated wide strings, where the last pair is terminated by an additional zero character (i.e. the last string should be terminated by two zero-characters). Each pair specifies a pattern description and the pattern itself, e.g. "Text files\0*.TXT\0". 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. To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (e.g. "Raw Files\0*.TXT;*.WAV;*.BMP"). If the lpszFilter is NULL, the dialog will not apply any filters.
[in]	lpszDefExt	is an optional pointer to a wide string specifying a default extension to be appended to a selected file name, if a user did not type an extension. The string can be of any length, but only first three characters are appended, and other ones are discarded. If the pointer is NULL and the user does not does not type an extension, then no extension is appended to the file name.
[in]	lpszInitialDir	is an optional wide string specifying the initial directory to be displayed by the dialog box. Despite the pointer is NULL or not, the algorithm of initial directory selection varies in different versions of Windows. See OPENFILENAME for the algorithms applied on various platforms.
	fAddToRecent	If the flag is set, it specifies that a file chosen by a user should be placed to a Windows list of recently used files.
	fShowReadOnlyFiles	specifies if the dialog box should display and provide a possibility of selection of read-only files.
	fDenyWriteProtectedFiles	If set, then the returned file does not have the Read Only check box selected and is not in a write-protected directory.
	fOverwritePrompt	Causes the dialog box to generate a message box, if the selected file already exists. The user must confirm whether to overwrite the file.
	fNoTestCreate	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.

Returns

If a user correctly enters or chooses a file, then the return value is a name of the file. If the user cancels the operation by closing the dialog box or by pressing the cancellation button, the function returns an empty string.

Exceptions

std::bad_alloc	The function was unable to allocate a required amount of memory to complete the request.
Chusov::Exceptions::ChsvCodeException	A system-level error occurred.

See also

GetUIFileNameForRead.