Package limn.graphics

Class BitmapIcon

java.lang.Object

limn.graphics.BitmapIcon

All Implemented Interfaces:

Icon

public final class BitmapIcon
extends Object
implements Icon

An Icon backed by pre-rendered Images (typically PNGs). Covers the raster cases that don't come from vectors:

• mask(Image...): a monochrome or grayscale mask that is recolored with the theme (tintable() is true). Pass more than one image to supply per-resolution variants (e.g. @1x, @2x); image(int, boolean, int) picks the smallest one that still covers the requested device size.
• themed(Image, Image): pre-colored light and dark variants, drawn as-is (tintable() is false); image(int, boolean, int) chooses by theme brightness.
• picture(Image): a single pre-colored image, drawn as-is.

Bitmaps do not resample as cleanly as vectors, so for crisp results supply a variant at (or above) the size you draw at, or prefer SvgIcon.

An animated image makes an animated icon (Image.isAnimated()), which a component plays by itself (see Icon). Every image of one icon is then animated, with the same number of frames shown for the same times and turning as many times, so that a theme or a resolution changes what is drawn and never when; an icon of images that differ in that is refused.

Nested Class Summary

Nested classes/interfaces inherited from interface limn.graphics.Icon

Icon.Mirroring

Method Summary

Modifier and Type	Method	Description
int	frameCount()
int	frameMillis(int frame)
Image	image(int pixelSize, boolean dark)	The bitmap best suited to a pixelSize×pixelSize box measured in device pixels, for the given theme brightness.
Image	image(int pixelSize, boolean dark, int frame)	One frame of the bitmap Icon.image(int, boolean) answers, which is that method's answer for frame 0.
boolean	isAnimated()
int	loopCount()
static BitmapIcon	mask(Image... resolutions)	A monochrome/grayscale mask recolored with the theme.
static BitmapIcon	picture(Image image)	A single, pre-colored image drawn without tinting; an animated one makes an animated icon.
static BitmapIcon	themed(Image light, Image dark)	Pre-colored light/dark variants, chosen by the active theme's brightness.
boolean	tintable()	Whether Icon.image(int, boolean) returns a single-color mask to be recolored with the theme (true: SVG, grayscale/mono PNG), or a finished picture to draw as-is (false: pre-colored light/dark variants).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface limn.graphics.Icon

paint, paint

Method Details

mask

public static BitmapIcon mask(Image... resolutions)

A monochrome/grayscale mask recolored with the theme. Supply one image, or several at different resolutions (any order) to be chosen by size.

Throws:

IllegalArgumentException - when there is no image, or the images do not play alike

picture

public static BitmapIcon picture(Image image)

A single, pre-colored image drawn without tinting; an animated one makes an animated icon.

themed

public static BitmapIcon themed(Image light,
 Image dark)

Pre-colored light/dark variants, chosen by the active theme's brightness.

Throws:

IllegalArgumentException - when the two do not play alike

tintable

public boolean tintable()

Description copied from interface: Icon

Whether Icon.image(int, boolean) returns a single-color mask to be recolored with the theme (true: SVG, grayscale/mono PNG), or a finished picture to draw as-is (false: pre-colored light/dark variants). Governs whether Icon.paint(limn.graphics.Canvas, float, float, float, limn.graphics.Color, boolean) applies its tint.

Specified by:

tintable in interface Icon

isAnimated

public boolean isAnimated()

Specified by:

isAnimated in interface Icon

Returns:

whether this icon has more than one frame, which a component plays; false unless overridden

frameCount

public int frameCount()

Specified by:

frameCount in interface Icon

Returns:

how many frames; 1 for a still icon

frameMillis

public int frameMillis(int frame)

Specified by:

frameMillis in interface Icon

Parameters:

frame - from 0 to Icon.frameCount() - 1

Returns:

how long that frame is shown, in milliseconds; 0 for a still icon

loopCount

public int loopCount()

Specified by:

loopCount in interface Icon

Returns:

how many turns the animation makes: 0 for one that does not end, which is also what a still icon answers

image

public Image image(int pixelSize,
 boolean dark,
 int frame)

Description copied from interface: Icon

One frame of the bitmap Icon.image(int, boolean) answers, which is that method's answer for frame 0. A frame of an animation decoded as it plays is decoded here, on the calling thread, if it is not in memory.

Specified by:

image in interface Icon

Parameters:

pixelSize - target extent in physical pixels (≥ 1)

dark - whether the active theme is dark

frame - from 0 to Icon.frameCount() - 1

Returns:

the frame, of the size frame 0 is

image

public Image image(int pixelSize,
 boolean dark)

The bitmap best suited to a pixelSize×pixelSize box measured in device pixels, for the given theme brightness. Vector icons rasterize at exactly this size (so they stay sharp on HiDPI and at any zoom); bitmap icons pick their nearest available variant.

Answers on the calling thread, and has no asynchronous form on purpose: Icon.paint(limn.graphics.Canvas, float, float, float, limn.graphics.Color, boolean) calls it from inside a frame, and a paint that asked for a bitmap has to be given one before it can finish. An implementation whose bitmap is expensive to produce carries the warm-up on its own type instead, where the caller can run it ahead of the frame; SvgIcon.imageAsync(int) is the one that does. For an animated icon, the image itself, whose own pixels are its first frame.

Specified by:

image in interface Icon

Parameters:

pixelSize - target extent in physical pixels (≥ 1)

dark - whether the active theme is dark (selects light/dark variants)