pub struct Image { /* private fields */ }Expand description
A picture from a PNG, JPEG, GIF, WebP or SVG file, drawn at a fixed size.
A GIF of more than one frame plays while it is drawn, at its own delays, looping as the file says. The filters run once on the picture at the size drawn, and the result is cached, so a filtered image costs what a plain one does to draw.
An image the renderer skips, at opacity 0, under an ancestor at
opacity 0, or cut out by its mask region, still loads its picture at
the size it would be drawn at whenever its area is repainted, with or
without a status, and the cache keeps it as it
keeps a drawn one, so revealing or moving it draws it on its first
frame. That is the way to keep pictures warm. A GIF doesn’t play
there. A hidden image, with visible false, loads nothing unless it
has a status.
Implementations§
Source§impl Image
impl Image
Sourcepub const DEFAULT_SIZE: u32 = 64
pub const DEFAULT_SIZE: u32 = 64
The default width and height in logical pixels.
Sourcepub fn new(source: impl IntoProp<PathBuf>) -> Image
pub fn new(source: impl IntoProp<PathBuf>) -> Image
An image of the file at source: a path (&str, String, &Path
or PathBuf) or a closure that returns one.
Sourcepub fn from_source(source: impl IntoProp<Option<IconSource>>) -> Image
pub fn from_source(source: impl IntoProp<Option<IconSource>>) -> Image
An image of an IconSource, or a closure that returns an
Option of one, such as crabshell-services’ Notification::image:
raw pixels, a file as new reads it, or an icon name
looked up in the icon theme at the box’s larger side and the
window’s scale rounded up, then read as that file. None shows
nothing and is ImageStatus::Empty, as an empty path is. fit,
the filters, transition and status work as for a file.
Pixels keep an Icon’s limits: at most 512 a side and exactly
width * height * 4 bytes, or the image is ImageStatus::Failed
and the bad buffer is logged once. They are scaled on the loop’s
thread, once for each size, fit and filters, and cached by their
shared allocation, so images showing the same IconPixels share
one picture. A new source with the same bytes keeps the one shown. A
name that no theme has fails as a missing file does.
Sourcepub fn fit(self, fit: impl IntoProp<Fit>) -> Image
pub fn fit(self, fit: impl IntoProp<Fit>) -> Image
Sets how the picture fills the image’s box when their shapes differ.
Sourcepub fn tint(self, tint: impl IntoProp<Option<Color>>) -> Image
pub fn tint(self, tint: impl IntoProp<Option<Color>>) -> Image
Paints the picture’s pixels in tint, keeping their alpha, as
Icon::tint does. None, the default, draws it as it is.
Sourcepub fn brightness(self, brightness: impl IntoProp<f32>) -> Image
pub fn brightness(self, brightness: impl IntoProp<f32>) -> Image
Scales the colors, as CSS’s brightness(): 1, the default, leaves
them, 0 is black and 2 twice as bright. A number that isn’t finite
counts as 1, and one below 0 as 0.
Sourcepub fn contrast(self, contrast: impl IntoProp<f32>) -> Image
pub fn contrast(self, contrast: impl IntoProp<f32>) -> Image
Sets the contrast, as CSS’s contrast(): 1, the default, leaves the
colors, 0 is middle gray and more than 1 is stronger. A number that
isn’t finite counts as 1, and one below 0 as 0.
Sourcepub fn saturation(self, saturation: impl IntoProp<f32>) -> Image
pub fn saturation(self, saturation: impl IntoProp<f32>) -> Image
Sets the saturation, as CSS’s saturate(): 1, the default, leaves
the colors, 0 is gray and more than 1 is more vivid. A number that
isn’t finite counts as 1, and one below 0 as 0.
Sourcepub fn blur(self, blur: impl IntoProp<f32>) -> Image
pub fn blur(self, blur: impl IntoProp<f32>) -> Image
Blurs the picture, as CSS’s blur(): the Gaussian’s standard
deviation in logical pixels, 0 by default. Pixels past the picture’s
edge count as its edge pixels, so a blurred picture keeps its edges
opaque. A number that isn’t finite or is below 0 counts as 0. The
blur is for still pictures, such as album art and wallpapers: a
blurred GIF shows its first frame, still.
Sourcepub fn playing(self, playing: impl IntoProp<bool>) -> Image
pub fn playing(self, playing: impl IntoProp<bool>) -> Image
Whether an animated GIF plays, true by default. False pauses it on the frame it shows.
Sourcepub fn transition(self, transition: impl IntoProp<ImageTransition>) -> Image
pub fn transition(self, transition: impl IntoProp<ImageTransition>) -> Image
How a new source comes in: ImageTransition::None, the default,
shows it at once; the others bring it in over the old picture on the
animation clock, repainting only the image’s box. A new source
mid-transition starts again from the picture most of the box shows:
the one leaving before halfway, the one coming in from halfway on.
A new source that can’t be loaded keeps the old picture; the clock
still runs and repaints the box for the transition’s length, since
only the renderer learns the file is bad.
Sourcepub fn status(self, status: Signal<ImageStatus>) -> Image
pub fn status(self, status: Signal<ImageStatus>) -> Image
Shares where the picture is, as Qt’s Image.status, so a config can
fade album art in once it has loaded or show a glyph when a picture
can’t be read: ImageStatus::Empty for an empty path,
ImageStatus::Loading from each new source until its picture is
loaded, ImageStatus::Ready once it is, and
ImageStatus::Failed when the file can’t be read or decoded, the
pixels or name of from_source are bad or
missing, or it is past the size limits. Each new source is loaded in
the loop turn that set it, whether the image is drawn or not, so its
own status can show it: one at opacity 0 or cut out by its mask
region loads at its size, as it does without a status, and one
hidden or of no size at the box it was last laid out in, or one
pixel if it has none. A hidden image is decoded again at its size
once shown, so binding its opacity to Ready is the cheap
way to fade it in. A picture decoded again at another size stays
Ready. Written only on a change; the signal belongs to the config,
and the image repaints nothing for it.
Sourcepub fn visible(self, visible: impl IntoProp<bool>) -> Self
pub fn visible(self, visible: impl IntoProp<bool>) -> Self
Shows or hides the widget. Hidden, it is taken out of the layout, so its space goes to the others, and it isn’t drawn, hit or reached by Tab; it drops the keyboard focus and the pointer. Its bindings and state stay, so it shows again as it was. Shown by default.
Sourcepub fn geometry(self, geometry: Signal<Rect>) -> Self
pub fn geometry(self, geometry: Signal<Rect>) -> Self
Shares where the widget is: after each layout that moves or
resizes it, its laid-out rectangle in the window’s logical
pixels, scrolled with any scroll view around it but not moved by
a style’s translate, scale or rotate, is written to geometry. A
hidden widget writes nothing. An effect that reads it may change
the layout: the window is laid out again at once, until nothing
moves.
Sourcepub fn mapped_geometry(self, geometry: Signal<Rect>) -> Self
pub fn mapped_geometry(self, geometry: Signal<Rect>) -> Self
Shares where the widget is drawn: the box around it once its own and its ancestors’ translate, scale and rotate have moved it, in the window’s logical pixels, scrolled with any scroll view around it. It is written after each layout that moves it and after each change of a transform or an offset that does, every frame of an animated one. A hidden widget writes nothing. Where the window itself is on its output is unknown: Wayland doesn’t tell a client.
Sourcepub fn accessible_name(self, name: impl IntoProp<String>) -> Self
pub fn accessible_name(self, name: impl IntoProp<String>) -> Self
What a screen reader calls the widget, instead of what it shows: a button’s text, a text’s own, or a field’s placeholder. An icon button needs one to be read at all.
Sourcepub fn mask_region(self, region: impl IntoProp<Option<Region>>) -> Self
pub fn mask_region(self, region: impl IntoProp<Option<Region>>) -> Self
Keeps the widget and everything inside it only within region,
given in the widget’s own logical pixels from its top-left
corner, with antialiased edges and rounded corners. Nothing shows
outside the widget’s box, as with a style’s
mask, and both apply when both are set.
None, the default, keeps it all.
It changes only what is drawn: the pointer still hits the whole
widget, so a click in a hole reaches it. A window’s own
mask is what lets clicks through.
A new region repaints the widget’s painted area, its box unless its children overflow it, and never lays the window out, so a region that changes every frame of an animation costs a repaint of that area each frame. A full-screen 1080p picture with a few rounded holes took about 6 to 8 ms a frame at scale 1 and 22 to 25 ms at scale 2 on a 12-core laptop, most of it in the tiles a hole’s edge crosses.