Update ui & utils

projects/kiwano/kiwano.vcxproj

@@ -15,7 +15,6 @@
     <ClInclude Include="..\..\src\kiwano\core\Event.h" />
     <ClInclude Include="..\..\src\kiwano\core\Library.h" />
     <ClInclude Include="..\..\src\kiwano\core\win32\ComPtr.hpp" />
-    <ClInclude Include="..\..\src\kiwano\core\win32\helper.h" />
     <ClInclude Include="..\..\src\kiwano\kiwano.h" />
     <ClInclude Include="..\..\src\kiwano\config.h" />
     <ClInclude Include="..\..\src\kiwano\macros.h" />

projects/kiwano/kiwano.vcxproj.filters

@@ -225,9 +225,6 @@
     <ClInclude Include="..\..\src\kiwano\core\win32\ComPtr.hpp">
       <Filter>core\win32</Filter>
     </ClInclude>
-    <ClInclude Include="..\..\src\kiwano\core\win32\helper.h">
-      <Filter>core\win32</Filter>
-    </ClInclude>
     <ClInclude Include="..\..\src\kiwano\utils\LocalStorage.h">
       <Filter>utils</Filter>
     </ClInclude>

src/kiwano-audio/AudioEngine.cpp

@@ -18,7 +18,6 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-#include <kiwano/core/win32/helper.h>
 #include <kiwano-audio/audio-modules.h>
 #include <kiwano-audio/AudioEngine.h>
 
@@ -52,7 +51,7 @@ namespace kiwano
 				hr = x_audio2_->CreateMasteringVoice(&mastering_voice_);
 			}
 
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 
 		void AudioEngine::DestroyComponent()

src/kiwano-imgui/imgui_impl_dx11.cpp

@@ -1,6 +1,6 @@
 // dear imgui: Renderer for Kiwano (DirectX11)
 
-#include <kiwano/core/win32/helper.h>
+#include <kiwano/renderer/win32/helper.h>
 #include <kiwano-imgui/imgui_impl_dx11.h>
 
 // DirectX
@@ -259,7 +259,7 @@ static void ImGui_ImplDX11_CreateFontsTexture()
         subResource.pSysMem = pixels;
         subResource.SysMemPitch = desc.Width * 4;
         subResource.SysMemSlicePitch = 0;
-        kiwano::ThrowIfFailed(
+        kiwano::DX::ThrowIfFailed(
             g_pd3dDevice->CreateTexture2D(&desc, &subResource, &pTexture)
         );
 
@@ -272,7 +272,7 @@ static void ImGui_ImplDX11_CreateFontsTexture()
             srvDesc.ViewDimension = D3D11_SRV_DIMENSION_TEXTURE2D;
             srvDesc.Texture2D.MipLevels = desc.MipLevels;
             srvDesc.Texture2D.MostDetailedMip = 0;
-            kiwano::ThrowIfFailed(
+            kiwano::DX::ThrowIfFailed(
                 g_pd3dDevice->CreateShaderResourceView(pTexture, &srvDesc, &g_pFontTextureView)
             );
 

src/kiwano/2d/FrameSequence.cpp

@@ -69,6 +69,11 @@ namespace kiwano
 		return frames_;
 	}
 
+	size_t FrameSequence::GetFramesCount() const
+	{
+		return frames_.size();
+	}
+
 	FrameSequencePtr FrameSequence::Clone() const
 	{
 		auto frame_seq = new (std::nothrow) FrameSequence;

src/kiwano/2d/FrameSequence.h

@@ -65,6 +65,10 @@ namespace kiwano
 		/// @brief 获取所有关键帧
 		Vector<FramePtr> const& GetFrames() const;
 
+		/// \~chinese
+		/// @brief 获取关键帧数量
+		size_t GetFramesCount() const;
+
 		/// \~chinese
 		/// @brief 获取序列帧的拷贝对象
 		FrameSequencePtr Clone() const;

src/kiwano/2d/GifSprite.cpp

@@ -19,7 +19,6 @@
 // THE SOFTWARE.
 
 #include <kiwano/2d/GifSprite.h>
-#include <kiwano/core/win32/helper.h>
 #include <kiwano/renderer/TextureCache.h>
 #include <kiwano/renderer/Renderer.h>
 
@@ -149,7 +148,7 @@ namespace kiwano
 		}
 
 		default:
-			ThrowIfFailed(E_FAIL);
+			DX::ThrowIfFailed(E_FAIL);
 		}
 	}
 
@@ -227,7 +226,7 @@ namespace kiwano
 			saved_frame_->CopyFrom(frame_to_be_saved);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void GifSprite::RestoreSavedFrame()
@@ -247,7 +246,7 @@ namespace kiwano
 			}
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void GifSprite::ClearCurrentFrameArea()

src/kiwano/core/win32/helper.h

@@ -1,38 +0,0 @@
-// Copyright (c) 2018-2019 Kiwano - Nomango
-// 
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-// 
-// The above copyright notice and this permission notice shall be included in
-// all copies or substantial portions of the Software.
-// 
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-// THE SOFTWARE.
-
-#include <stdexcept>
-#include <kiwano/macros.h>
-#include <3rd-party/StackWalker/StackWalker.h>
-
-namespace kiwano
-{
-	inline void ThrowIfFailed(HRESULT hr)
-	{
-		if (FAILED(hr))
-		{
-			StackWalker{}.ShowCallstack();
-
-			static char buffer[1024 + 1];
-			sprintf_s(buffer, "Failed with HRESULT of %08X", hr);
-			throw std::runtime_error(buffer);
-		}
-	}
-}

