Struct Image

pub struct Image(/* private fields */);

W Image presenter.

This widget loads a still image from a variety of sources and presents it.

Implementations

impl Image

pub fn img_fit(&self, fit: impl IntoVar<ImageFit>)

P Sets the ImageFit of all inner images.

This property sets the IMAGE_FIT_VAR.

impl Image

pub fn img_scale(&self, scale: impl IntoVar<Factor2d>)

P Sets the scale applied to all inner images.

The scaling is applied after img_scale_ppi if active.

By default not scaling is done.

impl Image

pub fn img_scale_factor(&self, enabled: impl IntoVar<bool>)

P If the image desired size is scaled by the screen scale factor.

The image desired size is its original size after img_crop, it is a pixel value, but widgets are layout using device independent pixels that automatically scale in higher definition displays, when this property is enabled the image size is also scaled so that the image will take the same screen space in all devices, the image can end

This is enabled by default.

impl Image

pub fn img_scale_ppi(&self, enabled: impl IntoVar<bool>)

P Sets if the image desired size is scaled considering the image and monitor PPI.

If the image desired size is scaled by PPI.

The image desired size is its original size, after img_crop, and it can be in pixels or scaled considering the image PPI, monitor PPI and scale factor.

By default this is false, if true the image is scaled in a attempt to recreate the original physical dimensions, but it only works if the image and monitor PPI are set correctly. The monitor PPI can be set using the MONITORS service.

impl Image

pub fn img_align(&self, fit: impl IntoVar<Align>)

P Sets the Align of all inner images within each image widget area.

If the image is smaller then the widget area it is aligned like normal, if it is larger the “viewport” it is aligned to clip, for example, alignment BOTTOM_RIGHT makes a smaller image sit at the bottom-right of the widget and makes a larger image bottom-right fill the widget, clipping the rest.

By default the alignment is CENTER. The BASELINE alignment is treaded the same as BOTTOM.

impl Image

pub fn img_offset(&self, offset: impl IntoVar<Vector>)

P Sets a Point that is an offset applied to all inner images within each image widget area.

Relative values are calculated from the widget final size. Note that this is different the applying the offset property on the widget itself, the widget is not moved just the image within the widget area.

This property sets the IMAGE_OFFSET_VAR. By default no offset is applied.

impl Image

pub fn img_crop(&self, crop: impl IntoVar<Rect>)

P Sets a Rect that is a clip applied to all inner images before their layout.

Relative values are calculated from the image pixel size, the img_scale_ppi is only considered after. Note that more complex clipping can be applied after to the full widget, this property exists primarily to render selections of a texture atlas.

By default no cropping is done.

impl Image

pub fn img_repeat(&self, repeat: impl IntoVar<ImageRepeat>)

P Sets the ImageRepeat of all inner images.

Note that repeat converts from bool so you can set this property to img_repeat = true; to enable repeat in all inner images.

See also img_repeat_spacing to control the space between repeated tiles.

This property sets the IMAGE_REPEAT_VAR.

impl Image

pub fn img_repeat_spacing(&self, spacing: impl IntoVar<Size>)

P Sets the spacing between copies of the image if it is repeated.

Relative lengths are computed on the size of a single repeated tile image, so 100.pct() is skips an entire image of space. The leftover size is set to the space taken by tile images that do not fully fit inside the clip area, 1.lft() will insert space to cause only fully visible tiles to remain on screen.

This property sets the IMAGE_REPEAT_SPACING_VAR.

impl Image

pub fn img_rendering(&self, rendering: impl IntoVar<ImageRendering>)

P Sets the ImageRendering of all inner images.

If the image layout size is not the same as the source pixel size the image must be re-scaled during rendering, this property selects what algorithm is used to do this re-scaling.

Note that the algorithms used in the renderer value performance over quality and do a good enough job for small or temporary changes in scale only. If the image stays at a very different scale after a short time a CPU re-scale task is automatically started to generate a better quality re-scaling.

If the image is an app resource known during build time you should consider pre-scaling it to match the screen size at different DPIs using mipmaps.

This is ImageRendering::Auto by default.

impl Image

pub fn img_cache(&self, enabled: impl IntoVar<bool>)

P Sets the cache mode of all inner images.

Sets if the source is cached.

By default this is true, meaning the image is loaded from cache and if not present it is inserted into the cache, the cache lives for the app in the IMAGES service, the image can be manually removed from cache.

If set to false the image is always loaded and decoded on init or when source updates and is dropped when the widget is deinited or dropped.

impl Image

pub fn img_limits(&self, limits: impl IntoVar<Option<ImageLimits>>)

P Sets custom image load and decode limits.

If not set or set to None the IMAGES.limits is used.

See also img_downscale for a way to still display unexpected large images.

impl Image

pub fn img_downscale(&self, downscale: impl IntoVar<Option<ImageDownscale>>)

