pango/auto/

functions.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{
    ffi, Analysis, AttrIterator, AttrList, Context, Direction, GlyphString, Item, Stretch, Style,
    Variant, Weight,
};
use glib::translate::*;

//#[cfg_attr(feature = "v1_44", deprecated = "Since 1.44")]
//#[allow(deprecated)]
//#[doc(alias = "pango_break")]
//#[doc(alias = "break")]
//pub fn break_(text: &str, analysis: &mut Analysis, attrs: /*Ignored*/&[LogAttr]) {
//    unsafe { TODO: call ffi:pango_break() }
//}

//#[doc(alias = "pango_default_break")]
//pub fn default_break(text: &str, analysis: Option<&mut Analysis>, attrs: /*Ignored*/&mut LogAttr, attrs_len: i32) {
//    unsafe { TODO: call ffi:pango_default_break() }
//}

/// Searches a string the first character that has a strong
/// direction, according to the Unicode bidirectional algorithm.
/// ## `text`
/// the text to process. Must be valid UTF-8
/// ## `length`
/// length of @text in bytes (may be -1 if @text is nul-terminated)
///
/// # Returns
///
/// The direction corresponding to the first strong character.
///   If no such character is found, then [`Direction::Neutral`][crate::Direction::Neutral] is returned.
#[doc(alias = "pango_find_base_dir")]
pub fn find_base_dir(text: &str) -> Direction {
    let length = text.len() as _;
    unsafe { from_glib(ffi::pango_find_base_dir(text.to_glib_none().0, length)) }
}

/// Locates a paragraph boundary in @text.
///
/// A boundary is caused by delimiter characters, such as
/// a newline, carriage return, carriage return-newline pair,
/// or Unicode paragraph separator character.
///
/// The index of the run of delimiters is returned in
/// @paragraph_delimiter_index. The index of the start of the
/// next paragraph (index after all delimiters) is stored n
/// @next_paragraph_start.
///
/// If no delimiters are found, both @paragraph_delimiter_index
/// and @next_paragraph_start are filled with the length of @text
/// (an index one off the end).
/// ## `text`
/// UTF-8 text
/// ## `length`
/// length of @text in bytes, or -1 if nul-terminated
///
/// # Returns
///
///
/// ## `paragraph_delimiter_index`
/// return location for index of
///   delimiter
///
/// ## `next_paragraph_start`
/// return location for start of next
///   paragraph
#[doc(alias = "pango_find_paragraph_boundary")]
pub fn find_paragraph_boundary(text: &str) -> (i32, i32) {
    let length = text.len() as _;
    unsafe {
        let mut paragraph_delimiter_index = std::mem::MaybeUninit::uninit();
        let mut next_paragraph_start = std::mem::MaybeUninit::uninit();
        ffi::pango_find_paragraph_boundary(
            text.to_glib_none().0,
            length,
            paragraph_delimiter_index.as_mut_ptr(),
            next_paragraph_start.as_mut_ptr(),
        );
        (
            paragraph_delimiter_index.assume_init(),
            next_paragraph_start.assume_init(),
        )
    }
}

//#[doc(alias = "pango_get_log_attrs")]
//#[doc(alias = "get_log_attrs")]
//pub fn log_attrs(text: &str, level: i32, language: &mut Language, attrs: /*Ignored*/&[LogAttr]) {
//    unsafe { TODO: call ffi:pango_get_log_attrs() }
//}

/// Checks if a character that should not be normally rendered.
///
/// This includes all Unicode characters with "ZERO WIDTH" in their name,
/// as well as *bidi* formatting characters, and a few other ones.
///
/// This is totally different from `unichar_iszerowidth()` and is at best misnamed.
/// ## `ch`
/// a Unicode character
///
/// # Returns
///
/// [`true`] if @ch is a zero-width character, [`false`] otherwise
#[doc(alias = "pango_is_zero_width")]
pub fn is_zero_width(ch: char) -> bool {
    unsafe { from_glib(ffi::pango_is_zero_width(ch.into_glib())) }
}

