yyc12345/YYCCommonplace
1
0
Fork 0
Code Activity

doc: add doc for 2 win chapters and fix typo in windows dialog

Browse Source
This commit is contained in:
yyc12345
2026-01-12 17:13:16 +08:00
parent c708e1e672
commit 2b6ac98f27
7 changed files with 90 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/index.dox
View File

@@ -69,11 +69,11 @@
\li \subpage windows__import_guard
\li \subpage windows__com
\li \subpage windows__dialog
<!--
\li \subpage com_helper
\li \subpage dialog_helper
\li \subpage win_fct_helper
\li \subpage exception_helper

31
doc/src/windows/com.dox Normal file
View File

@@ -0,0 +1,31 @@
namespace yycc::windows::com {
/**
\page windows__com COM Helper
This namespace is Windows specific.
It will be invisible on other platforms.
\section windows__com__memory_safe_ptr Memory Safe Pointer Types
This namespace provides various memory-safe types for interacting with COM functions.
Although Microsoft also has similar smart pointer called \c CComPtr.
But this library is eager to hide all Microsoft-related functions calling.
Using \c CComPtr is not corresponding with the philosophy of this library.
So these standard library based smart pointer and corresponding deleter types were created.
\section windows__com__com_guard COM Guard
This namespace contains a COM Guard which make sure COM was initialized in current module when loading current module.
It is essential because all calling to COM functions should be under the premise that COM has been initialized.
This guard also will uninitialize COM when unloading this module.
There is only an exposed function called is_initialized() for user calling.
This function will check whether COM environment is initialized.
If you want YYCC automatically initialize COM environment for you,
you must call this function in your program at least one time.
Otherwise COM Guard code may be unavailable,
because compiler may think these code is not referenced by any other code and drop them.
*/
}

35
doc/src/windows/com_helper.dox
View File

@@ -1,35 +0,0 @@
namespace YYCC::COMHelper {
/**
\page com_helper COM Helper
This namespace is Windows specific.
It will be invisible on other platforms.
This namespace is used by internal functions as intended.
They should not be used outside of this library.
But if you compel to use them, it is also okey.
\section com_helper__memory_safe_ptr Memory Safe Pointer Types
This namespace also provided various memory-safe types for interacting with COM functions.
Although Microsoft also has similar smart pointer called \c CComPtr.
But this library is eager to hide all Microsoft-related functions calling.
Using \c CComPtr is not corresponding with the philosophy of this library.
So these standard library based smart pointer types were created.
\section com_helper__com_guard COM Guard
This namespace contain a COM Guard which make sure COM was initialized in current module when loading current module.
It is essential because all calling to COM functions should be under the premise that COM has been initialized.
This guard also will uninitialize COM when unloading this module.
There is only an exposed function called #IsInitialized for user calling.
This function will check whether COM environment is initialized.
If you want YYCC automatically initialize COM environment for you,
you must call this function in your program at least one time.
Otherwise COM Guard code may be unavailable,
because compiler may think they are not essential code and drop them.
*/
}

106
doc/src/windows/dialog_helper.dox → doc/src/windows/dialog.dox
View File

