gtk4/auto/

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

use crate::{ffi, SymbolicPaintable};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// A paintable implementation that renders (a subset of) SVG,
    /// with animations.
    ///
    /// [`Svg`][crate::Svg] objects are created by parsing a subset of SVG,
    /// including SVG animations.
    ///
    /// The [`Svg`][crate::Svg] fills or strokes paths with symbolic or fixed
    /// colors. It can have multiple states, and paths can be included
    /// in a subset of the states. The special 'empty' state is always
    /// available. States can have animation, and the transition between
    /// different states can also be animated.
    ///
    /// To find out what states a [`Svg`][crate::Svg] has, use [`n_states()`][Self::n_states()].
    /// To set the current state, use [`set_state()`][Self::set_state()].
    ///
    /// To play the animations in an SVG file, use
    /// [`set_frame_clock()`][Self::set_frame_clock()] to connect the paintable to a frame clock,
    /// and then use [`play()`][Self::play()] to start the animation.
    ///
    ///
    /// ## Error handling
    ///
    /// Loading an SVG into [`Svg`][crate::Svg] will always produce a (possibly empty)
    /// paintable. GTK will drop things that it can't handle and try to make
    /// sense of the rest.
    ///
    /// To track errors during parsing or rednering, connect to the
    /// [`error`][struct@crate::Svg#error] signal.
    ///
    /// For parsing errors in the `GTK_SVG_ERROR` domain, the functions
    /// `Gtk::SvgError::get_start()`, `Gtk::SvgError::get_end()`,
    /// `Gtk::SvgError::get_element()` and `Gtk::SvgError::get_attribute()`
    /// can be used to obtain information about where the error occurred.
    ///
    ///
    /// ## The supported subset of SVG
    ///
    /// The paintable does not support text or images, only shapes and paths.
    ///
    /// In `<defs>`, only `<clipPath>`, `<mask>`, gradients and shapes are
    /// supported, not `<filter>`, `<pattern>` or other things.
    ///
    /// Gradient templating is not implemented.
    ///
    /// The support for filters is limited to filter functions minus
    /// `drop-shadow()` plus a custom `alpha-level()` function, which
    /// implements one particular case of feComponentTransfer.
    ///
    /// The `transform-origin` and `transform-box` attributes are not supported.
    ///
    /// The support for the `mask` attribute is limited to just a url
    /// referring to the `<mask>` element by ID.
    ///
    /// In animation elements, the parsing of `begin` and `end` attributes
    /// is limited, and the `by`, `min` and `max` attributes are not supported.
    ///
    /// Lastly, there is no CSS support, and no interactivity.
    ///
    ///
    /// ## SVG Extensions
    ///
    /// The paintable supports a number of [custom attributes](icon-format.html)
    /// that offer a convenient way to define states, transitions and animations.
    /// For example,
    ///
    ///     <circle cx='5' cy='5' r='5'
    ///             gpa:states='0 1'
    ///             gpa:animation-type='automatic'
    ///             gpa:animation-direction='segment'
    ///             gpa:animation-duration='600ms'/>
    ///
    /// defines the circle to be shown in states 0 and 1, and animates a segment
    /// of the circle.
    ///
    /// <image src="svg-renderer1.svg">
    ///
    /// Note that the generated animations assume a `pathLengh` value of 1.
    /// Setting `pathLength` in your SVG is therefore going to interfere with
    /// generated animations.
    ///
    /// To connect general SVG animations to the states of the paintable,
    /// use the custom `gpa:states(...)` condition in the `begin` and `end`
    /// attributes of SVG animation elements. For example,
    ///
    ///     <animate href='path1'
    ///              attributeName='fill'
    ///              begin='gpa:states(0).begin'
    ///              dur='300ms'
    ///              fill='freeze'
    ///              from='black'
    ///              to='magenta'/>
    ///
    /// will make the fill color of path1 transition from black to
    /// magenta when the renderer enters state 0.
    ///
    /// <image src="svg-renderer2.svg">
    ///
    /// The `gpa:states(...)` condition triggers for upcoming state changes
    /// as well, to support fade-out transitions. For example,
    ///
    ///     <animate href='path1'
    ///              attributeName='opacity'
    ///              begin='gpa:states(0).end -300ms'
    ///              dur='300ms'
    ///              fill='freeze'
    ///              from='1'
    ///              to='0'/>
    ///
    /// will start a fade-out of path1 300ms before state 0 ends.
    ///
    /// In addition to `gpa:fill` and `gpa:stroke`, symbolic colors can
    /// also be specified as a custom paint server reference, like this:
    /// `url(gpa:#warning)`. This works in `fill` and `stroke` attributes,
    /// but also when specifying colors in SVG animation attributes like
    /// `to` or `values`.
    ///
    /// Note that the SVG syntax allows for a fallback RGB color to be
    /// specified after the url, for compatibility with other SVG consumers:
    ///
    ///     fill='url(gpa:#warning) orange'
    ///
    /// In contrast to SVG 1.1 and 2.0, we allow the `transform` attribute
    /// to be animated with `<animate>`.
    ///
    /// ## Properties
    ///
    ///
    /// #### `playing`
    ///  Whether the paintable is currently animating its content.
    ///
    /// To set this property, use the [`Svg::play()`][crate::Svg::play()] and
    /// [`Svg::pause()`][crate::Svg::pause()] functions.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `resource`
    ///  Construct-only property to create a paintable from
    /// a resource in ui files.
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `state`
    ///  The current state of the renderer.
    ///
    /// This can be a number between 0 and 63, or the special value
    /// `(unsigned int) -1` to indicate the 'empty' state in which
    /// nothing is drawn.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `weight`
    ///  If not set to -1, this value overrides the weight used
    /// when rendering the paintable.
    ///
    /// Readable | Writeable
    ///
    /// ## Signals
    ///
    ///
    /// #### `error`
    ///  Signals that an error occurred.
    ///
    /// Errors can occur both during parsing and during rendering.
    ///
    /// The expected error values are in the `Gtk::SvgError` enumeration,
    /// context information about the location of parsing errors can
    /// be obtained with the various `gtk_svg_error` functions.
    ///
    /// Parsing errors are never fatal, so the parsing will resume after
    /// the error. Errors may however cause parts of the given data or
    /// even all of it to not be parsed at all. So it is a useful idea
    /// to check that the parsing succeeds by connecting to this signal.
    ///
    /// ::: note
    ///     This signal is emitted in the middle of parsing or rendering,
    ///     and if you handle it, you must be careful. Logging the errors
    ///     you receive is fine, but modifying the widget hierarchy or
    ///     changing the paintable state definitively isn't.
    ///
    ///     If in doubt, defer to an idle.
    ///
    ///
    /// <details><summary><h4>Paintable</h4></summary>
    ///
    ///
    /// #### `invalidate-contents`
    ///  Emitted when the contents of the @paintable change.
    ///
    /// Examples for such an event would be videos changing to the next frame or
    /// the icon theme for an icon changing.
    ///
    ///
    ///
    ///
    /// #### `invalidate-size`
    ///  Emitted when the intrinsic size of the @paintable changes.
    ///
    /// This means the values reported by at least one of
    /// [`PaintableExtManual::intrinsic_width()`][crate::gdk::prelude::PaintableExtManual::intrinsic_width()],
    /// [`PaintableExtManual::intrinsic_height()`][crate::gdk::prelude::PaintableExtManual::intrinsic_height()] or
    /// [`PaintableExtManual::intrinsic_aspect_ratio()`][crate::gdk::prelude::PaintableExtManual::intrinsic_aspect_ratio()]
    /// has changed.
    ///
    /// Examples for such an event would be a paintable displaying
    /// the contents of a toplevel surface being resized.
    ///
    ///
    /// </details>
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`trait@gdk::prelude::PaintableExt`], [`SymbolicPaintableExt`][trait@crate::prelude::SymbolicPaintableExt]
    #[doc(alias = "GtkSvg")]
    pub struct Svg(Object<ffi::GtkSvg, ffi::GtkSvgClass>) @implements gdk::Paintable, SymbolicPaintable;

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

