sdl3_sys/generated/
locale.rs

1//! SDL locale services.
2//!
3//! This provides a way to get a list of preferred locales (language plus
4//! country) for the user. There is exactly one function:
5//! [`SDL_GetPreferredLocales()`], which handles all the heavy lifting, and offers
6//! documentation on all the strange ways humans might have configured their
7//! language settings.
8
9use super::stdinc::*;
10
11use super::error::*;
12
13/// A struct to provide locale data.
14///
15/// Locale data is split into a spoken language, like English, and an optional
16/// country, like Canada. The language will be in ISO-639 format (so English
17/// would be "en"), and the country, if not NULL, will be an ISO-3166 country
18/// code (so Canada would be "CA").
19///
20/// ## Availability
21/// This function is available since SDL 3.2.0.
22///
23/// ## See also
24/// - [`SDL_GetPreferredLocales`]
25#[repr(C)]
26#[derive(Clone, Copy)]
27#[cfg_attr(feature = "debug-impls", derive(Debug))]
28pub struct SDL_Locale {
29    /// A language name, like "en" for English.
30    pub language: *const ::core::ffi::c_char,
31    /// A country, like "US" for America. Can be NULL.
32    pub country: *const ::core::ffi::c_char,
33}
34
35impl ::core::default::Default for SDL_Locale {
36    /// Initialize all fields to zero
37    #[inline(always)]
38    fn default() -> Self {
39        unsafe { ::core::mem::MaybeUninit::<Self>::zeroed().assume_init() }
40    }
41}
42
43unsafe extern "C" {
44    /// Report the user's preferred locale.
45    ///
46    /// Returned language strings are in the format xx, where 'xx' is an ISO-639
47    /// language specifier (such as "en" for English, "de" for German, etc).
48    /// Country strings are in the format YY, where "YY" is an ISO-3166 country
49    /// code (such as "US" for the United States, "CA" for Canada, etc). Country
50    /// might be NULL if there's no specific guidance on them (so you might get {
51    /// "en", "US" } for American English, but { "en", NULL } means "English
52    /// language, generically"). Language strings are never NULL, except to
53    /// terminate the array.
54    ///
55    /// Please note that not all of these strings are 2 characters; some are three
56    /// or more.
57    ///
58    /// The returned list of locales are in the order of the user's preference. For
59    /// example, a German citizen that is fluent in US English and knows enough
60    /// Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
61    /// "jp", NULL }. Someone from England might prefer British English (where
62    /// "color" is spelled "colour", etc), but will settle for anything like it: {
63    /// "en_GB", "en", NULL }.
64    ///
65    /// This function returns NULL on error, including when the platform does not
66    /// supply this information at all.
67    ///
68    /// This might be a "slow" call that has to query the operating system. It's
69    /// best to ask for this once and save the results. However, this list can
70    /// change, usually because the user has changed a system preference outside of
71    /// your program; SDL will send an [`SDL_EVENT_LOCALE_CHANGED`] event in this case,
72    /// if possible, and you can call this function again to get an updated copy of
73    /// preferred locales.
74    ///
75    /// ## Parameters
76    /// - `count`: a pointer filled in with the number of locales returned, may
77    ///   be NULL.
78    ///
79    /// ## Return value
80    /// Returns a NULL terminated array of locale pointers, or NULL on failure;
81    ///   call [`SDL_GetError()`] for more information. This is a single
82    ///   allocation that should be freed with [`SDL_free()`] when it is no
83    ///   longer needed.
84    ///
85    /// ## Thread safety
86    /// This function is not thread safe.
87    ///
88    /// ## Availability
89    /// This function is available since SDL 3.2.0.
90    pub fn SDL_GetPreferredLocales(count: *mut ::core::ffi::c_int) -> *mut *mut SDL_Locale;
91}
92
93#[cfg(doc)]
94use crate::everything::*;
sdl3_sys/generated/locale.rs

sdl3_sys/generated/
locale.rs
