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
// 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::{PaintableFlags, Snapshot};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`Paintable`][crate::Paintable] is a simple interface used by GTK to represent content that
    /// can be painted.
    ///
    /// The content of a [`Paintable`][crate::Paintable] can be painted anywhere at any size
    /// without requiring any sort of layout. The interface is inspired by
    /// similar concepts elsewhere, such as
    /// [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
    /// [HTML/CSS Paint Sources](https://www.w3.org/TR/css-images-4/#paint-source),
    /// or [SVG Paint Servers](https://www.w3.org/TR/SVG2/pservers.html).
    ///
    /// A [`Paintable`][crate::Paintable] can be snapshot at any time and size using
    /// [`PaintableExt::snapshot()`][crate::prelude::PaintableExt::snapshot()]. How the paintable interprets that size and
    /// if it scales or centers itself into the given rectangle is implementation
    /// defined, though if you are implementing a [`Paintable`][crate::Paintable] and don't know what
    /// to do, it is suggested that you scale your paintable ignoring any potential
    /// aspect ratio.
    ///
    /// The contents that a [`Paintable`][crate::Paintable] produces may depend on the [`Snapshot`][crate::Snapshot]
    /// passed to it. For example, paintables may decide to use more detailed images
    /// on higher resolution screens or when OpenGL is available. A [`Paintable`][crate::Paintable]
    /// will however always produce the same output for the same snapshot.
    ///
    /// A [`Paintable`][crate::Paintable] may change its contents, meaning that it will now produce
    /// a different output with the same snapshot. Once that happens, it will call
    /// [`PaintableExt::invalidate_contents()`][crate::prelude::PaintableExt::invalidate_contents()] which will emit the
    /// [`invalidate-contents`][struct@crate::Paintable#invalidate-contents] signal. If a paintable is known
    /// to never change its contents, it will set the [`PaintableFlags::CONTENTS`][crate::PaintableFlags::CONTENTS]
    /// flag. If a consumer cannot deal with changing contents, it may call
    /// [`PaintableExt::current_image()`][crate::prelude::PaintableExt::current_image()] which will return a static
    /// paintable and use that.
    ///
    /// A paintable can report an intrinsic (or preferred) size or aspect ratio it
    /// wishes to be rendered at, though it doesn't have to. Consumers of the interface
    /// can use this information to layout thepaintable appropriately. Just like the
    /// contents, the size of a paintable can change. A paintable will indicate this
    /// by calling [`PaintableExt::invalidate_size()`][crate::prelude::PaintableExt::invalidate_size()] which will emit the
    /// [`invalidate-size`][struct@crate::Paintable#invalidate-size] signal. And just like for contents,
    /// if a paintable is known to never change its size, it will set the
    /// [`PaintableFlags::SIZE`][crate::PaintableFlags::SIZE] flag.
    ///
    /// Besides API for applications, there are some functions that are only
    /// useful for implementing subclasses and should not be used by applications:
    /// [`PaintableExt::invalidate_contents()`][crate::prelude::PaintableExt::invalidate_contents()],
    /// [`PaintableExt::invalidate_size()`][crate::prelude::PaintableExt::invalidate_size()],
    /// [`new_empty()`][Self::new_empty()].
    ///
    /// ## Signals
    ///
    ///
    /// #### `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
    /// [`PaintableExt::intrinsic_width()`][crate::prelude::PaintableExt::intrinsic_width()],
    /// [`PaintableExt::intrinsic_height()`][crate::prelude::PaintableExt::intrinsic_height()] or
    /// [`PaintableExt::intrinsic_aspect_ratio()`][crate::prelude::PaintableExt::intrinsic_aspect_ratio()]
    /// has changed.
    ///
    /// Examples for such an event would be a paintable displaying
    /// the contents of a toplevel surface being resized.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`PaintableExt`][trait@crate::prelude::PaintableExt]
    #[doc(alias = "GdkPaintable")]
    pub struct Paintable(Interface<ffi::GdkPaintable, ffi::GdkPaintableInterface>);

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

impl Paintable {
    pub const NONE: Option<&'static Paintable> = None;

    /// Returns a paintable that has the given intrinsic size and draws nothing.
    ///
    /// This is often useful for implementing the
    /// `vfunc::Gdk::Paintable::get_current_image` virtual function
    /// when the paintable is in an incomplete state (like a
    /// [GtkMediaStream](../gtk4/class.MediaStream.html) before receiving
    /// the first frame).
    /// ## `intrinsic_width`
    /// The intrinsic width to report. Can be 0 for no width.
    /// ## `intrinsic_height`
    /// The intrinsic height to report. Can be 0 for no height.
    ///
    /// # Returns
    ///
    /// a [`Paintable`][crate::Paintable]
    #[doc(alias = "gdk_paintable_new_empty")]
    pub fn new_empty(intrinsic_width: i32, intrinsic_height: i32) -> Paintable {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gdk_paintable_new_empty(
                intrinsic_width,
                intrinsic_height,
            ))
        }
    }
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Paintable>> Sealed for T {}
}