P Custom pixel resize applied during image load/decode.

Note that this resize affects the image actual pixel size directly when it is loading to force the image pixels to be within an expected size. This property primary use is as error recover before the img_limits error happens, you set the limits to the size that should not even be processed and set this property to the maximum size expected.

Changing this value after an image is already loaded or loading will cause the image to reload, image cache allocates different entries for different downscale values, this means that this property should never be used for responsive resize,use the widget size and other properties to efficiently resize an image on screen.

impl Image

pub fn is_error(&self, state: impl IntoVar<bool>)

P If the CONTEXT_IMAGE_VAR is an error.

impl Image

pub fn is_loaded(&self, state: impl IntoVar<bool>)

P If the CONTEXT_IMAGE_VAR has successfully loaded.

impl Image

pub fn get_img(&self, state: impl IntoVar<Option<Img>>)

P Gets the CONTEXT_IMAGE_VAR.

impl Image

pub fn get_img_layout_size(&self, state: impl IntoVar<Size2D<Px, Px>>)

P Gets the CONTEXT_IMAGE_VAR ideal size.

impl Image

pub fn img_error_fn(&self, wgt_fn: impl IntoVar<WidgetFn<ImgErrorArgs>>)

P Sets the wgt_fn! that is used to create a content for the error message.

impl Image

pub fn img_loading_fn(&self, wgt_fn: impl IntoVar<WidgetFn<ImgLoadingArgs>>)

P Sets the wgt_fn! that is used to create a content for the loading message.

impl Image

pub fn on_error(&self, handler: impl WidgetHandler<ImgErrorArgs>)

P Image load or decode error event.

This property calls handler every time the CONTEXT_IMAGE_VAR updates with a different error or on the first update after init if the image is already in error on init.

Handlers

This property accepts any WidgetHandler, including the async handlers. Use one of the handler macros, hn!, hn_once!, async_hn! or async_hn_once!, to declare a handler closure.

Route

This property is not routed, it works only inside a widget that loads images. There is also no preview event.

impl Image

pub fn on_load(&self, handler: impl WidgetHandler<ImgLoadArgs>)

P Image loaded event.

This property calls handler every time the CONTEXT_IMAGE_VAR updates with a successfully loaded image or on the first update after init if the image is already loaded on init.

Handlers

This property accepts any WidgetHandler, including the async handlers. Use one of the handler macros, hn!, hn_once!, async_hn! or async_hn_once!, to declare a handler closure.

Route

This property is not routed, it works only inside a widget that loads images. There is also no preview event.

impl Image

pub fn img_block_window_load(&self, enabled: impl IntoValue<BlockWindowLoad>)

P Block window load until image is loaded.

If the image widget is in the initial window content a WindowLoadingHandle is used to delay the window visually opening until the source loads, fails to load or a timeout elapses. By default true sets the timeout to 1 second.

impl Image

pub fn widget_new() -> Image

Start building a new instance.

pub fn widget_type() -> WidgetType

Gets the widget type info.

impl Image

pub fn source(&self, source: impl IntoVar<ImageSource>)

c The image source.

Can be a file path, an URI, binary included in the app and more.

Methods from Deref<Target = WidgetBase>

pub fn widget_builder(&mut self) -> &mut WidgetBuilder

Returns a mutable reference to the widget builder.

pub fn widget_when(&mut self) -> Option<&mut WhenInfo>

Returns a mutable reference to the when block if called inside a when block.

pub fn widget_take(&mut self) -> WidgetBuilder

Takes the widget builder, finishing the widget macro build.

After this call trying to set a property using self will panic, the returned builder can still be manipulated directly.

pub fn widget_build(&mut self) -> impl UiNode

Build the widget.

After this call trying to set a property will panic.

pub fn widget_importance(&mut self) -> &mut Importance

Returns a mutable reference to the importance of the next property assigns, unsets or when blocks.

Note that during the widget_intrinsic call this is Importance::WIDGET and after it is Importance::INSTANCE.

pub fn start_when_block( &mut self, inputs: Box<[WhenInput]>, state: Box<dyn VarBoxed<bool>>, expr: &'static str, location: SourceLocation, )

Start building a when block, all properties set after this call are pushed in the when block.

pub fn end_when_block(&mut self)

End the current when block, all properties set after this call are pushed in the widget.

pub fn id(&self, id: impl IntoValue<WidgetId>)

c Unique ID of the widget instance.

Note that the id can convert from a &'static str unique name.

Trait Implementations

impl Deref for Image

type Target = WidgetBase

The resulting type after dereferencing.

fn deref(&self) -> &<Image as Deref>::Target

Dereferences the value.

impl DerefMut for Image

fn deref_mut(&mut self) -> &mut <Image as Deref>::Target

Mutably dereferences the value.