Class “Image”

Object > Image

This class represents an image source and optionally that image’s dimension or the scale it should be displayed at. For convenience there are various expressions that may be used in place of an Image instance. All API that accept these expressions will convert them to a Image object.

Type: Image extends Object
Constructor: public
Singleton: No
Namespace: tabris
Direct subclasses: None
JSX Support: No

The width and height of an image may optionally be specified in DIP (device independent pixel). If none are given the dimensions from the image file are used in combination with the given scale. If neither scale, width or height are given the scale may be extracted from an image URL if the file name contains the pattern “@<scale>x”, e.g. "image@2x.jpg". If the scale can not be determined by any of these methods it will be treated as 1.

The scale factor of the image is relevant when the intrinsic size (in DIP) of the image is needed for layouting. On high-density displays (i.e. devices with a scale factor higher than 1) an undetermined image scale factor (or scale factor 1) may make the image look blurry at full its full natural size. It is the application developers responsibility to provide and use image files with the appropriate scale factor for any given device.

When displaying images that are very large (eg. 3000 x 2000) on small widgets (like a 100 x 100 ImageView), it is strongly recommended to provided a concrete image size. This will allow the system to scale the image to the given size, saving memory and computing power, which leads to a faster display time overall.

Examples

JavaScript

import {Image} from 'tabris';

const image = Image.from({src: 'image@2x.png'});
console.log(image.scale); // "2"

Constructor

new Image(imageLike)

Parameter Type Description
imageLike ImageLikeObject An image configuration. See ImageLikeObject

Methods

equals(value)

Tests if the given value is a Image instance that is deeply equal to this one.

Parameter Type Description
value Image  

Returns: boolean

Static Methods

from(imageValue)

Creates a new instance of Image using any valid Image expression. For any other value, including null, the method throws.

Parameter Type Description
imageValue ImageValue The value to create an Image instance from. See ImageValue

Returns: Image

isImageValue(value)

Returns true if value is an ImageValue. This includes null. Use this to check if a value will be accepted by an image property. This is also a valid TypeScript type guard function.

Parameter Type Description
value any The value to test

Returns: boolean

isValidImageValue(value)

Returns true if value is a valid ImageValue. This excludes null. Use this to check if a value will be accepted by Image.from. This is also a valid TypeScript type guard function.

Parameter Type Description
value any The value to test

Returns: boolean

Properties

height

Image height in dip. Extracted from the image file when ‘auto’.

Type: number | 'auto'
Settable: No

This property can only be set via constructor. Once set, it cannot change anymore.

scale

Image scale factor - the image will be scaled down by this factor. See ImageLikeObject for details

Type: number | 'auto'
Settable: No

This property can only be set via constructor. Once set, it cannot change anymore.

src

As a string this is a file system path, relative path, full URL, a Blob containing a jpg or png file, or an ImageBitmap instance. Data URIs are also supported. Relative paths are resolved relative to ‘package.json’. On Android the name of a bundled drawable resource can be provided with the url scheme android-drawable, e.g. android-drawable://ic_info_black. If a closed ImageBitmap is given the constructor will throw. A given Blob must contain an encoded image.

Type: string
| ImageBitmap
| Blob
Settable: No

This property can only be set via constructor. Once set, it cannot change anymore.

width

Image width in dip. Extracted from the image file when ‘auto’.

Type: number | 'auto'
Settable: No

This property can only be set via constructor. Once set, it cannot change anymore.

ImageValue

  • JavaScript Type: tabris.Image, Object, string, Blob, ImageBitmap
  • TypeScript Type: tabris.ImageValue

ImageValue describes any value that can be used to as an image in Tabris.js, which includes Image instances, ImageLikeObject and ImageSource.

In TypeScript ImageValue is available as a union type exported by the tabris module.

ImageLikeObject

  • JavaScript Type: Object
  • TypeScript Type: tabris.ImageLikeObject
interface ImageLikeObject {
  src: string | ImageBitmap | Blob;
  scale?: number | "auto";
  width?: number | "auto";
  height?: number | "auto";
}

A plain object implementing the same properties as Image.

Examples:

{src: "images/catseye.jpg", width: 300, height: 200}
{src: blob, scale: 2}

ImageSource

  • JavaScript Type: string, Blob, ImageBitmap
  • TypeScript Type: tabris.ImageSource

This is just the source value of an Image by itself.

"images/catseye.jpg"  // same as:
{src: "images/catseye.jpg"}