/// Trait containing all [`struct@Paintable`] methods.
///
/// # Implementors
///
/// [`DmabufTexture`][struct@crate::DmabufTexture], [`GLTexture`][struct@crate::GLTexture], [`MemoryTexture`][struct@crate::MemoryTexture], [`Paintable`][struct@crate::Paintable], [`Texture`][struct@crate::Texture]
pub trait PaintableExt: IsA<Paintable> + sealed::Sealed + 'static {
    /// Compute a concrete size for the [`Paintable`][crate::Paintable].
    ///
    /// Applies the sizing algorithm outlined in the
    /// [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing)
    /// to the given @self. See that link for more details.
    ///
    /// It is not necessary to call this function when both @specified_width
    /// and @specified_height are known, but it is useful to call this
    /// function in GtkWidget:measure implementations to compute the
    /// other dimension when only one dimension is given.
    /// ## `specified_width`
    /// the width @self could be drawn into or
    ///   0.0 if unknown
    /// ## `specified_height`
    /// the height @self could be drawn into or
    ///   0.0 if unknown
    /// ## `default_width`
    /// the width @self would be drawn into if
    ///   no other constraints were given
    /// ## `default_height`
    /// the height @self would be drawn into if
    ///   no other constraints were given
    ///
    /// # Returns
    ///
    ///
    /// ## `concrete_width`
    /// will be set to the concrete width computed
    ///
    /// ## `concrete_height`
    /// will be set to the concrete height computed
    #[doc(alias = "gdk_paintable_compute_concrete_size")]
    fn compute_concrete_size(
        &self,
        specified_width: f64,
        specified_height: f64,
        default_width: f64,
        default_height: f64,
    ) -> (f64, f64) {
        unsafe {
            let mut concrete_width = std::mem::MaybeUninit::uninit();
            let mut concrete_height = std::mem::MaybeUninit::uninit();
            ffi::gdk_paintable_compute_concrete_size(
                self.as_ref().to_glib_none().0,
                specified_width,
                specified_height,
                default_width,
                default_height,
                concrete_width.as_mut_ptr(),
                concrete_height.as_mut_ptr(),
            );
            (concrete_width.assume_init(), concrete_height.assume_init())
        }
    }

    /// Gets an immutable paintable for the current contents displayed by @self.
    ///
    /// This is useful when you want to retain the current state of an animation,
    /// for example to take a screenshot of a running animation.
    ///
    /// If the @self is already immutable, it will return itself.
    ///
    /// # Returns
    ///
    /// An immutable paintable for the current
    ///   contents of @self
    #[doc(alias = "gdk_paintable_get_current_image")]
    #[doc(alias = "get_current_image")]
    #[must_use]
    fn current_image(&self) -> Paintable {
        unsafe {
            from_glib_full(ffi::gdk_paintable_get_current_image(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Get flags for the paintable.
    ///
    /// This is oftentimes useful for optimizations.
    ///
    /// See [`PaintableFlags`][crate::PaintableFlags] for the flags and what they mean.
    ///
    /// # Returns
    ///
    /// The [`PaintableFlags`][crate::PaintableFlags] for this paintable
    #[doc(alias = "gdk_paintable_get_flags")]
    #[doc(alias = "get_flags")]
    fn flags(&self) -> PaintableFlags {
        unsafe { from_glib(ffi::gdk_paintable_get_flags(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the preferred aspect ratio the @self would like to be displayed at.
    ///
    /// The aspect ratio is the width divided by the height, so a value of 0.5
    /// means that the @self prefers to be displayed twice as high as it
    /// is wide. Consumers of this interface can use this to preserve aspect
    /// ratio when displaying the paintable.
    ///
    /// This is a purely informational value and does not in any way limit the
    /// values that may be passed to [`snapshot()`][Self::snapshot()].
    ///
    /// Usually when a @self returns nonzero values from
    /// [`intrinsic_width()`][Self::intrinsic_width()] and
    /// [`intrinsic_height()`][Self::intrinsic_height()] the aspect ratio
    /// should conform to those values, though that is not required.
    ///
    /// If the @self does not have a preferred aspect ratio,
    /// it returns 0. Negative values are never returned.
    ///
    /// # Returns
    ///
    /// the intrinsic aspect ratio of @self or 0 if none.
    #[doc(alias = "gdk_paintable_get_intrinsic_aspect_ratio")]
    #[doc(alias = "get_intrinsic_aspect_ratio")]
    fn intrinsic_aspect_ratio(&self) -> f64 {
        unsafe { ffi::gdk_paintable_get_intrinsic_aspect_ratio(self.as_ref().to_glib_none().0) }
    }

    /// Gets the preferred height the @self would like to be displayed at.
    ///
    /// Consumers of this interface can use this to reserve enough space to draw
    /// the paintable.
    ///
    /// This is a purely informational value and does not in any way limit the
    /// values that may be passed to [`snapshot()`][Self::snapshot()].
    ///
    /// If the @self does not have a preferred height, it returns 0.
    /// Negative values are never returned.
    ///
    /// # Returns
    ///
    /// the intrinsic height of @self or 0 if none.
    #[doc(alias = "gdk_paintable_get_intrinsic_height")]
    #[doc(alias = "get_intrinsic_height")]
    fn intrinsic_height(&self) -> i32 {
        unsafe { ffi::gdk_paintable_get_intrinsic_height(self.as_ref().to_glib_none().0) }
    }

    /// Gets the preferred width the @self would like to be displayed at.
    ///
    /// Consumers of this interface can use this to reserve enough space to draw
    /// the paintable.
    ///
    /// This is a purely informational value and does not in any way limit the
    /// values that may be passed to [`snapshot()`][Self::snapshot()].
    ///
    /// If the @self does not have a preferred width, it returns 0.
    /// Negative values are never returned.
    ///
    /// # Returns
    ///
    /// the intrinsic width of @self or 0 if none.
    #[doc(alias = "gdk_paintable_get_intrinsic_width")]
    #[doc(alias = "get_intrinsic_width")]
    fn intrinsic_width(&self) -> i32 {
        unsafe { ffi::gdk_paintable_get_intrinsic_width(self.as_ref().to_glib_none().0) }
    }

    /// Called by implementations of [`Paintable`][crate::Paintable] to invalidate their contents.
    ///
    /// Unless the contents are invalidated, implementations must guarantee that
    /// multiple calls of [`snapshot()`][Self::snapshot()] produce the same output.
    ///
    /// This function will emit the [`invalidate-contents`][struct@crate::Paintable#invalidate-contents]
    /// signal.
    ///
    /// If a @self reports the [`PaintableFlags::CONTENTS`][crate::PaintableFlags::CONTENTS] flag,
    /// it must not call this function.
    #[doc(alias = "gdk_paintable_invalidate_contents")]
    fn invalidate_contents(&self) {
        unsafe {
            ffi::gdk_paintable_invalidate_contents(self.as_ref().to_glib_none().0);
        }
    }

    /// Called by implementations of [`Paintable`][crate::Paintable] to invalidate their size.
    ///
    /// As long as the size is not invalidated, @self must return the same
    /// values for its intrinsic width, height and aspect ratio.
    ///
    /// This function will emit the [`invalidate-size`][struct@crate::Paintable#invalidate-size]
    /// signal.
    ///
    /// If a @self reports the [`PaintableFlags::SIZE`][crate::PaintableFlags::SIZE] flag,
    /// it must not call this function.
    #[doc(alias = "gdk_paintable_invalidate_size")]
    fn invalidate_size(&self) {
        unsafe {
            ffi::gdk_paintable_invalidate_size(self.as_ref().to_glib_none().0);
        }
    }

    /// Snapshots the given paintable with the given @width and @height.
    ///
    /// The paintable is drawn at the current (0,0) offset of the @snapshot.
    /// If @width and @height are not larger than zero, this function will
    /// do nothing.
    /// ## `snapshot`
    /// a [`Snapshot`][crate::Snapshot] to snapshot to
    /// ## `width`
    /// width to snapshot in
    /// ## `height`
    /// height to snapshot in
    #[doc(alias = "gdk_paintable_snapshot")]
    fn snapshot(&self, snapshot: &impl IsA<Snapshot>, width: f64, height: f64) {
        unsafe {
            ffi::gdk_paintable_snapshot(
                self.as_ref().to_glib_none().0,
                snapshot.as_ref().to_glib_none().0,
                width,
                height,
            );
        }
    }

    /// 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.
    #[doc(alias = "invalidate-contents")]
    fn connect_invalidate_contents<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn invalidate_contents_trampoline<
            P: IsA<Paintable>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GdkPaintable,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Paintable::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"invalidate-contents\0".as_ptr() as *const _,
                Some(std::mem::transmute::<_, unsafe extern "C" fn()>(
                    invalidate_contents_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted when the intrinsic size of the @paintable changes.
    ///
    /// This means the values reported by at least one of
    /// [`intrinsic_width()`][Self::intrinsic_width()],
    /// [`intrinsic_height()`][Self::intrinsic_height()] or
    /// [`intrinsic_aspect_ratio()`][Self::intrinsic_aspect_ratio()]
    /// has changed.
    ///
    /// Examples for such an event would be a paintable displaying
    /// the contents of a toplevel surface being resized.
    #[doc(alias = "invalidate-size")]
    fn connect_invalidate_size<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn invalidate_size_trampoline<P: IsA<Paintable>, F: Fn(&P) + 'static>(
            this: *mut ffi::GdkPaintable,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Paintable::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"invalidate-size\0".as_ptr() as *const _,
                Some(std::mem::transmute::<_, unsafe extern "C" fn()>(
                    invalidate_size_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Paintable>> PaintableExt for O {}