src/kiwano/platform/Application.cpp

@@ -23,7 +23,6 @@
 #include <kiwano/platform/Application.h>
 #include <kiwano/platform/modules.h>
 #include <kiwano/core/Logger.h>
-#include <kiwano/core/win32/helper.h>
 #include <kiwano/platform/Input.h>
 #include <kiwano/platform/Director.h>
 #include <kiwano/renderer/TextureCache.h>
@@ -68,7 +67,7 @@ namespace kiwano
 		, inited_(false)
 		, time_scale_(1.f)
 	{
-		ThrowIfFailed(::CoInitialize(nullptr));
+		DX::ThrowIfFailed(::CoInitialize(nullptr));
 
 		Use(&Renderer::instance());
 		Use(&Input::instance());

src/kiwano/platform/Window.cpp

@@ -19,7 +19,6 @@
 // THE SOFTWARE.
 
 #include <kiwano/platform/Window.h>
-#include <kiwano/core/win32/helper.h>
 #include <kiwano/core/Logger.h>
 #include <kiwano/platform/Application.h>
 
@@ -161,7 +160,7 @@ namespace kiwano
 		if (handle_ == nullptr)
 		{
 			::UnregisterClass(KGE_WND_CLASS_NAME, hinst);
-			ThrowIfFailed(HRESULT_FROM_WIN32(GetLastError()));
+			DX::ThrowIfFailed(HRESULT_FROM_WIN32(GetLastError()));
 		}
 		else
 		{

src/kiwano/renderer/Font.cpp

@@ -27,21 +27,21 @@ namespace kiwano
 	{
 	}
 
-	bool Font::Load(String const& font_file)
+	bool Font::Load(String const& file)
 	{
-		return Load(Vector<String>{ font_file });
+		return Load(Vector<String>{ file });
 	}
 
-	bool Font::Load(Resource const& font_resource)
+	bool Font::Load(Resource const& resource)
 	{
-		return Load(Vector<Resource>{ font_resource });
+		return Load(Vector<Resource>{ resource });
 	}
 
-	bool Font::Load(Vector<String> const& font_file)
+	bool Font::Load(Vector<String> const& files)
 	{
 		try
 		{
-			Renderer::instance().CreateFontCollection(*this, font_file);
+			Renderer::instance().CreateFontCollection(*this, files);
 		}
 		catch (std::runtime_error&)
 		{
@@ -50,11 +50,11 @@ namespace kiwano
 		return true;
 	}
 
-	bool Font::Load(Vector<Resource> const& font_resource)
+	bool Font::Load(Vector<Resource> const& resources)
 	{
 		try
 		{
-			Renderer::instance().CreateFontCollection(*this, font_resource);
+			Renderer::instance().CreateFontCollection(*this, resources);
 		}
 		catch (std::runtime_error&)
 		{

src/kiwano/renderer/Font.h

@@ -44,19 +44,19 @@ namespace kiwano
 
 		/// \~chinese
 		/// @brief 加载字体文件
-		bool Load(String const& font_file);
+		bool Load(String const& file);
 
 		/// \~chinese
 		/// @brief 加载字体资源
-		bool Load(Resource const& font_resource);
+		bool Load(Resource const& resource);
 
 		/// \~chinese
 		/// @brief 加载多个字体文件
-		bool Load(Vector<String> const& font_file);
+		bool Load(Vector<String> const& files);
 
 		/// \~chinese
 		/// @brief 加载多个字体资源
-		bool Load(Vector<Resource> const& font_resource);
+		bool Load(Vector<Resource> const& resources);
 
 	private:
 		ComPtr<IDWriteFontCollection> GetCollection() const;

src/kiwano/renderer/Geometry.cpp

@@ -21,7 +21,6 @@
 #include <kiwano/renderer/Geometry.h>
 #include <kiwano/renderer/GeometrySink.h>
 #include <kiwano/renderer/Renderer.h>
-#include <kiwano/core/win32/helper.h>
 
 namespace kiwano
 {

src/kiwano/renderer/GeometrySink.cpp

@@ -20,7 +20,6 @@
 
 #include <kiwano/renderer/GeometrySink.h>
 #include <kiwano/renderer/Renderer.h>
-#include <kiwano/core/win32/helper.h>
 
 namespace kiwano
 {
@@ -41,7 +40,7 @@ namespace kiwano
 			path_geo_.reset();
 			Renderer::instance().CreateGeometrySink(*this);
 
-			ThrowIfFailed(path_geo_->Open(&sink_));
+			DX::ThrowIfFailed(path_geo_->Open(&sink_));
 		}
 	}
 
@@ -49,7 +48,7 @@ namespace kiwano
 	{
 		if (IsOpened())
 		{
-			ThrowIfFailed(sink_->Close());
+			DX::ThrowIfFailed(sink_->Close());
 			sink_.reset();
 		}
 	}
@@ -76,7 +75,7 @@ namespace kiwano
 		}
 
 		ComPtr<ID2D1Geometry> geo = input.geo_;
-		ThrowIfFailed(
+		DX::ThrowIfFailed(
 			geo->Outline(
 				DX::ConvertToMatrix3x2F(input_matrix),
 				D2D1_DEFAULT_FLATTENING_TOLERANCE,
@@ -165,7 +164,7 @@ namespace kiwano
 
 		ComPtr<ID2D1Geometry> geo_a_raw = geo_a.geo_;
 		ComPtr<ID2D1Geometry> geo_b_raw = geo_b.geo_;
-		ThrowIfFailed(
+		DX::ThrowIfFailed(
 			geo_a_raw->CombineWithGeometry(
 				geo_b_raw.get(),
 				D2D1_COMBINE_MODE(mode),

src/kiwano/renderer/RenderTarget.cpp

@@ -19,7 +19,6 @@
 // THE SOFTWARE.
 
 #include <kiwano/renderer/RenderTarget.h>
-#include <kiwano/core/win32/helper.h>
 #include <kiwano/core/Logger.h>
 
 namespace kiwano
@@ -133,7 +132,7 @@ namespace kiwano
 
 	void RenderTarget::EndDraw()
 	{
-		ThrowIfFailed( render_target_->EndDraw() );
+		DX::ThrowIfFailed( render_target_->EndDraw() );
 
 		if (collecting_status_)
 		{
@@ -378,7 +377,7 @@ namespace kiwano
 		}
 		else
 		{
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 	}
 
@@ -411,7 +410,7 @@ namespace kiwano
 			}
 			else
 			{
-				ThrowIfFailed(hr);
+				DX::ThrowIfFailed(hr);
 			}
 		}
 
@@ -540,9 +539,9 @@ namespace kiwano
 		visible_size_ = Rect(Point(), size);
 	}
 
-	void RenderTarget::SetCollectingStatus(bool collecting)
+	void RenderTarget::SetCollectingStatus(bool enable)
 	{
-		collecting_status_ = collecting;
+		collecting_status_ = enable;
 	}
 
 	void RenderTarget::IncreasePrimitivesCount(uint32_t increase) const

src/kiwano/renderer/RenderTarget.h

@@ -271,7 +271,7 @@ namespace kiwano
 
 		/// \~chinese
 		/// @brief 启用或禁用状态收集功能
-		void SetCollectingStatus(bool collecting);
+		void SetCollectingStatus(bool enable);
 
 		/// \~chinese
 		/// @brief 获取渲染目标状态

src/kiwano/renderer/Renderer.cpp

@@ -21,7 +21,6 @@
 #include <kiwano/renderer/Renderer.h>
 #include <kiwano/renderer/GeometrySink.h>
 #include <kiwano/core/Logger.h>
-#include <kiwano/core/win32/helper.h>
 #include <kiwano/platform/Window.h>
 #include <kiwano/platform/FileSystem.h>
 
@@ -119,7 +118,7 @@ namespace kiwano
 			}
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::DestroyComponent()
@@ -151,7 +150,7 @@ namespace kiwano
 			BeginDraw();
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::AfterRender()
@@ -169,7 +168,7 @@ namespace kiwano
 			hr = HandleDeviceLost();
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::HandleMessage(HWND hwnd, UINT32 msg, WPARAM wparam, LPARAM lparam)
@@ -597,7 +596,7 @@ namespace kiwano
 			}
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateFontCollection(Font& font, Vector<Resource> const& res_arr)
@@ -632,7 +631,7 @@ namespace kiwano
 			}
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateTextFormat(TextLayout& layout)
@@ -664,7 +663,7 @@ namespace kiwano
 			layout.SetTextFormat(output);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateTextLayout(TextLayout& layout)
@@ -690,7 +689,7 @@ namespace kiwano
 			layout.SetTextLayout(output);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateLineGeometry(Geometry& geo, Point const& begin_pos, Point const& end_pos)
@@ -726,7 +725,7 @@ namespace kiwano
 			geo.SetGeometry(path_geo);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateRectGeometry(Geometry& geo, Rect const& rect)
@@ -748,7 +747,7 @@ namespace kiwano
 			geo.SetGeometry(output);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateRoundedRectGeometry(Geometry& geo, Rect const& rect, Vec2 const& radius)
@@ -776,7 +775,7 @@ namespace kiwano
 			geo.SetGeometry(output);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateEllipseGeometry(Geometry& geo, Point const& center, Vec2 const& radius)
@@ -804,7 +803,7 @@ namespace kiwano
 			geo.SetGeometry(output);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateGeometrySink(GeometrySink& sink)
@@ -826,7 +825,7 @@ namespace kiwano
 			sink.SetPathGeometry(output);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateTextureRenderTarget(TextureRenderTargetPtr& render_target)
@@ -860,7 +859,7 @@ namespace kiwano
 			render_target = output;
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateSolidBrush(Brush& brush, Color const& color)
@@ -882,7 +881,7 @@ namespace kiwano
 			brush.SetBrush(output, Brush::Type::SolidColor);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateLinearGradientBrush(Brush& brush, Point const& begin, Point const& end, Vector<GradientStop> const& stops, GradientExtendMode extend_mode)
@@ -923,7 +922,7 @@ namespace kiwano
 			}
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::CreateRadialGradientBrush(Brush& brush, Point const& center, Vec2 const& offset, Vec2 const& radius,
@@ -967,7 +966,7 @@ namespace kiwano
 			}
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::SetDpi(float dpi)
@@ -980,7 +979,7 @@ namespace kiwano
 			hr = d2d_res_->SetDpi(dpi);
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void Renderer::SetVSyncEnabled(bool enabled)
@@ -1017,7 +1016,7 @@ namespace kiwano
 			Resize(reinterpret_cast<const Size&>(GetRenderTarget()->GetSize()));
 		}
 
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 }

src/kiwano/renderer/TextLayout.cpp

@@ -20,7 +20,6 @@
 
 #include <kiwano/renderer/TextLayout.h>
 #include <kiwano/renderer/Renderer.h>
-#include <kiwano/core/win32/helper.h>
 
 namespace kiwano
 {
@@ -182,7 +181,7 @@ namespace kiwano
 					}
 				}
 			}
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 	}
 
