Package io.github.libsdl4j.api.hints

Class SdlHints

  • public final class SdlHints
extends Object
    Definitions from file SDL_hints.h

    Official documentation for SDL configuration variables

    This file contains functions to set and get configuration hints, as well as listing each of them alphabetically.

    The convention for naming hints is SDL_HINT_X, where "SDL_X" is the environment variable that can be used to override the default.

    In general these hints are just that - they may or may not be supported or applicable on any given platform, but they provide a way for an application or user to give the library a hint as to how they would like the library to work.

    • Method Detail

      • SDL_SetHintWithPriority

        public static boolean SDL_SetHintWithPriority​(String name,
                                              String value,
                                              int priority)
        Set a hint with a specific priority.

        The priority controls the behavior when setting a hint that already has a value. Hints will replace existing hints of their priority and lower. Environment variables are considered to have override priority.

        Parameters:
        name - the hint to set
        value - the value of the hint variable
        priority - the SDL_HintPriority level for the hint
        Returns:
        true if the hint was set, false otherwise.
        Since:
        This function is available since SDL 2.0.0.
        See Also:
        SDL_GetHint(String), SDL_SetHint(String, String)

      • SDL_SetHint

        public static boolean SDL_SetHint​(String name,
                                  String value)
        Set a hint with normal priority.

        Hints will not be set if there is an existing override hint or environment variable that takes precedence. You can use SDL_SetHintWithPriority() to set the hint with override priority instead.

        Parameters:
        name - the hint to set
        value - the value of the hint variable
        Returns:
        true if the hint was set, false otherwise.
        Since:
        This function is available since SDL 2.0.0.
        See Also:
        SDL_GetHint(String), SDL_SetHintWithPriority(String, String, int)

      • SDL_ResetHint

        public static boolean SDL_ResetHint​(String name)
        Reset a hint to the default value.

        This will reset a hint to the value of the environment variable, or null if the environment isn't set. Callbacks will be called normally with this change.

        Parameters:
        name - the hint to set
        Returns:
        true if the hint was set, false otherwise.
        Since:
        This function is available since SDL 2.24.0.
        See Also:
        SDL_GetHint(String), SDL_SetHint(String, String)

      • SDL_ResetHints

        public static void SDL_ResetHints()
        Reset all hints to the default values.

        This will reset all hints to the value of the associated environment variable, or null if the environment isn't set. Callbacks will be called normally with this change.

        Since:
        This function is available since SDL 2.26.0.
        See Also:
        SDL_GetHint(String), SDL_SetHint(String, String), SDL_ResetHint(String)

      • SDL_GetHintBoolean

        public static boolean SDL_GetHintBoolean​(String name,
                                         boolean defaultValue)
        Get the boolean value of a hint variable.
        Parameters:
        name - the name of the hint to get the boolean value from
        defaultValue - the value to return if the hint does not exist
        Returns:
        the boolean value of a hint or the provided default value if the hint does not exist.
        Since:
        This function is available since SDL 2.0.5.
        See Also:
        SDL_GetHint(String), SDL_SetHint(String, String)

      • SDL_AddHintCallback

        public static void SDL_AddHintCallback​(String name,
                                       SDL_HintCallback callback,
                                       com.sun.jna.Pointer userdata)
        Add a function to watch a particular hint.
        Parameters:
        name - the hint to watch
        callback - An SDL_HintCallback function that will be called when the hint value changes
        userdata - a pointer to pass to the callback function
        Since:
        This function is available since SDL 2.0.0.
        See Also:
        SDL_DelHintCallback(String, SDL_HintCallback, Pointer)

      • SDL_DelHintCallback

        public static void SDL_DelHintCallback​(String name,
                                       SDL_HintCallback callback,
                                       com.sun.jna.Pointer userdata)
        Remove a function watching a particular hint.
        Parameters:
        name - the hint being watched
        callback - An SDL_HintCallback function that should no longer be called when the hint value changes
        userdata - a pointer being passed to the callback function
        Since:
        This function is available since SDL 2.0.0.
        See Also:
        SDL_AddHintCallback(String, SDL_HintCallback, Pointer)

      • SDL_ClearHints

        public static void SDL_ClearHints()
        Clear all hints.

        This function is automatically called during SDL_Quit(), and deletes all callbacks without calling them and frees all memory associated with hints. If you're calling this from application code you probably want to call SDL_ResetHints() instead.

        This function will be removed from the API the next time we rev the ABI.

        Since:
        This function is available since SDL 2.0.0.
        See Also:
        SDL_ResetHints()