/// Breaks a piece of text into segments with consistent directional
/// level and font.
///
/// Each byte of @text will be contained in exactly one of the items in the
/// returned list; the generated list of items will be in logical order (the
/// start offsets of the items are ascending).
///
/// @cached_iter should be an iterator over @attrs currently positioned
/// at a range before or containing @start_index; @cached_iter will be
/// advanced to the range covering the position just after
/// @start_index + @length. (i.e. if itemizing in a loop, just keep passing
/// in the same @cached_iter).
/// ## `context`
/// a structure holding information that affects
///   the itemization process.
/// ## `text`
/// the text to itemize. Must be valid UTF-8
/// ## `start_index`
/// first byte in @text to process
/// ## `length`
/// the number of bytes (not characters) to process
///   after @start_index. This must be >= 0.
/// ## `attrs`
/// the set of attributes that apply to @text.
/// ## `cached_iter`
/// Cached attribute iterator
///
/// # Returns
///
/// a `GList` of
///   [`Item`][crate::Item] structures. The items should be freed using
///   `Pango::Item::free()` in combination with `GLib::List::free_full()`.
#[doc(alias = "pango_itemize")]
pub fn itemize(
    context: &Context,
    text: &str,
    start_index: i32,
    length: i32,
    attrs: &AttrList,
    cached_iter: Option<&AttrIterator>,
) -> Vec<Item> {
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::pango_itemize(
            context.to_glib_none().0,
            text.to_glib_none().0,
            start_index,
            length,
            attrs.to_glib_none().0,
            mut_override(cached_iter.to_glib_none().0),
        ))
    }
}

/// Like `pango_itemize()`, but with an explicitly specified base direction.
///
/// The base direction is used when computing bidirectional levels.
/// [`itemize()`][crate::itemize()] gets the base direction from the [`Context`][crate::Context]
/// (see [`Context::set_base_dir()`][crate::Context::set_base_dir()]).
/// ## `context`
/// a structure holding information that affects
///   the itemization process.
/// ## `base_dir`
/// base direction to use for bidirectional processing
/// ## `text`
/// the text to itemize.
/// ## `start_index`
/// first byte in @text to process
/// ## `length`
/// the number of bytes (not characters) to process
///   after @start_index. This must be >= 0.
/// ## `attrs`
/// the set of attributes that apply to @text.
/// ## `cached_iter`
/// Cached attribute iterator
///
/// # Returns
///
/// a `GList` of
///   [`Item`][crate::Item] structures. The items should be freed using
///   `Pango::Item::free()` probably in combination with `GLib::List::free_full()`.
#[doc(alias = "pango_itemize_with_base_dir")]
pub fn itemize_with_base_dir(
    context: &Context,
    base_dir: Direction,
    text: &str,
    start_index: i32,
    length: i32,
    attrs: &AttrList,
    cached_iter: Option<&AttrIterator>,
) -> Vec<Item> {
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::pango_itemize_with_base_dir(
            context.to_glib_none().0,
            base_dir.into_glib(),
            text.to_glib_none().0,
            start_index,
            length,
            attrs.to_glib_none().0,
            mut_override(cached_iter.to_glib_none().0),
        ))
    }
}