@@ -201,7 +200,7 @@ namespace kiwano
 			{
 				hr = text_layout_->SetLineSpacing(DWRITE_LINE_SPACING_METHOD_UNIFORM, line_spacing, line_spacing * 0.8f);
 			}
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 	}
 
@@ -212,7 +211,7 @@ namespace kiwano
 		if (text_layout_)
 		{
 			HRESULT hr = text_layout_->SetTextAlignment(DWRITE_TEXT_ALIGNMENT(align));
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 	}
 
@@ -227,7 +226,7 @@ namespace kiwano
 		{
 			hr = text_layout_->SetUnderline(enable, { start, length });
 		}
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 	void TextLayout::SetStrikethrough(bool enable, uint32_t start, uint32_t length)
@@ -241,7 +240,7 @@ namespace kiwano
 		{
 			hr = text_layout_->SetStrikethrough(enable, { start, length });
 		}
-		ThrowIfFailed(hr);
+		DX::ThrowIfFailed(hr);
 	}
 
 }

src/kiwano/renderer/Texture.cpp

@@ -20,7 +20,6 @@
 
 #include <kiwano/renderer/Texture.h>
 #include <kiwano/renderer/Renderer.h>
-#include <kiwano/core/win32/helper.h>
 
 namespace kiwano
 {
@@ -119,7 +118,7 @@ namespace kiwano
 		{
 			HRESULT hr = bitmap_->CopyFromBitmap(nullptr, copy_from->GetBitmap().get(), nullptr);
 
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 	}
 
@@ -137,7 +136,7 @@ namespace kiwano
 					uint32_t(src_rect.GetBottom()))
 			);
 
