Table of Contents

Struct Hint

Namespace
Sdl3Sharp
Assembly
Sdl3Sharp.dll

Represents a hinting option to an application which can be changed via an environment variable or programmatically

public readonly struct Hint : IEquatable<Hint>, ISpanFormattable, IFormattable, IEqualityOperators<Hint, Hint, bool>
Implements
Inherited Members

Constructors

Hint(string)

Represents a hinting option to an application which can be changed via an environment variable or programmatically

public Hint(string name)

Parameters

name string

The name of the hint

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

Properties

AllowAltTabWhileGrabbed

Gets a hint specifying the behavior of Alt+Tab while the keyboard is grabbed

public static Hint AllowAltTabWhileGrabbed { get; }

Property Value

Hint

A hint specifing the behavior of Alt+Tab while the keyboard is grabbed

Remarks

By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed and your window is full-screen. This prevents the user from getting stuck in your application if you've enabled keyboard grab.

The hint can be set to the following values:

  • "0"SDL will not handle Alt+Tab. Your application is responsible for handling Alt+Tab while the keyboard is grabbed.
  • "1"SDL will minimize your window when Alt+Tab is pressed (default)

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

AppId

Gets a hint setting the app ID string

public static Hint AppId { get; }

Property Value

Hint

A hint setting the app ID string

Remarks

This string is used by desktop compositors to identify and group windows together, as well as match applications with associated desktop settings and icons.

This will override Identifier, if set by the application.

This hint should be set before SDL is initialized.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

AppName

Gets a hint setting the application name

public static Hint AppName { get; }

Property Value

Hint

A hint setting the application name

Remarks

This hint lets you specify the application name sent to the OS when required. For example, this will often appear in volume control applets for audio streams, and in lists of applications which are inhibiting the screensaver. You should use a string that describes your program ("My Game 2: The Revenge").

This will override Name, if set by the application.

This hint should be set before SDL is initialized.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

Assert

Gets a hint controlling response to SDL_assert failures

public static Hint Assert { get; }

Property Value

Hint

A hint controlling response to SDL_assert failures

Remarks

The hint can be set to the following case-sensitive values:

  • "abort"Program terminates immediately
  • "break"Program triggers a debugger breakpoint
  • "retry"Program reruns the SDL_assert's test again
  • "ignore"Program continues on, ignoring this assertion failure this time
  • "always_ignore"Program continues on, ignoring this assertion failure for the rest of the run

Note that SDL_SetAssertionHandler offers a programmatic means to deal with assertion failures through a callback, and this hint is largely intended to be used via environment variables by end users and automated tools.

This hint should be set before an assertion failure is triggered and can be changed at any time.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

AutoUpdateJoysticks

Gets a hint controlling whether SDL updates joystick state when getting input events

public static Hint AutoUpdateJoysticks { get; }

Property Value

Hint

A hint controlling whether SDL updates joystick state when getting input events

Remarks

The hint can be set to the following values:

  • "0"You'll call SDL_UpdateJoysticks() manually
  • "1"SDL will automatically call SDL_UpdateJoysticks() (default)

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

AutoUpdateSensors

Gets a hint controlling whether SDL updates sensor state when getting input events

public static Hint AutoUpdateSensors { get; }

Property Value

Hint

A hint controlling whether SDL updates sensor state when getting input events

Remarks

The hint can be set to the following values:

  • "0"You'll call SDL_UpdateSensors() manually
  • "1"SDL will automatically call SDL_UpdateSensors() (default)

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

BmpSaveLegacyFormat

Gets a hint to control whether or not to prevent SDL from using version 4 of the bitmap header when saving BMPs

public static Hint BmpSaveLegacyFormat { get; }

Property Value

Hint

A hint to control whether or not to prevent SDL from using version 4 of the bitmap header when saving BMPs

Remarks

The bitmap header version 4 is required for proper alpha channel support and SDL will use it when required. Should this not be desired, this hint can force the use of the 40 byte header version which is supported everywhere.

The hint can be set to the following values:

  • "0"Surfaces with a colorkey or an alpha channel are saved to a 32-bit BMP file with an alpha mask. SDL will use the bitmap header version 4 and set the alpha mask accordingly. (default)
  • "1"Surfaces with a colorkey or an alpha channel are saved to a 32-bit BMP file without an alpha mask. The alpha channel data will be in the file, but applications are going to ignore it.

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

CpuFeatureMask

Gets a hint that limits what CPU features are available

public static Hint CpuFeatureMask { get; }

Property Value

Hint

A hint that limits what CPU features are available

Remarks

By default, SDL marks all features the current CPU supports as available. This hint allows to limit these to a subset.

When the hint is unset, or empty, SDL will enable all detected CPU features.

The hint can be set to a comma separated list containing the following items:

  • "all"
  • "altivec"
  • "sse"
  • "sse2"
  • "sse3"
  • "sse41"
  • "sse42"
  • "avx"
  • "avx2"
  • "avx512f"
  • "arm-simd"
  • "neon"
  • "lsx"
  • "lasx"