/// Finishes parsing markup.
///
/// After feeding a Pango markup parser some data with [`glib::MarkupParseContext::parse()`][crate::glib::MarkupParseContext::parse()],
/// use this function to get the list of attributes and text out of the
/// markup. This function will not free @context, use `GLib::MarkupParseContext::free()`
/// to do so.
/// ## `context`
/// A valid parse context that was returned from [`markup_parser_new()`][crate::markup_parser_new()]
///
/// # Returns
///
/// [`false`] if @error is set, otherwise [`true`]
///
/// ## `attr_list`
/// address of return location for a [`AttrList`][crate::AttrList]
///
/// ## `text`
/// address of return location for text with tags stripped
///
/// ## `accel_char`
/// address of return location for accelerator char
#[doc(alias = "pango_markup_parser_finish")]
pub fn markup_parser_finish(
    context: &glib::MarkupParseContext,
) -> Result<(AttrList, glib::GString, char), glib::Error> {
    unsafe {
        let mut attr_list = std::ptr::null_mut();
        let mut text = std::ptr::null_mut();
        let mut accel_char = std::mem::MaybeUninit::uninit();
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::pango_markup_parser_finish(
            context.to_glib_none().0,
            &mut attr_list,
            &mut text,
            accel_char.as_mut_ptr(),
            &mut error,
        );
        debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok((
                from_glib_full(attr_list),
                from_glib_full(text),
                std::convert::TryFrom::try_from(accel_char.assume_init())
                    .expect("conversion from an invalid Unicode value attempted"),
            ))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Incrementally parses marked-up text to create a plain-text string
/// and an attribute list.
///
/// See the [Pango Markup](pango_markup.html) docs for details about the
/// supported markup.
///
/// If @accel_marker is nonzero, the given character will mark the
/// character following it as an accelerator. For example, @accel_marker
/// might be an ampersand or underscore. All characters marked
/// as an accelerator will receive a [`Underline::Low`][crate::Underline::Low] attribute,
/// and the first character so marked will be returned in @accel_char,
/// when calling [`markup_parser_finish()`][crate::markup_parser_finish()]. Two @accel_marker characters
/// following each other produce a single literal @accel_marker character.
///
/// To feed markup to the parser, use [`glib::MarkupParseContext::parse()`][crate::glib::MarkupParseContext::parse()]
/// on the returned [`glib::MarkupParseContext`][crate::glib::MarkupParseContext]. When done with feeding markup
/// to the parser, use [`markup_parser_finish()`][crate::markup_parser_finish()] to get the data out
/// of it, and then use `GLib::MarkupParseContext::free()` to free it.
///
/// This function is designed for applications that read Pango markup
/// from streams. To simply parse a string containing Pango markup,
/// the [`parse_markup()`][crate::parse_markup()] API is recommended instead.
/// ## `accel_marker`
/// character that precedes an accelerator, or 0 for none
///
/// # Returns
///
/// a `GMarkupParseContext` that should be
/// destroyed with `GLib::MarkupParseContext::free()`.
#[doc(alias = "pango_markup_parser_new")]
pub fn markup_parser_new(accel_marker: char) -> glib::MarkupParseContext {
    unsafe { from_glib_none(ffi::pango_markup_parser_new(accel_marker.into_glib())) }
}

/// Parses marked-up text to create a plain-text string and an attribute list.
///
/// See the [Pango Markup](pango_markup.html) docs for details about the
/// supported markup.
///
/// If @accel_marker is nonzero, the given character will mark the
/// character following it as an accelerator. For example, @accel_marker
/// might be an ampersand or underscore. All characters marked
/// as an accelerator will receive a [`Underline::Low`][crate::Underline::Low] attribute,
/// and the first character so marked will be returned in @accel_char.
/// Two @accel_marker characters following each other produce a single
/// literal @accel_marker character.
///
/// To parse a stream of pango markup incrementally, use [`markup_parser_new()`][crate::markup_parser_new()].
///
/// If any error happens, none of the output arguments are touched except
/// for @error.
/// ## `markup_text`
/// markup to parse (see the [Pango Markup](pango_markup.html) docs)
/// ## `length`
/// length of @markup_text, or -1 if nul-terminated
/// ## `accel_marker`
/// character that precedes an accelerator, or 0 for none
///
/// # Returns
///
/// [`false`] if @error is set, otherwise [`true`]
///
/// ## `attr_list`
/// address of return location for a [`AttrList`][crate::AttrList]
///
/// ## `text`
/// address of return location for text with tags stripped
///
/// ## `accel_char`
/// address of return location for accelerator char
#[doc(alias = "pango_parse_markup")]
pub fn parse_markup(
    markup_text: &str,
    accel_marker: char,
) -> Result<(AttrList, glib::GString, char), glib::Error> {
    let length = markup_text.len() as _;
    unsafe {
        let mut attr_list = std::ptr::null_mut();
        let mut text = std::ptr::null_mut();
        let mut accel_char = std::mem::MaybeUninit::uninit();
        let mut error = std::ptr::null_mut();
        let is_ok = ffi::pango_parse_markup(
            markup_text.to_glib_none().0,
            length,
            accel_marker.into_glib(),
            &mut attr_list,
            &mut text,
            accel_char.as_mut_ptr(),
            &mut error,
        );
        debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
        if error.is_null() {
            Ok((
                from_glib_full(attr_list),
                from_glib_full(text),
                std::convert::TryFrom::try_from(accel_char.assume_init())
                    .expect("conversion from an invalid Unicode value attempted"),
            ))
        } else {
            Err(from_glib_full(error))
        }
    }
}

/// Parses a font stretch.
///
/// The allowed values are
/// "ultra_condensed", "extra_condensed", "condensed",
/// "semi_condensed", "normal", "semi_expanded", "expanded",
/// "extra_expanded" and "ultra_expanded". Case variations are
/// ignored and the '_' characters may be omitted.
/// ## `str`
/// a string to parse.
/// ## `warn`
/// if [`true`], issue a g_warning() on bad input.
///
/// # Returns
///
/// [`true`] if @str was successfully parsed.
///
/// ## `stretch`
/// a [`Stretch`][crate::Stretch] to store the result in.
#[doc(alias = "pango_parse_stretch")]
pub fn parse_stretch(str: &str, warn: bool) -> Option<Stretch> {
    unsafe {
        let mut stretch = std::mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::pango_parse_stretch(
            str.to_glib_none().0,
            stretch.as_mut_ptr(),
            warn.into_glib(),
        ));
        if ret {
            Some(from_glib(stretch.assume_init()))
        } else {
            None
        }
    }
}

/// Parses a font style.
///
/// The allowed values are "normal", "italic" and "oblique", case
/// variations being
/// ignored.
/// ## `str`
/// a string to parse.
/// ## `warn`
/// if [`true`], issue a g_warning() on bad input.
///
/// # Returns
///
/// [`true`] if @str was successfully parsed.
///
/// ## `style`
/// a [`Style`][crate::Style] to store the result in.
#[doc(alias = "pango_parse_style")]
pub fn parse_style(str: &str, warn: bool) -> Option<Style> {
    unsafe {
        let mut style = std::mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::pango_parse_style(
            str.to_glib_none().0,
            style.as_mut_ptr(),
            warn.into_glib(),
        ));
        if ret {
            Some(from_glib(style.assume_init()))
        } else {
            None
        }
    }
}

