Add limited inline documentation.

Change _GLFWtheme's color components to floats.

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 Sets the system theme callback.
-
-/*! @brief Notifies the application when the system default theme changes.
  *
+ *  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] window The [window](@ref window) to set the theme for.
- *  @param[in] theme The theme to set. Pass `NULL` to set it to the system default.
+ *  @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.

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[0] = color.redComponent;
-        theme.color[1] = color.greenComponent * 255;
+        theme.color[1] = color.greenComponent;
-        theme.color[2] = color.blueComponent * 255;
+        theme.color[2] = color.blueComponent;
-        theme.color[3] = color.alphaComponent * 255;
+        theme.color[3] = color.alphaComponent;
     }
     
     _glfwInputSystemTheme(&theme);

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[0] = color.redComponent;
-        theme->color[1] = color.greenComponent * 255;
+        theme->color[1] = color.greenComponent;
-        theme->color[2] = color.blueComponent * 255;
+        theme->color[2] = color.blueComponent;
-        theme->color[3] = color.alphaComponent * 255;
+        theme->color[3] = color.alphaComponent;
     }
     
     return theme;

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;
 }

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

src/theme.c

@@ -1,9 +1,26 @@
+//========================================================================
+// GLFW 3.4 - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2023 Andreas O. Jansen
 //
-//  theme.c
+// This software is provided 'as-is', without any express or implied
-//  glfw
+// 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;
+    *red   = color[0];
-    *green = iTheme->color[1] / 255.0f;
+    *green = color[1];
-    *blue  = iTheme->color[2] / 255.0f;
+    *blue  = color[2];
-    *alpha = iTheme->color[3] / 255.0f;
+    *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;
+    color[0] = red;
-    iTheme->color[1] = green * 255.0f;
+    color[1] = green;
-    iTheme->color[2] = blue * 255.0f;
+    color[2] = blue;
-    iTheme->color[3] = alpha * 255.0f;
+    color[3] = alpha;
 }