From 31a7cb56754aaa7f64fdd66f3426d41f9c4e5aa0 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Thu, 25 Jul 2024 11:22:50 +0800 Subject: [PATCH] doc: update documentation in code --- src/COMHelper.hpp | 24 +++++-- src/DialogHelper.hpp | 159 +++++++++++++++++++++++++++++++++---------- 2 files changed, 140 insertions(+), 43 deletions(-) diff --git a/src/COMHelper.hpp b/src/COMHelper.hpp index aded88a..30420d3 100644 --- a/src/COMHelper.hpp +++ b/src/COMHelper.hpp @@ -9,11 +9,17 @@ #include #include "WinImportSuffix.hpp" +/** + * @brief Windows COM related types and checker. + * @details + * This namespace is Windows specific. + * In other platforms, this whole namespace will be unavailable. + * + * See also \ref com_helper. +*/ namespace YYCC::COMHelper { - /** - * @brief C++ standard deleter for every COM interfaces inheriting IUnknown. - */ + /// @brief C++ standard deleter for every COM interfaces inheriting IUnknown. class ComPtrDeleter { public: ComPtrDeleter() {} @@ -24,15 +30,18 @@ namespace YYCC::COMHelper { } }; + /// @brief Smart unique pointer of \c IFileDialog using SmartIFileDialog = std::unique_ptr; + /// @brief Smart unique pointer of \c IFileOpenDialog using SmartIFileOpenDialog = std::unique_ptr; + /// @brief Smart unique pointer of \c IShellItem using SmartIShellItem = std::unique_ptr; + /// @brief Smart unique pointer of \c IShellItemArray using SmartIShellItemArray = std::unique_ptr; + /// @brief Smart unique pointer of \c IShellFolder using SmartIShellFolder = std::unique_ptr; - /** - * @brief C++ standard deleter for almost raw pointer used in COM which need to be free by CoTaskMemFree() - */ + /// @brief C++ standard deleter for almost raw pointer used in COM which need to be free by CoTaskMemFree() class CoTaskMemDeleter { public: CoTaskMemDeleter() {} @@ -42,7 +51,8 @@ namespace YYCC::COMHelper { } } }; - + + /// @brief Smart unique pointer of COM created \c WCHAR sequence. using SmartLPWSTR = std::unique_ptr, CoTaskMemDeleter>; /** diff --git a/src/DialogHelper.hpp b/src/DialogHelper.hpp index 993dc79..5a5b762 100644 --- a/src/DialogHelper.hpp +++ b/src/DialogHelper.hpp @@ -12,11 +12,19 @@ #include #include "WinImportSuffix.hpp" +/** + * @brief The namespace providing Windows universal dialog features. + * @details + * This namespace only available on Windows platform. + * See also \ref dialog_helper. +*/ namespace YYCC::DialogHelper { /** - * @brief The class represent the file types region in file dialog - * @details THis class is specific for Windows use, not user oriented. + * @brief The class representing the file types region in file dialog. + * @details + * This class is served for Windows used. + * Programmer should \b not create this class manually. */ class WinFileFilters { friend class FileFilters; @@ -24,9 +32,11 @@ namespace YYCC::DialogHelper { public: WinFileFilters() : m_WinFilters(), m_WinDataStruct(nullptr) {} + /// @brief Get the count of available file filters UINT GetFilterCount() const { return static_cast(m_WinFilters.size()); } + /// @brief Get pointer to Windows used file filters declarations const COMDLG_FILTERSPEC* GetFilterSpecs() const { return m_WinDataStruct.get(); } @@ -39,6 +49,7 @@ namespace YYCC::DialogHelper { std::vector m_WinFilters; std::unique_ptr m_WinDataStruct; + /// @brief Clear all current file filters void Clear() { m_WinDataStruct.reset(); m_WinFilters.clear(); @@ -46,9 +57,12 @@ namespace YYCC::DialogHelper { }; /** - * @brief The class represent the file types region in file dialog. - * @details This class is user oriented. User can use function manipulate file types - * and final generation function will produce Windows-understood data struct from this. + * @brief The class representing the file types region in file dialog. + * @details + * This class is served for programmer using. + * But you don't need create it on your own. + * You can simply fetch it by FileDialog::ConfigreFileTypes , + * because this class is a part of FileDialog. */ class FileFilters { public: @@ -56,31 +70,34 @@ namespace YYCC::DialogHelper { /** * @brief Add a filter pair in file types list. - * @param filter_name[in] The friendly name of the filter. - * @param il[in] A C++ initialize list. - * Every entries must be `const yycc_char8_t*` represent a single filter pattern. + * @param[in] filter_name The friendly name of the filter. + * @param[in] il + * A C++ initialize list containing acceptable file filter pattern. + * Every entries must be `const yycc_char8_t*` representing a single filter pattern. * The list at least should have one valid pattern. * This function will not validate these filter patterns, so please write them carefully. * @return True if added success, otherwise false. - * @remarks This function allow you register multiple filter patterns for single friendly name. - * For example: `Add("Microsoft Word (*.doc; *.docx)", {"*.doc", "*.docx"})` + * @remarks + * This function allow you register multiple filter patterns for single friendly name. + * For example: Add(u8"Microsoft Word (*.doc; *.docx)", {u8"*.doc", u8"*.docx"}) */ bool Add(const yycc_char8_t* filter_name, std::initializer_list il); - /** - * @brief Clear filter pairs for following re-use. - */ - void Clear() { m_Filters.clear(); } /** * @brief Get the count of added filter pairs. * @return The count of already added filter pairs. */ size_t Count() const { return m_Filters.size(); } + /// @brief Clear filter pairs for following re-use. + void Clear() { m_Filters.clear(); } + /** * @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. + * @param[out] win_result The class receiving the generated filter data struct. + * @return True if generation success, otherwise false. + * @remarks + * Programmer should not call this function, + * this function is used as YYCC internal code. */ bool Generate(WinFileFilters& win_result) const; @@ -93,8 +110,10 @@ namespace YYCC::DialogHelper { }; /** - * @brief The class represent the file dialog - * @details THis class is specific for Windows use, not user oriented. + * @brief The class representing the file dialog. + * @details + * This class is served for Windows used. + * Programmer should \b not create this class manually. */ class WinFileDialog { friend class FileDialog; @@ -105,18 +124,28 @@ namespace YYCC::DialogHelper { m_HasTitle(false), m_HasInitFileName(false), m_WinTitle(), m_WinInitFileName(), m_WinInitDirectory(nullptr) {} + /// @brief Get whether this dialog has owner. bool HasOwner() const { return m_WinOwner != NULL; } + /// @brief Get the \c HWND of dialog owner. HWND GetOwner() const { return m_WinOwner; } - + + /// @brief Get the struct holding Windows used file filters data. const WinFileFilters& GetFileTypes() const { return m_WinFileTypes; } + /// @brief Get the index of default selected file filter. UINT GetDefaultFileTypeIndex() const { return m_WinDefaultFileTypeIndex; } - + + /// @brief Get whether dialog has custom title. bool HasTitle() const { return m_HasTitle; } + /// @brief Get custom title of dialog. const wchar_t* GetTitle() const { return m_WinTitle.c_str(); } + /// @brief Get whether dialog has custom initial file name. bool HasInitFileName() const { return m_HasInitFileName; } + /// @brief Get custom initial file name of dialog const wchar_t* GetInitFileName() const { return m_WinInitFileName.c_str(); } - + + /// @brief Get whether dialog has custom initial directory. bool HasInitDirectory() const { return m_WinInitDirectory.get() != nullptr; } + /// @brief Get custom initial directory of dialog. IShellItem* GetInitDirectory() const { return m_WinInitDirectory.get(); } protected: @@ -124,15 +153,17 @@ namespace YYCC::DialogHelper { WinFileFilters m_WinFileTypes; /** * @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. + * @remarks + * This is 1-based index according to Windows specification. + * In other words, when generating this struct from FileDialog to this struct this field should plus 1. + * Because the same field located in FileDialog is 0-based index. */ UINT m_WinDefaultFileTypeIndex; bool m_HasTitle, m_HasInitFileName; std::wstring m_WinTitle, m_WinInitFileName; COMHelper::SmartIShellItem m_WinInitDirectory; - + + /// @brief Clear all data and reset them to default value. void Clear() { m_WinOwner = nullptr; m_WinFileTypes.Clear(); @@ -146,8 +177,9 @@ namespace YYCC::DialogHelper { /** * @brief The class represent the file dialog. - * @details This class is user oriented. User can use function manipulate file dialog properties - * and final generation function will produce Windows-understood data struct from this. + * @details + * This class is served for programming using to describe every aspectes of the dialog. + * For how to use this struct, see \ref dialog_helper. */ class FileDialog { public: @@ -158,27 +190,55 @@ namespace YYCC::DialogHelper { m_Title(), m_InitFileName(), m_InitDirectory(), m_HasTitle(false), m_HasInitFileName(false), m_HasInitDirectory(false) {} + /** + * @brief Set the owner of dialog. + * @param[in] owner The \c HWND pointing to the owner of dialog, or NULL to remove owner. + */ void SetOwner(HWND owner) { m_Owner = owner; } + /** + * @brief Set custom title of dialog + * @param[in] title The string pointer to custom title, or nullptr to remove it. + */ void SetTitle(const yycc_char8_t* title) { if (m_HasTitle = title != nullptr) m_Title = title; } + /** + * @brief Fetch the struct describing file filters for future configuration. + * @return The reference to the struct describing file filters. + */ FileFilters& ConfigreFileTypes() { return m_FileTypes; } + /** + * @brief Set the index of default selected file filter. + * @param[in] idx + * The index to default one. + * This must be a valid index in file filters. + */ void SetDefaultFileTypeIndex(size_t idx) { m_DefaultFileTypeIndex = idx; } + /** + * @brief Set the initial file name of dialog + * @details If set, the file name will always be same one when opening dialog. + * @param[in] init_filename String pointer to initial file name, or nullptr to remove it. + */ void SetInitFileName(const yycc_char8_t* init_filename) { if (m_HasInitFileName = init_filename != nullptr) m_InitFileName = init_filename; } + /** + * @brief Set the initial directory of dialog + * @details If set, the opended directory will always be the same one when opening dialog + * @param[in] init_dir + * String pointer to initial directory. + * Invalid path or nullptr will remove this feature. + */ void SetInitDirectory(const yycc_char8_t* init_dir) { if (m_HasInitDirectory = init_dir != nullptr) m_InitDirectory = init_dir; } - /** - * @brief Clear file dialog parameters for following re-use. - */ + /// @brief Clear file dialog parameters for following re-use. void Clear() { m_Owner = nullptr; m_HasTitle = m_HasInitFileName = m_HasInitDirectory = false; @@ -191,9 +251,11 @@ namespace YYCC::DialogHelper { /** * @brief Generate Windows dialog system used data struct. - * @param win_result[out] The class holding the generated filter data struct. + * @param[out] win_result The class receiving 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. + * @remarks + * Programmer should not call this function. + * This function is used as YYCC internal code. */ bool Generate(WinFileDialog& win_result) const; @@ -204,16 +266,41 @@ namespace YYCC::DialogHelper { FileFilters m_FileTypes; /** * @brief The default selected file type in dialog - * @remarks Although Windows notice that this is a 1-based index, - * but for universal experience, we order this is 0-based index. + * @remarks + * The index Windows used is 1-based index. + * But for universal experience, we order this is 0-based index. + * And do convertion when generating Windows used struct. */ size_t m_DefaultFileTypeIndex; }; + /** + * @brief Open the dialog which order user select single file to open. + * @param[in] params The configuration of dialog. + * @param[out] ret Full path to user selected file. + * @return False if user calcel the operation or something went wrong, otherwise true. + */ bool OpenFileDialog(const FileDialog& params, yycc_u8string& ret); + /** + * @brief Open the dialog which order user select multiple file to open. + * @param[in] params The configuration of dialog. + * @param[out] ret The list of full path of user selected files. + * @return False if user calcel the operation or something went wrong, otherwise true. + */ bool OpenMultipleFileDialog(const FileDialog& params, std::vector& ret); + /** + * @brief Open the dialog which order user select single file to save. + * @param[in] params The configuration of dialog. + * @param[out] ret Full path to user selected file. + * @return False if user calcel the operation or something went wrong, otherwise true. + */ bool SaveFileDialog(const FileDialog& params, yycc_u8string& ret); - + /** + * @brief Open the dialog which order user select single directory to open. + * @param[in] params The configuration of dialog. + * @param[out] ret Full path to user selected directory. + * @return False if user calcel the operation or something went wrong, otherwise true. + */ bool OpenFolderDialog(const FileDialog& params, yycc_u8string& ret); }