/// Parses a font variant.
///
/// The allowed values are "normal", "small-caps", "all-small-caps",
/// "petite-caps", "all-petite-caps", "unicase" and "title-caps",
/// case variations being ignored.
/// ## `str`
/// a string to parse.
/// ## `warn`
/// if [`true`], issue a g_warning() on bad input.
///
/// # Returns
///
/// [`true`] if @str was successfully parsed.
///
/// ## `variant`
/// a [`Variant`][struct@crate::Variant] to store the result in.
#[doc(alias = "pango_parse_variant")]
pub fn parse_variant(str: &str, warn: bool) -> Option<Variant> {
    unsafe {
        let mut variant = std::mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::pango_parse_variant(
            str.to_glib_none().0,
            variant.as_mut_ptr(),
            warn.into_glib(),
        ));
        if ret {
            Some(from_glib(variant.assume_init()))
        } else {
            None
        }
    }
}

/// Parses a font weight.
///
/// The allowed values are "heavy",
/// "ultrabold", "bold", "normal", "light", "ultraleight"
/// and integers. Case variations are ignored.
/// ## `str`
/// a string to parse.
/// ## `warn`
/// if [`true`], issue a g_warning() on bad input.
///
/// # Returns
///
/// [`true`] if @str was successfully parsed.
///
/// ## `weight`
/// a [`Weight`][crate::Weight] to store the result in.
#[doc(alias = "pango_parse_weight")]
pub fn parse_weight(str: &str, warn: bool) -> Option<Weight> {
    unsafe {
        let mut weight = std::mem::MaybeUninit::uninit();
        let ret = from_glib(ffi::pango_parse_weight(
            str.to_glib_none().0,
            weight.as_mut_ptr(),
            warn.into_glib(),
        ));
        if ret {
            Some(from_glib(weight.assume_init()))
        } else {
            None
        }
    }
}

