pango/auto/

layout.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

#[cfg(feature = "v1_46")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
use crate::Direction;
#[cfg(feature = "v1_50")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
use crate::LayoutSerializeFlags;
use crate::{
    Alignment, AttrList, Context, EllipsizeMode, FontDescription, LayoutIter, LayoutLine,
    Rectangle, TabArray, WrapMode, ffi,
};
use glib::translate::*;

glib::wrapper! {
    ///
    ///
    /// The following images demonstrate the effect of alignment and
    /// justification on the layout of text:
    ///
    /// | | |
    /// | --- | --- |
    /// | ![align=left](align-left.png) | ![align=left, justify](align-left-justify.png) |
    /// | ![align=center](align-center.png) | ![align=center, justify](align-center-justify.png) |
    /// | ![align=right](align-right.png) | ![align=right, justify](align-right-justify.png) |
    ///
    ///
    /// It is possible, as well, to ignore the 2-D setup,
    /// and simply treat the results of a [`Layout`][crate::Layout] as a list of lines.
    #[doc(alias = "PangoLayout")]
    pub struct Layout(Object<ffi::PangoLayout, ffi::PangoLayoutClass>);

    match fn {
        type_ => || ffi::pango_layout_get_type(),
    }
}

impl Layout {
    /// Create a new [`Layout`][crate::Layout] object with attributes initialized to
    /// default values for a particular [`Context`][crate::Context].
    /// ## `context`
    /// a [`Context`][crate::Context]
    ///
    /// # Returns
    ///
    /// the newly allocated [`Layout`][crate::Layout]
    #[doc(alias = "pango_layout_new")]
    pub fn new(context: &Context) -> Layout {
        unsafe { from_glib_full(ffi::pango_layout_new(context.to_glib_none().0)) }
    }

    /// Forces recomputation of any state in the [`Layout`][crate::Layout] that
    /// might depend on the layout's context.
    ///
    /// This function should be called if you make changes to the context
    /// subsequent to creating the layout.
    #[doc(alias = "pango_layout_context_changed")]
    pub fn context_changed(&self) {
        unsafe {
            ffi::pango_layout_context_changed(self.to_glib_none().0);
        }
    }

    #[doc(alias = "pango_layout_copy")]
    #[must_use]
    pub fn copy(&self) -> Layout {
        unsafe { from_glib_full(ffi::pango_layout_copy(self.to_glib_none().0)) }
    }

    /// Gets the alignment for the layout: how partial lines are
    /// positioned within the horizontal space available.
    ///
    /// # Returns
    ///
    /// the alignment
    #[doc(alias = "pango_layout_get_alignment")]
    #[doc(alias = "get_alignment")]
    pub fn alignment(&self) -> Alignment {
        unsafe { from_glib(ffi::pango_layout_get_alignment(self.to_glib_none().0)) }
    }

    /// Gets the attribute list for the layout, if any.
    ///
    /// # Returns
    ///
    /// a [`AttrList`][crate::AttrList]
    #[doc(alias = "pango_layout_get_attributes")]
    #[doc(alias = "get_attributes")]
    pub fn attributes(&self) -> Option<AttrList> {
        unsafe { from_glib_none(ffi::pango_layout_get_attributes(self.to_glib_none().0)) }
    }

    /// Gets whether to calculate the base direction for the layout
    /// according to its contents.
    ///
    /// See [`set_auto_dir()`][Self::set_auto_dir()].
    ///
    /// # Returns
    ///
    /// [`true`] if the bidirectional base direction
    ///   is computed from the layout's contents, [`false`] otherwise
    #[doc(alias = "pango_layout_get_auto_dir")]
    #[doc(alias = "get_auto_dir")]
    pub fn is_auto_dir(&self) -> bool {
        unsafe { from_glib(ffi::pango_layout_get_auto_dir(self.to_glib_none().0)) }
    }

    /// Gets the Y position of baseline of the first line in @self.
    ///
    /// # Returns
    ///
    /// baseline of first line, from top of @self
    #[doc(alias = "pango_layout_get_baseline")]
    #[doc(alias = "get_baseline")]
    pub fn baseline(&self) -> i32 {
        unsafe { ffi::pango_layout_get_baseline(self.to_glib_none().0) }
    }

    /// /picture
    /// ## `index_`
    /// the byte index of the cursor
    ///
    /// # Returns
    ///
    ///
    /// ## `strong_pos`
    /// location to store the strong cursor position
    ///
    /// ## `weak_pos`
    /// location to store the weak cursor position
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_layout_get_caret_pos")]
    #[doc(alias = "get_caret_pos")]
    pub fn caret_pos(&self, index_: i32) -> (Rectangle, Rectangle) {
        unsafe {
            let mut strong_pos = Rectangle::uninitialized();
            let mut weak_pos = Rectangle::uninitialized();
            ffi::pango_layout_get_caret_pos(
                self.to_glib_none().0,
                index_,
                strong_pos.to_glib_none_mut().0,
                weak_pos.to_glib_none_mut().0,
            );
            (strong_pos, weak_pos)
        }
    }

    /// Returns the number of Unicode characters in the
    /// the text of @self.
    ///
    /// # Returns
    ///
    /// the number of Unicode characters
    ///   in the text of @self
    #[doc(alias = "pango_layout_get_character_count")]
    #[doc(alias = "get_character_count")]
    pub fn character_count(&self) -> i32 {
        unsafe { ffi::pango_layout_get_character_count(self.to_glib_none().0) }
    }

    /// Retrieves the [`Context`][crate::Context] used for this layout.
    ///
    /// # Returns
    ///
    /// the [`Context`][crate::Context] for the layout
    #[doc(alias = "pango_layout_get_context")]
    #[doc(alias = "get_context")]
    pub fn context(&self) -> Context {
        unsafe { from_glib_none(ffi::pango_layout_get_context(self.to_glib_none().0)) }
    }

