System preferences

CMakeLists.txt

@@ -1732,6 +1732,7 @@ elseif(UNIX AND NOT APPLE AND NOT RISCOS AND NOT HAIKU)
       sdl_sources(
         "${SDL3_SOURCE_DIR}/src/core/linux/SDL_dbus.c"
         "${SDL3_SOURCE_DIR}/src/core/linux/SDL_system_theme.c"
+        "${SDL3_SOURCE_DIR}/src/core/linux/SDL_system_preferences.c"
       )
     endif()
 

include/SDL3/SDL_events.h

@@ -118,6 +118,11 @@ typedef enum SDL_EventType
 
     SDL_EVENT_SYSTEM_THEME_CHANGED, /**< The system theme changed */
 
+    SDL_EVENT_SYSTEM_PREFERENCE_CHANGED, /**< A system preference setting changed */
+    SDL_EVENT_SYSTEM_TEXT_SCALE_CHANGED, /**< The text scale changed */
+    SDL_EVENT_SYSTEM_CURSOR_SCALE_CHANGED, /**< The cursor scale changed */
+    SDL_EVENT_SYSTEM_ACCENT_COLOR_CHANGED, /**< The accent color changed */
+
     /* Display events */
     /* 0x150 was SDL_DISPLAYEVENT, reserve the number for sdl2-compat */
     SDL_EVENT_DISPLAY_ORIENTATION = 0x151,   /**< Display orientation has changed to data1 */
@@ -925,6 +930,23 @@ typedef struct SDL_ClipboardEvent
     const char **mime_types; /**< current mime types */
 } SDL_ClipboardEvent;
 
+/**
+ * An event triggered when a system preference has changed (event.pref.*)
+ *
+ * Note that some platforms may provide certain settings, but not allow
+ * listening to changes; as such, there may be certain preferences that can be
+ * fetched but that won't produce events when they are changed.
+ *
+ * \since This struct is available since SDL 3.4.0.
+ */
+typedef struct SDL_PreferenceEvent
+{
+    SDL_EventType type;         /**< SDL_EVENT_SYSTEM_PREFERENCE_CHANGED */
+    Uint32 reserved;
+    Uint64 timestamp;           /**< In nanoseconds, populated using SDL_GetTicksNS() */
+    SDL_SystemPreference pref;  /**< The preference setting that changed */
+} SDL_PreferenceEvent;
+
 /**
  * Sensor event structure (event.sensor.*)
  *
@@ -1023,6 +1045,7 @@ typedef union SDL_Event
     SDL_RenderEvent render;                 /**< Render event data */
     SDL_DropEvent drop;                     /**< Drag and drop event data */
     SDL_ClipboardEvent clipboard;           /**< Clipboard event data */
+    SDL_PreferenceEvent pref;               /**< Preference event data */
 
     /* This is necessary for ABI compatibility between Visual C++ and GCC.
        Visual C++ will respect the push pack pragma and use 52 bytes (size of

include/SDL3/SDL_video.h

@@ -570,6 +570,113 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void);
  */
 extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
 
+/**
+ * An enumeration of various boolean system preferences.
+ *
+ * Some systems provide a variety of accessibility options that allow users to
+ * adapt their environment to various conditions.
+ *
+ * \since This enum is available since SDL 3.4.0.
+ *
+ * \sa SDL_GetSystemPreference
+ */
+typedef enum SDL_SystemPreference
+{
+    SDL_SYSTEM_PREFERENCE_REDUCED_MOTION,        /**< Disable smooth graphical transitions */
+    SDL_SYSTEM_PREFERENCE_REDUCED_TRANSPARENCY,  /**< Reduce usage of semi-transparent objects */
+    SDL_SYSTEM_PREFERENCE_HIGH_CONTRAST,         /**< Use extreme color differences between different elements of the interface */
+    SDL_SYSTEM_PREFERENCE_COLORBLIND,            /**< Add shape-based distinction between color-coded elements, for example "0" and "1" on switches */
+    SDL_SYSTEM_PREFERENCE_PERSIST_SCROLLBARS,    /**< Always show scrollbars, don't hide them after a few seconds of inactivity */
+    SDL_SYSTEM_PREFERENCE_SCREEN_READER,         /**< A screen reader is currently active */
+} SDL_SystemPreference;
+
+/**
+ * Get whether or not a certain system preference was enabled by the user.
+ *
+ * This setting will emit a `SDL_EVENT_SYSTEM_PREFERENCE_CHANGED` when the user
+ * updates the corresponding preference in their settings or accessibility app.
+ * Note that some platforms may provide certain settings, but not allow
+ * listening to changes; as such, there may be certain preferences that can be
+ * fetched but that won't produce events when they are changed.
+ *
+ * \param preference the preference to be fetched.
+ * \returns true if the user enabled the system preference; false if the user
+ *          disabled that setting, or the setting doesn't exist, or an error
+ *          occured.
+ *
+ * \threadsafety This function should only be called on the main thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ *
+ * \sa SDL_SystemPreference
+ * \sa SDL_PreferenceEvent
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_GetSystemPreference(SDL_SystemPreference preference);
+
+/**
+ * Get the system's accent color, as chosen by the user.
+ *
+ * If the current system does not have an accent color, false is returned and
+ * the struct is unaffected.
+ *
+ * This setting will emit a `SDL_EVENT_SYSTEM_ACCENT_COLOR_CHANGED` when the
+ * user updates the corresponding preference in their settings or accessibility
+ * app. Note that some platforms may provide certain settings, but not allow
+ * listening to changes; as such, there may be certain preferences that can be
+ * fetched but that won't produce events when they are changed.
+ *
+ * \param color a pointer to a struct to be filled with the color info. The
+ *              alpha channel is what the operating system returned and may or
+ *              may not be opaque.
+ * \returns true on success or false on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \threadsafety This function should only be called on the main thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_GetSystemAccentColor(SDL_Color *color);
+
+/**
+ * Get the scale factor for text, as set by the user for their system. For
+ * absolute scaling methods, this presumes a base size of 16 pixels.
+ *
+ * If the system does not have a setting to scale the font, 1 is returned.
+ *
+ * This setting will emit a `SDL_EVENT_SYSTEM_TEXT_SCALE_CHANGED` when the user
+ * updates the corresponding preference in their settings or accessibility app.
+ * Note that some platforms may provide certain settings, but not allow
+ * listening to changes; as such, there may be certain preferences that can be
+ * fetched but that won't produce events when they are changed.
+ *
+ * \returns the preferred scale for text; a scale of 1 means no scaling.
+ *
+ * \threadsafety This function should only be called on the main thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ */
+extern SDL_DECLSPEC float SDLCALL SDL_GetSystemTextScale(void);
+
+/**
+ * Get the scale factor for the cursor, as set by the user for their system. For
+ * absolute scaling methods, this presumes a base size of 32 pixels.
+ *
+ * If the system does not have a setting to scale the cursor, 1 is returned.
+ *
+ * This setting will emit a `SDL_EVENT_SYSTEM_CURSOR_SCALE_CHANGED` when the
+ * user updates the corresponding preference in their settings or accessibility
+ * app. Note that some platforms may provide certain settings, but not allow
+ * listening to changes; as such, there may be certain preferences that can be
+ * fetched but that won't produce events when they are changed.
+ *
+ * \returns the preferred scale for the cursor; a scale of 1 means no scaling.
+ *
+ * \threadsafety This function should only be called on the main thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ */
+extern SDL_DECLSPEC float SDLCALL SDL_GetSystemCursorScale(void);
+
 /**
  * Get a list of currently connected displays.
  *