/// Quantizes the thickness and position of a line to whole device pixels.
///
/// This is typically used for underline or strikethrough. The purpose of
/// this function is to avoid such lines looking blurry.
///
/// Care is taken to make sure @thickness is at least one pixel when this
/// function returns, but returned @position may become zero as a result
/// of rounding.
/// ## `thickness`
/// pointer to the thickness of a line, in Pango units
/// ## `position`
/// corresponding position
#[doc(alias = "pango_quantize_line_geometry")]
pub fn quantize_line_geometry(thickness: &mut i32, position: &mut i32) {
    unsafe {
        ffi::pango_quantize_line_geometry(thickness, position);
    }
}

/// Convert the characters in @text into glyphs.
///
/// Given a segment of text and the corresponding [`Analysis`][crate::Analysis] structure
/// returned from [`itemize()`][crate::itemize()], convert the characters into glyphs. You
/// may also pass in only a substring of the item from [`itemize()`][crate::itemize()].
///
/// It is recommended that you use [`shape_full()`][crate::shape_full()] instead, since
/// that API allows for shaping interaction happening across text item
/// boundaries.
///
/// Some aspects of hyphen insertion and text transformation (in particular,
/// capitalization) require log attrs, and thus can only be handled by
/// `shape_item()`.
///
/// Note that the extra attributes in the @analyis that is returned from
/// [`itemize()`][crate::itemize()] have indices that are relative to the entire paragraph,
/// so you need to subtract the item offset from their indices before
/// calling [`shape()`][crate::shape()].
/// ## `text`
/// the text to process
/// ## `length`
/// the length (in bytes) of @text
/// ## `analysis`
/// [`Analysis`][crate::Analysis] structure from [`itemize()`][crate::itemize()]
/// ## `glyphs`
/// glyph string in which to store results
#[doc(alias = "pango_shape")]
pub fn shape(text: &str, analysis: &Analysis, glyphs: &mut GlyphString) {
    let length = text.len() as _;
    unsafe {
        ffi::pango_shape(
            text.to_glib_none().0,
            length,
            analysis.to_glib_none().0,
            glyphs.to_glib_none_mut().0,
        );
    }
}

//#[cfg(feature = "v1_50")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
//#[doc(alias = "pango_shape_item")]
//pub fn shape_item(item: &mut Item, paragraph_text: Option<&str>, log_attrs: /*Ignored*/Option<&mut LogAttr>, glyphs: &mut GlyphString, flags: ShapeFlags) {
//    unsafe { TODO: call ffi:pango_shape_item() }
//}

//#[cfg(feature = "v1_44")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
//#[doc(alias = "pango_tailor_break")]
//pub fn tailor_break(text: &str, analysis: &mut Analysis, offset: i32, attrs: /*Ignored*/&[LogAttr]) {
//    unsafe { TODO: call ffi:pango_tailor_break() }
//}

