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