From b5758af15579f0d20fa4235f85fcb2971010d38f Mon Sep 17 00:00:00 2001 From: ws909 <37029098+ws909@users.noreply.github.com> Date: Mon, 30 Jan 2023 00:02:44 +0100 Subject: [PATCH] Add limited inline documentation. Change _GLFWtheme's color components to floats. --- include/GLFW/glfw3.h | 186 +++++++++++++++++++++++++++++++++++++++---- src/cocoa_init.m | 8 +- src/cocoa_window.m | 8 +- src/init.c | 2 +- src/internal.h | 18 ++++- src/theme.c | 43 +++++++--- 6 files changed, 228 insertions(+), 37 deletions(-) diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h index ca8e1e87..75ba656e 100644 --- a/include/GLFW/glfw3.h +++ b/include/GLFW/glfw3.h @@ -1394,6 +1394,18 @@ typedef struct GLFWwindow GLFWwindow; */ typedef struct GLFWcursor GLFWcursor; +/*! @brief Opaque theme object. + * + * Opaque theme object. + * + * @see @ref theme_object + * + * @since Added in version 3.4. + * + * @ingroup theme + */ +typedef struct GLFWtheme GLFWtheme; + /*! @brief The function pointer type for memory allocation callbacks. * * This is the function pointer type for memory allocation callbacks. A memory @@ -1964,6 +1976,28 @@ typedef void (* GLFWmonitorfun)(GLFWmonitor* monitor, int event); */ typedef void (* GLFWjoystickfun)(int jid, int event); +/*! @brief The function pointer type for system theme callbacks. + * + * This is the function pointer type for system theme callbacks. A system + * theme callback function has the following signature: + * @code + * void function_name(GLFWtheme* theme) + * @endcode + * + * @param[in] theme The new system theme. + * + * @pointer_lifetime The theme is valid until the callback + * function returns. + * + * @sa @ref theme + * @sa @ref glfwSetSystemThemeCallback + * + * @since Added in version 3.4. + * + * @ingroup theme + */ +typedef void (* GLFWthemefun)(GLFWtheme* theme); + /*! @brief Video mode type. * * This describes a single video mode. @@ -5845,15 +5879,6 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); */ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); -typedef struct GLFWtheme GLFWtheme; - -typedef struct _GLFWtheme -{ - int variation; // light/dark - int flags; - unsigned char color[4]; // TODO: change to 128 bit (4 floats) to support wider gamuts. -} _GLFWtheme; - GLFWAPI GLFWtheme* glfwCreateTheme(void); GLFWAPI void glfwDestroyTheme(GLFWtheme* theme); GLFWAPI void glfwCopyTheme(const GLFWtheme* source, GLFWtheme* target); @@ -5867,28 +5892,161 @@ GLFWAPI void glfwThemeSetFlags(GLFWtheme* theme, int value); GLFWAPI void glfwThemeGetColor(const GLFWtheme* theme, float* red, float* green, float* blue, float* alpha); GLFWAPI void glfwThemeSetColor(GLFWtheme* theme, float red, float green, float blue, float alpha); +/*! @brief Theme variation type. + * + * Specifies that a theme is of a dark variation. + * + * @ingroup theme + */ #define GLFW_THEME_DARK -1 + +/*! @brief Theme variation type. + * + * Specifies that a theme has no specific variation. + * This is an invalid value for themes returned by GLFW, but this + * variation can be set to make GLFW use the default system theme when + * applying a user-specified theme. + * + * @ingroup theme + */ #define GLFW_THEME_DEFAULT 0 + +/*! @brief Theme variation type. + * + * Specifies that a theme is of a light variation. + * + * @ingroup theme + */ #define GLFW_THEME_LIGHT 1 + +/*! @brief Theme flag. + * + * Specifies that a theme provides a color. If this flag is set on a theme + * returned by GLFW, this theme contains a color. If this flag is set on a + * theme supplied to GLFW, GLFW applies this theme if the platform supports it. + * If the flag is unset, the theme's color is ignored. + * + * @ingroup theme + */ #define GLFW_THEME_FLAG_HAS_COLOR 1 + +/*! @brief Theme flag. + * + * Specifies that a theme uses a high contrast mode. + * + * @ingroup theme + */ #define GLFW_THEME_FLAG_HIGH_CONTRAST 2 + +/*! @brief Theme flag. + * + * Specifies that a theme is vibrant. + * + * @ingroup theme + */ #define GLFW_THEME_FLAG_VIBRANT 4 -typedef void (* GLFWthemefun)(GLFWtheme* theme); - -/*! @brief Notifies the application when the system default theme changes. +/*! @brief Sets the system theme callback. * + * This function sets the system theme callback, or removes the + * currently set callback. This is called when the system theme changes, + * either because the user edited it, or the system automatically changed it. + * + * @param[in] callback The new callback, or `NULL` to remove the currently set + * callback. + * @return The previously set callback, or `NULL` if no callback was set or the + * library had not been [initialized](@ref intro_init). + * + * @callback_signature + * @code + * void function_name(GLFWtheme* theme) + * @endcode + * For more information about the callback parameters, see the + * [function pointer type](@ref GLFWthemefun). + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. + * + * @thread_safety This function must only be called from the main thread. + * + * @sa @ref theme_event + * + * @since Added in version 3.4. + * + * @ingroup theme */ GLFWAPI GLFWthemefun glfwSetSystemThemeCallback(GLFWthemefun callback); /*! @brief Sets the theme for a window. * - * @param[in] window The window to set the theme for. - * @param[in] theme The theme to set. Pass `NULL` to set it to the system default. + * @param[in] window The [window](@ref window) to set the theme for. + * @param[in] theme The [theme](@ref theme) to set. Pass `NULL` to set it to the system default. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, + * and @ref GLFW_FEATURE_UNIMPLEMENTED. + * + * @pointer_lifetime The returned theme is allocated and freed by GLFW. You + * should not free it yourself. It is valid until this function or @ref glfwGetTheme + * is called again for the specified window, or the window is destroyed. + * + * @thread_safety This function must only be called from the main thread. + * + * @sa @ref theme + * @sa @ref glfwGetTheme + * + * @since Added in version 3.4. + * + * @ingroup theme */ GLFWAPI void glfwSetTheme(GLFWwindow* handle, const GLFWtheme* theme); + +/*! @brief Returns the currently active system theme. + * + * @param[in] window The [window](@ref window) to retrieve the current theme for. + * + * @return A mutable [theme](@ref theme) object, or `NULL` if an + * [error](@ref error_handling) occurred. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, + * and @ref GLFW_FEATURE_UNIMPLEMENTED. + * + * @pointer_lifetime The returned theme is allocated and freed by GLFW. You + * should not free it yourself. It is valid until this function or @ref glfwSetTheme + * is called again for the specified window, or the window is destroyed. + * + * @thread_safety This function must only be called from the main thread. + * + * @sa @ref theme + * @sa @ref glfwSetTheme + * + * @since Added in version 3.4. + * + * @ingroup theme + */ GLFWAPI GLFWtheme* glfwGetTheme(GLFWwindow* handle); + +/*! @brief Returns the currently active system theme. + * + * @return A mutable [theme](@ref theme) object, or `NULL` if an + * [error](@ref error_handling) occurred. + * + * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, + * and @ref GLFW_FEATURE_UNIMPLEMENTED. + * + * @pointer_lifetime The returned theme is allocated and freed by GLFW. You + * should not free it yourself. It is valid until this function is called + * again, or the library is terminated. + * + * @thread_safety This function must only be called from the main thread. + * + * @sa @ref theme + * @sa @ref glfwSetSystemThemeCallback + * @sa @ref glfwSetTheme + * + * @since Added in version 3.4. + * + * @ingroup theme + */ GLFWAPI GLFWtheme* glfwGetSystemDefaultTheme(); /*! @brief Returns the GLFW time. diff --git a/src/cocoa_init.m b/src/cocoa_init.m index 5c8b0e82..d075a0e1 100644 --- a/src/cocoa_init.m +++ b/src/cocoa_init.m @@ -502,10 +502,10 @@ static GLFWbool initializeTIS(void) NSColor* color = [[NSColor controlAccentColor] colorUsingColorSpace:NSColorSpace.genericRGBColorSpace]; theme.flags |= GLFW_THEME_FLAG_HAS_COLOR; - theme.color[0] = color.redComponent * 255; - theme.color[1] = color.greenComponent * 255; - theme.color[2] = color.blueComponent * 255; - theme.color[3] = color.alphaComponent * 255; + theme.color[0] = color.redComponent; + theme.color[1] = color.greenComponent; + theme.color[2] = color.blueComponent; + theme.color[3] = color.alphaComponent; } _glfwInputSystemTheme(&theme); diff --git a/src/cocoa_window.m b/src/cocoa_window.m index b99a9e85..acb23f94 100644 --- a/src/cocoa_window.m +++ b/src/cocoa_window.m @@ -1944,10 +1944,10 @@ _GLFWtheme* _glfwGetThemeCocoa(_GLFWwindow* window) // TODO: Cannot use the accent color directly, for window themes, because the accent color is never overridden. theme->flags |= GLFW_THEME_FLAG_HAS_COLOR; - theme->color[0] = color.redComponent * 255; - theme->color[1] = color.greenComponent * 255; - theme->color[2] = color.blueComponent * 255; - theme->color[3] = color.alphaComponent * 255; + theme->color[0] = color.redComponent; + theme->color[1] = color.greenComponent; + theme->color[2] = color.blueComponent; + theme->color[3] = color.alphaComponent; } return theme; diff --git a/src/init.c b/src/init.c index 69d391c1..6cd16a76 100644 --- a/src/init.c +++ b/src/init.c @@ -548,7 +548,7 @@ GLFWAPI GLFWtheme* glfwGetSystemDefaultTheme() _GLFW_REQUIRE_INIT_OR_RETURN(NULL); _GLFWtheme* theme = _glfw.platform.getSystemDefaultTheme(); - assert(theme->variation != GLFW_THEME_DEFAULT); + assert(theme->variation != GLFW_THEME_DEFAULT); return (GLFWtheme*) theme; } diff --git a/src/internal.h b/src/internal.h index 9795fc6b..50f4674d 100644 --- a/src/internal.h +++ b/src/internal.h @@ -72,6 +72,7 @@ typedef struct _GLFWplatform _GLFWplatform; typedef struct _GLFWlibrary _GLFWlibrary; typedef struct _GLFWmonitor _GLFWmonitor; typedef struct _GLFWcursor _GLFWcursor; +typedef struct _GLFWtheme _GLFWtheme; typedef struct _GLFWmapelement _GLFWmapelement; typedef struct _GLFWmapping _GLFWmapping; typedef struct _GLFWjoystick _GLFWjoystick; @@ -515,6 +516,20 @@ struct _GLFWcontext GLFW_PLATFORM_CONTEXT_STATE }; +// Theme structure +// +struct _GLFWtheme +{ + // The light/dark variation. If set to DEFAULT, use the system theme variation. + int variation; + + int flags; + + // When applying a theme, ignore this color if the HAS_COLOR + // flag is unset, and use the system theme color instead. + float color[4]; +}; + // Window and context structure // struct _GLFWwindow @@ -571,7 +586,8 @@ struct _GLFWwindow GLFWdropfun drop; } callbacks; - _GLFWtheme theme; // TODO: This data is mutable by clients, so remove it. + // Clients can mutate this theme data at any time + _GLFWtheme theme; // This is defined in platform.h GLFW_PLATFORM_WINDOW_STATE diff --git a/src/theme.c b/src/theme.c index bcb119a0..b27d6bb3 100644 --- a/src/theme.c +++ b/src/theme.c @@ -1,9 +1,26 @@ +//======================================================================== +// GLFW 3.4 - www.glfw.org +//------------------------------------------------------------------------ +// Copyright (c) 2023 Andreas O. Jansen // -// theme.c -// glfw +// This software is provided 'as-is', without any express or implied +// warranty. In no event will the authors be held liable for any damages +// arising from the use of this software. // -// Created by Andreas Ormevik Jansen on 28/01/2023. +// Permission is granted to anyone to use this software for any purpose, +// including commercial applications, and to alter it and redistribute it +// freely, subject to the following restrictions: // +// 1. The origin of this software must not be misrepresented; you must not +// claim that you wrote the original software. If you use this software +// in a product, an acknowledgment in the product documentation would +// be appreciated but is not required. +// +// 2. Altered source versions must be plainly marked as such, and must not +// be misrepresented as being the original software. +// +// 3. This notice may not be removed or altered from any source +// distribution. #include "internal.h" @@ -67,22 +84,22 @@ GLFWAPI void glfwThemeGetColor(const GLFWtheme* theme, float* red, float* green, assert(theme != NULL); assert(red != NULL && green != NULL && blue != NULL && alpha != NULL); - const _GLFWtheme* iTheme = ((_GLFWtheme*) theme); + const float* color = ((_GLFWtheme*) theme)->color; - *red = iTheme->color[0] / 255.0f; - *green = iTheme->color[1] / 255.0f; - *blue = iTheme->color[2] / 255.0f; - *alpha = iTheme->color[3] / 255.0f; + *red = color[0]; + *green = color[1]; + *blue = color[2]; + *alpha = color[3]; } GLFWAPI void glfwThemeSetColor(GLFWtheme* theme, float red, float green, float blue, float alpha) { assert(theme != NULL); - _GLFWtheme* iTheme = ((_GLFWtheme*) theme); + float* color = ((_GLFWtheme*) theme)->color; - iTheme->color[0] = red * 255.0f; - iTheme->color[1] = green * 255.0f; - iTheme->color[2] = blue * 255.0f; - iTheme->color[3] = alpha * 255.0f; + color[0] = red; + color[1] = green; + color[2] = blue; + color[3] = alpha; }