GetUIFileNameForRead()

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

Displays standard explorer-style Windows dialog box offering a selection of a file to be opened for reading, and, if a user selects a file, returns its name.

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 "Open" 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.
	fShowReadOnlyFiles	specifies if the dialog box should display and provide a possibility of selection of read-only files.
	fCreatePrompt	If the flag is set, it specifies that a dialog box should prompt a user for permission to create a file, if a file name entered by the user does not exist.
	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.
	fFileMustExist	If the flag is set, it is specified that a user is only able to choose or enter names of files that exist. The function will not return until a user either enters a name of existent file, or cancels the file opening operation.

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

GetUIFileNameForWrite;
GetUIMultipleFileNamesForRead.

Examples

chsvwinutilex\CreateDACL.cpp.