rtk.MultiImage
¶
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.
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.
| rtk.MultiImage() | Constructor to create a new MultiImage |
| add() | Adds (or loads) an image variant to the multi image |
| refresh_scale() | 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.
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 |
| density | (number or nil) | the pixel |
| (rtk.Image or nil) | returns the |
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.MultiImage) | returns self for method chaining |