    /// ',
    /// will insert it at the end.
    /// ## `index_`
    /// the byte index of the cursor
    ///
    /// # Returns
    ///
    ///
    /// ## `strong_pos`
    /// location to store the strong cursor position
    ///
    /// ## `weak_pos`
    /// location to store the weak cursor position
    #[doc(alias = "pango_layout_get_cursor_pos")]
    #[doc(alias = "get_cursor_pos")]
    pub fn cursor_pos(&self, index_: i32) -> (Rectangle, Rectangle) {
        unsafe {
            let mut strong_pos = Rectangle::uninitialized();
            let mut weak_pos = Rectangle::uninitialized();
            ffi::pango_layout_get_cursor_pos(
                self.to_glib_none().0,
                index_,
                strong_pos.to_glib_none_mut().0,
                weak_pos.to_glib_none_mut().0,
            );
            (strong_pos, weak_pos)
        }
    }

    /// Gets the text direction at the given character position in @self.
    /// ## `index`
    /// the byte index of the char
    ///
    /// # Returns
    ///
    /// the text direction at @index
    #[cfg(feature = "v1_46")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
    #[doc(alias = "pango_layout_get_direction")]
    #[doc(alias = "get_direction")]
    pub fn direction(&self, index: i32) -> Direction {
        unsafe {
            from_glib(ffi::pango_layout_get_direction(
                self.to_glib_none().0,
                index,
            ))
        }
    }

    /// Gets the type of ellipsization being performed for @self.
    ///
    /// See [`set_ellipsize()`][Self::set_ellipsize()].
    ///
    /// Use [`is_ellipsized()`][Self::is_ellipsized()] to query whether any
    /// paragraphs were actually ellipsized.
    ///
    /// # Returns
    ///
    /// the current ellipsization mode for @self
    #[doc(alias = "pango_layout_get_ellipsize")]
    #[doc(alias = "get_ellipsize")]
    pub fn ellipsize(&self) -> EllipsizeMode {
        unsafe { from_glib(ffi::pango_layout_get_ellipsize(self.to_glib_none().0)) }
    }

    /// Computes the logical and ink extents of @self.
    ///
    /// Logical extents are usually what you want for positioning things. Note
    /// that both extents may have non-zero x and y. You may want to use those
    /// to offset where you render the layout. Not doing that is a very typical
    /// bug that shows up as right-to-left layouts not being correctly positioned
    /// in a layout with a set width.
    ///
    /// The extents are given in layout coordinates and in Pango units; layout
    /// coordinates begin at the top left corner of the layout.
    ///
    /// # Returns
    ///
    ///
    /// ## `ink_rect`
    /// rectangle used to store the extents of the
    ///   layout as drawn
    ///
    /// ## `logical_rect`
    /// rectangle used to store the logical
    ///   extents of the layout
    #[doc(alias = "pango_layout_get_extents")]
    #[doc(alias = "get_extents")]
    pub fn extents(&self) -> (Rectangle, Rectangle) {
        unsafe {
            let mut ink_rect = Rectangle::uninitialized();
            let mut logical_rect = Rectangle::uninitialized();
            ffi::pango_layout_get_extents(
                self.to_glib_none().0,
                ink_rect.to_glib_none_mut().0,
                logical_rect.to_glib_none_mut().0,
            );
            (ink_rect, logical_rect)
        }
    }

