From 19f9247a681963f1fae86c0aa43f108c22287c6b Mon Sep 17 00:00:00 2001 From: GamesTrap Date: Sun, 5 Feb 2023 02:50:53 +0100 Subject: [PATCH] Added documentation --- docs/window.dox | 5 +++ include/GLFW/glfw3.h | 81 ++++++++++++++++++++++++++++++++++++++++++++ src/win32_window.c | 6 ++-- src/window.c | 4 +-- 4 files changed, 92 insertions(+), 4 deletions(-) diff --git a/docs/window.dox b/docs/window.dox index 3cec6358..f464d3c9 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -1159,6 +1159,11 @@ not supported, the application as a whole. Once the user has given it attention, the system will automatically end the request. +@subsection window_taskbar_progress Window taskbar progress + +TBD + + @subsection window_refresh Window damage and refresh If you wish to be notified when the contents of a window is damaged and needs diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index 62cc0056..6ac16c82 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1272,11 +1272,56 @@ extern "C" { #define GLFW_HAND_CURSOR GLFW_POINTING_HAND_CURSOR /*! @} */ +/*! @addtogroup window + * @{ */ +/*! @brief Disable the progress bar. + * + * Disable the progress bar. + * + * Used by @ref window_taskbar_progress. + */ #define GLFW_TASKBAR_PROGRESS_NOPROGRESS 0 +/*! @brief Display the progress bar in an indeterminate state. + * + * Display the progress bar in an indeterminate state. + * + * @remark @win32 This displays the progress bar animation cycling repeatedly. + * + * @remark @x11 @wayland This behaves like @ref GLFW_TASKBAR_PROGRESS_NORMAL. + * + * Used by @ref window_taskbar_progress. + */ #define GLFW_TASKBAR_PROGRESS_INDETERMINATE 1 +/*! @brief Display the normal progress bar. + * + * Display the normal progress bar. + * + * Used by @ref window_taskbar_progress. + */ #define GLFW_TASKBAR_PROGRESS_NORMAL 2 +/*! @brief Display the progress bar in an error state. + * + * Display the progress bar in an error state. + * + * @remark @win32 This displays a red progress bar with 100% progress. + * + * @remark @x11 @wayland This behaves like @ref GLFW_TASKBAR_PROGRESS_NORMAL. + * + * Used by @ref window_taskbar_progress. + */ #define GLFW_TASKBAR_PROGRESS_ERROR 3 +/*! @brief Display the progress bar in a paused state. + * + * Display the progress bar in a paused state. + * + * @remark @win32 This displays a yellow filled progress bar. + * + * @remark @x11 @wayland This behaves like @ref GLFW_TASKBAR_PROGRESS_NORMAL. + * + * Used by @ref window_taskbar_progress. + */ #define GLFW_TASKBAR_PROGRESS_PAUSED 4 +/*! @} */ #define GLFW_CONNECTED 0x00040001 #define GLFW_DISCONNECTED 0x00040002 @@ -1321,6 +1366,7 @@ extern "C" { * * Hint value for @ref GLFW_PLATFORM that enables automatic platform selection. */ + #define GLFW_ANY_PLATFORM 0x00060000 #define GLFW_PLATFORM_WIN32 0x00060001 #define GLFW_PLATFORM_COCOA 0x00060002 @@ -3310,6 +3356,41 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); */ GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images); +/*! @brief Sets the taskbar progress for the specified window. + * + * This function sets the taskbar progress of the specified window. + * + * @param[in] window The window whose taskbar progress to set. + * @param[in] progressState State of the progress to be displayed in the taskbar. Valid values are: + * @ref GLFW_TASKBAR_PROGRESS_NOPROGRESS, @ref GLFW_TASKBAR_PROGRESS_INDETERMINATE, + * @ref GLFW_TASKBAR_PROGRESS_NORMAL, @ref GLFW_TASKBAR_PROGRESS_ERROR + * and @ref GLFW_TASKBAR_PROGRESS_PAUSED. + * @param[in] completed The amount of completed progress to set. Valid range is 0 to 100. + * This is ignored if progressState is set to @ref GLFW_TASKBAR_PROGRESS_NOPROGRESS. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref + * GLFW_INVALID_VALUE, @ref GLFW_INVALID_ENUM, @ref GLFW_PLATFORM_ERROR, + * @ref GLFW_FEATURE_UNIMPLEMENTED and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). + * + * @remark @win32 On Windows Vista and earlier, this function will emit @ref GLFW_FEATURE_UNAVAILABLE. + * + * @remark @macos This function will emit @ref GLFW_FEATURE_UNIMPLEMENTED. + * + * @remark @x11 @wayland Requires a valid application desktop file with the same name + * as the compiled executable. Due to limitations in the Unity Launcher API + * @ref GLFW_TASKBAR_PROGRESS_INDETERMINATE, @ref GLFW_TASKBAR_PROGRESS_ERROR and @ref GLFW_TASKBAR_PROGRESS_PAUSED + * have the same behaviour as @ref GLFW_TASKBAR_PROGRESS_NORMAL. The Unity Launcher API is only known + * to be supported on the Unity and KDE desktop environments, on other desktop environments this + * function may do nothing. + * + * @thread_safety This function must only be called from the main thread. + * + * @sa @ref window_taskbar_progress + * + * @since Added in version 3.4. + * + * @ingroup window + */ GLFWAPI void glfwSetWindowTaskbarProgress(GLFWwindow* window, const int progressState, int completed); /*! @brief Retrieves the position of the content area of the specified window. diff --git a/src/win32_window.c b/src/win32_window.c index 05f12bda..28f60b52 100644 --- a/src/win32_window.c +++ b/src/win32_window.c @@ -1598,17 +1598,19 @@ void _glfwSetWindowIconWin32(_GLFWwindow* window, int count, const GLFWimage* im void _glfwSetWindowTaskbarProgressWin32(_GLFWwindow* window, const int progressState, int completed) { + HRESULT res = S_OK; + int32_t winProgressState = 0; + if(!window->win32.TaskbarList) return; - HRESULT res = window->win32.TaskbarList->lpVtbl->SetProgressValue(window->win32.TaskbarList, window->win32.handle, completed, 100); + res = window->win32.TaskbarList->lpVtbl->SetProgressValue(window->win32.TaskbarList, window->win32.handle, completed, 100); if(res != S_OK) { _glfwInputErrorWin32(GLFW_PLATFORM_ERROR, "Win32: Failed to set taskbar progress value"); return; } - int32_t winProgressState = 0; switch(progressState) { case 1: diff --git a/src/window.c b/src/window.c index 82807ef2..f74cb521 100644 --- a/src/window.c +++ b/src/window.c @@ -563,8 +563,8 @@ GLFWAPI void glfwSetWindowTaskbarProgress(GLFWwindow* handle, const int progress _GLFWwindow* window = (_GLFWwindow*) handle; assert(window != NULL); - assert(completed >= 0); - assert(completed <= 100); + + _GLFW_REQUIRE_INIT(); if (completed < 0) {