-			ThrowIfFailed(hr);
+			DX::ThrowIfFailed(hr);
 		}
 	}
 

src/kiwano/renderer/win32/D3D10DeviceResources.cpp

@@ -19,7 +19,6 @@
 // THE SOFTWARE.
 
 #include <kiwano/renderer/win32/D3D10DeviceResources.h>
-
 #include <kiwano/core/Logger.h>
 
 #pragma comment(lib, "d3d10_1.lib")

src/kiwano/renderer/win32/helper.h

@@ -19,9 +19,11 @@
 // THE SOFTWARE.
 
 #pragma once
+#include <stdexcept>
 #include <kiwano/math/math.h>
 #include <kiwano/core/win32/ComPtr.hpp>
 #include <kiwano/renderer/Color.h>
+#include <3rd-party/StackWalker/StackWalker.h>
 #include <d2d1.h>
 
 namespace kiwano
@@ -173,5 +175,17 @@ namespace kiwano
 			static const float dips_per_inch = 96.0f;
 			return math::Floor(dips * dpi / dips_per_inch + 0.5f); // Round to nearest integer.
 		}
+
+		inline void ThrowIfFailed(HRESULT hr)
+		{
+			if (FAILED(hr))
+			{
+				StackWalker().ShowCallstack();
+
+				static char buffer[1024 + 1];
+				sprintf_s(buffer, "Failed with HRESULT of %08X", hr);
+				throw std::runtime_error(buffer);
+			}
+		}
 	}
 }

src/kiwano/ui/Button.h

