yyc12345/YYCCommonplace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: add document for dialog helper

Browse Source
This commit is contained in:
yyc12345 2024-05-27 21:21:39 +08:00
parent efcc371e31
commit d437ecc140
2 changed files with 49 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
src/DialogHelper.cpp
View File

@ -8,6 +8,12 @@ namespace YYCC::DialogHelper {
#pragma region COM Guard
/**
* @brief The guard for initialize COM environment.
* @details This class will try initializing COM environment by calling CoInitialize when constructing,
* and it also will try uninitializing COM environment when destructing.
* If initialization failed, uninitialization will not be executed.
*/
class ComGuard {
public:
ComGuard() : m_HasInit(false) {
@ -24,6 +30,14 @@ namespace YYCC::DialogHelper {
bool m_HasInit;
};
/**
* @brief The instance of COM environment guard.
* @details Dialog related function need COM environment,
* so we need initializing COM environment when loading this module,
* and uninitializing COM environment when we no longer use this module.
* So we use a static instance in here.
* And make it be const so no one can change it.
*/
static const ComGuard c_ComGuard;
#pragma endregion
@ -159,6 +173,13 @@ namespace YYCC::DialogHelper {
OpenFolder
};
/**
* @brief Extract display name from given IShellItem*.
* @param item[in] The pointer to IShellItem for extracting.
* @param ret[out] Extracted display name container.
* @return True if success, otherwise false.
* @remarks This is an assist function of CommonFileDialog.
*/
bool ExtractDisplayName(IShellItem* item, std::string& ret) {
// fetch display name from IShellItem*
LPWSTR _name;
@ -174,6 +195,15 @@ namespace YYCC::DialogHelper {
return true;
}
/**
* @brief General file dialog.
* @param params[in] User specified parameter controlling the behavior of this file dialog,
* including title, file types and etc.
* @param ret[out] The path to user selected files or folders.
* For multiple selection, the count of items >= 1. For other scenario, the count of item is 1.
* @return True if success, otherwise false (input parameters is wrong or user click "Cancel" in popup window).
* @remarks This function is the real underlying function of all dialog functions.
*/
template<CommonFileDialogType EDialogType>
bool CommonFileDialog(const FileDialog& params, std::vector<std::string>& ret) {
// Reference: https://learn.microsoft.com/en-us/windows/win32/shell/common-file-dialog

18
src/DialogHelper.hpp
View File

@ -16,6 +16,9 @@ namespace YYCC::DialogHelper {
#pragma region COM Pointer Management
/**
* @brief C++ standard deleter for every COM interfaces inheriting IUnknown.
*/
class ComPtrDeleter {
public:
ComPtrDeleter() {}
@ -32,6 +35,9 @@ namespace YYCC::DialogHelper {
using SmartIShellItemArray = std::unique_ptr<IShellItemArray, ComPtrDeleter>;
using SmartIShellFolder = std::unique_ptr<IShellFolder, ComPtrDeleter>;
/**
* @brief C++ standard deleter for almost raw pointer used in COM which need to be free by CoTaskMemFree()
*/
class CoTaskMemDeleter {
public:
CoTaskMemDeleter() {}
@ -112,6 +118,7 @@ namespace YYCC::DialogHelper {
* @brief Generate Windows dialog system used data struct.
* @param win_result[out] The class holding the generated filter data struct.
* @return True if generation is success, otherwise false.
* @remarks User should not call this function, this function is used in internal code.
*/
bool Generate(WinFileFilters& win_result) const;
@ -156,6 +163,8 @@ namespace YYCC::DialogHelper {
/**
* @brief The default selected file type in dialog
* @remarks This is 1-based index according to Windows specification.
* In other words, you should plus 1 for this index when generating this struct from
* user oriented file dialog parameters.
*/
UINT m_WinDefaultFileTypeIndex;
bool m_HasTitle, m_HasInitFileName;
@ -205,6 +214,9 @@ namespace YYCC::DialogHelper {
m_InitDirectory = init_dir;
}
/**
* @brief Clear file dialog parameters for following re-use.
*/
void Clear() {
m_Owner = nullptr;
m_HasTitle = m_HasInitFileName = m_HasInitDirectory = false;
@ -215,6 +227,12 @@ namespace YYCC::DialogHelper {
m_DefaultFileTypeIndex = 0u;
}
/**
* @brief Generate Windows dialog system used data struct.
* @param win_result[out] The class holding the generated filter data struct.
* @return True if generation is success, otherwise false.
* @remarks User should not call this function, this function is used in internal code.
*/
bool Generate(WinFileDialog& win_result) const;
protected: