GetUIMultipleFileNamesForRead()

container_t<std::basic_string<wchar_t, char_traits_t, string_alloc_t>, container_alloc_t> Chusov::Win32::GDI::GetUIMultipleFileNamesForRead	(	HWND	hParent = NULL,
		LPCWSTR	lpszDialogTitle = NULL,
		LPCWSTR	lpszFilter = NULL,
		LPCWSTR	lpszInitialDir = NULL,
		bool	fShowReadOnlyFiles = true,
		bool	fAddToRecent = true,
		bool	fFileMustExist = true
	)

Displays standard explorer-style Windows dialog box offering a selection of one or several files to be opened for reading, and, if a user selects files, returns their names within the returned container object.

Template Parameters

container_t	is a container class template, such as std::list or std::vector. See the details for the requirements to the container template.
container_alloc_t	is template of a class of allocator objects, used to manage objects held within the container. The default template used is Chusov::Memory::allocator. See details for the requirements to the allocator class template.
char_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>.
string_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]	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.
	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 one or several files, then their names are added to the returned container object. The file names are represented as Chusov::String::wstring objects. If the user cancels the operation by closing the dialog box or by pressing the cancellation button, the function returns an empty container.

The Container class template specifies a type of a container of file names returned to the caller. The template must satisfy the following requirements:

1. The container template must be able to be fully instantiated with two template parameters, with the first one being a type of an element contained, and the second one being a type of an allocator object.
2. The container instances must be default constructible.
3. The container template instantiations must implement a push_back method allowing adding new elements, referenced by the method parameter, to the container.

Standard std::list and std::vector classes satisfy these requirements.

The ContainerAllocator class template must be a template with one type parameter, specifying a type of elements managed by allocator objects. See std::allocator or Chusov::Memory::allocator for the requirements to the template.

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.