sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Keyboard

Description

SDL keyboard management.

Please refer to the Best Keyboard Practices document for details on how best to accept keyboard input in various types of programs:

https://wiki.libsdl.org/SDL3/BestKeyboardPractices This is a unique ID for a keyboard for the time it is connected to the system, and is never reused for the lifetime of the application.

If the keyboard is disconnected and reconnected, it will get a new ID.

The value 0 is an invalid ID.

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Keyboard.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Since: 3.2.0

Synopsis

Documentation

Function aliases

hasKeyboard :: IO Bool Source #

Return whether a keyboard is currently connected.

Returns
true if a keyboard is connected, false otherwise.
Thread safety
This function should only be called on the main thread.
See also
getKeyboards

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_HasKeyboard. The safe flavor is hasKeyboardSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_HasKeyboard, defined at SDL3/SDL_keyboard.h 75:34

Since: 3.2.0

hasKeyboardSafe :: IO Bool Source #

Return whether a keyboard is currently connected.

Returns
true if a keyboard is connected, false otherwise.
Thread safety
This function should only be called on the main thread.
See also
getKeyboards

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_HasKeyboard. The unsafe flavor is hasKeyboard .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_HasKeyboard, defined at SDL3/SDL_keyboard.h 75:34

Since: 3.2.0

getKeyboards Source #

Arguments

:: Ptr CInt
count
a pointer filled in with the number of keyboards returned, may be NULL.
-> IO (Ptr SDL_KeyboardID) 

Get a list of currently connected keyboards.

Note that this will include any device or virtual driver that includes keyboard functionality, including some mice, KVM switches, motherboard power buttons, etc. You should wait for input from a device before you consider it actively in use.

Returns
a 0 terminated array of keyboards instance IDs or NULL on failure; call getError for more information. This should be freed with free when it is no longer needed.
Thread safety
This function should only be called on the main thread.
See also
getKeyboardNameForID, hasKeyboard

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyboards. The safe flavor is getKeyboardsSafe .
C declaration
SDL_GetKeyboards, defined at SDL3/SDL_keyboard.h 98:46

Since: 3.2.0

getKeyboardsSafe Source #

Arguments

:: Ptr CInt
count
a pointer filled in with the number of keyboards returned, may be NULL.
-> IO (Ptr SDL_KeyboardID) 

Get a list of currently connected keyboards.

Note that this will include any device or virtual driver that includes keyboard functionality, including some mice, KVM switches, motherboard power buttons, etc. You should wait for input from a device before you consider it actively in use.

Returns
a 0 terminated array of keyboards instance IDs or NULL on failure; call getError for more information. This should be freed with free when it is no longer needed.
Thread safety
This function should only be called on the main thread.
See also
getKeyboardNameForID, hasKeyboard

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyboards. The unsafe flavor is getKeyboards .
C declaration
SDL_GetKeyboards, defined at SDL3/SDL_keyboard.h 98:46

Since: 3.2.0

getKeyboardNameForID Source #

Arguments

:: SDL_KeyboardID
instance_id
the keyboard instance ID.
-> IO (PtrConst CChar) 

Get the name of a keyboard.

This function returns "" if the keyboard doesn't have a name.

Returns
the name of the selected keyboard or NULL on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
getKeyboards

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyboardNameForID. The safe flavor is getKeyboardNameForIDSafe .
C declaration
SDL_GetKeyboardNameForID, defined at SDL3/SDL_keyboard.h 115:42

Since: 3.2.0

getKeyboardNameForIDSafe Source #

Arguments

:: SDL_KeyboardID
instance_id
the keyboard instance ID.
-> IO (PtrConst CChar) 

Get the name of a keyboard.

This function returns "" if the keyboard doesn't have a name.

Returns
the name of the selected keyboard or NULL on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
getKeyboards

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyboardNameForID. The unsafe flavor is getKeyboardNameForID .
C declaration
SDL_GetKeyboardNameForID, defined at SDL3/SDL_keyboard.h 115:42

Since: 3.2.0

getKeyboardFocus :: IO (Ptr SDL_Window) Source #

Query the window which currently has keyboard focus.

