yyc12345/YYCCommonplace
1
0
Fork 0
Code Activity

refactor: refactor doc layout

Browse Source
This commit is contained in:
yyc12345
2025-12-25 15:12:29 +08:00
parent 45f32297da
commit 337734d340
18 changed files with 52 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,35 @@
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.
*/
}

169
doc/src/windows/dialog_helper.dox Normal file
View File

@@ -0,0 +1,169 @@
namespace YYCC::DialogHelper {
/**
\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 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
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 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
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
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
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.
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 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.
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
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
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 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 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 #OpenFileDialog: Open single file
\li #OpenMultipleFileDialog: Open multiple files
\li #SaveFileDialog: Save single file
\li #OpenFolderDialog: Open single directory
\subsection dialog_helper__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.
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 WinFileDialog: The converted FileDialog passed to Windows.
\li WinFileFilters: Same as WinFileDialog. It will be passed to Windows functions.
\li etc...
*/
}

23
doc/src/windows/win_fct_helper.dox Normal file
View File

@@ -0,0 +1,23 @@
namespace YYCC::WinFctHelper {
/**
\page win_fct_helper Windows Function Helper
This helper give a more convenient way to call Windows functions.
This namespace is Windows specific.
It will be entirely invisible in other platforms.
Currently this namespace has following functions:
\li #GetCurrentModule: Get the handle to current module.
\li #GetTempDirectory: Get temporary directory in Windows.
\li #GetModuleFileName: Get the path to module in file system by given handle.
\li #GetLocalAppData: Get the path inside \%LOCALAPPDATA\%
\li #IsValidCodePage: Check whether given code page number is valid.
\li #CopyFile: The UTF8 version of Win32 \c CopyFile.
\li #MoveFile: The UTF8 version of Win32 \c MoveFile.
\li #DeleteFile: The UTF8 version of Win32 \c DeleteFile.
*/
}

71
doc/src/windows/win_import.dox Normal file
View File

@@ -0,0 +1,71 @@
namespace YYCC {
/**
\page win_import Windows Import Guard
Windows is shitty for the programmer who is familiar with UNIX programming.
Due to legacy reason, Windows defines various things which are not compatible with UNIX or standard C++ programming.
\section win_import__usage Usage
YYCC has a way to solve the issue introduced above.
\code
#if defined(YYCC_OS_WINDOWS)
#include <WinImportPrefix.hpp>
#include <Windows.h>
#include "other_header_depend_on_windows.h"
#include <WinImportSuffix.hpp>
#endif
\endcode
The including of WinImportPrefix.hpp and WinImportSuffix.hpp is a pair.
They just like a guard bracket the include operation of Windows related headers,
to keep all Windows shitty contents will not be leaked outside.
This guard can solve following issues:
<UL>
<LI>
Programmer can not use \c std::max and \c std::min normally.
<UL>
<LI>Windows defines \c MAX and \c MIN as macros for personal use. This is why this happened.</LI>
<LI>Guard defines some special macros to tell Windows do not create these 2 macros.</LI>
</UL>
</LI>
<LI>
Programmer will not be affected by the automatical rename of \c GetObject, \c GetClassName and etc.
<UL>
<LI>These are all macros for Windows personal use to automatically redirect calling to A function and W function by compiling environment.</LI>
<LI>Guard \c \#undef these annoy macros.</LI>
</UL>
</LI>
<LI>
Compiler throw annoy warnings and errors when using specific standard library functions.
<UL>
<LI>MSVC will throw warnings and errors when you are using Microsoft so-called \e depracted or \e unsafe standard library functions.</LI>
<LI>YYCCInternal.hpp, which has been included by this pair, defines some macros to purge these warnings and errors out.</LI>
</UL>
</LI>
</UL>
\section win_import__notes Notes
If you have other header files which are strongly depend on Windows header,
you should put them into this bracket at the same time like example did.
Because this guard operate some Windows macros as we introduced above.
The headers depending on Windows may throw error if you put them outside of this pair.
Please note WinImportPrefix.hpp and WinImportSuffix.hpp can be included multiple times.
Because they do not have the proprocessor command like <I>\#pragma once</I> or etc to make sure they only can be included once.
That's by design. Because we actually may use this pair multiple times.
The only thing you should pledge is that you must make sure they are presented by pair.
This guard is Windows specific.
It does nothing if you accidently use it in other platforms such as Linux,
because the headers use \c \#if to check environment out and will do nothing in non-Windows environment.
However, we still highly recommend you use this pair with platform checker bracket like example does,
if your program need to be run on multiple platforms.
*/
}