pango/auto/language.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, Script};
6use glib::translate::*;
7
8glib::wrapper! {
9 /// The [`Language`][crate::Language] structure is used to
10 /// represent a language.
11 ///
12 /// [`Language`][crate::Language] pointers can be efficiently
13 /// copied and compared with each other.
14 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
15 pub struct Language(Boxed<ffi::PangoLanguage>);
16
17 match fn {
18 copy => |ptr| glib::gobject_ffi::g_boxed_copy(ffi::pango_language_get_type(), ptr as *mut _) as *mut ffi::PangoLanguage,
19 free => |ptr| glib::gobject_ffi::g_boxed_free(ffi::pango_language_get_type(), ptr as *mut _),
20 type_ => || ffi::pango_language_get_type(),
21 }
22}
23
24impl Language {
25 /// Get a string that is representative of the characters needed to
26 /// render a particular language.
27 ///
28 /// The sample text may be a pangram, but is not necessarily. It is chosen
29 /// to be demonstrative of normal text in the language, as well as exposing
30 /// font feature requirements unique to the language. It is suitable for use
31 /// as sample text in a font selection dialog.
32 ///
33 /// If @self is [`None`], the default language as found by
34 /// [`default()`][Self::default()] is used.
35 ///
36 /// If Pango does not have a sample string for @self, the classic
37 /// "The quick brown fox..." is returned. This can be detected by
38 /// comparing the returned pointer value to that returned for (non-existent)
39 /// language code "xx". That is, compare to:
40 ///
41 /// ```text
42 /// pango_language_get_sample_string (pango_language_from_string ("xx"))
43 /// ```
44 ///
45 /// # Returns
46 ///
47 /// the sample string
48 #[doc(alias = "pango_language_get_sample_string")]
49 #[doc(alias = "get_sample_string")]
50 pub fn sample_string(&self) -> glib::GString {
51 unsafe {
52 from_glib_none(ffi::pango_language_get_sample_string(mut_override(
53 self.to_glib_none().0,
54 )))
55 }
56 }
57
58 /// Determines if @script is one of the scripts used to
59 /// write @self.
60 ///
61 /// The returned value is conservative; if nothing is known about
62 /// the language tag @self, [`true`] will be returned, since, as
63 /// far as Pango knows, @script might be used to write @self.
64 ///
65 /// This routine is used in Pango's itemization process when
66 /// determining if a supplied language tag is relevant to
67 /// a particular section of text. It probably is not useful
68 /// for applications in most circumstances.
69 ///
70 /// This function uses [`scripts()`][Self::scripts()] internally.
71 /// ## `script`
72 /// a [`Script`][crate::Script]
73 ///
74 /// # Returns
75 ///
76 /// [`true`] if @script is one of the scripts used
77 /// to write @self or if nothing is known about @self
78 /// (including the case that @self is [`None`]), [`false`] otherwise.
79 #[doc(alias = "pango_language_includes_script")]
80 pub fn includes_script(&self, script: Script) -> bool {
81 unsafe {
82 from_glib(ffi::pango_language_includes_script(
83 mut_override(self.to_glib_none().0),
84 script.into_glib(),
85 ))
86 }
87 }
88
89 /// Checks if a language tag matches one of the elements in a list of
90 /// language ranges.
91 ///
92 /// A language tag is considered to match a range in the list if the
93 /// range is '*', the range is exactly the tag, or the range is a prefix
94 /// of the tag, and the character after it in the tag is '-'.
95 /// ## `range_list`
96 /// a list of language ranges, separated by ';', ':',
97 /// ',', or space characters.
98 /// Each element must either be '*', or a RFC 3066 language range
99 /// canonicalized as by [`from_string()`][Self::from_string()]
100 ///
101 /// # Returns
102 ///
103 /// [`true`] if a match was found
104 #[doc(alias = "pango_language_matches")]
105 pub fn matches(&self, range_list: &str) -> bool {
106 unsafe {
107 from_glib(ffi::pango_language_matches(
108 mut_override(self.to_glib_none().0),
109 range_list.to_glib_none().0,
110 ))
111 }
112 }
113
114 /// Gets the RFC-3066 format string representing the given language tag.
115 ///
116 /// Returns (transfer none): a string representing the language tag
117 #[doc(alias = "pango_language_to_string")]
118 #[doc(alias = "to_string")]
119 pub fn to_str(&self) -> glib::GString {
120 unsafe {
121 from_glib_none(ffi::pango_language_to_string(mut_override(
122 self.to_glib_none().0,
123 )))
124 }
125 }
126
127 /// Convert a language tag to a [`Language`][crate::Language].
128 ///
129 /// The language tag must be in a RFC-3066 format. [`Language`][crate::Language] pointers
130 /// can be efficiently copied (copy the pointer) and compared with other
131 /// language tags (compare the pointer.)
132 ///
133 /// This function first canonicalizes the string by converting it to
134 /// lowercase, mapping '_' to '-', and stripping all characters other
135 /// than letters and '-'.
136 ///
137 /// Use [`default()`][Self::default()] if you want to get the
138 /// [`Language`][crate::Language] for the current locale of the process.
139 /// ## `language`
140 /// a string representing a language tag
141 ///
142 /// # Returns
143 ///
144 /// a [`Language`][crate::Language]
145 #[doc(alias = "pango_language_from_string")]
146 pub fn from_string(language: &str) -> Language {
147 unsafe { from_glib_none(ffi::pango_language_from_string(language.to_glib_none().0)) }
148 }
149
150 /// Returns the [`Language`][crate::Language] for the current locale of the process.
151 ///
152 /// On Unix systems, this is the return value is derived from
153 /// `setlocale (LC_CTYPE, NULL)`, and the user can
154 /// affect this through the environment variables LC_ALL, LC_CTYPE or
155 /// LANG (checked in that order). The locale string typically is in
156 /// the form lang_COUNTRY, where lang is an ISO-639 language code, and
157 /// COUNTRY is an ISO-3166 country code. For instance, sv_FI for
158 /// Swedish as written in Finland or pt_BR for Portuguese as written in
159 /// Brazil.
160 ///
161 /// On Windows, the C library does not use any such environment
162 /// variables, and setting them won't affect the behavior of functions
163 /// like ctime(). The user sets the locale through the Regional Options
164 /// in the Control Panel. The C library (in the setlocale() function)
165 /// does not use country and language codes, but country and language
166 /// names spelled out in English.
167 /// However, this function does check the above environment
168 /// variables, and does return a Unix-style locale string based on
169 /// either said environment variables or the thread's current locale.
170 ///
171 /// Your application should call `setlocale(LC_ALL, "")` for the user
172 /// settings to take effect. GTK does this in its initialization
173 /// functions automatically (by calling gtk_set_locale()).
174 /// See the setlocale() manpage for more details.
175 ///
176 /// Note that the default language can change over the life of an application.
177 ///
178 /// Also note that this function will not do the right thing if you
179 /// use per-thread locales with uselocale(). In that case, you should
180 /// just call pango_language_from_string() yourself.
181 ///
182 /// # Returns
183 ///
184 /// the default language as a [`Language`][crate::Language]
185 #[doc(alias = "pango_language_get_default")]
186 #[doc(alias = "get_default")]
187 #[allow(clippy::should_implement_trait)]
188 pub fn default() -> Language {
189 unsafe { from_glib_none(ffi::pango_language_get_default()) }
190 }
191
192 /// Returns the list of languages that the user prefers.
193 ///
194 /// The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE`
195 /// environment variables, in order of preference. Note that this
196 /// list does not necessarily include the language returned by
197 /// [`default()`][Self::default()].
198 ///
199 /// When choosing language-specific resources, such as the sample
200 /// text returned by [`sample_string()`][Self::sample_string()],
201 /// you should first try the default language, followed by the
202 /// languages returned by this function.
203 ///
204 /// # Returns
205 ///
206 /// a [`None`]-terminated array
207 /// of [`Language`][crate::Language]*
208 #[cfg(feature = "v1_48")]
209 #[cfg_attr(docsrs, doc(cfg(feature = "v1_48")))]
210 #[doc(alias = "pango_language_get_preferred")]
211 #[doc(alias = "get_preferred")]
212 pub fn preferred() -> Vec<Language> {
213 unsafe { FromGlibPtrContainer::from_glib_none(ffi::pango_language_get_preferred()) }
214 }
215}
216
217impl std::fmt::Display for Language {
218 #[inline]
219 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
220 f.write_str(&self.to_str())
221 }
222}