Returns
the window with keyboard focus.
Thread safety
This function should only be called on the main thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyboardFocus. The safe flavor is getKeyboardFocusSafe .
C declaration
SDL_GetKeyboardFocus, defined at SDL3/SDL_keyboard.h 126:42

Since: 3.2.0

getKeyboardFocusSafe :: IO (Ptr SDL_Window) Source #

Query the window which currently has keyboard focus.

Returns
the window with keyboard focus.
Thread safety
This function should only be called on the main thread.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyboardFocus. The unsafe flavor is getKeyboardFocus .
C declaration
SDL_GetKeyboardFocus, defined at SDL3/SDL_keyboard.h 126:42

Since: 3.2.0

getKeyboardState Source #

Arguments

:: Ptr CInt
numkeys
if non-NULL, receives the length of the returned array.
-> IO (PtrConst CBool) 

Get a snapshot of the current state of the keyboard.

The pointer returned is a pointer to an internal SDL array. It will be valid for the whole lifetime of the application and should not be freed by the caller.

A array element with a value of true means that the key is pressed and a value of false means that it is not. Indexes into this array are obtained by using SDL_Scancode values.

Use pumpEvents to update the state array.

This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you process events, then the pressed state will never show up in the getKeyboardState calls.

Note: This function doesn't take into account whether shift has been pressed or not.

Returns
a pointer to an array of key states.
Thread safety
It is safe to call this function from any thread.
See also
pumpEvents, resetKeyboard

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyboardState. The safe flavor is getKeyboardStateSafe .
C declaration
SDL_GetKeyboardState, defined at SDL3/SDL_keyboard.h 159:42

Since: 3.2.0

getKeyboardStateSafe Source #

Arguments

:: Ptr CInt
numkeys
if non-NULL, receives the length of the returned array.
-> IO (PtrConst CBool) 

Get a snapshot of the current state of the keyboard.

The pointer returned is a pointer to an internal SDL array. It will be valid for the whole lifetime of the application and should not be freed by the caller.

A array element with a value of true means that the key is pressed and a value of false means that it is not. Indexes into this array are obtained by using SDL_Scancode values.

Use pumpEvents to update the state array.

This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you process events, then the pressed state will never show up in the getKeyboardState calls.

Note: This function doesn't take into account whether shift has been pressed or not.

Returns
a pointer to an array of key states.
Thread safety
It is safe to call this function from any thread.
See also
pumpEvents, resetKeyboard

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyboardState. The unsafe flavor is getKeyboardState .
C declaration
SDL_GetKeyboardState, defined at SDL3/SDL_keyboard.h 159:42

Since: 3.2.0

resetKeyboard :: IO () Source #

Clear the state of the keyboard.

This function will generate key up events for all pressed keys.

Thread safety
This function should only be called on the main thread.
See also
getKeyboardState

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ResetKeyboard. The safe flavor is resetKeyboardSafe .
C declaration
SDL_ResetKeyboard, defined at SDL3/SDL_keyboard.h 172:34

Since: 3.2.0

resetKeyboardSafe :: IO () Source #

Clear the state of the keyboard.

This function will generate key up events for all pressed keys.

Thread safety
This function should only be called on the main thread.
See also
getKeyboardState

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ResetKeyboard. The unsafe flavor is resetKeyboard .
C declaration
SDL_ResetKeyboard, defined at SDL3/SDL_keyboard.h 172:34

Since: 3.2.0

getModState :: IO SDL_Keymod Source #

Get the current key modifier state for the keyboard.

Returns
an OR'd combination of the modifier keys for the keyboard.
Thread safety
It is safe to call this function from any thread.
See also
getKeyboardState, setModState

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetModState. The safe flavor is getModStateSafe .
C declaration
SDL_GetModState, defined at SDL3/SDL_keyboard.h 186:40

Since: 3.2.0

getModStateSafe :: IO SDL_Keymod Source #

Get the current key modifier state for the keyboard.

Returns
an OR'd combination of the modifier keys for the keyboard.
Thread safety
It is safe to call this function from any thread.
See also
getKeyboardState, setModState

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetModState. The unsafe flavor is getModState .
C declaration
SDL_GetModState, defined at SDL3/SDL_keyboard.h 186:40

Since: 3.2.0

setModState Source #

Arguments

