# Titanium.UI.ImageView

A view to display a single image or series of animated images.

Availability

0.9

9.2.0

Extends

Titanium.UI.View

# Overview

Use the Titanium.UI.createImageView method or <ImageView> Alloy element to create an ImageView.

Specifying either a width or height property for this view will scale its image(s) with the aspect ratio maintained, up to a maximum size that does not exceed its parent view.

# Remote Images

You can display both local and remote images in an ImageView. When loading remote images, you should set the defaultImage property to a local image, which will be displayed while the remote image is being downloaded. Remote images are cached automatically on the iOS-, Android- and Windows platform.

Android Note: Android 6 and later uses runtime permissions to secure the user's privacy. Therefore, you should call Titanium.Filesystem.requestStoragePermissions before attempting to load remote images.

Read more about remote images and general best practices in the Image Best Practices Guide (opens new window).

# Android 9-Patch Scaled Images

A nine-patch (9-patch) image is simply a standard png image with a transparent border of a single pixel, containing "guides" defined by solid black (#000) color fills. Guides added to the top and left edges determine that the image may be stretched in horizontal and vertical planes respectively. Optionally, the content area may be defined by guides added to the bottom and right edges.

Although any image editor may be used to create the guides, certain settings can cause the edges of the graphic to "bleed" into the transparent border, consequently making it non-transparent. Thus, the draw9patch utility provided in the Android SDK tools directory is recommended for this purpose.

For further information about nine-patch images and the Android utility, see the Nine-patch (opens new window) and Draw 9-patch (opens new window) sections of the Android Developer website.

The nine-patch technique may be used with any of Titanium's static image properties. See the "Button with Nine-patch Background Image" example for a demonstration.

# Examples

# Basic Image View

In this example, we create a simple image view:

Ti.UI.backgroundColor = 'white';
var win = Ti.UI.createWindow();
var image = Ti.UI.createImageView({
  image:'/images/myimage.png'
});
win.add(image);
win.open();

# Button with Nine-patch Background Image

Create a button with a nine-patch image background, that swaps with another image when selected, and generates a message in the console when clicked.

Note that images are referenced in the code without the .9 part of the filename, and that the project should be cleaned to ensure that the files are correctly copied to the project.

var win = Ti.UI.createWindow({
    backgroundColor: 'white',
    exitOnClose: true,
    fullscreen: false,
    title: 'Click button to test'
});

var button = Ti.UI.createButton({
    backgroundImage: '/images/custom-slider-right.png',
    backgroundSelectedImage:'/images/custom-slider-left.png',
    title: 'Click me!',
    top: 10,
    width: 300,
    height: 200
});
button.addEventListener('click',function(e){
    Ti.API.info("You clicked the button");
});
win.add(button);
win.open();

# Alloy XML Markup

Previous basic image view example as an Alloy view.

<Alloy>
    <Window id="win" backgroundColor="white">
        <ImageView id="image" image="/images/myimage.png" />
    </Window>
</Alloy>

# Properties

# animating READONLY

Availability

0.9

9.2.0

animating :Boolean

Indicates whether animation is running.

Default: false on creation, true on load (Android), false (iPhone, iPad)

# autorotate CREATION ONLY

Availability

3.0.0

9.2.0

autorotate :Boolean

Indicates whether the image should be rotated based on EXIF orientation data.

Before Titanium 10.1.0, this defaulted to false on Android.

Default: true

# decodeRetries

Availability

1.7.0

decodeRetries :Number

Number of times to retry decoding the bitmap at a URL.

Defaults to 2 on Titanium 10.1.0 and higher. Defaults to 5 on older SDK versions.

Default: 2

# defaultImage

Availability

0.9

9.2.0

defaultImage :String

Local path to the default image to display while loading a remote image.

# duration

Availability

0.9

9.2.0

duration :Number

Amount of time in milliseconds to animate one cycle.

Starting with release 2.1.1, the minimum duration is 30 ms and the default duration is 200 ms.

On Android, prior to release 2.1.1, if any images are assigned to the images property when the animation is started, duration will be set to the number of images multiplied by 33 ms. If no images are assigned, duration will be set to 100 ms.

On iOS, prior to release 2.1.1, the default is 30 ms.

On Android, if the value of duration is changed, stop and start need to be called for the new value to take effect.

Default: 200 ms in Release 2.1.1 and later. Platform-specific default in earlier releases.

# enableZoomControls

Availability

1.3.0

enableZoomControls :Boolean

Show zoom controls when the user touches the image view.

Default: false

# hires

Availability

0.9

9.2.0

hires :Boolean

Set to true to prevent scaling of 2x/3x-resolution remote images for retina displays.

Causes images to display at 50%, where one pixel of the graphic maps to one physical pixel on-screen. This functionality is automatically determined for local images via their filenames, and thus this property is only applicable to remote images.

Default: false

# image

Availability

0.9

9.2.0

image :String | Titanium.Blob | Titanium.Filesystem.File

Image to display.

Image to display, defined using a local filesystem path, a File object, a remote URL, or a Blob object containing image data.

For Android, if there is a redirect and change in protocol, it will not follow. For example, from http to https and vice versa. See Java Bug Database for more information.

# images

Availability

0.9

9.2.0

images :Array<String> | Array<Titanium.Blob> | Array<Titanium.Filesystem.File>

Array of images to animate, defined using local filesystem paths, File objects, remote URLs (Android only), or Blob objects containing image data.

When using this property, an initial start() needs to be called upon the ImageView before any image will show in this imageview.

Related properties/methods to look at: start, stop, pause, reverse, resume and repeatCount

# imageTouchFeedback

Availability

10.1.0

imageTouchFeedback :Boolean

Enables a ripple effect when the foreground image is touched.

Note that the touchFeedback property applies a ripple effect to the view's background. If the image is opaque and completely covers the view (such as a photo), then the background's ripple won't be visible. In this case, you should use this imageTouchFeedback property to apply a ripple effect to the foreground image assigned via the image property.

Default: false

# imageTouchFeedbackColor

Availability

10.1.0

imageTouchFeedbackColor :String

Optional touch feedback ripple color. This has no effect unless imageTouchFeedback is true.

Defaults to provided theme color.

# paused READONLY

Availability

0.9

9.2.0

paused :Boolean

Indicates whether the animation is paused.

Default: false

# preventDefaultImage

Availability

0.9

9.2.0

preventDefaultImage :Boolean

Prevent the default image from being displayed while loading a remote image. This property is ignored when the defaultImage property is set.

Default: false

# repeatCount

Availability

0.9

9.2.0

repeatCount :Number

Number of times to repeat the image animation.

Default: 0 (infinite)

# reverse

Availability

0.9

9.2.0

reverse :Boolean

Run the animation in reverse.

Default: false

# scalingMode

Availability

10.1.0

scalingMode :Number

Determines how the image is scaled within the view.

This API can be assigned the following constants:

Default: Titanium.Media.IMAGE_SCALING_AUTO

# tintColor

Availability

5.4.0

9.2.0

tintColor :String | Titanium.UI.Color

The view's tintColor. Android does not support setting instances of Titanium.UI.Color

This property is a direct correspondant of the tintColor property of UIView on iOS. If no value is specified, the tintColor of the View is inherited from its superview.

Default: null

# Methods

# pause

Availability

0.9

9.2.0

pause() → void

Pauses a running animation. Use resume method to continue.

This method only works if multiple images are specified.

Returns

Type: void

# resume

Availability

0.9

9.2.0

resume() → void

Resumes an animation from a pause state.

This method only works if multiple images are specified.

Returns

Type: void

# start

Availability

0.9

9.2.0

start() → void

Starts the image animation. On Android, also resets index to the first image.

This method only works if multiple images are specified.

Returns

Type: void

# stop

Availability

0.9

9.2.0

stop() → void

Stops a running animation. On iOS, also resets index to the first image.

This method only works if multiple images are specified.

Returns

Type: void

# toBlob

Availability

0.9

9.2.0

toBlob() → Titanium.Blob

Returns the image as a Blob object.

Returns

Type: Titanium.Blob

# Events

# change

Availability

0.9

9.2.0

Fired for each frame change during an animation.

Properties

Name	Type	Description
index	Number	Index of the image frame being displayed.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# load

Availability

0.9

9.2.0

Fired when either the initial image and/or all of the images in an animation are loaded.

Properties

Name	Type	Description
state	String	Set to `image` when the image defined in the image property is loaded. Set to `images`, when the series of images defined in the images property are loaded.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# start

Availability

0.9

9.2.0

Fired when the animation starts.

# stop

Availability

0.9

9.2.0

Fired when the animation stops.

# error

Availability

0.9

9.2.0

Fired when an image fails to load.

Properties

Name	Type	Description
success	Boolean	Indicates a successful operation. Returns `false`.
error	String	Error message, if any returned. May be undefined.
code	Number	Error code. If the error was generated by the operating system, that system's error value is used. Otherwise, this value will be -1.
image	String	URL of the image that failed to load.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# pause

Availability

2.1.1

0.9

9.2.0

Fired when the animation pauses.