Class rtk.MultiImage

Class Hierarchy

Encapsulates multiple underlying rtk.Image objects, representing different pixel density variants of the same image.

Being a subclass of rtk.Image, rtk.MultiImage can be used anywhere an rtk.Image is expected. When provided to widget attributes, such as rtk.Button.icon, the best variant is selected based on the current rtk.scale.value.

The entire rtk.Image API works with rtk.MultiImage, so it is not re-documented here.

In cases where rtk.Image methods return a new image, those same methods here will return rtk.MultiImage instead. For example, viewport() will return a new rtk.MultiImage with each encapsulated image being a viewport into the original variants.

Geometry is implicitly adjusted

Methods that receive coordinates and sizes will always be relative to a pixel density of 1.0. All geometry values passed to rtk.MultiImage methods are automatically adjusted according to the density of the underlying variants.

For example, suppose a multi-image has two images with density 1.0 and 2.0:

local img = rtk.MultiImage{
    rtk.Image:load('icon@1x.png', 1),
    rtk.Image:load('icon@2x.png', 2),
local vp = img:viewport(16, 16, 32, 32)

The above vp viewport will contain a viewport at position 16,16 and size 32x32 within the 1.0 density variant, and position 32,32 and size 64x64 within the 2.0 density variant. In other words, the supplied geometry is multiplied by the density of the image variant being acted upon.



Constructor to create a new MultiImage


Adds (or loads) an image variant to the multi image


Updates the current context of the multi image based on the given scale


Constructor to create a new MultiImage.

For convenience, a variable number of existing rtk.Image objects may be passed here, and they will all be included as variants for the multi image. Alternatively the add() method may be explicitly called.

rtk.MultiImage:add(path_or_image, density)

Adds (or loads) an image variant to the multi image.

path_or_image (rtk.Image or string)

if a string, the image is loaded via rtk.Image:load() and assigned the supplied density; if an rtk.Image, the image is added directly as a variant (and in this case the density argument is ignored)

density (number or nil)

the pixel density of the image when path_or_image is a filename string; is ignored (and therefore may be nil) when path_or_image is an rtk.Image

Return Values
(rtk.Image or nil)

returns the rtk.Image if load was successful, or nil if the load failed.


Updates the current context of the multi image based on the given scale. After this method is called, all the image attributes are updated to reflect the chosen variant.

The variant that's chosen will be that whose density most closely matches the scale argument. Larger density variants will be favored if an exact match can't be found.


Widgets that receive images as attributes (for example rtk.Entry.icon) will automatically call this method when rtk.scale.value changes. However if you are using an rtk.MultiImage outside the context of a widget attribute, you will need to explicitly call this method when the UI scale changes.

scale (number or nil)

the variant whose density most closely matches this scale will be selected; if nil, the current value of rtk.scale.value is used.`

Return Values

returns self for method chaining