:: SDL_Keymod
modstate
the desired SDL_Keymod for the keyboard.
-> IO () 

Set the current key modifier state for the keyboard.

The inverse of getModState, setModState allows you to impose modifier key states on your application. Simply pass your desired modifier states into modstate. This value may be a bitwise, OR'd combination of SDL_Keymod values.

This does not change the keyboard state, only the key modifier flags that SDL reports.

Thread safety
It is safe to call this function from any thread.
See also
getModState

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetModState. The safe flavor is setModStateSafe .
C declaration
SDL_SetModState, defined at SDL3/SDL_keyboard.h 207:34

Since: 3.2.0

setModStateSafe Source #

Arguments

:: SDL_Keymod
modstate
the desired SDL_Keymod for the keyboard.
-> IO () 

Set the current key modifier state for the keyboard.

The inverse of getModState, setModState allows you to impose modifier key states on your application. Simply pass your desired modifier states into modstate. This value may be a bitwise, OR'd combination of SDL_Keymod values.

This does not change the keyboard state, only the key modifier flags that SDL reports.

Thread safety
It is safe to call this function from any thread.
See also
getModState

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetModState. The unsafe flavor is setModState .
C declaration
SDL_SetModState, defined at SDL3/SDL_keyboard.h 207:34

Since: 3.2.0

getKeyFromScancode Source #

Arguments

:: SDL_Scancode
scancode
the desired SDL_Scancode to query.
-> SDL_Keymod
modstate
the modifier state to use when translating the scancode to a keycode.
-> Bool
key_event
true if the keycode will be used in key events.
-> IO SDL_Keycode 

Get the key code corresponding to the given scancode according to the current keyboard layout.

If you want to get the keycode as it would be delivered in key events, including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should pass key_event as true. Otherwise this function simply translates the scancode based on the given modifier state.

Returns
the SDL_Keycode that corresponds to the given SDL_Scancode.
Thread safety
This function is not thread safe.
See also
getKeyName, getScancodeFromKey

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyFromScancode. The safe flavor is getKeyFromScancodeSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetKeyFromScancode, defined at SDL3/SDL_keyboard.h 231:41

Since: 3.2.0

getKeyFromScancodeSafe Source #

Arguments

:: SDL_Scancode
scancode
the desired SDL_Scancode to query.
-> SDL_Keymod
modstate
the modifier state to use when translating the scancode to a keycode.
-> Bool
key_event
true if the keycode will be used in key events.
-> IO SDL_Keycode 

Get the key code corresponding to the given scancode according to the current keyboard layout.

If you want to get the keycode as it would be delivered in key events, including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should pass key_event as true. Otherwise this function simply translates the scancode based on the given modifier state.

Returns
the SDL_Keycode that corresponds to the given SDL_Scancode.
Thread safety
This function is not thread safe.
See also
getKeyName, getScancodeFromKey

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyFromScancode. The unsafe flavor is getKeyFromScancode .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetKeyFromScancode, defined at SDL3/SDL_keyboard.h 231:41

Since: 3.2.0

getScancodeFromKey Source #

Arguments

:: SDL_Keycode
key
the desired SDL_Keycode to query.
-> Ptr SDL_Keymod
modstate
a pointer to the modifier state that would be used when the scancode generates this key, may be NULL.
-> IO SDL_Scancode 

Get the scancode corresponding to the given key code according to the current keyboard layout.

Note that there may be multiple scancode+modifier states that can generate this keycode, this will just return the first one found.

Returns
the SDL_Scancode that corresponds to the given SDL_Keycode.
Thread safety
This function is not thread safe.
See also
getKeyFromScancode, getScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetScancodeFromKey. The safe flavor is getScancodeFromKeySafe .
C declaration
SDL_GetScancodeFromKey, defined at SDL3/SDL_keyboard.h 252:42

Since: 3.2.0

getScancodeFromKeySafe Source #

Arguments

:: SDL_Keycode
key
the desired SDL_Keycode to query.
-> Ptr SDL_Keymod
modstate
a pointer to the modifier state that would be used when the scancode generates this key, may be NULL.
-> IO SDL_Scancode 

Get the scancode corresponding to the given key code according to the current keyboard layout.