/// Determines the inherent direction of a character.
///
/// The inherent direction is either `PANGO_DIRECTION_LTR`, `PANGO_DIRECTION_RTL`,
/// or `PANGO_DIRECTION_NEUTRAL`.
///
/// This function is useful to categorize characters into left-to-right
/// letters, right-to-left letters, and everything else. If full Unicode
/// bidirectional type of a character is needed, [`BidiType::for_unichar()`][crate::BidiType::for_unichar()]
/// can be used instead.
/// ## `ch`
/// a Unicode character
///
/// # Returns
///
/// the direction of the character.
#[doc(alias = "pango_unichar_direction")]
pub fn unichar_direction(ch: char) -> Direction {
    unsafe { from_glib(ffi::pango_unichar_direction(ch.into_glib())) }
}

/// Converts a floating-point number to Pango units.
///
/// The conversion is done by multiplying @d by `PANGO_SCALE` and
/// rounding the result to nearest integer.
/// ## `d`
/// double floating-point value
///
/// # Returns
///
/// the value in Pango units.
#[doc(alias = "pango_units_from_double")]
pub fn units_from_double(d: f64) -> i32 {
    unsafe { ffi::pango_units_from_double(d) }
}

/// Converts a number in Pango units to floating-point.
///
/// The conversion is done by dividing @i by `PANGO_SCALE`.
/// ## `i`
/// value in Pango units
///
/// # Returns
///
/// the double value.
#[doc(alias = "pango_units_to_double")]
pub fn units_to_double(i: i32) -> f64 {
    unsafe { ffi::pango_units_to_double(i) }
}

/// Returns the encoded version of Pango available at run-time.
///
/// This is similar to the macro `PANGO_VERSION` except that the macro
/// returns the encoded version available at compile-time. A version
/// number can be encoded into an integer using PANGO_VERSION_ENCODE().
///
/// # Returns
///
/// The encoded version of Pango library available at run time.
#[doc(alias = "pango_version")]
pub fn version() -> i32 {
    unsafe { ffi::pango_version() }
}

/// Checks that the Pango library in use is compatible with the
/// given version.
///
/// Generally you would pass in the constants `PANGO_VERSION_MAJOR`,
/// `PANGO_VERSION_MINOR`, `PANGO_VERSION_MICRO` as the three arguments
/// to this function; that produces a check that the library in use at
/// run-time is compatible with the version of Pango the application or
/// module was compiled against.
///
/// Compatibility is defined by two things: first the version
/// of the running library is newer than the version
/// @required_major.required_minor.@required_micro. Second
/// the running library must be binary compatible with the
/// version @required_major.required_minor.@required_micro
/// (same major version.)
///
/// For compile-time version checking use PANGO_VERSION_CHECK().
/// ## `required_major`
/// the required major version
/// ## `required_minor`
/// the required minor version
/// ## `required_micro`
/// the required major version
///
/// # Returns
///
/// [`None`] if the Pango library is compatible
///   with the given version, or a string describing the version
///   mismatch.  The returned string is owned by Pango and should not
///   be modified or freed.
#[doc(alias = "pango_version_check")]
pub fn version_check(
    required_major: i32,
    required_minor: i32,
    required_micro: i32,
) -> Option<glib::GString> {
    unsafe {
        from_glib_none(ffi::pango_version_check(
            required_major,
            required_minor,
            required_micro,
        ))
    }
}

/// Returns the version of Pango available at run-time.
///
/// This is similar to the macro `PANGO_VERSION_STRING` except that the
/// macro returns the version available at compile-time.
///
/// # Returns
///
/// A string containing the version of Pango library available
///   at run time. The returned string is owned by Pango and should not
///   be modified or freed.
#[doc(alias = "pango_version_string")]
pub fn version_string() -> glib::GString {
    unsafe { from_glib_none(ffi::pango_version_string()) }
}