pango/functions.rs
1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use glib::translate::*;
4
5pub use crate::auto::functions::*;
6#[cfg(feature = "v1_44")]
7use crate::ShapeFlags;
8use crate::{ffi, Analysis, GlyphString, Item};
9
10/// Reorder items from logical order to visual order.
11///
12/// The visual order is determined from the associated directional
13/// levels of the items. The original list is unmodified.
14///
15/// (Please open a bug if you use this function.
16/// It is not a particularly convenient interface, and the code
17/// is duplicated elsewhere in Pango for that reason.)
18/// ## `items`
19/// a `GList` of [`Item`][crate::Item]
20/// in logical order.
21///
22/// # Returns
23///
24/// a `GList`
25/// of [`Item`][crate::Item] structures in visual order.
26#[doc(alias = "pango_reorder_items")]
27pub fn reorder_items(logical_items: &glib::List<Item>) -> glib::List<Item> {
28 unsafe {
29 FromGlibPtrContainer::from_glib_full(ffi::pango_reorder_items(
30 logical_items.as_ptr() as *mut _
31 ))
32 }
33}
34
35/// Convert the characters in @text into glyphs.
36///
37/// Given a segment of text and the corresponding [`Analysis`][crate::Analysis] structure
38/// returned from [`itemize()`][crate::itemize()], convert the characters into glyphs.
39/// You may also pass in only a substring of the item from [`itemize()`][crate::itemize()].
40///
41/// This is similar to [`shape()`][crate::shape()], except it also can optionally take
42/// the full paragraph text as input, which will then be used to perform
43/// certain cross-item shaping interactions. If you have access to the broader
44/// text of which @item_text is part of, provide the broader text as
45/// @paragraph_text. If @paragraph_text is [`None`], item text is used instead.
46///
47/// Some aspects of hyphen insertion and text transformation (in particular,
48/// capitalization) require log attrs, and thus can only be handled by
49/// `shape_item()`.
50///
51/// Note that the extra attributes in the @analyis that is returned from
52/// [`itemize()`][crate::itemize()] have indices that are relative to the entire paragraph,
53/// so you do not pass the full paragraph text as @paragraph_text, you need
54/// to subtract the item offset from their indices before calling
55/// [`shape_full()`][crate::shape_full()].
56/// ## `item_text`
57/// valid UTF-8 text to shape.
58/// ## `item_length`
59/// the length (in bytes) of @item_text. -1 means nul-terminated text.
60/// ## `paragraph_text`
61/// text of the paragraph (see details).
62/// ## `paragraph_length`
63/// the length (in bytes) of @paragraph_text. -1 means nul-terminated text.
64/// ## `analysis`
65/// [`Analysis`][crate::Analysis] structure from [`itemize()`][crate::itemize()].
66/// ## `glyphs`
67/// glyph string in which to store results.
68#[doc(alias = "pango_shape_full")]
69pub fn shape_full(
70 item_text: &str,
71 paragraph_text: Option<&str>,
72 analysis: &Analysis,
73 glyphs: &mut GlyphString,
74) {
75 let paragraph_length = match paragraph_text {
76 Some(s) => s.len(),
77 None => 0,
78 } as i32;
79 let paragraph_text = paragraph_text.to_glib_none();
80 let item_length = item_text.len() as i32;
81 unsafe {
82 ffi::pango_shape_full(
83 item_text.to_glib_none().0,
84 item_length,
85 paragraph_text.0,
86 paragraph_length,
87 analysis.to_glib_none().0,
88 glyphs.to_glib_none_mut().0,
89 );
90 }
91}
92
93/// Convert the characters in @text into glyphs.
94///
95/// Given a segment of text and the corresponding [`Analysis`][crate::Analysis] structure
96/// returned from [`itemize()`][crate::itemize()], convert the characters into glyphs.
97/// You may also pass in only a substring of the item from [`itemize()`][crate::itemize()].
98///
99/// This is similar to [`shape_full()`][crate::shape_full()], except it also takes flags
100/// that can influence the shaping process.
101///
102/// Some aspects of hyphen insertion and text transformation (in particular,
103/// capitalization) require log attrs, and thus can only be handled by
104/// `shape_item()`.
105///
106/// Note that the extra attributes in the @analyis that is returned from
107/// [`itemize()`][crate::itemize()] have indices that are relative to the entire paragraph,
108/// so you do not pass the full paragraph text as @paragraph_text, you need
109/// to subtract the item offset from their indices before calling
110/// [`shape_with_flags()`][crate::shape_with_flags()].
111/// ## `item_text`
112/// valid UTF-8 text to shape
113/// ## `item_length`
114/// the length (in bytes) of @item_text.
115/// -1 means nul-terminated text.
116/// ## `paragraph_text`
117/// text of the paragraph (see details).
118/// ## `paragraph_length`
119/// the length (in bytes) of @paragraph_text.
120/// -1 means nul-terminated text.
121/// ## `analysis`
122/// [`Analysis`][crate::Analysis] structure from [`itemize()`][crate::itemize()]
123/// ## `glyphs`
124/// glyph string in which to store results
125/// ## `flags`
126/// flags influencing the shaping process
127#[cfg(feature = "v1_44")]
128#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
129#[doc(alias = "pango_shape_with_flags")]
130pub fn shape_with_flags(
131 item_text: &str,
132 paragraph_text: Option<&str>,
133 analysis: &Analysis,
134 glyphs: &mut GlyphString,
135 flags: ShapeFlags,
136) {
137 let item_length = item_text.len() as i32;
138 let paragraph_length = paragraph_text.map(|t| t.len() as i32).unwrap_or_default();
139 unsafe {
140 ffi::pango_shape_with_flags(
141 item_text.to_glib_none().0,
142 item_length,
143 paragraph_text.to_glib_none().0,
144 paragraph_length,
145 analysis.to_glib_none().0,
146 glyphs.to_glib_none_mut().0,
147 flags.into_glib(),
148 );
149 }
150}
151
152/// Converts extents from Pango units to device units.
153///
154/// The conversion is done by dividing by the `PANGO_SCALE` factor and
155/// performing rounding.
156///
157/// The @inclusive rectangle is converted by flooring the x/y coordinates
158/// and extending width/height, such that the final rectangle completely
159/// includes the original rectangle.
160///
161/// The @nearest rectangle is converted by rounding the coordinates
162/// of the rectangle to the nearest device unit (pixel).
163///
164/// The rule to which argument to use is: if you want the resulting device-space
165/// rectangle to completely contain the original rectangle, pass it in as
166/// @inclusive. If you want two touching-but-not-overlapping rectangles stay
167/// touching-but-not-overlapping after rounding to device units, pass them in
168/// as @nearest.
169/// ## `inclusive`
170/// rectangle to round to pixels inclusively
171/// ## `nearest`
172/// rectangle to round to nearest pixels
173#[doc(alias = "pango_extents_to_pixels")]
174pub fn extents_to_pixels(
175 mut inclusive: Option<&mut crate::Rectangle>,
176 mut nearest: Option<&mut crate::Rectangle>,
177) {
178 unsafe {
179 ffi::pango_extents_to_pixels(inclusive.to_glib_none_mut().0, nearest.to_glib_none_mut().0);
180 }
181}