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}