pango/auto/
attr_list.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, AttrIterator, Attribute};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// A [`AttrList`][crate::AttrList] represents a list of attributes that apply to a section
10    /// of text.
11    ///
12    /// The attributes in a [`AttrList`][crate::AttrList] are, in general, allowed to overlap in
13    /// an arbitrary fashion. However, if the attributes are manipulated only through
14    /// [`change()`][Self::change()], the overlap between properties will meet
15    /// stricter criteria.
16    ///
17    /// Since the [`AttrList`][crate::AttrList] structure is stored as a linear list, it is not
18    /// suitable for storing attributes for large amounts of text. In general, you
19    /// should not use a single [`AttrList`][crate::AttrList] for more than one paragraph of text.
20    #[derive(Debug)]
21    pub struct AttrList(Shared<ffi::PangoAttrList>);
22
23    match fn {
24        ref => |ptr| ffi::pango_attr_list_ref(ptr),
25        unref => |ptr| ffi::pango_attr_list_unref(ptr),
26        type_ => || ffi::pango_attr_list_get_type(),
27    }
28}
29
30impl AttrList {
31    /// Create a new empty attribute list with a reference
32    /// count of one.
33    ///
34    /// # Returns
35    ///
36    /// the newly allocated
37    ///   [`AttrList`][crate::AttrList], which should be freed with
38    ///   `Pango::AttrList::unref()`
39    #[doc(alias = "pango_attr_list_new")]
40    pub fn new() -> AttrList {
41        unsafe { from_glib_full(ffi::pango_attr_list_new()) }
42    }
43
44    #[doc(alias = "pango_attr_list_copy")]
45    #[must_use]
46    pub fn copy(&self) -> Option<AttrList> {
47        unsafe { from_glib_full(ffi::pango_attr_list_copy(self.to_glib_none().0)) }
48    }
49
50    /// Given a [`AttrList`][crate::AttrList] and callback function, removes
51    /// any elements of @self for which @func returns [`true`] and
52    /// inserts them into a new list.
53    /// ## `func`
54    /// callback function;
55    ///   returns [`true`] if an attribute should be filtered out
56    ///
57    /// # Returns
58    ///
59    /// the new
60    ///   [`AttrList`][crate::AttrList] or [`None`] if no attributes of the
61    ///   given types were found
62    #[doc(alias = "pango_attr_list_filter")]
63    #[must_use]
64    pub fn filter<P: FnMut(&Attribute) -> bool>(&self, func: P) -> Option<AttrList> {
65        let mut func_data: P = func;
66        unsafe extern "C" fn func_func<P: FnMut(&Attribute) -> bool>(
67            attribute: *mut ffi::PangoAttribute,
68            user_data: glib::ffi::gpointer,
69        ) -> glib::ffi::gboolean {
70            let attribute = from_glib_borrow(attribute);
71            let callback = user_data as *mut P;
72            (*callback)(&attribute).into_glib()
73        }
74        let func = Some(func_func::<P> as _);
75        let super_callback0: &mut P = &mut func_data;
76        unsafe {
77            from_glib_full(ffi::pango_attr_list_filter(
78                self.to_glib_none().0,
79                func,
80                super_callback0 as *mut _ as *mut _,
81            ))
82        }
83    }
84
85    /// Gets a list of all attributes in @self.
86    ///
87    /// # Returns
88    ///
89    ///
90    ///   a list of all attributes in @self. To free this value,
91    ///   call `Pango::Attribute::destroy()` on each value and
92    ///   g_slist_free() on the list.
93    #[cfg(feature = "v1_44")]
94    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
95    #[doc(alias = "pango_attr_list_get_attributes")]
96    #[doc(alias = "get_attributes")]
97    pub fn attributes(&self) -> Vec<Attribute> {
98        unsafe {
99            FromGlibPtrContainer::from_glib_full(ffi::pango_attr_list_get_attributes(
100                self.to_glib_none().0,
101            ))
102        }
103    }
104
105    /// Create a iterator initialized to the beginning of the list.
106    ///
107    /// @self must not be modified until this iterator is freed.
108    ///
109    /// # Returns
110    ///
111    /// the newly allocated
112    ///   [`AttrIterator`][crate::AttrIterator], which should be freed with
113    ///   `Pango::AttrIterator::destroy()`
114    #[doc(alias = "pango_attr_list_get_iterator")]
115    #[doc(alias = "get_iterator")]
116    pub fn iterator(&self) -> AttrIterator {
117        unsafe { from_glib_full(ffi::pango_attr_list_get_iterator(self.to_glib_none().0)) }
118    }
119
120    /// This function opens up a hole in @self, fills it
121    /// in with attributes from the left, and then merges
122    /// @other on top of the hole.
123    ///
124    /// This operation is equivalent to stretching every attribute
125    /// that applies at position @pos in @self by an amount @len,
126    /// and then calling [`change()`][Self::change()] with a copy
127    /// of each attribute in @other in sequence (offset in position
128    /// by @pos, and limited in length to @len).
129    ///
130    /// This operation proves useful for, for instance, inserting
131    /// a pre-edit string in the middle of an edit buffer.
132    ///
133    /// For backwards compatibility, the function behaves differently
134    /// when @len is 0. In this case, the attributes from @other are
135    /// not imited to @len, and are just overlayed on top of @self.
136    ///
137    /// This mode is useful for merging two lists of attributes together.
138    /// ## `other`
139    /// another [`AttrList`][crate::AttrList]
140    /// ## `pos`
141    /// the position in @self at which to insert @other
142    /// ## `len`
143    /// the length of the spliced segment. (Note that this
144    ///   must be specified since the attributes in @other may only
145    ///   be present at some subsection of this range)
146    #[doc(alias = "pango_attr_list_splice")]
147    pub fn splice(&self, other: &AttrList, pos: i32, len: i32) {
148        unsafe {
149            ffi::pango_attr_list_splice(self.to_glib_none().0, other.to_glib_none().0, pos, len);
150        }
151    }
152
153    /// Serializes a [`AttrList`][crate::AttrList] to a string.
154    ///
155    /// In the resulting string, serialized attributes are separated by newlines or commas.
156    /// Individual attributes are serialized to a string of the form
157    ///
158    ///     [START END] TYPE VALUE
159    ///
160    /// Where START and END are the indices (with -1 being accepted in place
161    /// of MAXUINT), TYPE is the nickname of the attribute value type, e.g.
162    /// _weight_ or _stretch_, and the value is serialized according to its type:
163    ///
164    /// Optionally, START and END can be omitted to indicate unlimited extent.
165    ///
166    /// - enum values as nick or numeric value
167    /// - boolean values as _true_ or _false_
168    /// - integers and floats as numbers
169    /// - strings as string, optionally quoted
170    /// - font features as quoted string
171    /// - PangoLanguage as string
172    /// - PangoFontDescription as serialized by [`FontDescription::to_str()`][crate::FontDescription::to_str()], quoted
173    /// - PangoColor as serialized by [`Color::to_str()`][crate::Color::to_str()]
174    ///
175    /// Examples:
176    ///
177    ///     0 10 foreground red, 5 15 weight bold, 0 200 font-desc "Sans 10"
178    ///
179    ///     0 -1 weight 700
180    ///     0 100 family Times
181    ///
182    ///     weight bold
183    ///
184    /// To parse the returned value, use [`from_string()`][Self::from_string()].
185    ///
186    /// Note that shape attributes can not be serialized.
187    ///
188    /// # Returns
189    ///
190    /// a newly allocated string
191    #[cfg(feature = "v1_50")]
192    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
193    #[doc(alias = "pango_attr_list_to_string")]
194    #[doc(alias = "to_string")]
195    pub fn to_str(&self) -> glib::GString {
196        unsafe { from_glib_full(ffi::pango_attr_list_to_string(self.to_glib_none().0)) }
197    }
198
199    /// Update indices of attributes in @self for a change in the
200    /// text they refer to.
201    ///
202    /// The change that this function applies is removing @remove
203    /// bytes at position @pos and inserting @add bytes instead.
204    ///
205    /// Attributes that fall entirely in the (@pos, @pos + @remove)
206    /// range are removed.
207    ///
208    /// Attributes that start or end inside the (@pos, @pos + @remove)
209    /// range are shortened to reflect the removal.
210    ///
211    /// Attributes start and end positions are updated if they are
212    /// behind @pos + @remove.
213    /// ## `pos`
214    /// the position of the change
215    /// ## `remove`
216    /// the number of removed bytes
217    /// ## `add`
218    /// the number of added bytes
219    #[cfg(feature = "v1_44")]
220    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
221    #[doc(alias = "pango_attr_list_update")]
222    pub fn update(&self, pos: i32, remove: i32, add: i32) {
223        unsafe {
224            ffi::pango_attr_list_update(self.to_glib_none().0, pos, remove, add);
225        }
226    }
227
228    /// Deserializes a [`AttrList`][crate::AttrList] from a string.
229    ///
230    /// This is the counterpart to [`to_str()`][Self::to_str()].
231    /// See that functions for details about the format.
232    /// ## `text`
233    /// a string
234    ///
235    /// # Returns
236    ///
237    /// a new [`AttrList`][crate::AttrList]
238    #[cfg(feature = "v1_50")]
239    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
240    #[doc(alias = "pango_attr_list_from_string")]
241    pub fn from_string(text: &str) -> Result<AttrList, glib::BoolError> {
242        unsafe {
243            Option::<_>::from_glib_full(ffi::pango_attr_list_from_string(text.to_glib_none().0))
244                .ok_or_else(|| glib::bool_error!("Can't parse AttrList"))
245        }
246    }
247}
248
249impl Default for AttrList {
250    fn default() -> Self {
251        Self::new()
252    }
253}
254
255#[cfg(feature = "v1_50")]
256#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
257impl std::fmt::Display for AttrList {
258    #[inline]
259    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
260        f.write_str(&self.to_str())
261    }
262}