Module zng::image

Images service, widget and other types.

Image

The Image! widget is the primary way of presenting images, the example below defines a repeating pattern image as the window background, the image source is embedded in this case, see ImageSource for other supported sources.

use zng::prelude::*;

Window! {
    widget::background = Image! {
        source = include_bytes!("../res/image/pattern.png");
        img_fit = zng::image::ImageFit::None;
        img_repeat = true;
    }
}

Mask

Mask images are loaded just like normal images, the mask::mask_image property can be set on any widget to apply a mask to it. The example below applies a mask to a button, by default the mask uses the alpha channel, see mask for more details.

use zng::{prelude::*, image::mask};

Button! {
    mask::mask_image = include_bytes!("../res/image/star.png");
}

Service

The IMAGES service manages image loading, the image cache and image rendering. Image decoding is implemented by the view-process, for this reason to get image with actual pixels the service must be used in a headed app or headless app with renderer, in a headless app without renderer all images are a placeholder dummy.

The images service also define security limits, the IMAGES.limits variable to configure these limits. See ImageLimits::default for the defaults.

use zng::{prelude::*, image};

image::IMAGES.limits().modify(|l| {
    let l = l.to_mut();
    l.allow_uri = image::UriFilter::allow_host("httpbin.org");
    l.max_encoded_len = 1.megabytes();
    l.max_decoded_len = 10.megabytes();
});

The example above changes the global limits to allow image downloads only from an specific host and only allow images with sizes less or equal to 1 megabyte and that only expands to up to 10 megabytes after decoding.

Full API

See zng_ext_image for the full image API and zng_wgt_image for the full widget API.

Modules

• mask
  Mask image properties.

Structs

• IMAGES
  Image loading, cache and render service.
• IMAGE_RENDER
  Controls properties of the render window used by IMAGES.render.
• Image
  W Image presenter.
• ImageHash
  A 256-bit hash for image entries.
• ImageHasher
  Hasher that computes a ImageHash.
• ImageLimits
  Limits for image loading and decoding.
• ImagePpi
  Pixels-per-inch of each dimension of an image.
• ImageRenderArgs
  Arguments for the ImageSource::Render closure.
• Img
  State of an ImageVar.
• ImgErrorArgs
  Arguments for on_error and img_error_fn.
• ImgLoadArgs
  Arguments for on_load.
• ImgLoadingArgs
  Arguments for img_loading_fn.

Enums

• ImageCacheMode
  Cache mode of IMAGES.
• ImageDataFormat
  Format of the image bytes.
• ImageDownscale
  Defines how an image is downscaled after decoding.
• ImageFit
  Image layout mode.
• ImageRepeat
  Image repeat mode.
• ImageSource
  The different sources of an image resource.
• ImageSourceFilter
  Represents a PathFilter and UriFilter.

Functions

• img_align
  P Sets the Align of all inner images within each image widget area.
• img_cache
  P Sets the cache mode of all inner images.
• img_crop
  P Sets a Rect that is a clip applied to all inner images before their layout.
• img_downscale
  P Custom pixel resize applied during image load/decode.
• img_error_fn
  P Sets the wgt_fn! that is used to create a content for the error message.
• img_fit
  P Sets the ImageFit of all inner images.
• img_limits
  P Sets custom image load and decode limits.
• img_loading_fn
  P Sets the wgt_fn! that is used to create a content for the loading message.
• img_offset
  P Sets a Point that is an offset applied to all inner images within each image widget area.
• img_rendering
  P Sets the ImageRendering of all inner images.
• img_repeat
  P Sets the ImageRepeat of all inner images.
• img_repeat_spacing
  P Sets the spacing between copies of the image if it is repeated.
• img_scale
  P Sets the scale applied to all inner images.
• img_scale_factor
  P If the image desired size is scaled by the screen scale factor.
• img_scale_ppi
  P Sets if the image desired size is scaled considering the image and monitor PPI.
• is_error
  P If the CONTEXT_IMAGE_VAR is an error.
• is_loaded
  P If the CONTEXT_IMAGE_VAR has successfully loaded.
• on_error
  P Image load or decode error event.
• on_load
  P Image loaded event.
• render_retain
  P If the render task is kept alive after a frame is produced, this is false by default meaning the image only renders once, if set to true the image will automatically update when the render widget requests a new frame.

Type Aliases

• ImageVar
  Represents an Img tracked by the IMAGES cache.
• PathFilter
  Represents a ImageSource::Read path request filter.
• UriFilter
  Represents a ImageSource::Download path request filter.