@@ -25,66 +25,67 @@ namespace kiwano
 {
 	KGE_DECLARE_SMART_PTR(Button);
 
+	/**
+	* \~chinese
+	* @brief 按钮
+	*/
 	class KGE_API Button
 		: public Sprite
 	{
 	public:
-		using Callback = Function<void()>;
+		/// \~chinese
+		/// @brief 按钮回调函数
+		using Callback = Function<void(Button* /* self */)>;
 
 		Button();
 
-		explicit Button(
+		/// \~chinese
-			Callback const& click		/* 按钮点击回调函数 */
+		/// @brief 构造按钮
-		);
+		/// @param click 按钮点击回调函数
+		explicit Button(Callback const& click);
 
-		Button(
+		/// \~chinese
-			Callback const& click,		/* 按钮点击回调函数 */
+		/// @brief 获取按钮状态是启用还是禁用
-			Callback const& pressed,	/* 按钮按下回调函数 */
+		/// @param click 按钮点击回调函数
-			Callback const& mouse_over,	/* 按钮移入回调函数 */
+		/// @param pressed 按钮按下回调函数
-			Callback const& mouse_out	/* 按钮移出回调函数 */
+		/// @param mouse_over 按钮移入回调函数
-		);
+		/// @param mouse_out 按钮移出回调函数
+		Button(Callback const& click, Callback const& pressed, Callback const& mouse_over, Callback const& mouse_out);
 
 		virtual ~Button();
 
-		// 获取按钮状态是启用还是禁用
+		/// \~chinese
+		/// @brief 获取按钮状态是启用还是禁用
 		bool IsEnable() const;
 
-		// 设置按钮启用或禁用
+		/// \~chinese
-		void SetEnabled(
+		/// @brief 设置按钮启用或禁用
-			bool enabled
+		void SetEnabled(bool enabled);
-		);
 
-		// 设置按钮点击后的回调函数
+		/// \~chinese
-		void SetClickCallback(
+		/// @brief 设置按钮点击后的回调函数
-			const Callback& func
+		void SetClickCallback(const Callback& func);
-		);
 
-		// 设置按钮被按下时的回调函数
+		/// \~chinese
-		void SetPressedCallback(
+		/// @brief 设置按钮被按下时的回调函数
-			const Callback& func
+		void SetPressedCallback(const Callback& func);
-		);
 
-		// 设置按钮被抬起时的回调函数
+		/// \~chinese
-		void SetReleasedCallback(
+		/// @brief 设置按钮被抬起时的回调函数
-			const Callback& func
+		void SetReleasedCallback(const Callback& func);
-		);
 
-		// 设置鼠标移入按钮时的回调函数
+		/// \~chinese
-		void SetMouseOverCallback(
+		/// @brief 设置鼠标移入按钮时的回调函数
-			const Callback& func
+		void SetMouseOverCallback(const Callback& func);
-		);
 
-		// 设置鼠标移出按钮时的回调函数
+		/// \~chinese
-		void SetMouseOutCallback(
+		/// @brief 设置鼠标移出按钮时的回调函数
-			const Callback& func
+		void SetMouseOutCallback(const Callback& func);
-		);
 
 	private:
 		enum class Status { Normal, Hover, Pressed };
 
-		void SetStatus(
+		void SetStatus(Status status);
-			Status status
-		);
 
 		void UpdateStatus(Event& evt);
 

src/kiwano/ui/Menu.cpp

@@ -27,15 +27,6 @@ namespace kiwano
 	{
 	}
 
-	Menu::Menu(Vector<ButtonPtr> const& buttons)
-		: enabled_(true)
-	{
-		for (const auto& button : buttons)
-		{
-			this->AddButton(button);
-		}
-	}
-
 	bool Menu::IsEnable() const
 	{
 		return enabled_;

src/kiwano/ui/Menu.h

@@ -25,39 +25,38 @@ namespace kiwano
 {
 	KGE_DECLARE_SMART_PTR(Menu);
 
-	// 菜单
+	/**
+	* \~chinese
+	* @brief 菜单，用于管理多个按钮
+	*/
 	class KGE_API Menu
 		: public Actor
 	{
 	public:
 		Menu();
 
-		explicit Menu(
+		/// \~chinese
-			Vector<ButtonPtr> const& buttons	/* 按钮数组 */
+		/// @brief 获取菜单是否禁用
-		);
-
-		// 获取菜单是否禁用
 		bool IsEnable() const;
 
-		// 获取菜单中的按钮数量
+		/// \~chinese
+		/// @brief 获取菜单中的按钮数量
 		size_t GetButtonCount() const;
 
-		// 设置菜单启用或禁用
+		/// \~chinese
-		void SetEnabled(
+		/// @brief 设置菜单启用或禁用
-			bool enabled
+		void SetEnabled(bool enabled);
-		);
 
-		// 添加按钮
+		/// \~chinese
-		void AddButton(
+		/// @brief 添加按钮
-			ButtonPtr button
+		void AddButton(ButtonPtr button);
-		);
 
-		// 移除按钮
+		/// \~chinese
-		bool RemoveButton(
+		/// @brief 移除按钮
-			ButtonPtr button
+		bool RemoveButton(ButtonPtr button);
-		);
 
-		// 获取所有按钮
+		/// \~chinese
+		/// @brief 获取所有按钮
 		Vector<ButtonPtr> const& GetAllButtons() const;
 
 	private:

src/kiwano/utils/LocalStorage.cpp

@@ -28,16 +28,6 @@ namespace kiwano
 		SetFieldName(field);
 	}
 
-	void LocalStorage::SetFilePath(String const & file_path)
-	{
-		file_path_ = file_path;
-	}
-
-	void LocalStorage::SetFieldName(String const & field_name)
-	{
-		field_name_ = field_name;
-	}
-
 	bool LocalStorage::Exists(String const& key) const
 	{
 		wchar_t temp[256] = { 0 };

src/kiwano/utils/LocalStorage.h

@@ -24,107 +24,137 @@
 
 namespace kiwano
 {
-	//
+	/// \~chinese
-	// 本地数据存取工具
+	/// @brief 本地存储
-	// LocalStorage 用于在本地存取数据, 支持的数据类型包括 (bool | int | float | double | String)
+	/// @details LocalStorage是一个简易的持久化工具，存放（字符串-值）的键值对
-	// 数据都采用 key-value (键-值) 的方式存取
+	/// 支持的数据类型包括 (bool | int | float | double | String)
-	// 例如, 保存一份游戏最高分, 以便下次进行游戏时读取:
+	/// 例如, 保存游戏最高分, 以便下次进行游戏时读取:
-	// LocalStorage data;                      // 创建数据对象
+	///   @code
-	// data.SaveInt(L"best-score", 20);        // 保存最高分 20
+	///     LocalStorage data;                      // 创建数据对象
-	// int best = data.GetInt(L"best-score");  // 读取之前储存的最高分
+	///     data.SaveInt(L"best-score", 20);        // 保存最高分 20
-	//
+	///     int best = data.GetInt(L"best-score");  // 读取之前储存的最高分
-
+	///   @endcode
 	class KGE_API LocalStorage
 	{
 	public:
-		LocalStorage(
+		/// \~chinese
-			String const& file_path = L"./data.ini",	// 文件路径
+		/// @brief 构建本地存储对象
-			String const& field = L"defalut"			// 字段名
+		/// @param file_path 文件储存路径
-		);
+		/// @param field 字段名
+		LocalStorage(String const& file_path = L"data.ini", String const& field = L"defalut");
 
-		// 获取数据存放路径
+		/// \~chinese
-		inline String const& GetFilePath() const { return file_path_; }
+		/// @brief 获取文件储存路径
+		String const& GetFilePath() const;
 
-		// 设置数据存放路径
+		/// \~chinese
-		void SetFilePath(
+		/// @brief 设置文件储存路径
-			String const& file_path
+		void SetFilePath(String const& file_path);
-		);
 
-		// 获取字段名
+		/// \~chinese
-		inline String const& GetFieldName() const { return field_name_; }
+		/// @brief 获取字段名
+		String const& GetFieldName() const;
 
-		// 设置字段名
+		/// \~chinese
-		void SetFieldName(
+		/// @brief 设置字段名
-			String const& field
+		void SetFieldName(String const& field);
-		);
 
-		// 判断数据是否存在
+		/// \~chinese
-		bool Exists(
+		/// @brief 判断键对应的数据是否存在
-			String const& key
+		bool Exists(String const& key) const;
-		) const;
 
-		// 保存 int 类型的值
+		/// \~chinese
-		bool SaveInt(
+		/// @brief 保存 int 类型的值
-			String const& key,
+		/// @param key 键
-			int val
+		/// @param val 值
-		) const;
+		/// @return 操作是否成功
+		bool SaveInt(String const& key, int val) const;
 
-		// 保存 float 类型的值
+		/// \~chinese
-		bool SaveFloat(
+		/// @brief 保存 float 类型的值
-			String const& key,
+		/// @param key 键
-			float val
+		/// @param val 值
-		) const;
+		/// @return 操作是否成功
+		bool SaveFloat(String const& key, float val) const;
 
-		// 保存 double 类型的值
+		/// \~chinese
-		bool SaveDouble(
+		/// @brief 保存 double 类型的值
-			String const& key,
+		/// @param key 键
-			double val
+		/// @param val 值
-		) const;
+		/// @return 操作是否成功
+		bool SaveDouble(String const& key, double val) const;
 
-		// 保存 bool 类型的值
+		/// \~chinese
-		bool SaveBool(
+		/// @brief 保存 bool 类型的值
-			String const& key,
+		/// @param key 键
-			bool val
+		/// @param val 值
-		) const;
+		/// @return 操作是否成功
+		bool SaveBool(String const& key, bool val) const;
 
-		// 保存 String 类型的值
+		/// \~chinese
-		bool SaveString(
+		/// @brief 保存 String 类型的值
-			String const& key,
+		/// @param key 键
-			String const& val
+		/// @param val 值
-		) const;
+		/// @return 操作是否成功
+		bool SaveString(String const& key, String const& val) const;
 
-		// 获取 int 类型的值
+		/// \~chinese
-		int GetInt(
+		/// @brief 获取 int 类型的值
-			String const& key,
+		/// @param key 键
-			int default_value = 0
+		/// @param default_value 值不存在时返回的默认值
-		) const;
+		/// @return 值
+		int GetInt(String const& key, int default_value = 0) const;
 
-		// 获取 float 类型的值
+		/// \~chinese
-		float GetFloat(
+		/// @brief 获取 float 类型的值
-			String const& key,
+		/// @param key 键
-			float default_value = 0.0f
+		/// @param default_value 值不存在时返回的默认值
-		) const;
+		/// @return 值
+		float GetFloat(String const& key, float default_value = 0.0f) const;
 
-		// 获取 double 类型的值
+		/// \~chinese
-		double GetDouble(
+		/// @brief 获取 double 类型的值
-			String const& key,
+		/// @param key 键
-			double default_value = 0.0
+		/// @param default_value 值不存在时返回的默认值
-		) const;
+		/// @return 值
+		double GetDouble(String const& key, double default_value = 0.0) const;
 
-		// 获取 bool 类型的值
+		/// \~chinese
-		bool GetBool(
+		/// @brief 获取 bool 类型的值
-			String const& key,
+		/// @param key 键
-			bool default_value = false
+		/// @param default_value 值不存在时返回的默认值
-		) const;
+		/// @return 值
+		bool GetBool(String const& key, bool default_value = false) const;
 
-		// 获取 字符串 类型的值
+		/// \~chinese
-		String GetString(
+		/// @brief 获取 字符串 类型的值
-			String const& key,
+		/// @param key 键
-			String const& default_value = String()
+		/// @param default_value 值不存在时返回的默认值
-		) const;
+		/// @return 值
+		String GetString(String const& key, String const& default_value = String()) const;
 
 	private:
 		String file_path_;
 		String field_name_;
 	};
+
+	inline String const& LocalStorage::GetFilePath() const
+	{
+		return file_path_;
+	}
+
+	inline String const& LocalStorage::GetFieldName() const
+	{
+		return field_name_;
+	}
+
+	inline void LocalStorage::SetFilePath(String const& file_path)
+	{
+		file_path_ = file_path;
+	}
+
+	inline void LocalStorage::SetFieldName(String const& field_name)
+	{
+		field_name_ = field_name;
+	}
 }

src/kiwano/utils/ResourceCache.cpp

@@ -203,26 +203,55 @@ namespace kiwano
 				}
 			}
 		}
-
+		return AddFrameSequence(id, frames);
-		if (!frames.empty())
-		{
-			FrameSequencePtr fs = new (std::nothrow) FrameSequence(frames);
-			return AddObject(id, fs);
-		}
-		return 0;
 	}
 
-	size_t ResourceCache::AddFrameSequence(String const & id, String const& file_path, int cols, int rows, float padding_x, float padding_y)
+	size_t ResourceCache::AddFrameSequence(String const& id, Vector<Resource> const& resources)
+	{
+		if (resources.empty())
+			return 0;
+
+		Vector<FramePtr> frames;
+		frames.reserve(resources.size());
+
+		for (const auto& res : resources)
+		{
+			FramePtr ptr = new (std::nothrow) Frame;
+			if (ptr)
+			{
+				if (ptr->Load(res))
+				{
+					frames.push_back(ptr);
+				}
+			}
+		}
+		return AddFrameSequence(id, frames);
+	}
+
+	size_t ResourceCache::AddFrameSequence(String const& id, Vector<FramePtr> const& frames)
+	{
+		if (frames.empty())
+			return 0;
+
+		FrameSequencePtr fs = new (std::nothrow) FrameSequence(frames);
+		if (fs)
+		{
+			fs->AddFrames(frames);
+			AddObject(id, fs);
+			return fs->GetFramesCount();
+		}
+	}
+
+	size_t ResourceCache::AddFrameSequence(String const& id, FramePtr frame, int cols, int rows, float padding_x, float padding_y)
 	{
 		if (cols <= 0 || rows <= 0)
 			return 0;
 
-		FramePtr raw = new (std::nothrow) Frame;
+		if (!frame)
-		if (!raw || !raw->Load(file_path))
+			return 0;
-			return false;
 
-		float raw_width = raw->GetWidth();
+		float raw_width = frame->GetWidth();
-		float raw_height = raw->GetHeight();
+		float raw_height = frame->GetHeight();
 		float width = (raw_width - (cols - 1) * padding_x) / cols;
 		float height = (raw_height - (rows - 1) * padding_y) / rows;
 
@@ -238,7 +267,7 @@ namespace kiwano
 				FramePtr ptr = new (std::nothrow) Frame;
 				if (ptr)
 				{
-					ptr->SetTexture(raw->GetTexture());
+					ptr->SetTexture(frame->GetTexture());
 					ptr->SetCropRect(Rect{ dtx, dty, dtx + width, dty + height });
 					frames.push_back(ptr);
 				}
@@ -247,8 +276,14 @@ namespace kiwano
 			dty += (height + padding_y);
 		}
 
-		FrameSequencePtr fs = new (std::nothrow) FrameSequence(frames);
+		FrameSequencePtr fs = new (std::nothrow) FrameSequence;
-		return AddObject(id, fs);
+		if (fs)
+		{
+			fs->AddFrames(frames);
+			AddObject(id, fs);
+			return fs->GetFramesCount();
+		}
+		return 0;
 	}
 
 	bool ResourceCache::AddObject(String const& id, ObjectBasePtr obj)