Note that there may be multiple scancode+modifier states that can generate this keycode, this will just return the first one found.

Returns
the SDL_Scancode that corresponds to the given SDL_Keycode.
Thread safety
This function is not thread safe.
See also
getKeyFromScancode, getScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetScancodeFromKey. The unsafe flavor is getScancodeFromKey .
C declaration
SDL_GetScancodeFromKey, defined at SDL3/SDL_keyboard.h 252:42

Since: 3.2.0

setScancodeName Source #

Arguments

:: SDL_Scancode
scancode
the desired SDL_Scancode.
-> PtrConst CChar
name
the name to use for the scancode, encoded as UTF-8. The string is not copied, so the pointer given to this function must stay valid while SDL is being used.
-> IO Bool 

Set a human-readable name for a scancode.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function is not thread safe.
See also
getScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetScancodeName. The safe flavor is setScancodeNameSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetScancodeName, defined at SDL3/SDL_keyboard.h 270:34

Since: 3.2.0

setScancodeNameSafe Source #

Arguments

:: SDL_Scancode
scancode
the desired SDL_Scancode.
-> PtrConst CChar
name
the name to use for the scancode, encoded as UTF-8. The string is not copied, so the pointer given to this function must stay valid while SDL is being used.
-> IO Bool 

Set a human-readable name for a scancode.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function is not thread safe.
See also
getScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetScancodeName. The unsafe flavor is setScancodeName .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetScancodeName, defined at SDL3/SDL_keyboard.h 270:34

Since: 3.2.0

getScancodeName Source #

Arguments

:: SDL_Scancode
scancode
the desired SDL_Scancode to query.
-> IO (PtrConst CChar) 

Get a human-readable name for a scancode.

Warning: The returned name is by design not stable across platforms, e.g. the name for SDL_SCANCODE_LGUI is "Left GUI" under Linux but "Left Windows" under Microsoft Windows, and some scancodes like SDL_SCANCODE_NONUSBACKSLASH don't have any name at all. There are even scancodes that share names, e.g. SDL_SCANCODE_RETURN and SDL_SCANCODE_RETURN2 (both called "Return"). This function is therefore unsuitable for creating a stable cross-platform two-way mapping between strings and scancodes.

Returns
a pointer to the name for the scancode. If the scancode doesn't have a name this function returns an empty string ("").
Thread safety
This function is not thread safe.
See also
getScancodeFromKey, getScancodeFromName, setScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetScancodeName. The safe flavor is getScancodeNameSafe .
C declaration
SDL_GetScancodeName, defined at SDL3/SDL_keyboard.h 296:42

Since: 3.2.0

getScancodeNameSafe Source #

Arguments

:: SDL_Scancode
scancode
the desired SDL_Scancode to query.
-> IO (PtrConst CChar) 

Get a human-readable name for a scancode.

Warning: The returned name is by design not stable across platforms, e.g. the name for SDL_SCANCODE_LGUI is "Left GUI" under Linux but "Left Windows" under Microsoft Windows, and some scancodes like SDL_SCANCODE_NONUSBACKSLASH don't have any name at all. There are even scancodes that share names, e.g. SDL_SCANCODE_RETURN and SDL_SCANCODE_RETURN2 (both called "Return"). This function is therefore unsuitable for creating a stable cross-platform two-way mapping between strings and scancodes.

Returns
a pointer to the name for the scancode. If the scancode doesn't have a name this function returns an empty string ("").
Thread safety
This function is not thread safe.
See also
getScancodeFromKey, getScancodeFromName, setScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetScancodeName. The unsafe flavor is getScancodeName .
C declaration
SDL_GetScancodeName, defined at SDL3/SDL_keyboard.h 296:42

Since: 3.2.0

getScancodeFromName Source #

Arguments

:: PtrConst CChar
name
the human-readable scancode name.
-> IO SDL_Scancode 

Get a scancode from a human-readable name.

Returns
the SDL_Scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized; call getError for more information.
Thread safety
This function is not thread safe.
See also
getKeyFromName, getScancodeFromKey, getScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetScancodeFromName. The safe flavor is getScancodeFromNameSafe .
C declaration
SDL_GetScancodeFromName, defined at SDL3/SDL_keyboard.h 313:42