The items can be prefixed by '+'/'-' to add/remove features.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

EnableScreenKeyboard

Gets a hint that controls whether the on-screen keyboard should be shown when text input is active

public static Hint EnableScreenKeyboard { get; }

Property Value

Hint

A hint that controls whether the on-screen keyboard should be shown when text input is active

Remarks

The hint can be set to the following values:

  • "auto"The on-screen keyboard will be shown if there is no physical keyboard attached (default)
  • "0"Do not show the on-screen keyboard
  • "1"Show the on-screen keyboard, if available

This hint must be set before SDL_StartTextInput() is called.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

EvDevDevices

Gets a hint containing a list of evdev devices to use if udev is not available

public static Hint EvDevDevices { get; }

Property Value

Hint

A hint containing a list of evdev devices to use if udev is not available

Remarks

The list of devices is in the form: deviceclass:path[,deviceclass:path[,...]], where deviceclass is an integer representing the SDL_UDEV_deviceclass and path is the full path to the event device.

This hint should be set before SDL is initialized.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

EventLogging

Gets a hint controlling verbosity of the logging of SDL events pushed onto the internal queue

public static Hint EventLogging { get; }

Property Value

Hint

A hint controlling verbosity of the logging of SDL events pushed onto the internal queue

Remarks

The hint can be set to the following values, from least to most verbose:

  • "0"Don't log any events. (default)
  • "1"Log most events (other than the really spammy ones)
  • "2"Include mouse and finger motion events

This is generally meant to be used to debug SDL itself, but can be useful for application developers that need better visibility into what is going on in the event queue. Logged events are sent through Info(string), which means by default they appear on stdout on most platforms or maybe OutputDebugString() on Windows (when UseDefaultOutputForUnhandledMessages is true), and can be funneled by the app with the Output event, etc.

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

FileDialogDriver

Gets a hint that specifies a dialog backend to use

public static Hint FileDialogDriver { get; }

Property Value

Hint

A hint that specifies a dialog backend to use

Remarks

By default, SDL will try all available dialog backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific target.

If the specified target does not exist or is not available, the dialog-related calls will fail.

This hint currently only applies to platforms using the generic "Unix" dialog implementation, but may be extended to more platforms in the future. Note that some Unix and Unix-like platforms have their own implementation, such as macOS and Haiku.

The hint can be set to the following values:

  • nullSelect automatically (default, all platforms)
  • "portal"Use XDG Portals through DBus (Unix only)
  • "zenity"Use the Zenity program (Unix only)

More options may be added in the future.

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

ForceRaiseWindow

Gets a hint controlling whether raising the window should be done more forcefully

public static Hint ForceRaiseWindow { get; }

Property Value

Hint

A hint controlling whether raising the window should be done more forcefully

Remarks

The hint can be set to the following values:

  • "0"Honor the OS policy for raising windows (default)
  • "1"Force the window to be raised, overriding any OS policy

At present, this is only an issue under MS Windows, which makes it nearly impossible to programmatically move a window to the foreground, for "security" reasons. See http://stackoverflow.com/a/34414846 for a discussion.

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

FrameBufferAcceleration

Gets a hint controlling how 3D acceleration is used to accelerate the SDL screen surface

public static Hint FrameBufferAcceleration { get; }

Property Value

Hint

A hint controlling how 3D acceleration is used to accelerate the SDL screen surface

Remarks

SDL can try to accelerate the SDL screen surface by using streaming textures with a 3D rendering engine. This hint controls whether and how this is done.

The hint can be set to the following values:

  • "0"Disable 3D acceleration
  • "1"Enable 3D acceleration, using the default renderer (default)
  • Any other string Enable 3D acceleration, using the specified valid rendering drivers (e.g. "direct3d", "opengl", etc.). You can use the Name value of any of the predefined rendering drivers to set this hint (e.g. Name).

This hint should be set before accessing a Surface.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

ImeImplementedUI

Gets a hint describing what IME UI elements the application can display

public static Hint ImeImplementedUI { get; }

Property Value

Hint

A hint describing what IME UI elements the application can display

Remarks

By default IME UI is handled using native components by the OS where possible, however this can interfere with or not be visible when exclusive fullscreen mode is used.

The hint can be set to a comma separated list containing the following items:

  • "none" or "0"The application can't render any IME elements, and native UI should be used (default)
  • "composition"The application handles EventType.Keyboard.TextEditing events and can render the composition text
  • "candidates"The application handles EventType.Keyboard.TextEditingCandidates and can render the candidate list

This hint should be set before SDL is initialized.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

KeycodeOptions

Gets a hint that controls keycode representation in keyboard events

public static Hint KeycodeOptions { get; }

Property Value

Hint

A hint that controls keycode representation in keyboard events

Remarks