impl Svg {
    /// Creates a new, empty SVG paintable.
    ///
    /// # Returns
    ///
    /// the paintable
    #[doc(alias = "gtk_svg_new")]
    pub fn new() -> Svg {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_svg_new()) }
    }

    /// Parses the SVG data in @bytes and creates a paintable.
    /// ## `bytes`
    /// the data
    ///
    /// # Returns
    ///
    /// the paintable
    #[doc(alias = "gtk_svg_new_from_bytes")]
    #[doc(alias = "new_from_bytes")]
    pub fn from_bytes(bytes: &glib::Bytes) -> Svg {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_svg_new_from_bytes(bytes.to_glib_none().0)) }
    }

    /// Parses the SVG data in the resource and creates a paintable.
    /// ## `path`
    /// the resource path
    ///
    /// # Returns
    ///
    /// the paintable
    #[doc(alias = "gtk_svg_new_from_resource")]
    #[doc(alias = "new_from_resource")]
    pub fn from_resource(path: &str) -> Svg {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_svg_new_from_resource(path.to_glib_none().0)) }
    }

    /// Gets the number of states defined in the SVG.
    ///
    /// Note that there is always an empty state, which does
    /// not count towards this number. If this function returns
    /// the value N, the meaningful states of the SVG are
    /// 0, 1, ..., N - 1 and `GTK_SVG_STATE_EMPTY`.
    ///
    /// # Returns
    ///
    /// the number of states
    #[doc(alias = "gtk_svg_get_n_states")]
    #[doc(alias = "get_n_states")]
    pub fn n_states(&self) -> u32 {
        unsafe { ffi::gtk_svg_get_n_states(self.to_glib_none().0) }
    }

    /// Gets the current state of the paintable.
    ///
    /// # Returns
    ///
    /// the state
    #[doc(alias = "gtk_svg_get_state")]
    #[doc(alias = "get_state")]
    pub fn state(&self) -> u32 {
        unsafe { ffi::gtk_svg_get_state(self.to_glib_none().0) }
    }

    /// Gets the value of the weight property.
    ///
    /// # Returns
    ///
    /// the weight
    #[doc(alias = "gtk_svg_get_weight")]
    #[doc(alias = "get_weight")]
    pub fn weight(&self) -> f64 {
        unsafe { ffi::gtk_svg_get_weight(self.to_glib_none().0) }
    }

    /// Loads SVG content into an existing SVG paintable.
    ///
    /// To track errors while loading SVG content,
    /// connect to the [`error`][struct@crate::Svg#error] signal.
    ///
    /// This clears any previously loaded content.
    /// ## `bytes`
    /// the data to load
    #[doc(alias = "gtk_svg_load_from_bytes")]
    pub fn load_from_bytes(&self, bytes: &glib::Bytes) {
        unsafe {
            ffi::gtk_svg_load_from_bytes(self.to_glib_none().0, bytes.to_glib_none().0);
        }
    }

    /// Stop any playing animations.
    ///
    /// Animations can be paused and started repeatedly.
    #[doc(alias = "gtk_svg_pause")]
    pub fn pause(&self) {
        unsafe {
            ffi::gtk_svg_pause(self.to_glib_none().0);
        }
    }

    /// Start playing animations.
    ///
    /// Note that this is necessary for state changes as
    /// well.
    #[doc(alias = "gtk_svg_play")]
    pub fn play(&self) {
        unsafe {
            ffi::gtk_svg_play(self.to_glib_none().0);
        }
    }

    /// Serializes the content of the renderer as SVG.
    ///
    /// The SVG will be similar to the orignally loaded one,
    /// but is not guaranteed to be 100% identical.
    ///
    /// This function serializes the DOM, i.e. the results
    /// of parsing the SVG. It does not reflect the effect
    /// of applying animations.
    ///
    /// # Returns
    ///
    /// the serialized contents
    #[doc(alias = "gtk_svg_serialize")]
    pub fn serialize(&self) -> glib::Bytes {
        unsafe { from_glib_full(ffi::gtk_svg_serialize(self.to_glib_none().0)) }
    }

    /// Sets a frame clock.
    ///
    /// Without a frame clock, GTK has to rely
    /// on simple timeouts to run animations.
    /// ## `clock`
    /// the frame clock
    #[doc(alias = "gtk_svg_set_frame_clock")]
    pub fn set_frame_clock(&self, clock: &gdk::FrameClock) {
        unsafe {
            ffi::gtk_svg_set_frame_clock(self.to_glib_none().0, clock.to_glib_none().0);
        }
    }

    /// Sets the state of the paintable.
    ///
    /// Use [`n_states()`][Self::n_states()] to find out
    /// what states @self has.
    ///
    /// Note that [`play()`][Self::play()] must have been
    /// called for the SVG paintable to react to state changes.
    /// ## `state`
    /// the state to set, as a value between 0 and 63,
    ///   or `(unsigned int) -1`
    #[doc(alias = "gtk_svg_set_state")]
    #[doc(alias = "state")]
    pub fn set_state(&self, state: u32) {
        unsafe {
            ffi::gtk_svg_set_state(self.to_glib_none().0, state);
        }
    }

    /// Sets the weight that is used when rendering.
    ///
    /// The default value of -1 means to use the font weight
    /// from CSS.
    /// ## `weight`
    /// the font weight, as a value between -1 and 1000
    #[doc(alias = "gtk_svg_set_weight")]
    #[doc(alias = "weight")]
    pub fn set_weight(&self, weight: f64) {
        unsafe {
            ffi::gtk_svg_set_weight(self.to_glib_none().0, weight);
        }
    }

    /// Serializes the paintable, and saves the result to a file.
    /// ## `filename`
    /// the file to save to
    ///
    /// # Returns
    ///
    /// true, unless an error occurred
    #[doc(alias = "gtk_svg_write_to_file")]
    pub fn write_to_file(&self, filename: &str) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gtk_svg_write_to_file(
                self.to_glib_none().0,
                filename.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))
            }
        }
    }

    /// Whether the paintable is currently animating its content.
    ///
    /// To set this property, use the [`play()`][Self::play()] and
    /// [`pause()`][Self::pause()] functions.
    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    pub fn is_playing(&self) -> bool {
        ObjectExt::property(self, "playing")
    }

    /// Whether the paintable is currently animating its content.
    ///
    /// To set this property, use the [`play()`][Self::play()] and
    /// [`pause()`][Self::pause()] functions.
    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    pub fn set_playing(&self, playing: bool) {
        ObjectExt::set_property(self, "playing", playing)
    }

    /// Signals that an error occurred.
    ///
    /// Errors can occur both during parsing and during rendering.
    ///
    /// The expected error values are in the `Gtk::SvgError` enumeration,
    /// context information about the location of parsing errors can
    /// be obtained with the various `gtk_svg_error` functions.
    ///
    /// Parsing errors are never fatal, so the parsing will resume after
    /// the error. Errors may however cause parts of the given data or
    /// even all of it to not be parsed at all. So it is a useful idea
    /// to check that the parsing succeeds by connecting to this signal.
    ///
    /// ::: note
    ///     This signal is emitted in the middle of parsing or rendering,
    ///     and if you handle it, you must be careful. Logging the errors
    ///     you receive is fine, but modifying the widget hierarchy or
    ///     changing the paintable state definitively isn't.
    ///
    ///     If in doubt, defer to an idle.
    /// ## `error`
    /// the error
    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "error")]
    pub fn connect_error<F: Fn(&Self, &glib::Error) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn error_trampoline<F: Fn(&Svg, &glib::Error) + 'static>(
            this: *mut ffi::GtkSvg,
            error: *mut glib::ffi::GError,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(error))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"error".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    error_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "playing")]
    pub fn connect_playing_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_playing_trampoline<F: Fn(&Svg) + 'static>(
            this: *mut ffi::GtkSvg,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::playing".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_playing_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "state")]
    pub fn connect_state_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_state_trampoline<F: Fn(&Svg) + 'static>(
            this: *mut ffi::GtkSvg,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::state".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_state_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "weight")]
    pub fn connect_weight_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_weight_trampoline<F: Fn(&Svg) + 'static>(
            this: *mut ffi::GtkSvg,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::weight".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_weight_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

#[cfg(feature = "v4_22")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
impl Default for Svg {
    fn default() -> Self {
        Self::new()
    }
}