Since: 3.2.0

getScancodeFromNameSafe Source #

Arguments

:: PtrConst CChar
name
the human-readable scancode name.
-> IO SDL_Scancode 

Get a scancode from a human-readable name.

Returns
the SDL_Scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized; call getError for more information.
Thread safety
This function is not thread safe.
See also
getKeyFromName, getScancodeFromKey, getScancodeName

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetScancodeFromName. The unsafe flavor is getScancodeFromName .
C declaration
SDL_GetScancodeFromName, defined at SDL3/SDL_keyboard.h 313:42

Since: 3.2.0

getKeyName Source #

Arguments

:: SDL_Keycode
key
the desired SDL_Keycode to query.
-> IO (PtrConst CChar) 

Get a human-readable name for a key.

If the key doesn't have a name, this function returns an empty string ("").

Letters will be presented in their uppercase form, if applicable.

Returns
a UTF-8 encoded string of the key name.
Thread safety
This function is not thread safe.
See also
getKeyFromName, getKeyFromScancode, getScancodeFromKey

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyName. The safe flavor is getKeyNameSafe .
C declaration
SDL_GetKeyName, defined at SDL3/SDL_keyboard.h 333:42

Since: 3.2.0

getKeyNameSafe Source #

Arguments

:: SDL_Keycode
key
the desired SDL_Keycode to query.
-> IO (PtrConst CChar) 

Get a human-readable name for a key.

If the key doesn't have a name, this function returns an empty string ("").

Letters will be presented in their uppercase form, if applicable.

Returns
a UTF-8 encoded string of the key name.
Thread safety
This function is not thread safe.
See also
getKeyFromName, getKeyFromScancode, getScancodeFromKey

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyName. The unsafe flavor is getKeyName .
C declaration
SDL_GetKeyName, defined at SDL3/SDL_keyboard.h 333:42

Since: 3.2.0

getKeyFromName Source #

Arguments

:: PtrConst CChar
name
the human-readable key name.
-> IO SDL_Keycode 

Get a key code from a human-readable name.

Returns
key code, or SDLK_UNKNOWN if the name wasn't recognized; call getError for more information.
Thread safety
This function is not thread safe.
See also
getKeyFromScancode, getKeyName, getScancodeFromName

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetKeyFromName. The safe flavor is getKeyFromNameSafe .
C declaration
SDL_GetKeyFromName, defined at SDL3/SDL_keyboard.h 350:41

Since: 3.2.0

getKeyFromNameSafe Source #

Arguments

:: PtrConst CChar
name
the human-readable key name.
-> IO SDL_Keycode 

Get a key code from a human-readable name.

Returns
key code, or SDLK_UNKNOWN if the name wasn't recognized; call getError for more information.
Thread safety
This function is not thread safe.
See also
getKeyFromScancode, getKeyName, getScancodeFromName

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetKeyFromName. The unsafe flavor is getKeyFromName .
C declaration
SDL_GetKeyFromName, defined at SDL3/SDL_keyboard.h 350:41

Since: 3.2.0

startTextInput Source #

Arguments

:: Ptr SDL_Window
window
the window to enable text input.
-> IO Bool 

Start accepting Unicode text input events in a window.