src/kiwano/utils/ResourceCache.h

@@ -28,49 +28,99 @@
 
 namespace kiwano
 {
-	// 资源缓存
+	/// \~chinese
+	/// @brief 资源缓存
+	/// @details 资源缓存
 	class KGE_API ResourceCache
 		: public Singleton<ResourceCache>
 	{
 		friend Singleton<ResourceCache>;
 
 	public:
-		// 从 JSON 文件加载资源信息
+		/// \~chinese
+		/// @brief 从 JSON 文件加载资源信息
+		/// @param file_path JSON文件路径
 		bool LoadFromJsonFile(String const& file_path);
 
-		// 从 JSON 加载资源信息
+		/// \~chinese
+		/// @brief 从 JSON 加载资源信息
+		/// @param json_data JSON对象
 		bool LoadFromJson(Json const& json_data);
 
-		// 从 XML 文件加载资源信息
+		/// \~chinese
+		/// @brief 从 XML 文件加载资源信息
+		/// @param file_path XML文件路径
 		bool LoadFromXmlFile(String const& file_path);
 
-		// 从 XML 文档对象加载资源信息
+		/// \~chinese
+		/// @brief 从 XML 文档对象加载资源信息
+		/// @param doc XML文档对象
 		bool LoadFromXml(const tinyxml2::XMLDocument* doc);
 
-		// 添加对象
+		/// \~chinese
-		bool AddObject(String const& id, ObjectBasePtr obj);
+		/// @brief 获取资源
-
+		/// @param id 对象ID
-		// 添加序列帧
-		size_t AddFrameSequence(String const& id, Vector<String> const& files);
-
-		// 添加序列帧
-		// 按行列数裁剪图片
-		size_t AddFrameSequence(String const& id, String const& file_path, int cols, int rows = 1, float padding_x = 0, float padding_y = 0);
-
-		// 删除指定资源
-		void Remove(String const& id);
-
-		// 清空所有资源
-		void Clear();
-
 		ObjectBasePtr Get(String const& id) const;
 
+		/// \~chinese
+		/// @brief 获取资源
+		/// @tparam _Ty 对象类型
+		/// @param id 对象ID
+		/// @return 指定对象类型的指针
 		template<typename _Ty>
 		SmartPtr<_Ty> Get(String const& id) const
 		{
 			return dynamic_cast<_Ty*>(Get(id).get());
 		}
 
+		/// \~chinese
+		/// @brief 将对象放入缓存
+		/// @param id 对象ID
+		/// @param obj 对象
+		bool AddObject(String const& id, ObjectBasePtr obj);
+
+		/// \~chinese
+		/// @brief 从多个本地图片构建序列帧，并放入缓存
+		/// @param id 对象ID
+		/// @param files 本地图片路径集合
+		/// @return 序列帧的帧数量
+		size_t AddFrameSequence(String const& id, Vector<String> const& files);
+
+		/// \~chinese
+		/// @brief 从多个图片资源构建序列帧，并放入缓存
+		/// @param id 对象ID
+		/// @param resources 图片资源集合
+		/// @return 序列帧的帧数量
+		size_t AddFrameSequence(String const& id, Vector<Resource> const& resources);
+
+		/// \~chinese
+		/// @brief 从多个图像帧构建序列帧，并放入缓存
+		/// @param id 对象ID
+		/// @param frames 图像帧集合
+		/// @return 序列帧的帧数量
+		size_t AddFrameSequence(String const& id, Vector<FramePtr> const& frames);
+
+		/// \~chinese
+		/// @brief 将图像帧按行列分割构建序列帧，并放入缓存
+		/// @brief 按行列数裁剪图片
+		/// @param id 对象ID
+		/// @param frame 图像帧
+		/// @param cols 列
+		/// @param rows 行
+		/// @param padding_x X方向间隔
+		/// @param padding_y Y方向间隔
+		/// @return 序列帧的帧数量
+		size_t AddFrameSequence(String const& id, FramePtr frame, int cols, int rows = 1, float padding_x = 0, float padding_y = 0);
+
+		/// \~chinese
+		/// @brief 删除指定资源
+		/// @param id 对象ID
+		void Remove(String const& id);
+
+		/// \~chinese
+		/// @brief 清空所有资源
+		void Clear();
+
 	private:
 		ResourceCache();
 

src/kiwano/utils/UserData.cpp

@@ -37,12 +37,12 @@ namespace kiwano
 		data_.insert(std::make_pair(key, data));
 	}
 
-	void UserData::Set(Pair<String, Any> const& pair)
+	void UserData::Set(DataPair const& pair)
 	{
 		data_.insert(pair);
 	}
 
-	void UserData::Set(std::initializer_list<Pair<String, Any>> const& list)
+	void UserData::Set(std::initializer_list<DataPair> const& list)
 	{
 		for (const auto& pair : list)
 		{
@@ -60,7 +60,7 @@ namespace kiwano
 		return data_.count(key) != 0;
 	}
 
-	const UnorderedMap<String, Any>& UserData::GetData() const
+	const UserData::DataMap& UserData::GetDataMap() const
 	{
 		return data_;
 	}

src/kiwano/utils/UserData.h

@@ -23,29 +23,62 @@
 
 namespace kiwano
 {
-	// UserData is a simple database for user
+	/// \~chinese
+	/// @brief 用户数据
+	/// @details UserData是一个简易的运行时数据库，存放（字符串-值）的键值对，无持久化
 	class KGE_API UserData
 		: public Singleton<UserData>
 	{
 		friend Singleton<UserData>;
 
 	public:
+		/// \~chinese
+		/// @brief 数据字典
 		using DataMap = UnorderedMap<String, Any>;
 
+		/// \~chinese
+		/// @brief 键值对
+		using DataPair = Pair<const String, Any>;
+
+		/// \~chinese
+		/// @brief 取数据
+		/// @param key 键
+		/// @param default_data 数据不存在时返回的默认值
+		/// @return 键对应的值数据
 		Any Get(String const& key, Any const& default_data = Any()) const;
 
+		/// \~chinese
+		/// @brief 存数据
+		/// @param key 键
+		/// @param data 值
 		void Set(String const& key, Any const& data);
 
-		void Set(Pair<String, Any> const& pair);
+		/// \~chinese
+		/// @brief 存数据
+		/// @param pair 键值对
+		void Set(DataPair const& pair);
 
-		void Set(std::initializer_list<Pair<String, Any>> const& list);
+		/// \~chinese
+		/// @brief 存数据
+		/// @param list 键值对列表
+		void Set(std::initializer_list<DataPair> const& list);
 
+		/// \~chinese
+		/// @brief 存数据
+		/// @param map 数据字典
 		void Set(DataMap const& map);
 
+		/// \~chinese
+		/// @brief 判断是否包含键对应的数据
+		/// @param key 键
 		bool Contains(String const& key) const;
 
-		const DataMap& GetData() const;
+		/// \~chinese
+		/// @brief 获取数据字典
+		const DataMap& GetDataMap() const;
 
+		/// \~chinese
+		/// @brief 清空所有数据
 		void Clear();
 
 	private: