A widget that wraps an rtk.Image.

rtk.Image is a low-level class for managing images and therefore can't be added to containers, while rtk.ImageBox can because it is a proper widget.

Example

-- Create an ImageBox widget with photo.jpg that's located in an img
-- directory up a level from the current script.
local img = rtk.ImageBox{'../img/photo.jpg', border='2px black'}
-- Add the image centered to the window
window:add(img, {halign='center', valign='center'})
-- Just a bit of fun ...
img.onclick = function()
    img:animate{'scale', dst=0.2, easing='out-bounce', duration=2}
end

rtk.ImageBox.image rtk.Image, string or nil read/write ¶

The image (default nil).

Either an existing rtk.Image, or a string that refers to a file in an image path that was previously registered with rtk.add_image_search_path(). If a string is provided then a new rtk.Image is automatically created and the calculated value of this attribute will contain this rtk.Image instance, where rtk.Image.icon() is used to load the image and the ImageBox's bg attribute is used between either light or dark variants of the image (if available).

This attribute may be passed as the first positional argument during initialization. (In other words, rtk.ImageBox{img} is equivalent to rtk.ImageBox{image=img}.)

If image is nil, nothing is drawn and the ImageBox takes up no space in its container, notwithstanding minw or minh which will still be respected. The image attribute can be assigned later.

rtk.ImageBox.scale number or nil read/write ¶

Forces a scale for the image (default nil).

By default (nil), images will shrink to fit their container (while preserving aspect), but will not grow beyond their native size. Assigning scale=1 (or any other value) will fix the image at the given size. This means rtk.scale is also ignored when the scale attribute is defined.

However, the w and h, and maxw and maxh attributes, if defined, will take precedence and override scale. Similarly, if adding to a container and setting either fillw or fillh cell attributes to true will also override scale.

rtk.ImageBox.aspect number or nil read/write ¶

The aspect ratio of the rendered image (default nil).

By default (nil), the image's native aspect ratio is used. The drawn aspect ratio can be overridden by setting this attribute.

If both w and h are defined, the aspect ratio dictated by those attributes will override aspect. Likewise, if both fillw and fillh cell attributes are set to true, the aspect will be overridden. However if only one of these is set, the aspect ratio will be preserved.