pango/auto/functions.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, AttrList, Direction, Stretch, Style, Variant, Weight};
6use glib::translate::*;
7
8//#[cfg_attr(feature = "v1_44", deprecated = "Since 1.44")]
9//#[allow(deprecated)]
10//#[doc(alias = "pango_break")]
11//#[doc(alias = "break")]
12//pub fn break_(text: &str, analysis: &mut Analysis, attrs: /*Ignored*/Vec<LogAttr>) {
13// unsafe { TODO: call ffi:pango_break() }
14//}
15
16//#[doc(alias = "pango_default_break")]
17//pub fn default_break(text: &str, analysis: Option<&mut Analysis>, attrs: /*Ignored*/Vec<LogAttr>) {
18// unsafe { TODO: call ffi:pango_default_break() }
19//}
20
21/// Searches a string the first character that has a strong
22/// direction, according to the Unicode bidirectional algorithm.
23/// ## `text`
24/// the text to process. Must be valid UTF-8
25/// ## `length`
26/// length of @text in bytes (may be -1 if @text is nul-terminated)
27///
28/// # Returns
29///
30/// The direction corresponding to the first strong character.
31/// If no such character is found, then [`Direction::Neutral`][crate::Direction::Neutral] is returned.
32#[doc(alias = "pango_find_base_dir")]
33pub fn find_base_dir(text: &str) -> Direction {
34 let length = text.len() as _;
35 unsafe { from_glib(ffi::pango_find_base_dir(text.to_glib_none().0, length)) }
36}
37
38/// Locates a paragraph boundary in @text.
39///
40/// A boundary is caused by delimiter characters, such as
41/// a newline, carriage return, carriage return-newline pair,
42/// or Unicode paragraph separator character.
43///
44/// The index of the run of delimiters is returned in
45/// @paragraph_delimiter_index. The index of the start of the
46/// next paragraph (index after all delimiters) is stored n
47/// @next_paragraph_start.
48///
49/// If no delimiters are found, both @paragraph_delimiter_index
50/// and @next_paragraph_start are filled with the length of @text
51/// (an index one off the end).
52/// ## `text`
53/// UTF-8 text
54/// ## `length`
55/// length of @text in bytes, or -1 if nul-terminated
56///
57/// # Returns
58///
59///
60/// ## `paragraph_delimiter_index`
61/// return location
62/// for index of delimiter
63///
64/// ## `next_paragraph_start`
65/// return location for
66/// start of next paragraph
67#[doc(alias = "pango_find_paragraph_boundary")]
68pub fn find_paragraph_boundary(text: &str) -> (i32, i32) {
69 let length = text.len() as _;
70 unsafe {
71 let mut paragraph_delimiter_index = std::mem::MaybeUninit::uninit();
72 let mut next_paragraph_start = std::mem::MaybeUninit::uninit();
73 ffi::pango_find_paragraph_boundary(
74 text.to_glib_none().0,
75 length,
76 paragraph_delimiter_index.as_mut_ptr(),
77 next_paragraph_start.as_mut_ptr(),
78 );
79 (
80 paragraph_delimiter_index.assume_init(),
81 next_paragraph_start.assume_init(),
82 )
83 }
84}
85
86//#[doc(alias = "pango_get_log_attrs")]
87//#[doc(alias = "get_log_attrs")]
88//pub fn log_attrs(text: &str, level: i32, language: &mut Language, attrs: /*Ignored*/Vec<LogAttr>) {
89// unsafe { TODO: call ffi:pango_get_log_attrs() }
90//}
91
92/// Checks if a character that should not be normally rendered.
93///
94/// This includes all Unicode characters with "ZERO WIDTH" in their name,
95/// as well as *bidi* formatting characters, and a few other ones.
96///
97/// This is totally different from `unichar_iszerowidth()` and is at best misnamed.
98/// ## `ch`
99/// a Unicode character
100///
101/// # Returns
102///
103/// [`true`] if @ch is a zero-width character, [`false`] otherwise
104#[doc(alias = "pango_is_zero_width")]
105pub fn is_zero_width(ch: char) -> bool {
106 unsafe { from_glib(ffi::pango_is_zero_width(ch.into_glib())) }
107}
108
109/// Finishes parsing markup.
110///
111/// After feeding a Pango markup parser some data with [`glib::MarkupParseContext::parse()`][crate::glib::MarkupParseContext::parse()],
112/// use this function to get the list of attributes and text out of the
113/// markup. This function will not free @context, use `GLib::MarkupParseContext::free()`
114/// to do so.
115/// ## `context`
116/// A valid parse context that was returned from [`markup_parser_new()`][crate::markup_parser_new()]
117///
118/// # Returns
119///
120/// [`false`] if @error is set, otherwise [`true`]
121///
122/// ## `attr_list`
123/// address of return location for a [`AttrList`][crate::AttrList]
124///
125/// ## `text`
126/// address of return location for text with tags stripped
127///
128/// ## `accel_char`
129/// address of return location for accelerator char
130#[doc(alias = "pango_markup_parser_finish")]
131pub fn markup_parser_finish(
132 context: &glib::MarkupParseContext,
133) -> Result<(AttrList, glib::GString, char), glib::Error> {
134 unsafe {
135 let mut attr_list = std::ptr::null_mut();
136 let mut text = std::ptr::null_mut();
137 let mut accel_char = std::mem::MaybeUninit::uninit();
138 let mut error = std::ptr::null_mut();
139 let is_ok = ffi::pango_markup_parser_finish(
140 context.to_glib_none().0,
141 &mut attr_list,
142 &mut text,
143 accel_char.as_mut_ptr(),
144 &mut error,
145 );
146 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
147 if error.is_null() {
148 Ok((
149 from_glib_full(attr_list),
150 from_glib_full(text),
151 std::convert::TryFrom::try_from(accel_char.assume_init())
152 .expect("conversion from an invalid Unicode value attempted"),
153 ))
154 } else {
155 Err(from_glib_full(error))
156 }
157 }
158}
159
160/// Incrementally parses marked-up text to create a plain-text string
161/// and an attribute list.
162///
163/// See the [Pango Markup](pango_markup.html) docs for details about the
164/// supported markup.
165///
166/// If @accel_marker is nonzero, the given character will mark the
167/// character following it as an accelerator. For example, @accel_marker
168/// might be an ampersand or underscore. All characters marked
169/// as an accelerator will receive a [`Underline::Low`][crate::Underline::Low] attribute,
170/// and the first character so marked will be returned in @accel_char,
171/// when calling [`markup_parser_finish()`][crate::markup_parser_finish()]. Two @accel_marker characters
172/// following each other produce a single literal @accel_marker character.
173///
174/// To feed markup to the parser, use [`glib::MarkupParseContext::parse()`][crate::glib::MarkupParseContext::parse()]
175/// on the returned [`glib::MarkupParseContext`][crate::glib::MarkupParseContext]. When done with feeding markup
176/// to the parser, use [`markup_parser_finish()`][crate::markup_parser_finish()] to get the data out
177/// of it, and then use `GLib::MarkupParseContext::free()` to free it.
178///
179/// This function is designed for applications that read Pango markup
180/// from streams. To simply parse a string containing Pango markup,
181/// the [`parse_markup()`][crate::parse_markup()] API is recommended instead.
182/// ## `accel_marker`
183/// character that precedes an accelerator, or 0 for none
184///
185/// # Returns
186///
187/// a `GMarkupParseContext` that should be
188/// destroyed with `GLib::MarkupParseContext::free()`.
189#[doc(alias = "pango_markup_parser_new")]
190pub fn markup_parser_new(accel_marker: char) -> glib::MarkupParseContext {
191 unsafe { from_glib_none(ffi::pango_markup_parser_new(accel_marker.into_glib())) }
192}
193
194/// Parses marked-up text to create a plain-text string and an attribute list.
195///
196/// See the [Pango Markup](pango_markup.html) docs for details about the
197/// supported markup.
198///
199/// If @accel_marker is nonzero, the given character will mark the
200/// character following it as an accelerator. For example, @accel_marker
201/// might be an ampersand or underscore. All characters marked
202/// as an accelerator will receive a [`Underline::Low`][crate::Underline::Low] attribute,
203/// and the first character so marked will be returned in @accel_char.
204/// Two @accel_marker characters following each other produce a single
205/// literal @accel_marker character.
206///
207/// To parse a stream of pango markup incrementally, use [`markup_parser_new()`][crate::markup_parser_new()].
208///
209/// If any error happens, none of the output arguments are touched except
210/// for @error.
211/// ## `markup_text`
212/// markup to parse (see the [Pango Markup](pango_markup.html) docs)
213/// ## `length`
214/// length of @markup_text, or -1 if nul-terminated
215/// ## `accel_marker`
216/// character that precedes an accelerator, or 0 for none
217///
218/// # Returns
219///
220/// [`false`] if @error is set, otherwise [`true`]
221///
222/// ## `attr_list`
223/// address of return location for a [`AttrList`][crate::AttrList]
224///
225/// ## `text`
226/// address of return location for text with tags stripped
227///
228/// ## `accel_char`
229/// address of return location for accelerator char
230#[doc(alias = "pango_parse_markup")]
231pub fn parse_markup(
232 markup_text: &str,
233 accel_marker: char,
234) -> Result<(AttrList, glib::GString, char), glib::Error> {
235 let length = markup_text.len() as _;
236 unsafe {
237 let mut attr_list = std::ptr::null_mut();
238 let mut text = std::ptr::null_mut();
239 let mut accel_char = std::mem::MaybeUninit::uninit();
240 let mut error = std::ptr::null_mut();
241 let is_ok = ffi::pango_parse_markup(
242 markup_text.to_glib_none().0,
243 length,
244 accel_marker.into_glib(),
245 &mut attr_list,
246 &mut text,
247 accel_char.as_mut_ptr(),
248 &mut error,
249 );
250 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
251 if error.is_null() {
252 Ok((
253 from_glib_full(attr_list),
254 from_glib_full(text),
255 std::convert::TryFrom::try_from(accel_char.assume_init())
256 .expect("conversion from an invalid Unicode value attempted"),
257 ))
258 } else {
259 Err(from_glib_full(error))
260 }
261 }
262}
263
264/// Parses a font stretch.
265///
266/// The allowed values are
267/// "ultra_condensed", "extra_condensed", "condensed",
268/// "semi_condensed", "normal", "semi_expanded", "expanded",
269/// "extra_expanded" and "ultra_expanded". Case variations are
270/// ignored and the '_' characters may be omitted.
271/// ## `str`
272/// a string to parse.
273/// ## `warn`
274/// if [`true`], issue a g_warning() on bad input.
275///
276/// # Returns
277///
278/// [`true`] if @str was successfully parsed.
279///
280/// ## `stretch`
281/// a [`Stretch`][crate::Stretch] to store the result in.
282#[doc(alias = "pango_parse_stretch")]
283pub fn parse_stretch(str: &str, warn: bool) -> Option<Stretch> {
284 unsafe {
285 let mut stretch = std::mem::MaybeUninit::uninit();
286 let ret = from_glib(ffi::pango_parse_stretch(
287 str.to_glib_none().0,
288 stretch.as_mut_ptr(),
289 warn.into_glib(),
290 ));
291 if ret {
292 Some(from_glib(stretch.assume_init()))
293 } else {
294 None
295 }
296 }
297}
298
299/// Parses a font style.
300///
301/// The allowed values are "normal", "italic" and "oblique", case
302/// variations being
303/// ignored.
304/// ## `str`
305/// a string to parse.
306/// ## `warn`
307/// if [`true`], issue a g_warning() on bad input.
308///
309/// # Returns
310///
311/// [`true`] if @str was successfully parsed.
312///
313/// ## `style`
314/// a [`Style`][crate::Style] to store the result in.
315#[doc(alias = "pango_parse_style")]
316pub fn parse_style(str: &str, warn: bool) -> Option<Style> {
317 unsafe {
318 let mut style = std::mem::MaybeUninit::uninit();
319 let ret = from_glib(ffi::pango_parse_style(
320 str.to_glib_none().0,
321 style.as_mut_ptr(),
322 warn.into_glib(),
323 ));
324 if ret {
325 Some(from_glib(style.assume_init()))
326 } else {
327 None
328 }
329 }
330}
331
332/// Parses a font variant.
333///
334/// The allowed values are "normal", "small-caps", "all-small-caps",
335/// "petite-caps", "all-petite-caps", "unicase" and "title-caps",
336/// case variations being ignored.
337/// ## `str`
338/// a string to parse.
339/// ## `warn`
340/// if [`true`], issue a g_warning() on bad input.
341///
342/// # Returns
343///
344/// [`true`] if @str was successfully parsed.
345///
346/// ## `variant`
347/// a [`Variant`][struct@crate::Variant] to store the result in.
348#[doc(alias = "pango_parse_variant")]
349pub fn parse_variant(str: &str, warn: bool) -> Option<Variant> {
350 unsafe {
351 let mut variant = std::mem::MaybeUninit::uninit();
352 let ret = from_glib(ffi::pango_parse_variant(
353 str.to_glib_none().0,
354 variant.as_mut_ptr(),
355 warn.into_glib(),
356 ));
357 if ret {
358 Some(from_glib(variant.assume_init()))
359 } else {
360 None
361 }
362 }
363}
364
365/// Parses a font weight.
366///
367/// The allowed values are "heavy",
368/// "ultrabold", "bold", "normal", "light", "ultraleight"
369/// and integers. Case variations are ignored.
370/// ## `str`
371/// a string to parse.
372/// ## `warn`
373/// if [`true`], issue a g_warning() on bad input.
374///
375/// # Returns
376///
377/// [`true`] if @str was successfully parsed.
378///
379/// ## `weight`
380/// a [`Weight`][crate::Weight] to store the result in.
381#[doc(alias = "pango_parse_weight")]
382pub fn parse_weight(str: &str, warn: bool) -> Option<Weight> {
383 unsafe {
384 let mut weight = std::mem::MaybeUninit::uninit();
385 let ret = from_glib(ffi::pango_parse_weight(
386 str.to_glib_none().0,
387 weight.as_mut_ptr(),
388 warn.into_glib(),
389 ));
390 if ret {
391 Some(from_glib(weight.assume_init()))
392 } else {
393 None
394 }
395 }
396}
397
398/// Quantizes the thickness and position of a line to whole device pixels.
399///
400/// This is typically used for underline or strikethrough. The purpose of
401/// this function is to avoid such lines looking blurry.
402///
403/// Care is taken to make sure @thickness is at least one pixel when this
404/// function returns, but returned @position may become zero as a result
405/// of rounding.
406/// ## `thickness`
407/// pointer to the thickness of a line, in Pango units
408/// ## `position`
409/// corresponding position
410#[doc(alias = "pango_quantize_line_geometry")]
411pub fn quantize_line_geometry(thickness: &mut i32, position: &mut i32) {
412 unsafe {
413 ffi::pango_quantize_line_geometry(thickness, position);
414 }
415}
416
417//#[cfg(feature = "v1_44")]
418//#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
419//#[doc(alias = "pango_tailor_break")]
420//pub fn tailor_break(text: &str, analysis: &mut Analysis, offset: i32, attrs: /*Ignored*/Vec<LogAttr>) {
421// unsafe { TODO: call ffi:pango_tailor_break() }
422//}
423
424/// Determines the inherent direction of a character.
425///
426/// The inherent direction is either `PANGO_DIRECTION_LTR`, `PANGO_DIRECTION_RTL`,
427/// or `PANGO_DIRECTION_NEUTRAL`.
428///
429/// This function is useful to categorize characters into left-to-right
430/// letters, right-to-left letters, and everything else. If full Unicode
431/// bidirectional type of a character is needed, [`BidiType::for_unichar()`][crate::BidiType::for_unichar()]
432/// can be used instead.
433/// ## `ch`
434/// a Unicode character
435///
436/// # Returns
437///
438/// the direction of the character.
439#[doc(alias = "pango_unichar_direction")]
440pub fn unichar_direction(ch: char) -> Direction {
441 unsafe { from_glib(ffi::pango_unichar_direction(ch.into_glib())) }
442}
443
444/// Converts a floating-point number to Pango units.
445///
446/// The conversion is done by multiplying @d by `PANGO_SCALE` and
447/// rounding the result to nearest integer.
448/// ## `d`
449/// double floating-point value
450///
451/// # Returns
452///
453/// the value in Pango units.
454#[doc(alias = "pango_units_from_double")]
455pub fn units_from_double(d: f64) -> i32 {
456 unsafe { ffi::pango_units_from_double(d) }
457}
458
459/// Converts a number in Pango units to floating-point.
460///
461/// The conversion is done by dividing @i by `PANGO_SCALE`.
462/// ## `i`
463/// value in Pango units
464///
465/// # Returns
466///
467/// the double value.
468#[doc(alias = "pango_units_to_double")]
469pub fn units_to_double(i: i32) -> f64 {
470 unsafe { ffi::pango_units_to_double(i) }
471}
472
473/// Returns the encoded version of Pango available at run-time.
474///
475/// This is similar to the macro `PANGO_VERSION` except that the macro
476/// returns the encoded version available at compile-time. A version
477/// number can be encoded into an integer using PANGO_VERSION_ENCODE().
478///
479/// # Returns
480///
481/// The encoded version of Pango library available at run time.
482#[doc(alias = "pango_version")]
483pub fn version() -> i32 {
484 unsafe { ffi::pango_version() }
485}
486
487/// Checks that the Pango library in use is compatible with the
488/// given version.
489///
490/// Generally you would pass in the constants `PANGO_VERSION_MAJOR`,
491/// `PANGO_VERSION_MINOR`, `PANGO_VERSION_MICRO` as the three arguments
492/// to this function; that produces a check that the library in use at
493/// run-time is compatible with the version of Pango the application or
494/// module was compiled against.
495///
496/// Compatibility is defined by two things: first the version
497/// of the running library is newer than the version
498/// @required_major.required_minor.@required_micro. Second
499/// the running library must be binary compatible with the
500/// version @required_major.required_minor.@required_micro
501/// (same major version.)
502///
503/// For compile-time version checking use PANGO_VERSION_CHECK().
504/// ## `required_major`
505/// the required major version
506/// ## `required_minor`
507/// the required minor version
508/// ## `required_micro`
509/// the required major version
510///
511/// # Returns
512///
513/// [`None`] if the Pango library is compatible
514/// with the given version, or a string describing the version
515/// mismatch. The returned string is owned by Pango and should not
516/// be modified or freed.
517#[doc(alias = "pango_version_check")]
518pub fn version_check(
519 required_major: i32,
520 required_minor: i32,
521 required_micro: i32,
522) -> Option<glib::GString> {
523 unsafe {
524 from_glib_none(ffi::pango_version_check(
525 required_major,
526 required_minor,
527 required_micro,
528 ))
529 }
530}
531
532/// Returns the version of Pango available at run-time.
533///
534/// This is similar to the macro `PANGO_VERSION_STRING` except that the
535/// macro returns the version available at compile-time.
536///
537/// # Returns
538///
539/// A string containing the version of Pango library available
540/// at run time. The returned string is owned by Pango and should not
541/// be modified or freed.
542#[doc(alias = "pango_version_string")]
543pub fn version_string() -> glib::GString {
544 unsafe { from_glib_none(ffi::pango_version_string()) }
545}