pango/auto/context.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451
// 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
use crate::{
ffi, Direction, Font, FontDescription, FontFamily, FontMap, FontMetrics, Fontset, Gravity,
GravityHint, Language, Matrix,
};
use glib::{prelude::*, translate::*};
glib::wrapper! {
/// A [`Context`][crate::Context] stores global information used to control the
/// itemization process.
///
/// The information stored by [`Context`][crate::Context] includes the fontmap used
/// to look up fonts, and default values such as the default language,
/// default gravity, or default font.
///
/// To obtain a [`Context`][crate::Context], use [`FontMapExt::create_context()`][crate::prelude::FontMapExt::create_context()].
#[doc(alias = "PangoContext")]
pub struct Context(Object<ffi::PangoContext, ffi::PangoContextClass>);
match fn {
type_ => || ffi::pango_context_get_type(),
}
}
impl Context {
/// Creates a new [`Context`][crate::Context] initialized to default values.
///
/// This function is not particularly useful as it should always
/// be followed by a [`set_font_map()`][Self::set_font_map()] call, and the
/// function [`FontMapExt::create_context()`][crate::prelude::FontMapExt::create_context()] does these two steps
/// together and hence users are recommended to use that.
///
/// If you are using Pango as part of a higher-level system,
/// that system may have it's own way of create a [`Context`][crate::Context].
/// For instance, the GTK toolkit has, among others,
/// `gtk_widget_get_pango_context()`. Use those instead.
///
/// # Returns
///
/// the newly allocated [`Context`][crate::Context], which should
/// be freed with g_object_unref().
#[doc(alias = "pango_context_new")]
pub fn new() -> Context {
unsafe { from_glib_full(ffi::pango_context_new()) }
}
/// Forces a change in the context, which will cause any [`Layout`][crate::Layout]
/// using this context to re-layout.
///
/// This function is only useful when implementing a new backend
/// for Pango, something applications won't do. Backends should
/// call this function if they have attached extra data to the context
/// and such data is changed.
#[doc(alias = "pango_context_changed")]
pub fn changed(&self) {
unsafe {
ffi::pango_context_changed(self.to_glib_none().0);
}
}
/// Retrieves the base direction for the context.
///
/// See [`set_base_dir()`][Self::set_base_dir()].
///
/// # Returns
///
/// the base direction for the context.
#[doc(alias = "pango_context_get_base_dir")]
#[doc(alias = "get_base_dir")]
pub fn base_dir(&self) -> Direction {
unsafe { from_glib(ffi::pango_context_get_base_dir(self.to_glib_none().0)) }
}
/// Retrieves the base gravity for the context.
///
/// See [`set_base_gravity()`][Self::set_base_gravity()].
///
/// # Returns
///
/// the base gravity for the context.
#[doc(alias = "pango_context_get_base_gravity")]
#[doc(alias = "get_base_gravity")]
pub fn base_gravity(&self) -> Gravity {
unsafe { from_glib(ffi::pango_context_get_base_gravity(self.to_glib_none().0)) }
}
/// Retrieve the default font description for the context.
///
/// # Returns
///
/// a pointer to the context's default font
/// description. This value must not be modified or freed.
#[doc(alias = "pango_context_get_font_description")]
#[doc(alias = "get_font_description")]
pub fn font_description(&self) -> Option<FontDescription> {
unsafe {
from_glib_none(ffi::pango_context_get_font_description(
self.to_glib_none().0,
))
}
}
/// Gets the [`FontMap`][crate::FontMap] used to look up fonts for this context.
///
/// # Returns
///
/// the font map for the.
/// [`Context`][crate::Context] This value is owned by Pango and should not be
/// unreferenced.
#[doc(alias = "pango_context_get_font_map")]
#[doc(alias = "get_font_map")]
pub fn font_map(&self) -> Option<FontMap> {
unsafe { from_glib_none(ffi::pango_context_get_font_map(self.to_glib_none().0)) }
}
/// Retrieves the gravity for the context.
///
/// This is similar to [`base_gravity()`][Self::base_gravity()],
/// except for when the base gravity is [`Gravity::Auto`][crate::Gravity::Auto] for
/// which [`Gravity::for_matrix()`][crate::Gravity::for_matrix()] is used to return the
/// gravity from the current context matrix.
///
/// # Returns
///
/// the resolved gravity for the context.
#[doc(alias = "pango_context_get_gravity")]
#[doc(alias = "get_gravity")]
pub fn gravity(&self) -> Gravity {
unsafe { from_glib(ffi::pango_context_get_gravity(self.to_glib_none().0)) }
}
/// Retrieves the gravity hint for the context.
///
/// See [`set_gravity_hint()`][Self::set_gravity_hint()] for details.
///
/// # Returns
///
/// the gravity hint for the context.
#[doc(alias = "pango_context_get_gravity_hint")]
#[doc(alias = "get_gravity_hint")]
pub fn gravity_hint(&self) -> GravityHint {
unsafe { from_glib(ffi::pango_context_get_gravity_hint(self.to_glib_none().0)) }
}
/// Retrieves the global language tag for the context.
///
/// # Returns
///
/// the global language tag.
#[doc(alias = "pango_context_get_language")]
#[doc(alias = "get_language")]
pub fn language(&self) -> Option<Language> {
unsafe { from_glib_none(ffi::pango_context_get_language(self.to_glib_none().0)) }
}
/// Gets the transformation matrix that will be applied when
/// rendering with this context.
///
/// See [`set_matrix()`][Self::set_matrix()].
///
/// # Returns
///
/// the matrix, or [`None`] if no
/// matrix has been set (which is the same as the identity matrix).
/// The returned matrix is owned by Pango and must not be modified
/// or freed.
#[doc(alias = "pango_context_get_matrix")]
#[doc(alias = "get_matrix")]
pub fn matrix(&self) -> Option<Matrix> {
unsafe { from_glib_none(ffi::pango_context_get_matrix(self.to_glib_none().0)) }
}
/// Get overall metric information for a particular font description.
///
/// Since the metrics may be substantially different for different scripts,
/// a language tag can be provided to indicate that the metrics should be
/// retrieved that correspond to the script(s) used by that language.
///
/// The [`FontDescription`][crate::FontDescription] is interpreted in the same way as by [`itemize()`][crate::itemize()],
/// and the family name may be a comma separated list of names. If characters
/// from multiple of these families would be used to render the string, then
/// the returned fonts would be a composite of the metrics for the fonts loaded
/// for the individual families.
/// ## `desc`
/// a [`FontDescription`][crate::FontDescription] structure. [`None`] means that the
/// font description from the context will be used.
/// ## `language`
/// language tag used to determine which script to get
/// the metrics for. [`None`] means that the language tag from the context
/// will be used. If no language tag is set on the context, metrics
/// for the default language (as determined by [`Language::default()`][crate::Language::default()]
/// will be returned.
///
/// # Returns
///
/// a [`FontMetrics`][crate::FontMetrics] object. The caller must call
/// `Pango::FontMetrics::unref()` when finished using the object.
#[doc(alias = "pango_context_get_metrics")]
#[doc(alias = "get_metrics")]
pub fn metrics(
&self,
desc: Option<&FontDescription>,
language: Option<&Language>,
) -> FontMetrics {
unsafe {
from_glib_full(ffi::pango_context_get_metrics(
self.to_glib_none().0,
desc.to_glib_none().0,
mut_override(language.to_glib_none().0),
))
}
}
/// Returns whether font rendering with this context should
/// round glyph positions and widths.
#[cfg(feature = "v1_44")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
#[doc(alias = "pango_context_get_round_glyph_positions")]
#[doc(alias = "get_round_glyph_positions")]
pub fn is_round_glyph_positions(&self) -> bool {
unsafe {
from_glib(ffi::pango_context_get_round_glyph_positions(
self.to_glib_none().0,
))
}
}
/// Returns the current serial number of @self.
///
/// The serial number is initialized to an small number larger than zero
/// when a new context is created and is increased whenever the context
/// is changed using any of the setter functions, or the [`FontMap`][crate::FontMap] it
/// uses to find fonts 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 [`Context`][crate::Context],
/// and is only useful when implementing objects that need update when their
/// [`Context`][crate::Context] changes, like [`Layout`][crate::Layout].
///
/// # Returns
///
/// The current serial number of @self.
#[doc(alias = "pango_context_get_serial")]
#[doc(alias = "get_serial")]
pub fn serial(&self) -> u32 {
unsafe { ffi::pango_context_get_serial(self.to_glib_none().0) }
}
/// List all families for a context.
///
/// # Returns
///
///
/// ## `families`
/// location
/// to store a pointer to an array of [`FontFamily`][crate::FontFamily]. This array should
/// be freed with g_free().
#[doc(alias = "pango_context_list_families")]
pub fn list_families(&self) -> Vec<FontFamily> {
unsafe {
let mut families = std::ptr::null_mut();
let mut n_families = std::mem::MaybeUninit::uninit();
ffi::pango_context_list_families(
self.to_glib_none().0,
&mut families,
n_families.as_mut_ptr(),
);
FromGlibContainer::from_glib_container_num(families, n_families.assume_init() as _)
}
}
/// Loads the font in one of the fontmaps in the context
/// that is the closest match for @desc.
/// ## `desc`
/// a [`FontDescription`][crate::FontDescription] describing the font to load
///
/// # Returns
///
/// the newly allocated [`Font`][crate::Font]
/// that was loaded, or [`None`] if no font matched.
#[doc(alias = "pango_context_load_font")]
pub fn load_font(&self, desc: &FontDescription) -> Option<Font> {
unsafe {
from_glib_full(ffi::pango_context_load_font(
self.to_glib_none().0,
desc.to_glib_none().0,
))
}
}
/// Load a set of fonts in the context that can be used to render
/// a font matching @desc.
/// ## `desc`
/// a [`FontDescription`][crate::FontDescription] describing the fonts to load
/// ## `language`
/// a [`Language`][crate::Language] the fonts will be used for
///
/// # Returns
///
/// the newly allocated
/// [`Fontset`][crate::Fontset] loaded, or [`None`] if no font matched.
#[doc(alias = "pango_context_load_fontset")]
pub fn load_fontset(&self, desc: &FontDescription, language: &Language) -> Option<Fontset> {
unsafe {
from_glib_full(ffi::pango_context_load_fontset(
self.to_glib_none().0,
desc.to_glib_none().0,
mut_override(language.to_glib_none().0),
))
}
}
/// Sets the base direction for the context.
///
/// The base direction is used in applying the Unicode bidirectional
/// algorithm; if the @direction is [`Direction::Ltr`][crate::Direction::Ltr] or
/// [`Direction::Rtl`][crate::Direction::Rtl], then the value will be used as the paragraph
/// direction in the Unicode bidirectional algorithm. A value of
/// [`Direction::WeakLtr`][crate::Direction::WeakLtr] or [`Direction::WeakRtl`][crate::Direction::WeakRtl] is used only
/// for paragraphs that do not contain any strong characters themselves.
/// ## `direction`
/// the new base direction
#[doc(alias = "pango_context_set_base_dir")]
pub fn set_base_dir(&self, direction: Direction) {
unsafe {
ffi::pango_context_set_base_dir(self.to_glib_none().0, direction.into_glib());
}
}
/// Sets the base gravity for the context.
///
/// The base gravity is used in laying vertical text out.
/// ## `gravity`
/// the new base gravity
#[doc(alias = "pango_context_set_base_gravity")]
pub fn set_base_gravity(&self, gravity: Gravity) {
unsafe {
ffi::pango_context_set_base_gravity(self.to_glib_none().0, gravity.into_glib());
}
}
/// Set the default font description for the context
/// ## `desc`
/// the new pango font description
#[doc(alias = "pango_context_set_font_description")]
pub fn set_font_description(&self, desc: Option<&FontDescription>) {
unsafe {
ffi::pango_context_set_font_description(self.to_glib_none().0, desc.to_glib_none().0);
}
}
/// Sets the font map to be searched when fonts are looked-up
/// in this context.
///
/// This is only for internal use by Pango backends, a [`Context`][crate::Context]
/// obtained via one of the recommended methods should already have a
/// suitable font map.
/// ## `font_map`
/// the [`FontMap`][crate::FontMap] to set.
#[doc(alias = "pango_context_set_font_map")]
pub fn set_font_map(&self, font_map: Option<&impl IsA<FontMap>>) {
unsafe {
ffi::pango_context_set_font_map(
self.to_glib_none().0,
font_map.map(|p| p.as_ref()).to_glib_none().0,
);
}
}
/// Sets the gravity hint for the context.
///
/// The gravity hint is used in laying vertical text out, and
/// is only relevant if gravity of the context as returned by
/// [`gravity()`][Self::gravity()] is set to [`Gravity::East`][crate::Gravity::East]
/// or [`Gravity::West`][crate::Gravity::West].
/// ## `hint`
/// the new gravity hint
#[doc(alias = "pango_context_set_gravity_hint")]
pub fn set_gravity_hint(&self, hint: GravityHint) {
unsafe {
ffi::pango_context_set_gravity_hint(self.to_glib_none().0, hint.into_glib());
}
}
/// Sets the global language tag for the context.
///
/// The default language for the locale of the running process
/// can be found using [`Language::default()`][crate::Language::default()].
/// ## `language`
/// the new language tag.
#[doc(alias = "pango_context_set_language")]
pub fn set_language(&self, language: Option<&Language>) {
unsafe {
ffi::pango_context_set_language(
self.to_glib_none().0,
mut_override(language.to_glib_none().0),
);
}
}
/// Sets the transformation matrix that will be applied when rendering
/// with this context.
///
/// Note that reported metrics are in the user space coordinates before
/// the application of the matrix, not device-space coordinates after the
/// application of the matrix. So, they don't scale with the matrix, though
/// they may change slightly for different matrices, depending on how the
/// text is fit to the pixel grid.
/// ## `matrix`
/// a [`Matrix`][crate::Matrix], or [`None`] to unset any existing
/// matrix. (No matrix set is the same as setting the identity matrix.)
#[doc(alias = "pango_context_set_matrix")]
pub fn set_matrix(&self, matrix: Option<&Matrix>) {
unsafe {
ffi::pango_context_set_matrix(self.to_glib_none().0, matrix.to_glib_none().0);
}
}
/// Sets whether font rendering with this context should
/// round glyph positions and widths to integral positions,
/// in device units.
///
/// This is useful when the renderer can't handle subpixel
/// positioning of glyphs.
///
/// The default value is to round glyph positions, to remain
/// compatible with previous Pango behavior.
/// ## `round_positions`
/// whether to round glyph positions
#[cfg(feature = "v1_44")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
#[doc(alias = "pango_context_set_round_glyph_positions")]
pub fn set_round_glyph_positions(&self, round_positions: bool) {
unsafe {
ffi::pango_context_set_round_glyph_positions(
self.to_glib_none().0,
round_positions.into_glib(),
);
}
}
}
impl Default for Context {
fn default() -> Self {
Self::new()
}
}