    /// Gets the font description for the layout, if any.
    ///
    /// # Returns
    ///
    /// a pointer to the
    ///   layout's font description, or [`None`] if the font description
    ///   from the layout's context is inherited.
    #[doc(alias = "pango_layout_get_font_description")]
    #[doc(alias = "get_font_description")]
    pub fn font_description(&self) -> Option<FontDescription> {
        unsafe {
            from_glib_none(ffi::pango_layout_get_font_description(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the height of layout used for ellipsization.
    ///
    /// See [`set_height()`][Self::set_height()] for details.
    ///
    /// # Returns
    ///
    /// the height, in Pango units if positive,
    ///   or number of lines if negative.
    #[doc(alias = "pango_layout_get_height")]
    #[doc(alias = "get_height")]
    pub fn height(&self) -> i32 {
        unsafe { ffi::pango_layout_get_height(self.to_glib_none().0) }
    }

    /// Gets the paragraph indent width in Pango units.
    ///
    /// A negative value indicates a hanging indentation.
    ///
    /// # Returns
    ///
    /// the indent in Pango units
    #[doc(alias = "pango_layout_get_indent")]
    #[doc(alias = "get_indent")]
    pub fn indent(&self) -> i32 {
        unsafe { ffi::pango_layout_get_indent(self.to_glib_none().0) }
    }

    /// Returns an iterator to iterate over the visual extents of the layout.
    ///
    /// # Returns
    ///
    /// the new [`LayoutIter`][crate::LayoutIter]
    #[doc(alias = "pango_layout_get_iter")]
    #[doc(alias = "get_iter")]
    pub fn iter(&self) -> LayoutIter {
        unsafe { from_glib_full(ffi::pango_layout_get_iter(self.to_glib_none().0)) }
    }

    /// Gets whether each complete line should be stretched to fill the entire
    /// width of the layout.
    ///
    /// # Returns
    ///
    /// the justify value
    #[doc(alias = "pango_layout_get_justify")]
    #[doc(alias = "get_justify")]
    pub fn is_justify(&self) -> bool {
        unsafe { from_glib(ffi::pango_layout_get_justify(self.to_glib_none().0)) }
    }

    /// Gets whether the last line should be stretched
    /// to fill the entire width of the layout.
    ///
    /// # Returns
    ///
    /// the justify value
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_layout_get_justify_last_line")]
    #[doc(alias = "get_justify_last_line")]
    pub fn is_justify_last_line(&self) -> bool {
        unsafe {
            from_glib(ffi::pango_layout_get_justify_last_line(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves a particular line from a [`Layout`][crate::Layout].
    ///
    /// Use the faster [`line_readonly()`][Self::line_readonly()] if you do not
    /// plan to modify the contents of the line (glyphs, glyph widths, etc.).
    /// ## `line`
    /// the index of a line, which must be between 0 and
    ///   `pango_layout_get_line_count(layout) - 1`, inclusive.
    ///
    /// # Returns
    ///
    /// the requested [`LayoutLine`][crate::LayoutLine],
    ///   or [`None`] if the index is out of range. This layout line can be ref'ed
    ///   and retained, but will become invalid if changes are made to the
    ///   [`Layout`][crate::Layout].
    #[doc(alias = "pango_layout_get_line")]
    #[doc(alias = "get_line")]
    pub fn line(&self, line: i32) -> Option<LayoutLine> {
        unsafe { from_glib_none(ffi::pango_layout_get_line(self.to_glib_none().0, line)) }
    }

    /// Retrieves the count of lines for the @self.
    ///
    /// # Returns
    ///
    /// the line count
    #[doc(alias = "pango_layout_get_line_count")]
    #[doc(alias = "get_line_count")]
    pub fn line_count(&self) -> i32 {
        unsafe { ffi::pango_layout_get_line_count(self.to_glib_none().0) }
    }

    /// Retrieves a particular line from a [`Layout`][crate::Layout].
    ///
    /// This is a faster alternative to [`line()`][Self::line()],
    /// but the user is not expected to modify the contents of the line
    /// (glyphs, glyph widths, etc.).
    /// ## `line`
    /// the index of a line, which must be between 0 and
    ///   `pango_layout_get_line_count(layout) - 1`, inclusive.
    ///
    /// # Returns
    ///
    /// the requested [`LayoutLine`][crate::LayoutLine],
    ///   or [`None`] if the index is out of range. This layout line can be ref'ed
    ///   and retained, but will become invalid if changes are made to the
    ///   [`Layout`][crate::Layout]. No changes should be made to the line.
    #[doc(alias = "pango_layout_get_line_readonly")]
    #[doc(alias = "get_line_readonly")]
    pub fn line_readonly(&self, line: i32) -> Option<LayoutLine> {
        unsafe {
            from_glib_none(ffi::pango_layout_get_line_readonly(
                self.to_glib_none().0,
                line,
            ))
        }
    }

    /// Gets the line spacing factor of @self.
    ///
    /// See [`set_line_spacing()`][Self::set_line_spacing()].
    #[cfg(feature = "v1_44")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    #[doc(alias = "pango_layout_get_line_spacing")]
    #[doc(alias = "get_line_spacing")]
    pub fn line_spacing(&self) -> f32 {
        unsafe { ffi::pango_layout_get_line_spacing(self.to_glib_none().0) }
    }

    /// Returns the lines of the @self as a list.
    ///
    /// Use the faster [`lines_readonly()`][Self::lines_readonly()] if you do not
    /// plan to modify the contents of the lines (glyphs, glyph widths, etc.).
    ///
    /// # Returns
    ///
    /// a `GSList`
    ///   containing the lines in the layout. This points to internal data of the
    ///   [`Layout`][crate::Layout] and must be used with care. It will become invalid on any
    ///   change to the layout's text or properties.
    #[doc(alias = "pango_layout_get_lines")]
    #[doc(alias = "get_lines")]
    pub fn lines(&self) -> Vec<LayoutLine> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::pango_layout_get_lines(self.to_glib_none().0))
        }
    }

    /// Returns the lines of the @self as a list.
    ///
    /// This is a faster alternative to [`lines()`][Self::lines()],
    /// but the user is not expected to modify the contents of the lines
    /// (glyphs, glyph widths, etc.).
    ///
    /// # Returns
    ///
    /// a `GSList`
    ///   containing the lines in the layout. This points to internal data of the
    ///   [`Layout`][crate::Layout] and must be used with care. It will become invalid on any
    ///   change to the layout's text or properties. No changes should be made to
    ///   the lines.
    #[doc(alias = "pango_layout_get_lines_readonly")]
    #[doc(alias = "get_lines_readonly")]
    pub fn lines_readonly(&self) -> Vec<LayoutLine> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::pango_layout_get_lines_readonly(
                self.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "pango_layout_get_log_attrs")]
    //#[doc(alias = "get_log_attrs")]
    //pub fn log_attrs(&self, attrs: /*Ignored*/Vec<LogAttr>) -> i32 {
    //    unsafe { TODO: call ffi:pango_layout_get_log_attrs() }
    //}

    //#[doc(alias = "pango_layout_get_log_attrs_readonly")]
    //#[doc(alias = "get_log_attrs_readonly")]
    //pub fn log_attrs_readonly(&self) -> /*Ignored*/Vec<LogAttr> {
    //    unsafe { TODO: call ffi:pango_layout_get_log_attrs_readonly() }
    //}

    /// Computes the logical and ink extents of @self in device units.
    ///
    /// This function just calls [`extents()`][Self::extents()] followed by
    /// two [`extents_to_pixels()`][crate::extents_to_pixels()] calls, rounding @ink_rect and @logical_rect
    /// such that the rounded rectangles fully contain the unrounded one (that is,
    /// passes them as first argument to [`extents_to_pixels()`][crate::extents_to_pixels()]).
    ///
    /// # Returns
    ///
    ///
    /// ## `ink_rect`
    /// rectangle used to store the extents of the
    ///   layout as drawn
    ///
    /// ## `logical_rect`
    /// rectangle used to store the logical
    ///   extents of the layout
    #[doc(alias = "pango_layout_get_pixel_extents")]
    #[doc(alias = "get_pixel_extents")]
    pub fn pixel_extents(&self) -> (Rectangle, Rectangle) {
        unsafe {
            let mut ink_rect = Rectangle::uninitialized();
            let mut logical_rect = Rectangle::uninitialized();
            ffi::pango_layout_get_pixel_extents(
                self.to_glib_none().0,
                ink_rect.to_glib_none_mut().0,
                logical_rect.to_glib_none_mut().0,
            );
            (ink_rect, logical_rect)
        }
    }

    /// Determines the logical width and height of a [`Layout`][crate::Layout] in device
    /// units.
    ///
    /// [`size()`][Self::size()] returns the width and height
    /// scaled by `PANGO_SCALE`. This is simply a convenience function
    /// around [`pixel_extents()`][Self::pixel_extents()].
    ///
    /// # Returns
    ///
    ///
    /// ## `width`
    /// location to store the logical width
    ///
    /// ## `height`
    /// location to store the logical height
    #[doc(alias = "pango_layout_get_pixel_size")]
    #[doc(alias = "get_pixel_size")]
    pub fn pixel_size(&self) -> (i32, i32) {
        unsafe {
            let mut width = std::mem::MaybeUninit::uninit();
            let mut height = std::mem::MaybeUninit::uninit();
            ffi::pango_layout_get_pixel_size(
                self.to_glib_none().0,
                width.as_mut_ptr(),
                height.as_mut_ptr(),
            );
            (width.assume_init(), height.assume_init())
        }
    }

    /// Returns the current serial number of @self.
    ///
    /// The serial number is initialized to an small number larger than zero
    /// when a new layout is created and is increased whenever the layout is
    /// changed using any of the setter functions, or the [`Context`][crate::Context] it
    /// uses has changed. The serial may wrap, but will never have the value 0.
    /// Since it can wrap, never compare it with "less than", always use "not equals".
    ///
    /// This can be used to automatically detect changes to a [`Layout`][crate::Layout],
    /// and is useful for example to decide whether a layout needs redrawing.
    /// To force the serial to be increased, use
    /// [`context_changed()`][Self::context_changed()].
    ///
    /// # Returns
    ///
    /// The current serial number of @self.
    #[doc(alias = "pango_layout_get_serial")]
    #[doc(alias = "get_serial")]
    pub fn serial(&self) -> u32 {
        unsafe { ffi::pango_layout_get_serial(self.to_glib_none().0) }
    }

    /// Obtains whether @self is in single paragraph mode.
    ///
    /// See [`set_single_paragraph_mode()`][Self::set_single_paragraph_mode()].
    ///
    /// # Returns
    ///
    /// [`true`] if the layout does not break paragraphs
    ///   at paragraph separator characters, [`false`] otherwise
    #[doc(alias = "pango_layout_get_single_paragraph_mode")]
    #[doc(alias = "get_single_paragraph_mode")]
    pub fn is_single_paragraph_mode(&self) -> bool {
        unsafe {
            from_glib(ffi::pango_layout_get_single_paragraph_mode(
                self.to_glib_none().0,
            ))
        }
    }

    /// Determines the logical width and height of a [`Layout`][crate::Layout] in Pango
    /// units.
    ///
    /// This is simply a convenience function around [`extents()`][Self::extents()].
    ///
    /// # Returns
    ///
    ///
    /// ## `width`
    /// location to store the logical width
    ///
    /// ## `height`
    /// location to store the logical height
    #[doc(alias = "pango_layout_get_size")]
    #[doc(alias = "get_size")]
    pub fn size(&self) -> (i32, i32) {
        unsafe {
            let mut width = std::mem::MaybeUninit::uninit();
            let mut height = std::mem::MaybeUninit::uninit();
            ffi::pango_layout_get_size(
                self.to_glib_none().0,
                width.as_mut_ptr(),
                height.as_mut_ptr(),
            );
            (width.assume_init(), height.assume_init())
        }
    }

    /// Gets the amount of spacing between the lines of the layout.
    ///
    /// # Returns
    ///
    /// the spacing in Pango units
    #[doc(alias = "pango_layout_get_spacing")]
    #[doc(alias = "get_spacing")]
    pub fn spacing(&self) -> i32 {
        unsafe { ffi::pango_layout_get_spacing(self.to_glib_none().0) }
    }

    /// Gets the current [`TabArray`][crate::TabArray] used by this layout.
    ///
    /// If no [`TabArray`][crate::TabArray] has been set, then the default tabs are
    /// in use and [`None`] is returned. Default tabs are every 8 spaces.
    ///
    /// The return value should be freed with `Pango::TabArray::free()`.
    ///
    /// # Returns
    ///
    /// a copy of the tabs for this layout
    #[doc(alias = "pango_layout_get_tabs")]
    #[doc(alias = "get_tabs")]
    pub fn tabs(&self) -> Option<TabArray> {
        unsafe { from_glib_full(ffi::pango_layout_get_tabs(self.to_glib_none().0)) }
    }

    /// Gets the text in the layout.
    ///
    /// The returned text should not be freed or modified.
    ///
    /// # Returns
    ///
    /// the text in the @self
    #[doc(alias = "pango_layout_get_text")]
    #[doc(alias = "get_text")]
    pub fn text(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::pango_layout_get_text(self.to_glib_none().0)) }
    }

    /// Counts the number of unknown glyphs in @self.
    ///
    /// This function can be used to determine if there are any fonts
    /// available to render all characters in a certain string, or when
    /// used in combination with [`AttrType::Fallback`][crate::AttrType::Fallback], to check if a
    /// certain font supports all the characters in the string.
    ///
    /// # Returns
    ///
    /// The number of unknown glyphs in @self
    #[doc(alias = "pango_layout_get_unknown_glyphs_count")]
    #[doc(alias = "get_unknown_glyphs_count")]
    pub fn unknown_glyphs_count(&self) -> i32 {
        unsafe { ffi::pango_layout_get_unknown_glyphs_count(self.to_glib_none().0) }
    }

    /// Gets the width to which the lines of the [`Layout`][crate::Layout] should wrap.
    ///
    /// # Returns
    ///
    /// the width in Pango units, or -1 if no width set.
    #[doc(alias = "pango_layout_get_width")]
    #[doc(alias = "get_width")]
    pub fn width(&self) -> i32 {
        unsafe { ffi::pango_layout_get_width(self.to_glib_none().0) }
    }

    /// Gets the wrap mode for the layout.
    ///
    /// Use [`is_wrapped()`][Self::is_wrapped()] to query whether
    /// any paragraphs were actually wrapped.
    ///
    /// # Returns
    ///
    /// active wrap mode.
    #[doc(alias = "pango_layout_get_wrap")]
    #[doc(alias = "get_wrap")]
    pub fn wrap(&self) -> WrapMode {
        unsafe { from_glib(ffi::pango_layout_get_wrap(self.to_glib_none().0)) }
    }

    /// Converts from byte @index_ within the @self to line and X position.
    ///
    /// The X position is measured from the left edge of the line.
    /// ## `index_`
    /// the byte index of a grapheme within the layout
    /// ## `trailing`
    ///  0, the trailing edge of the grapheme, if 0,
    ///   the leading of the grapheme
    ///
    /// # Returns
    ///
    ///
    /// ## `line`
    /// location to store resulting line index. (which will
    ///   between 0 and pango_layout_get_line_count(layout) - 1)
    ///
    /// ## `x_pos`
    /// location to store resulting position within line
    ///   (`PANGO_SCALE` units per device unit)
    #[doc(alias = "pango_layout_index_to_line_x")]
    pub fn index_to_line_x(&self, index_: i32, trailing: bool) -> (i32, i32) {
        unsafe {
            let mut line = std::mem::MaybeUninit::uninit();
            let mut x_pos = std::mem::MaybeUninit::uninit();
            ffi::pango_layout_index_to_line_x(
                self.to_glib_none().0,
                index_,
                trailing.into_glib(),
                line.as_mut_ptr(),
                x_pos.as_mut_ptr(),
            );
            (line.assume_init(), x_pos.assume_init())
        }
    }

    /// width` will be negative.
    /// ## `index_`
    /// byte index within @self
    ///
    /// # Returns
    ///
    ///
    /// ## `pos`
    /// rectangle in which to store the position of the grapheme
    #[doc(alias = "pango_layout_index_to_pos")]
    pub fn index_to_pos(&self, index_: i32) -> Rectangle {
        unsafe {
            let mut pos = Rectangle::uninitialized();
            ffi::pango_layout_index_to_pos(self.to_glib_none().0, index_, pos.to_glib_none_mut().0);
            pos
        }
    }

    /// Queries whether the layout had to ellipsize any paragraphs.
    ///
    /// This returns [`true`] if the ellipsization mode for @self
    /// is not [`EllipsizeMode::None`][crate::EllipsizeMode::None], a positive width is set on @self,
    /// and there are paragraphs exceeding that width that have to be
    /// ellipsized.
    ///
    /// # Returns
    ///
    /// [`true`] if any paragraphs had to be ellipsized,
    ///   [`false`] otherwise
    #[doc(alias = "pango_layout_is_ellipsized")]
    pub fn is_ellipsized(&self) -> bool {
        unsafe { from_glib(ffi::pango_layout_is_ellipsized(self.to_glib_none().0)) }
    }

    /// Queries whether the layout had to wrap any paragraphs.
    ///
    /// This returns [`true`] if a positive width is set on @self,
    /// and there are paragraphs exceeding the layout width that have
    /// to be wrapped.
    ///
    /// # Returns
    ///
    /// [`true`] if any paragraphs had to be wrapped, [`false`]
    ///   otherwise
    #[doc(alias = "pango_layout_is_wrapped")]
    pub fn is_wrapped(&self) -> bool {
        unsafe { from_glib(ffi::pango_layout_is_wrapped(self.to_glib_none().0)) }
    }

    /// Computes a new cursor position from an old position and a direction.
    ///
    /// If @direction is positive, then the new position will cause the strong
    /// or weak cursor to be displayed one position to right of where it was
    /// with the old cursor position. If @direction is negative, it will be
    /// moved to the left.
    ///
    /// In the presence of bidirectional text, the correspondence between
    /// logical and visual order will depend on the direction of the current
    /// run, and there may be jumps when the cursor is moved off of the end
    /// of a run.
    ///
    /// Motion here is in cursor positions, not in characters, so a single
    /// call to this function may move the cursor over multiple characters
    /// when multiple characters combine to form a single grapheme.
    /// ## `strong`
    /// whether the moving cursor is the strong cursor or the
    ///   weak cursor. The strong cursor is the cursor corresponding
    ///   to text insertion in the base direction for the layout.
    /// ## `old_index`
    /// the byte index of the current cursor position
    /// ## `old_trailing`
    ///  0, the cursor
    ///   was at the trailing edge.
    /// ## `direction`
    /// direction to move cursor. A negative
    ///   value indicates motion to the left
    ///
    /// # Returns
    ///
    ///
    /// ## `new_index`
    /// location to store the new cursor byte index.
    ///   A value of -1 indicates that the cursor has been moved off the
    ///   beginning of the layout. A value of `G_MAXINT` indicates that
    ///   the cursor has been moved off the end of the layout.
    ///
    /// ## `new_trailing`
    /// number of characters to move forward from
    ///   the location returned for @new_index to get the position where
    ///   the cursor should be displayed. This allows distinguishing the
    ///   position at the beginning of one line from the position at the
    ///   end of the preceding line. @new_index is always on the line where
    ///   the cursor should be displayed.
    #[doc(alias = "pango_layout_move_cursor_visually")]
    pub fn move_cursor_visually(
        &self,
        strong: bool,
        old_index: i32,
        old_trailing: i32,
        direction: i32,
    ) -> (i32, i32) {
        unsafe {
            let mut new_index = std::mem::MaybeUninit::uninit();
            let mut new_trailing = std::mem::MaybeUninit::uninit();
            ffi::pango_layout_move_cursor_visually(
                self.to_glib_none().0,
                strong.into_glib(),
                old_index,
                old_trailing,
                direction,
                new_index.as_mut_ptr(),
                new_trailing.as_mut_ptr(),
            );
            (new_index.assume_init(), new_trailing.assume_init())
        }
    }

    /// Serializes the @self for later deserialization via `Pango::Layout::deserialize()`.
    ///
    /// There are no guarantees about the format of the output across different
    /// versions of Pango and `Pango::Layout::deserialize()` will reject data
    /// that it cannot parse.
    ///
    /// The intended use of this function is testing, benchmarking and debugging.
    /// The format is not meant as a permanent storage format.
    /// ## `flags`
    /// [`LayoutSerializeFlags`][crate::LayoutSerializeFlags]
    ///
    /// # Returns
    ///
    /// a `GBytes` containing the serialized form of @self
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_layout_serialize")]
    pub fn serialize(&self, flags: LayoutSerializeFlags) -> glib::Bytes {
        unsafe {
            from_glib_full(ffi::pango_layout_serialize(
                self.to_glib_none().0,
                flags.into_glib(),
            ))
        }
    }

    /// Sets the alignment for the layout: how partial lines are
    /// positioned within the horizontal space available.
    ///
    /// The default alignment is [`Alignment::Left`][crate::Alignment::Left].
    /// ## `alignment`
    /// the alignment
    #[doc(alias = "pango_layout_set_alignment")]
    pub fn set_alignment(&self, alignment: Alignment) {
        unsafe {
            ffi::pango_layout_set_alignment(self.to_glib_none().0, alignment.into_glib());
        }
    }

    /// Sets the text attributes for a layout object.
    ///
    /// References @attrs, so the caller can unref its reference.
    /// ## `attrs`
    /// a [`AttrList`][crate::AttrList]
    #[doc(alias = "pango_layout_set_attributes")]
    pub fn set_attributes(&self, attrs: Option<&AttrList>) {
        unsafe {
            ffi::pango_layout_set_attributes(self.to_glib_none().0, attrs.to_glib_none().0);
        }
    }

    /// Sets whether to calculate the base direction
    /// for the layout according to its contents.
    ///
    /// When this flag is on (the default), then paragraphs in @self that
    /// begin with strong right-to-left characters (Arabic and Hebrew principally),
    /// will have right-to-left layout, paragraphs with letters from other scripts
    /// will have left-to-right layout. Paragraphs with only neutral characters
    /// get their direction from the surrounding paragraphs.
    ///
    /// When [`false`], the choice between left-to-right and right-to-left
    /// layout is done according to the base direction of the layout's
    /// [`Context`][crate::Context]. (See [`Context::set_base_dir()`][crate::Context::set_base_dir()]).
    ///
    /// When the auto-computed direction of a paragraph differs from the
    /// base direction of the context, the interpretation of
    /// [`Alignment::Left`][crate::Alignment::Left] and [`Alignment::Right`][crate::Alignment::Right] are swapped.
    /// ## `auto_dir`
    /// if [`true`], compute the bidirectional base direction
    ///   from the layout's contents
    #[doc(alias = "pango_layout_set_auto_dir")]
    pub fn set_auto_dir(&self, auto_dir: bool) {
        unsafe {
            ffi::pango_layout_set_auto_dir(self.to_glib_none().0, auto_dir.into_glib());
        }
    }

    /// Sets the type of ellipsization being performed for @self.
    ///
    /// Depending on the ellipsization mode @ellipsize text is
    /// removed from the start, middle, or end of text so they
    /// fit within the width and height of layout set with
    /// [`set_width()`][Self::set_width()] and [`set_height()`][Self::set_height()].
    ///
    /// If the layout contains characters such as newlines that
    /// force it to be layed out in multiple paragraphs, then whether
    /// each paragraph is ellipsized separately or the entire layout
    /// is ellipsized as a whole depends on the set height of the layout.
    ///
    /// The default value is [`EllipsizeMode::None`][crate::EllipsizeMode::None].
    ///
    /// See [`set_height()`][Self::set_height()] for details.
    /// ## `ellipsize`
    /// the new ellipsization mode for @self
    #[doc(alias = "pango_layout_set_ellipsize")]
    pub fn set_ellipsize(&self, ellipsize: EllipsizeMode) {
        unsafe {
            ffi::pango_layout_set_ellipsize(self.to_glib_none().0, ellipsize.into_glib());
        }
    }

    /// Sets the default font description for the layout.
    ///
    /// If no font description is set on the layout, the
    /// font description from the layout's context is used.
    /// ## `desc`
    /// the new [`FontDescription`][crate::FontDescription]
    ///   to unset the current font description
    #[doc(alias = "pango_layout_set_font_description")]
    pub fn set_font_description(&self, desc: Option<&FontDescription>) {
        unsafe {
            ffi::pango_layout_set_font_description(self.to_glib_none().0, desc.to_glib_none().0);
        }
    }

    /// Sets the height to which the [`Layout`][crate::Layout] should be ellipsized at.
    ///
    /// There are two different behaviors, based on whether @height is positive
    /// or negative.
    ///
    /// If @height is positive, it will be the maximum height of the layout. Only
    /// lines would be shown that would fit, and if there is any text omitted,
    /// an ellipsis added. At least one line is included in each paragraph regardless
    /// of how small the height value is. A value of zero will render exactly one
    /// line for the entire layout.
    ///
    /// If @height is negative, it will be the (negative of) maximum number of lines
    /// per paragraph. That is, the total number of lines shown may well be more than
    /// this value if the layout contains multiple paragraphs of text.
    /// The default value of -1 means that the first line of each paragraph is ellipsized.
    /// This behavior may be changed in the future to act per layout instead of per
    /// paragraph. File a bug against pango at
    /// [https://gitlab.gnome.org/gnome/pango](https://gitlab.gnome.org/gnome/pango)
    /// if your code relies on this behavior.
    ///
    /// Height setting only has effect if a positive width is set on
    /// @self and ellipsization mode of @self is not [`EllipsizeMode::None`][crate::EllipsizeMode::None].
    /// The behavior is undefined if a height other than -1 is set and
    /// ellipsization mode is set to [`EllipsizeMode::None`][crate::EllipsizeMode::None], and may change in the
    /// future.
    /// ## `height`
    /// the desired height of the layout in Pango units if positive,
    ///   or desired number of lines if negative.
    #[doc(alias = "pango_layout_set_height")]
    pub fn set_height(&self, height: i32) {
        unsafe {
            ffi::pango_layout_set_height(self.to_glib_none().0, height);
        }
    }

    /// Sets the width in Pango units to indent each paragraph.
    ///
    /// A negative value of @indent will produce a hanging indentation.
    /// That is, the first line will have the full width, and subsequent
    /// lines will be indented by the absolute value of @indent.
    ///
    /// The indent setting is ignored if layout alignment is set to
    /// [`Alignment::Center`][crate::Alignment::Center].
    ///
    /// The default value is 0.
    /// ## `indent`
    /// the amount by which to indent
    #[doc(alias = "pango_layout_set_indent")]
    pub fn set_indent(&self, indent: i32) {
        unsafe {
            ffi::pango_layout_set_indent(self.to_glib_none().0, indent);
        }
    }

    /// Sets whether each complete line should be stretched to fill the
    /// entire width of the layout.
    ///
    /// Stretching is typically done by adding whitespace, but for some scripts
    /// (such as Arabic), the justification may be done in more complex ways,
    /// like extending the characters.
    ///
    /// Note that this setting is not implemented and so is ignored in
    /// Pango older than 1.18.
    ///
    /// Note that tabs and justification conflict with each other:
    /// Justification will move content away from its tab-aligned
    /// positions.
    ///
    /// The default value is [`false`].
    ///
    /// Also see [`set_justify_last_line()`][Self::set_justify_last_line()].
    /// ## `justify`
    /// whether the lines in the layout should be justified
    #[doc(alias = "pango_layout_set_justify")]
    pub fn set_justify(&self, justify: bool) {
        unsafe {
            ffi::pango_layout_set_justify(self.to_glib_none().0, justify.into_glib());
        }
    }

    /// Sets whether the last line should be stretched to fill the
    /// entire width of the layout.
    ///
    /// This only has an effect if [`set_justify()`][Self::set_justify()] has
    /// been called as well.
    ///
    /// The default value is [`false`].
    /// ## `justify`
    /// whether the last line in the layout should be justified
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_layout_set_justify_last_line")]
    pub fn set_justify_last_line(&self, justify: bool) {
        unsafe {
            ffi::pango_layout_set_justify_last_line(self.to_glib_none().0, justify.into_glib());
        }
    }

    /// Sets a factor for line spacing.
    ///
    /// Typical values are: 0, 1, 1.5, 2. The default values is 0.
    ///
    /// If @factor is non-zero, lines are placed so that
    ///
    ///     baseline2 = baseline1 + factor * height2
    ///
    /// where height2 is the line height of the second line
    /// (as determined by the font(s)). In this case, the spacing
    /// set with [`set_spacing()`][Self::set_spacing()] is ignored.
    ///
    /// If @factor is zero (the default), spacing is applied as before.
    ///
    /// Note: for semantics that are closer to the CSS line-height
    /// property, see `attr_line_height_new()`.
    /// ## `factor`
    /// the new line spacing factor
    #[cfg(feature = "v1_44")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    #[doc(alias = "pango_layout_set_line_spacing")]
    pub fn set_line_spacing(&self, factor: f32) {
        unsafe {
            ffi::pango_layout_set_line_spacing(self.to_glib_none().0, factor);
        }
    }

    /// Sets the layout text and attribute list from marked-up text.
    ///
    /// See [Pango Markup](pango_markup.html)).
    ///
    /// Replaces the current text and attribute list.
    ///
    /// This is the same as [`set_markup_with_accel()`][Self::set_markup_with_accel()],
    /// but the markup text isn't scanned for accelerators.
    /// ## `markup`
    /// marked-up text
    /// ## `length`
    /// length of marked-up text in bytes, or -1 if @markup is
    ///   `NUL`-terminated
    #[doc(alias = "pango_layout_set_markup")]
    pub fn set_markup(&self, markup: &str) {
        let length = markup.len() as _;
        unsafe {
            ffi::pango_layout_set_markup(self.to_glib_none().0, markup.to_glib_none().0, length);
        }
    }

    /// Sets the layout text and attribute list from marked-up text.
    ///
    /// See [Pango Markup](pango_markup.html)).
    ///
    /// Replaces the current text and attribute list.
    ///
    /// 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.
    /// ## `markup`
    /// marked-up text (see [Pango Markup](pango_markup.html))
    /// ## `length`
    /// length of marked-up text in bytes, or -1 if @markup is
    ///   `NUL`-terminated
    /// ## `accel_marker`
    /// marker for accelerators in the text
    ///
    /// # Returns
    ///
    ///
    /// ## `accel_char`
    /// return location
    ///   for first located accelerator
    #[doc(alias = "pango_layout_set_markup_with_accel")]
    pub fn set_markup_with_accel(&self, markup: &str, accel_marker: char) -> char {
        let length = markup.len() as _;
        unsafe {
            let mut accel_char = std::mem::MaybeUninit::uninit();
            ffi::pango_layout_set_markup_with_accel(
                self.to_glib_none().0,
                markup.to_glib_none().0,
                length,
                accel_marker.into_glib(),
                accel_char.as_mut_ptr(),
            );
            std::convert::TryFrom::try_from(accel_char.assume_init())
                .expect("conversion from an invalid Unicode value attempted")
        }
    }

    /// Sets the single paragraph mode of @self.
    ///
    /// If @setting is [`true`], do not treat newlines and similar characters
    /// as paragraph separators; instead, keep all text in a single paragraph,
    /// and display a glyph for paragraph separator characters. Used when
    /// you want to allow editing of newlines on a single text line.
    ///
    /// The default value is [`false`].
    /// ## `setting`
    /// new setting
    #[doc(alias = "pango_layout_set_single_paragraph_mode")]
    pub fn set_single_paragraph_mode(&self, setting: bool) {
        unsafe {
            ffi::pango_layout_set_single_paragraph_mode(self.to_glib_none().0, setting.into_glib());
        }
    }

    /// Sets the amount of spacing in Pango units between
    /// the lines of the layout.
    ///
    /// When placing lines with spacing, Pango arranges things so that
    ///
    ///     line2.top = line1.bottom + spacing
    ///
    /// The default value is 0.
    ///
    /// Note: Since 1.44, Pango is using the line height (as determined
    /// by the font) for placing lines when the line spacing factor is set
    /// to a non-zero value with [`set_line_spacing()`][Self::set_line_spacing()].
    /// In that case, the @spacing set with this function is ignored.
    ///
    /// Note: for semantics that are closer to the CSS line-height
    /// property, see `attr_line_height_new()`.
    /// ## `spacing`
    /// the amount of spacing
    #[doc(alias = "pango_layout_set_spacing")]
    pub fn set_spacing(&self, spacing: i32) {
        unsafe {
            ffi::pango_layout_set_spacing(self.to_glib_none().0, spacing);
        }
    }

    /// Sets the tabs to use for @self, overriding the default tabs.
    ///
    /// [`Layout`][crate::Layout] will place content at the next tab position
    /// whenever it meets a Tab character (U+0009).
    ///
    /// By default, tabs are every 8 spaces. If @tabs is [`None`], the
    /// default tabs are reinstated. @tabs is copied into the layout;
    /// you must free your copy of @tabs yourself.
    ///
    /// Note that tabs and justification conflict with each other:
    /// Justification will move content away from its tab-aligned
    /// positions. The same is true for alignments other than
    /// [`Alignment::Left`][crate::Alignment::Left].
    /// ## `tabs`
    /// a [`TabArray`][crate::TabArray]
    #[doc(alias = "pango_layout_set_tabs")]
    pub fn set_tabs(&self, tabs: Option<&TabArray>) {
        unsafe {
            ffi::pango_layout_set_tabs(self.to_glib_none().0, mut_override(tabs.to_glib_none().0));
        }
    }

    /// Sets the text of the layout.
    ///
    /// This function validates @text and renders invalid UTF-8
    /// with a placeholder glyph.
    ///
    /// Note that if you have used [`set_markup()`][Self::set_markup()] or
    /// [`set_markup_with_accel()`][Self::set_markup_with_accel()] on @self before, you
    /// may want to call [`set_attributes()`][Self::set_attributes()] to clear the
    /// attributes set on the layout from the markup as this function does
    /// not clear attributes.
    /// ## `text`
    /// the text
    /// ## `length`
    /// maximum length of @text, in bytes. -1 indicates that
    ///   the string is nul-terminated and the length should be calculated.
    ///   The text will also be truncated on encountering a nul-termination
    ///   even when @length is positive.
    #[doc(alias = "pango_layout_set_text")]
    pub fn set_text(&self, text: &str) {
        let length = text.len() as _;
        unsafe {
            ffi::pango_layout_set_text(self.to_glib_none().0, text.to_glib_none().0, length);
        }
    }

    /// Sets the width to which the lines of the [`Layout`][crate::Layout] should wrap or
    /// get ellipsized.
    ///
    /// The default value is -1: no width set.
    /// ## `width`
    /// the desired width in Pango units, or -1 to indicate that no
    ///   wrapping or ellipsization should be performed.
    #[doc(alias = "pango_layout_set_width")]
    pub fn set_width(&self, width: i32) {
        unsafe {
            ffi::pango_layout_set_width(self.to_glib_none().0, width);
        }
    }

    /// Sets the wrap mode.
    ///
    /// The wrap mode only has effect if a width is set on the layout
    /// with [`set_width()`][Self::set_width()]. To turn off wrapping,
    /// set the width to -1.
    ///
    /// The default value is [`WrapMode::Word`][crate::WrapMode::Word].
    /// ## `wrap`
    /// the wrap mode
    #[doc(alias = "pango_layout_set_wrap")]
    pub fn set_wrap(&self, wrap: WrapMode) {
        unsafe {
            ffi::pango_layout_set_wrap(self.to_glib_none().0, wrap.into_glib());
        }
    }

    /// A convenience method to serialize a layout to a file.
    ///
    /// It is equivalent to calling [`serialize()`][Self::serialize()]
    /// followed by `file_set_contents()`.
    ///
    /// See those two functions for details on the arguments.
    ///
    /// It is mostly intended for use inside a debugger to quickly dump
    /// a layout to a file for later inspection.
    /// ## `flags`
    /// [`LayoutSerializeFlags`][crate::LayoutSerializeFlags]
    /// ## `filename`
    /// the file to save it to
    ///
    /// # Returns
    ///
    /// [`true`] if saving was successful
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_layout_write_to_file")]
    pub fn write_to_file(
        &self,
        flags: LayoutSerializeFlags,
        filename: impl AsRef<std::path::Path>,
    ) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::pango_layout_write_to_file(
                self.to_glib_none().0,
                flags.into_glib(),
                filename.as_ref().to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Converts from X and Y position within a layout to the byte index to the
    /// character at that logical position.
    ///
    /// If the Y position is not inside the layout, the closest position is
    /// chosen (the position will be clamped inside the layout). If the X position
    /// is not within the layout, then the start or the end of the line is
    /// chosen as described for [`LayoutLine::x_to_index()`][crate::LayoutLine::x_to_index()]. If either
    /// the X or Y positions were not inside the layout, then the function returns
    /// [`false`]; on an exact hit, it returns [`true`].
    /// ## `x`
    /// the X offset (in Pango units) from the left edge of the layout
    /// ## `y`
    /// the Y offset (in Pango units) from the top edge of the layout
    ///
    /// # Returns
    ///
    /// [`true`] if the coordinates were inside text, [`false`] otherwise
    ///
    /// ## `index_`
    /// location to store calculated byte index
    ///
    /// ## `trailing`
    /// location to store a integer indicating where
    ///   in the grapheme the user clicked. It will either be zero, or the
    ///   number of characters in the grapheme. 0 represents the leading edge
    ///   of the grapheme.
    #[doc(alias = "pango_layout_xy_to_index")]
    pub fn xy_to_index(&self, x: i32, y: i32) -> (bool, i32, i32) {
        unsafe {
            let mut index_ = std::mem::MaybeUninit::uninit();
            let mut trailing = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::pango_layout_xy_to_index(
                self.to_glib_none().0,
                x,
                y,
                index_.as_mut_ptr(),
                trailing.as_mut_ptr(),
            ));
            (ret, index_.assume_init(), trailing.assume_init())
        }
    }
}