pango/

functions.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use glib::translate::*;
use std::{ffi::c_char, ptr};

#[cfg(feature = "v1_44")]
use crate::ShapeFlags;
pub use crate::auto::functions::*;
use crate::{Analysis, AttrIterator, AttrList, Context, Direction, GlyphString, Item, ffi};

/// Reorder items from logical order to visual order.
///
/// The visual order is determined from the associated directional
/// levels of the items. The original list is unmodified.
///
/// (Please open a bug if you use this function.
///  It is not a particularly convenient interface, and the code
///  is duplicated elsewhere in Pango for that reason.)
/// ## `items`
/// a `GList` of [`Item`][crate::Item]
///   in logical order.
///
/// # Returns
///
/// a `GList`
///   of [`Item`][crate::Item] structures in visual order.
#[doc(alias = "pango_reorder_items")]
pub fn reorder_items(logical_items: &glib::List<Item>) -> glib::List<Item> {
    unsafe {
        FromGlibPtrContainer::from_glib_full(ffi::pango_reorder_items(
            logical_items.as_ptr() as *mut _
        ))
    }
}

/// 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()].
///
/// This is similar to [`shape()`][crate::shape()], except it also can optionally take
/// the full paragraph text as input, which will then be used to perform
/// certain cross-item shaping interactions. If you have access to the broader
/// text of which @item_text is part of, provide the broader text as
/// @paragraph_text. If @paragraph_text is [`None`], item text is used instead.
///
/// 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 do not pass the full paragraph text as @paragraph_text, you need
/// to subtract the item offset from their indices before calling
/// [`shape_full()`][crate::shape_full()].
/// ## `item_text`
/// valid UTF-8 text to shape.
/// ## `item_length`
/// the length (in bytes) of @item_text. -1 means nul-terminated text.
/// ## `paragraph_text`
/// text of the paragraph (see details).
/// ## `paragraph_length`
/// the length (in bytes) of @paragraph_text. -1 means nul-terminated text.
/// ## `analysis`
/// [`Analysis`][crate::Analysis] structure from [`itemize()`][crate::itemize()].
///
/// # Returns
///
///
/// ## `glyphs`
/// glyph string in which to store results.
#[doc(alias = "pango_shape_full")]
pub fn shape_full(
    item_text: &str,
    paragraph_text: Option<&str>,
    analysis: &Analysis,
    glyphs: &mut GlyphString,
) {
    let item_length = item_text.len() as i32;
    let paragraph_length = paragraph_text.map(|t| t.len() as i32).unwrap_or_default();
    let paragraph_ptr = paragraph_text.map_or(ptr::null(), |t| t.as_ptr() as *const c_char);
    unsafe {
        // The function does not take null-terminated strings when a length is provided.
        // It also requires item_text to point to a subsequence of paragraph_text.
        // Using to_glib_none() on &str will copy the string and cause problems.
        ffi::pango_shape_full(
            item_text.as_ptr() as *const c_char,
            item_length,
            paragraph_ptr,
            paragraph_length,
            analysis.to_glib_none().0,
            glyphs.to_glib_none_mut().0,
        );
    }
}

/// 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()]
///
/// # Returns
///
///
/// ## `glyphs`
/// glyph string in which to store results
#[doc(alias = "pango_shape")]
pub fn shape(item_text: &str, analysis: &Analysis, glyphs: &mut GlyphString) {
    let item_length = item_text.len() as i32;
    unsafe {
        // The function does not take null-terminated strings when a length is provided.
        // Using to_glib_none() on &str will copy the string unnecessarily.
        ffi::pango_shape(
            item_text.as_ptr() as *const c_char,
            item_length,
            analysis.to_glib_none().0,
            glyphs.to_glib_none_mut().0,
        );
    }
}

/// 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()].
///
/// This is similar to [`shape_full()`][crate::shape_full()], except it also takes flags
/// that can influence the shaping process.
///
/// 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 do not pass the full paragraph text as @paragraph_text, you need
/// to subtract the item offset from their indices before calling
/// [`shape_with_flags()`][crate::shape_with_flags()].
/// ## `item_text`
/// valid UTF-8 text to shape
/// ## `item_length`
/// the length (in bytes) of @item_text.
///     -1 means nul-terminated text.
/// ## `paragraph_text`
/// text of the paragraph (see details).
/// ## `paragraph_length`
/// the length (in bytes) of @paragraph_text.
///     -1 means nul-terminated text.
/// ## `analysis`
/// [`Analysis`][crate::Analysis] structure from [`itemize()`][crate::itemize()]
/// ## `flags`
/// flags influencing the shaping process
///
/// # Returns
///
///
/// ## `glyphs`
/// glyph string in which to store results
#[cfg(feature = "v1_44")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
#[doc(alias = "pango_shape_with_flags")]
pub fn shape_with_flags(
    item_text: &str,
    paragraph_text: Option<&str>,
    analysis: &Analysis,
    glyphs: &mut GlyphString,
    flags: ShapeFlags,
) {
    let item_length = item_text.len() as i32;
    let paragraph_length = paragraph_text.map(|t| t.len() as i32).unwrap_or_default();
    let paragraph_ptr = paragraph_text.map_or(ptr::null(), |t| t.as_ptr() as *const c_char);
    unsafe {
        // See: shape_full
        ffi::pango_shape_with_flags(
            item_text.as_ptr() as *const c_char,
            item_length,
            paragraph_ptr,
            paragraph_length,
            analysis.to_glib_none().0,
            glyphs.to_glib_none_mut().0,
            flags.into_glib(),
        );
    }
}

/// Converts extents from Pango units to device units.
///
/// The conversion is done by dividing by the `PANGO_SCALE` factor and
/// performing rounding.
///
/// The @inclusive rectangle is converted by flooring the x/y coordinates
/// and extending width/height, such that the final rectangle completely
/// includes the original rectangle.
///
/// The @nearest rectangle is converted by rounding the coordinates
/// of the rectangle to the nearest device unit (pixel).
///
/// The rule to which argument to use is: if you want the resulting device-space
/// rectangle to completely contain the original rectangle, pass it in as
/// @inclusive. If you want two touching-but-not-overlapping rectangles stay
/// touching-but-not-overlapping after rounding to device units, pass them in
/// as @nearest.
///
/// # Returns
///
///
/// ## `inclusive`
/// rectangle to round to pixels inclusively
///
/// ## `nearest`
/// rectangle to round to nearest pixels
#[doc(alias = "pango_extents_to_pixels")]
pub fn extents_to_pixels(
    mut inclusive: Option<&mut crate::Rectangle>,
    mut nearest: Option<&mut crate::Rectangle>,
) {
    unsafe {
        ffi::pango_extents_to_pixels(inclusive.to_glib_none_mut().0, nearest.to_glib_none_mut().0);
    }
}

/// 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> {
    let total_length = text.len() as i32;
    assert!(
        start_index >= 0 && start_index < total_length,
        "start_index is out of range"
    );
    assert!(
        length >= 0 && start_index.checked_add(length).unwrap() <= total_length,
        "start_index + length is out of range"
    );
    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> {
    let total_length = text.len() as i32;
    assert!(
        start_index >= 0 && start_index < total_length,
        "start_index is out of range"
    );
    assert!(
        length >= 0 && start_index.checked_add(length).unwrap() <= total_length,
        "start_index + length is out of range"
    );
    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),
        ))
    }
}