The hint is a comma separated set of options for translating keycodes in events:

  • "none"Keycode options are cleared, this overrides other options
  • "hide_numpad"The numpad keysyms will be translated into their non-numpad versions based on the current NumLock state. For example, Keypad4 would become _4 if NumLock is set in the event modifiers, and Left if it is unset.
  • "french_numbers"The number row on French keyboards is inverted, so pressing the 1 key would yield the keycode _1, or '1', instead of Ampersand, or '&'
  • "latin_letters"For keyboards using non-Latin letters, such as Russian or Thai, the letter keys generate keycodes as though it had an en_US layout. E.g. pressing the key associated with A on a Russian keyboard would yield 'a' instead of a Cyrillic letter.

The default value for this hint is "french_numbers,latin_letters"

Some platforms like Emscripten only provide modified keycodes and the options are not used.

These options do not affect the return value of TryGetFromScancode(Scancode, Keymod, out Keycode)() or TryGetFromKeycode(Keycode, out Keymod, out Scancode)(), they just apply to the keycode included in key events.

This hint can be set anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

MainCallbackRate

Gets a hint that request OnIterate(Sdl) to be called at a specific rate

public static Hint MainCallbackRate { get; }

Property Value

Hint

A hint that request OnIterate(Sdl) to be called at a specific rate

Remarks

If this hint is set to a number, it represents Hz, so "60" means try to iterate 60 times per second. "0" means to iterate as fast as possible. Negative values are illegal, but reserved, in case they are useful in a future revision of SDL.

There are other string values that have special meaning. If set to "waitevent", OnIterate(Sdl) will not be called until new event(s) have arrived (and been processed by OnEvent(Sdl, ref Event)). This can be useful for apps that are completely idle except in response to input.

This hint defaults to 0, and specifying null for the hint's value will restore the default.

This hint can be set anytime and is allowed to be changed at anytime.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

See Also

Name

Gets the name of the hint

public string Name { get; }

Property Value

string

The name of the hint

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

Methods

Equals(Hint)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Hint other)

Parameters

other Hint

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

GetBooleanValue(bool)

Gets a boolean value representation of the value of the hint

public bool GetBooleanValue(bool defaultValue)

Parameters

defaultValue bool

A value to use if the hint value does not exist

Returns

bool

defaultValue if the hint value is null or empty; otherwise, true if the hint value is neither "0" nor "false"; otherwise, false

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

ResetValueForAll()

Reset all hints to their default value

public static void ResetValueForAll()

Remarks

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

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

TryFormat(Span<char>, out int)

Tries to format the value of the current instance into the provided span of characters.

public bool TryFormat(Span<char> destination, out int charsWritten)

Parameters

destination Span<char>

The span in which to write this instance's value formatted as a span of characters.

charsWritten int

When this method returns, contains the number of characters that were written in destination.

Returns

bool

true if the formatting was successful; otherwise, false.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

TryGetValue(out string?)

Tries to retrieve the value of the hint

public bool TryGetValue(out string? value)

Parameters

value string

The value of the hint, or null if the value of the hint does not exist

Returns

bool

true if the hint has a value set; otherwise, false

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

TryResetValue()

Tries to reset the hint to its default value

public bool TryResetValue()

Returns

bool

true if the hint was successfully reset to its default value; otherwise, false (check TryGet(out string?) for more information)

Remarks

This will reset a hint to the value of the associated environment variable, or null if the environment isn't set. The ValueChanged event will be raised normally with this change.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

TrySetValue(string?)

Tries to set the value of the hint with normal priority.

public bool TrySetValue(string? value)

Parameters

value string

The value to assign to the hint; use null to indicate that the hint has no value set

Returns

bool

true if the value of the hint was successfully set; otherwise, false (check TryGet(out string?) for more information)

Remarks

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

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

TrySetValue(string?, HintPriority)

Tries to set the value of the hint with a specific priority

public bool TrySetValue(string? value, HintPriority priority)

Parameters

value string

The value to assign to the hint; use null to indicate that the hint has no value set

priority HintPriority

The priority of the hint

Returns

bool

true if the value of the hint was successfully set; otherwise, false (check TryGet(out string?) for more information)

Remarks

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

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

Events

ValueChanged

Raised when the value of a hint has changed

public event HintValueChangedEventHandler? ValueChanged

Event Type

HintValueChangedEventHandler

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

Operators

operator ==(Hint, Hint)

Compares two values to determine equality.

public static bool operator ==(Hint left, Hint right)

Parameters

left Hint

The value to compare with right.

right Hint

The value to compare with left.

Returns

bool

true if left is equal to right; otherwise, false.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters

operator !=(Hint, Hint)

Compares two values to determine inequality.

public static bool operator !=(Hint left, Hint right)

Parameters

left Hint

The value to compare with right.

right Hint

The value to compare with left.

Returns

bool

true if left is not equal to right; otherwise, false.

Exceptions

ArgumentException

name is either null, empty, or consists only of white-space characters