@@ -1,7 +1,7 @@
namespace YYCC::DialogHelper {
namespace yycc::windows::dialog {
/**
\page dialog_helper Dialog Helper
\page windows__dialog Dialog Helper
Picking files and folders is an important and essential operation under Windows.
However the functions picking files and folders are so complex.
@@ -11,7 +11,7 @@ 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
\section windows__dialog__file_dialog Configure File Dialog
The first thing is that we should initialize FileDialog,
and configure it according to your requirements.
@@ -20,16 +20,16 @@ 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());
FileDialog params;
params.set_owner(owner_getter());
params.set_title(u8"My File Picker");
params.set_init_file_name(u8"test.txt");
params.set_init_directory(initial_directory_getter());
\endcode
\subsection dialog_helper__file_dialog__owner Owner
\subsection windows__dialog__file_dialog__owner Owner
FileDialog::SetOwner will set owner of this dialog.
FileDialog::set_owner() 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>
@@ -37,9 +37,9 @@ I don't what will happen 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
\subsection windows__dialog__file_dialog__title Title
FileDialog::SetTitle will set dialog title of this dialog.
FileDialog::set_title() 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,
@@ -48,9 +48,9 @@ At the same time, the language of this title filled by system is system UI depen
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
\subsection windows__dialog__file_dialog__init_file_name Initial File Name
FileDialog::SetInitFileName will set the initial file name presented in dialog file name input box.
FileDialog::set_init_file_name() 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.
@@ -58,9 +58,9 @@ But if you assign this value, the dialog will lose the ability that remember the
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
\subsection windows__dialog__file_dialog__init_directory Initial Directory
FileDialog::SetInitDirectory will set the initial directory (startup directory) when opening dialog.
FileDialog::set_init_directory() will set the initial directory (startup directory) when opening dialog.
In following cases, initial directory will fall back to system behavior:
@@ -72,7 +72,7 @@ The system default behavior of initial directory is similar with initial file na
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
\section windows__dialog__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.
@@ -84,20 +84,20 @@ Directory can not be filtered.
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);
auto& filters = params.configure_file_types();
filters.add_filter(u8"Microsoft Word (*.docx; *.doc)", { u8"*.docx", u8"*.doc" });
filters.add_filter(u8"Microsoft Excel (*.xlsx; *.xls)", { u8"*.xlsx", u8"*.xls" });
filters.add_filter(u8"Microsoft PowerPoint (*.pptx; *.ppt)", { u8"*.pptx", u8"*.ppt" });
filters.add_filter(u8"Text File (*.txt)", { u8"*.txt" });
filters.add_filter(u8"All Files (*.*)", { u8"*.*" });
params.set_default_file_type_index(0u);
\endcode
\subsection dialog_helper__file_filters__setup File Filters
\subsection windows__dialog__file_filters__setup File Filters
We don't need to initialize FileFilters by ourselves.
Oppositely, we fetch it from FileDialog instance by calling FileDialog::ConfigreFileTypes.
After fetching, we can call FileFilters::Add to add a filter pair for file filters.
Oppositely, we fetch it from FileDialog instance by calling FileDialog::configure_file_types().
After fetching, we can call FileFilters::add_filter() 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.
@@ -107,55 +107,51 @@ 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
FileFilters::Add also will return a bool to indicate the success of this adding.
FileFilters::add_filter() throws std::invalid_argument if filter name is blank or filter patterns is empty.
Because these errors should be found during developing.
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
\subsection windows__dialog__file_filters__default_filter Default File Type
FileDialog::SetDefaultFileTypeIndex will set the default selected file filter of this dialog.
FileDialog::set_default_file_type_index() 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 FileFilters::Add above.
The index of file filters is the order where you call FileFilters::add_filter() 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
\section windows__dialog__result Create Dialog and Get Result
Finally, we can call file dialog functions by we initialized 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);
auto result1 = open_file(params);
auto result2 = open_files(params);
auto result3 = save_file(params);
auto result4 = open_folder(params);
\endcode
There are 4 file dialogs you can choose:
\li #OpenFileDialog: Open single file
\li #OpenMultipleFileDialog: Open multiple files
\li #SaveFileDialog: Save single file
\li #OpenFolderDialog: Open single directory
\li #open_file: Open single file
\li #open_files: Open multiple files
\li #save_file: Save single file
\li #open_folder: Open single directory
\subsection dialog_helper__result__arguments Arguments
\subsection windows__dialog__result__arguments Arguments
Among these 4 functions, the first argument always is the reference to FileDialog.
Function will use it to decide what should be shown in this file dialog.
Among these 4 functions, the only argument is the reference to FileDialog.
Function will use it to decide what would 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 windows__dialog__result__return_value Return Value
\subsection dialog_helper__result__return_value Return Value
Please note these 4 functions will return a dialog specified result type as their return value.
If this result type is an error, it means that an error occurred during execution.
Otherwise, there is an optional value inside this result type.
If user click Cancel button, this optional value will be empty.
otherwise, this optional value will hold user selected a file or directory.
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
\section windows__dialog__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.