This function will enable text input (SDL_EVENT_TEXT_INPUT and SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with stopTextInput.

Text input events are not received by default.

On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setTextInputArea, startTextInputWithProperties, stopTextInput, textInputActive

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_StartTextInput. The safe flavor is startTextInputSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StartTextInput, defined at SDL3/SDL_keyboard.h 378:34

Since: 3.2.0

startTextInputSafe Source #

Arguments

:: Ptr SDL_Window
window
the window to enable text input.
-> IO Bool 

Start accepting Unicode text input events in a window.

This function will enable text input (SDL_EVENT_TEXT_INPUT and SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with stopTextInput.

Text input events are not received by default.

On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setTextInputArea, startTextInputWithProperties, stopTextInput, textInputActive

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_StartTextInput. The unsafe flavor is startTextInput .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StartTextInput, defined at SDL3/SDL_keyboard.h 378:34

Since: 3.2.0

startTextInputWithProperties Source #

Arguments

:: Ptr SDL_Window
window
the window to enable text input.
-> SDL_PropertiesID
props
the properties to use.
-> IO Bool 

Start accepting Unicode text input events in a window, with properties describing the input.

This function will enable text input (SDL_EVENT_TEXT_INPUT and SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with stopTextInput.

Text input events are not received by default.

On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.

These are the supported properties:

On Android you can directly specify the input type:

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setTextInputArea, startTextInput, stopTextInput, textInputActive

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_StartTextInputWithProperties. The safe flavor is startTextInputWithPropertiesSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StartTextInputWithProperties, defined at SDL3/SDL_keyboard.h 473:34

Since: 3.2.0

startTextInputWithPropertiesSafe Source #

Arguments

:: Ptr SDL_Window
window
the window to enable text input.
-> SDL_PropertiesID
props
the properties to use.
-> IO Bool 

Start accepting Unicode text input events in a window, with properties describing the input.

This function will enable text input (SDL_EVENT_TEXT_INPUT and SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with stopTextInput.

Text input events are not received by default.

On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.

These are the supported properties:

On Android you can directly specify the input type:

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setTextInputArea, startTextInput, stopTextInput, textInputActive

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_StartTextInputWithProperties. The unsafe flavor is startTextInputWithProperties .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StartTextInputWithProperties, defined at SDL3/SDL_keyboard.h 473:34

Since: 3.2.0

textInputActive Source #

Arguments

:: Ptr SDL_Window
window
the window to check.
-> IO Bool 

Check whether or not Unicode text input events are enabled for a window.

Returns
true if text input events are enabled else false.
Thread safety
This function should only be called on the main thread.
See also
startTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_TextInputActive. The safe flavor is textInputActiveSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_TextInputActive, defined at SDL3/SDL_keyboard.h 493:34

Since: 3.2.0

textInputActiveSafe Source #

Arguments

:: Ptr SDL_Window
window
the window to check.
-> IO Bool 

Check whether or not Unicode text input events are enabled for a window.

Returns
true if text input events are enabled else false.
Thread safety
This function should only be called on the main thread.
See also
startTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_TextInputActive. The unsafe flavor is textInputActive .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_TextInputActive, defined at SDL3/SDL_keyboard.h 493:34

Since: 3.2.0

stopTextInput Source #

Arguments

:: Ptr SDL_Window
window
the window to disable text input.
-> IO Bool 

Stop receiving any text input events in a window.

If startTextInput showed the screen keyboard, this function will hide it.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
startTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_StopTextInput. The safe flavor is stopTextInputSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StopTextInput, defined at SDL3/SDL_keyboard.h 511:34

Since: 3.2.0

stopTextInputSafe Source #

Arguments

:: Ptr SDL_Window
window
the window to disable text input.
-> IO Bool 

Stop receiving any text input events in a window.

If startTextInput showed the screen keyboard, this function will hide it.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
startTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_StopTextInput. The unsafe flavor is stopTextInput .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_StopTextInput, defined at SDL3/SDL_keyboard.h 511:34

Since: 3.2.0

clearComposition Source #

Arguments

:: Ptr SDL_Window
window
the window to affect.
-> IO Bool 

Dismiss the composition window/IME without disabling the subsystem.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
startTextInput, stopTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ClearComposition. The safe flavor is clearCompositionSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ClearComposition, defined at SDL3/SDL_keyboard.h 527:34

Since: 3.2.0

clearCompositionSafe Source #

Arguments

:: Ptr SDL_Window
window
the window to affect.
-> IO Bool 

Dismiss the composition window/IME without disabling the subsystem.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
startTextInput, stopTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ClearComposition. The unsafe flavor is clearComposition .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ClearComposition, defined at SDL3/SDL_keyboard.h 527:34

Since: 3.2.0

setTextInputArea Source #

Arguments

:: Ptr SDL_Window
window
the window for which to set the text input area.
-> PtrConst SDL_Rect
rect
the SDL_Rect representing the text input area, in window coordinates, or NULL to clear it.
-> Int32
cursor
the offset of the current cursor location relative to rect->x, in window coordinates.
-> IO Bool 

Set the area used to type Unicode text input.

Native input methods may place a window with word suggestions near the cursor, without covering the text being entered.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
getTextInputArea, startTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetTextInputArea. The safe flavor is setTextInputAreaSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetTextInputArea, defined at SDL3/SDL_keyboard.h 550:34

Since: 3.2.0

setTextInputAreaSafe Source #

Arguments

:: Ptr SDL_Window
window
the window for which to set the text input area.
-> PtrConst SDL_Rect
rect
the SDL_Rect representing the text input area, in window coordinates, or NULL to clear it.
-> Int32
cursor
the offset of the current cursor location relative to rect->x, in window coordinates.
-> IO Bool 

Set the area used to type Unicode text input.

Native input methods may place a window with word suggestions near the cursor, without covering the text being entered.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
getTextInputArea, startTextInput

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetTextInputArea. The unsafe flavor is setTextInputArea .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_SetTextInputArea, defined at SDL3/SDL_keyboard.h 550:34

Since: 3.2.0

getTextInputArea Source #

Arguments

:: Ptr SDL_Window
window
the window for which to query the text input area.
-> Ptr SDL_Rect
rect
a pointer to an SDL_Rect filled in with the text input area, may be NULL.
-> Ptr CInt
cursor
a pointer to the offset of the current cursor location relative to rect->x, may be NULL.
-> IO Bool 

Get the area used to type Unicode text input.

This returns the values previously set by setTextInputArea.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setTextInputArea

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetTextInputArea. The safe flavor is getTextInputAreaSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetTextInputArea, defined at SDL3/SDL_keyboard.h 571:34

Since: 3.2.0

getTextInputAreaSafe Source #

Arguments

:: Ptr SDL_Window
window
the window for which to query the text input area.
-> Ptr SDL_Rect
rect
a pointer to an SDL_Rect filled in with the text input area, may be NULL.
-> Ptr CInt
cursor
a pointer to the offset of the current cursor location relative to rect->x, may be NULL.
-> IO Bool 

Get the area used to type Unicode text input.

This returns the values previously set by setTextInputArea.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setTextInputArea

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetTextInputArea. The unsafe flavor is getTextInputArea .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_GetTextInputArea, defined at SDL3/SDL_keyboard.h 571:34

Since: 3.2.0

hasScreenKeyboardSupport :: IO Bool Source #

Check whether the platform has screen keyboard support.

Returns
true if the platform has some screen keyboard support or false if not.
Thread safety
This function should only be called on the main thread.
See also
startTextInput, screenKeyboardShown

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_HasScreenKeyboardSupport. The safe flavor is hasScreenKeyboardSupportSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_HasScreenKeyboardSupport, defined at SDL3/SDL_keyboard.h 586:34

Since: 3.2.0

hasScreenKeyboardSupportSafe :: IO Bool Source #

Check whether the platform has screen keyboard support.

Returns
true if the platform has some screen keyboard support or false if not.
Thread safety
This function should only be called on the main thread.
See also
startTextInput, screenKeyboardShown

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_HasScreenKeyboardSupport. The unsafe flavor is hasScreenKeyboardSupport .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_HasScreenKeyboardSupport, defined at SDL3/SDL_keyboard.h 586:34

Since: 3.2.0

screenKeyboardShown Source #

Arguments

:: Ptr SDL_Window
window
the window for which screen keyboard should be queried.
-> IO Bool 

Check whether the screen keyboard is shown for given window.

Returns
true if screen keyboard is shown or false if not.
Thread safety
This function should only be called on the main thread.
See also
hasScreenKeyboardSupport

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ScreenKeyboardShown. The safe flavor is screenKeyboardShownSafe .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ScreenKeyboardShown, defined at SDL3/SDL_keyboard.h 600:34

Since: 3.2.0

screenKeyboardShownSafe Source #

Arguments

:: Ptr SDL_Window
window
the window for which screen keyboard should be queried.
-> IO Bool 

Check whether the screen keyboard is shown for given window.

Returns
true if screen keyboard is shown or false if not.
Thread safety
This function should only be called on the main thread.
See also
hasScreenKeyboardSupport

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ScreenKeyboardShown. The unsafe flavor is screenKeyboardShown .
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ScreenKeyboardShown, defined at SDL3/SDL_keyboard.h 600:34

Since: 3.2.0