zng/
image.rs

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//! # fn example() {
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::{image::mask, prelude::*};
35//! # fn example() {
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::{image, prelude::*};
57//! # fn example() {
58//!
59//! image::IMAGES.limits().modify(|l| {
60//!     l.allow_uri = image::UriFilter::allow_host("httpbin.org");
61//!     l.max_encoded_len = 1.megabytes();
62//!     l.max_decoded_len = 10.megabytes();
63//! }); }
64//! ```
65//!
66//! The example above changes the global limits to allow image downloads only from an specific host and
67//! only allow images with sizes less or equal to 1 megabyte and that only expands to up to 10 megabytes
68//! after decoding.
69//!  
70//! # Full API
71//!
72//! See [`zng_ext_image`] for the full image API and [`zng_wgt_image`] for the full widget API.
73
74pub use zng_ext_image::{
75    IMAGE_RENDER, IMAGES, ImageCacheMode, ImageDataFormat, ImageDownscale, ImageHash, ImageHasher, ImageLimits, ImageRenderArgs,
76    ImageSource, ImageSourceFilter, ImageVar, Img, PathFilter, render_retain,
77};
78
79#[cfg(feature = "http")]
80pub use zng_ext_image::UriFilter;
81
82pub use zng_wgt_image::{
83    Image, ImageFit, ImageRepeat, ImgErrorArgs, ImgLoadArgs, ImgLoadingArgs, img_align, img_cache, img_crop, img_downscale, img_error_fn,
84    img_fit, img_limits, img_loading_fn, img_offset, img_rendering, img_repeat, img_repeat_spacing, img_scale, img_scale_density,
85    img_scale_factor, is_error, is_loaded, on_error, on_load,
86};
87
88/// Mask image properties.
89///
90/// See [`zng_wgt_image::mask`] for the full API.
91pub mod mask {
92    pub use zng_ext_image::ImageMaskMode;
93    pub use zng_wgt_image::mask::{
94        mask_align, mask_fit, mask_image, mask_image_cache, mask_image_downscale, mask_image_limits, mask_mode, mask_offset,
95    };
96}
zng/image.rs

zng/
image.rs
