167 lines
7.9 KiB
Plaintext
167 lines
7.9 KiB
Plaintext
/**
|
|
|
|
\page dialog_helper Dialog Helper
|
|
|
|
Picking files and folders is an important and essential operation under Windows.
|
|
However the functions picking files and folders are so complex.
|
|
This helper provides universal dialog picker by simple classes and functions.
|
|
In following contents we will tell you how to call them.
|
|
|
|
This helper is Windows specific.
|
|
It will be totally invisible if you are in other platforms.
|
|
|
|
\section dialog_helper__file_dialog Configure File Dialog
|
|
|
|
The first thing is that we should initialize YYCC::DialogHelper::FileDialog,
|
|
and configure it according to your requirements.
|
|
|
|
This class is the data struct representing all aspects of file dialog.
|
|
It also one of the arguments in final dialog function.
|
|
|
|
\code
|
|
YYCC::DialogHelper::FileDialog params;
|
|
params.SetOwner(owner_getter());
|
|
params.SetTitle(YYCC_U8("My File Picker"));
|
|
params.SetInitFileName(YYCC_U8("test.txt"));
|
|
params.SetInitDirectory(initial_directory_getter());
|
|
\endcode
|
|
|
|
\subsection dialog_helper__file_dialog__owner Owner
|
|
|
|
YYCC::DialogHelper::FileDialog::SetOwner will set owner of this dialog.
|
|
It accepts a Microsoft defined \c HWND as argument which should be familiar with Windows programmer.
|
|
If you pass \c NULL to it or skip calling this function, it indicate that there is no owner of this dialog.
|
|
<I>
|
|
I don't what whill happend if there is no owner for it.
|
|
But it would be better to have an owner if possible.
|
|
</I>
|
|
|
|
\subsection dialog_helper__file_dialog__title Title
|
|
|
|
YYCC::DialogHelper::FileDialog::SetTitle will set dialog title of this dialog.
|
|
If you pass \c nullptr or skip calling it,
|
|
the title of dialog will be filled by system and the function type you calling.
|
|
For example, the title will be "Open..." if you call open file function,
|
|
and will be "Save As..." if you call save file function.
|
|
At the same time, the language of this title filled by system is system UI dependent.
|
|
It means that you do not need to do any extra I18N work for it.
|
|
So I suggest you do not set title except you really want to modify title.
|
|
|
|
\subsection dialog_helper__file_dialog__init_file_name Initial File Name
|
|
|
|
YYCC::DialogHelper::FileDialog::SetInitFileName will set the initial file name presented in dialog file name input box.
|
|
If you pass \c nullptr or skip calling it, the text in dialog file name input box will be empty.
|
|
|
|
User can modify the name presented in input box later.
|
|
But if you assign this value, the dialog will lose the ability that remember the previous name user input in previous calling.
|
|
In normal case, dialog will try remembering the file name user input in dialog, and represent it in the next calling.
|
|
However, if you specify this field, the dialog will always presented your specified value in every calling.
|
|
|
|
\subsection dialog_helper__file_dialog__init_directory Initial Directory
|
|
|
|
YYCC::DialogHelper::FileDialog::SetInitDirectory will set the initial directory (startup directory) when opening dialog.
|
|
|
|
In following cases, initial directory will fall back to system behavior:
|
|
|
|
\li Pass \c nullptr to this function.
|
|
\li Skip calling this function.
|
|
\li Given directory path is invalid.
|
|
|
|
The system default behavior of initial directory is similar with initial file name.
|
|
The dialog will try remembering the last directory you just entering, and will back into it in the next calling.
|
|
The directory we meeting in the first launch is system defined.
|
|
|
|
\section dialog_helper__file_filters Configure File Filters
|
|
|
|
File filters is a drop down list represented in file dialog which allow user filter files by their extensions.
|
|
It is beneficial to let user get the file which they want in a directory including massive different files.
|
|
|
|
<B>For file dialog picking a directory,</B> you can skip this step.
|
|
Because the file dialog picking directory does not have file filter drop down box.
|
|
Directory can not be filtered.
|
|
|
|
YYCC::DialogHelper::FileFilters takes responsibility for this feature:
|
|
|
|
\code
|
|
auto& filters = params.ConfigreFileTypes();
|
|
filters.Add(YYCC_U8("Microsoft Word (*.docx; *.doc)"), { YYCC_U8("*.docx"), YYCC_U8("*.doc") });
|
|
filters.Add(YYCC_U8("Microsoft Excel (*.xlsx; *.xls)"), { YYCC_U8("*.xlsx"), YYCC_U8("*.xls") });
|
|
filters.Add(YYCC_U8("Microsoft PowerPoint (*.pptx; *.ppt)"), { YYCC_U8("*.pptx"), YYCC_U8("*.ppt") });
|
|
filters.Add(YYCC_U8("Text File (*.txt)"), { YYCC_U8("*.txt") });
|
|
filters.Add(YYCC_U8("All Files (*.*)"), { YYCC_U8("*.*") });
|
|
params.SetDefaultFileTypeIndex(0u);
|
|
\endcode
|
|
|
|
\subsection dialog_helper__file_filters__setup File Filters
|
|
|
|
We don't need to initialize YYCC::DialogHelper::FileFilters by ourselves.
|
|
Oppositely, we fetch it from YYCC::DialogHelper::FileDialog instance by calling YYCC::DialogHelper::FileDialog::ConfigreFileTypes.
|
|
After fetching, we can call YYCC::DialogHelper::FileFilters::Add to add a filter pair for file filters.
|
|
|
|
The first argument is the display text which user will see in file filter drop down box.
|
|
|
|
The second argument is a \c std::initializer_list.
|
|
Every items are Windows used wildcard string instructing which file should be shown in file dialog.
|
|
It is okey to use multiple wildcard string in list.
|
|
This is suit for those file types involving multiple file extensions, such as the old and new file types of Microsoft Office as we illustracted.
|
|
Empty list not allowed
|
|
|
|
YYCC::DialogHelper::FileFilters::Add also will return a bool to indicate the success of this adding.
|
|
|
|
It should at least has one file filter in file dialog.
|
|
I don't know the consequence if you don't provide any file filter.
|
|
|
|
\subsection dialog_helper__file_filters__default_filter Default File Type
|
|
|
|
YYCC::DialogHelper::FileDialog::SetDefaultFileTypeIndex will set the default selected file filter of this dialog.
|
|
It accepts an index pointing to the file filter which you want to show in default for this file dialog.
|
|
The index of file filters is the order where you call YYCC::DialogHelper::FileFilters::Add above.
|
|
If you pass \c NULL to it or skip calling this function, the first one will be default.
|
|
|
|
\section dialog_helper__result Create Dialog and Get Result
|
|
|
|
Finally, we can call file dialog functions by we initialized YYCC::DialogHelper::FileDialog
|
|
|
|
\code
|
|
YYCC::yycc_u8string single_selection;
|
|
std::vector<YYCC::yycc_u8string> multiple_selection;
|
|
|
|
YYCC::DialogHelper::OpenFileDialog(params, single_selection);
|
|
YYCC::DialogHelper::OpenMultipleFileDialog(params, multiple_selection);
|
|
YYCC::DialogHelper::SaveFileDialog(params, single_selection);
|
|
YYCC::DialogHelper::OpenFolderDialog(params, single_selection);
|
|
\endcode
|
|
|
|
There are 4 file dialogs you can choose:
|
|
|
|
\li YYCC::DialogHelper::OpenFileDialog: Open single file
|
|
\li YYCC::DialogHelper::OpenMultipleFileDialog: Open multiple files
|
|
\li YYCC::DialogHelper::SaveFileDialog: Save single file
|
|
\li YYCC::DialogHelper::OpenFolderDialog: Open single directory
|
|
|
|
\subsection dialog_helper__result__arguments Arguments
|
|
|
|
Among these 4 functions, the first argument always is the reference to YYCC::DialogHelper::FileDialog.
|
|
Function will use it to decide what should be shown in this file dialog.
|
|
|
|
The second argument always is the reference to the container receiving the result.
|
|
For single selection, the return type is \c yycc_u8string.
|
|
For multiple selection, the return type is a list of strings: \c std::vector<yycc_u8string>.
|
|
|
|
\subsection dialog_helper__result__return_value Return Value
|
|
|
|
Please note among these 4 functions will return a bool as its return value to indicate the success of function.
|
|
If they return false, it means that the execution of functions are failed or user click Cancel button.
|
|
In this case, there is no guaranteen to the content of second argument (the real return value).
|
|
|
|
\section dialog_helper__notes Notes
|
|
|
|
You may notice there are various classes which we never introduce.
|
|
Because they are intermediate classes and should not be used by programmer.
|
|
For example:
|
|
|
|
\li YYCC::DialogHelper::WinFileDialog: The converted YYCC::DialogHelper::FileDialog passed to Windows.
|
|
\li YYCC::DialogHelper::WinFileFilters: Same as YYCC::DialogHelper::WinFileDialog. It will be passed to Windows functions.
|
|
\li etc...
|
|
|
|
*/ |