zng/
image.rs

Help
1#![cfg(feature = "image")]
2
3//! Images service, widget and other types.
4//!
5//! # Image
6//!
7//! The [`Image!`](struct@Image) widget is the primary way of presenting images, the example below defines
8//! a repeating pattern image as the window background, the image source is embedded in this case, see [`ImageSource`]
9//! for other supported sources.
10//!
11//! ```
12//! use zng::prelude::*;
13//! # let _scope = APP.defaults();
14//! # macro_rules! include_bytes { ($tt:tt) => { &[0u8] } }
15//!
16//! # let _ =
17//! Window! {
18//!     widget::background = Image! {
19//!         source = include_bytes!("../res/image/pattern.png");
20//!         img_fit = zng::image::ImageFit::None;
21//!         img_repeat = true;
22//!     }
23//! }
24//! # ;
25//! ```
26//!
27//! # Mask
28//!
29//! Mask images are loaded just like normal images, the [`mask::mask_image`](fn@mask::mask_image) property
30//! can be set on any widget to apply a mask to it. The example below applies a mask to a button, by
31//! default the mask uses the alpha channel, see [`mask`] for more details.
32//!
33//! ```
34//! use zng::{prelude::*, image::mask};
35//! # let _scope = APP.defaults();
36//! # macro_rules! include_bytes { ($tt:tt) => { &[0u8] } }
37//!
38//! # let _ =
39//! Button! {
40//!     mask::mask_image = include_bytes!("../res/image/star.png");
41//! }
42//! # ;
43//! ```
44//!
45//! # Service
46//!
47//! The [`IMAGES`] service manages image loading, the image cache and image rendering. Image decoding is
48//! implemented by the view-process, for this reason to get image with actual pixels the service must be
49//! used in a headed app or headless app with renderer, in a headless app without renderer all images are
50//! a placeholder dummy.
51//!
52//! The images service also define security limits, the [`IMAGES.limits`](fn@IMAGES::limits)
53//! variable to configure these limits. See [`ImageLimits::default`] for the defaults.
54//!
55//! ```
56//! use zng::{prelude::*, image};
57//! # let _scope = APP.defaults();
58//!
59//! image::IMAGES.limits().modify(|l| {
60//!     let l = l.to_mut();
61//!     l.allow_uri = image::UriFilter::allow_host("httpbin.org");
62//!     l.max_encoded_len = 1.megabytes();
63//!     l.max_decoded_len = 10.megabytes();
64//! });
65//! ```
66//!
67//! The example above changes the global limits to allow image downloads only from an specific host and
68//! only allow images with sizes less or equal to 1 megabyte and that only expands to up to 10 megabytes
69//! after decoding.
70//!  
71//! # Full API
72//!
73//! See [`zng_ext_image`] for the full image API and [`zng_wgt_image`] for the full widget API.
74
75pub use zng_ext_image::{
76    IMAGE_RENDER, IMAGES, ImageCacheMode, ImageDataFormat, ImageDownscale, ImageHash, ImageHasher, ImageLimits, ImagePpi, ImageRenderArgs,
77    ImageSource, ImageSourceFilter, ImageVar, Img, PathFilter, render_retain,
78};
79
80#[cfg(feature = "http")]
81pub use zng_ext_image::UriFilter;
82
83pub use zng_wgt_image::{
84    Image, ImageFit, ImageRepeat, ImgErrorArgs, ImgLoadArgs, ImgLoadingArgs, img_align, img_cache, img_crop, img_downscale, img_error_fn,
85    img_fit, img_limits, img_loading_fn, img_offset, img_rendering, img_repeat, img_repeat_spacing, img_scale, img_scale_factor,
86    img_scale_ppi, is_error, is_loaded, on_error, on_load,
87};
88
89/// Mask image properties.
90///
91/// See [`zng_wgt_image::mask`] for the full API.
92pub mod mask {
93    pub use zng_ext_image::ImageMaskMode;
94    pub use zng_wgt_image::mask::{
95        mask_align, mask_fit, mask_image, mask_image_cache, mask_image_downscale, mask_image_limits, mask_mode, mask_offset,
96    };
97}
zng/image.rs

zng/
image.rs
