Titanium.UI.ImageView

viewAndroidiPhoneiPadmacOSsince 0.9

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

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.

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 and Draw 9-patch 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 87

accessibilityDisableLongPress

BooleanAndroidsince 12.4.0

Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

Parameters	Type	Description
symbolEffect	String	The symbol effect to add. One of `pulse`, `bounce`, `appear`, `disappear`, `variableColor` or `scale`.
options	String	The options for the symbol effect. One of `repeating`, `nonRepeating`, `repeatCount` or `speed`.
animated	Boolean	A Boolean value that indicates whether to animate the addition of a `scale`, `appear`, or `disappear` effect.
callback	Callback	A callback the system calls after the effect’s addition is complete.

Parameters	Type	Description
animation	Titanium.UI.Animation \| Dictionary<Titanium.UI.Animation>	Either a dictionary of animation properties or an Animation object.
callback?	Callback<Object>	Function to be invoked upon completion of the animation.

Parameters	Type	Description
point	Point	A point in this view's coordinate system. If this argument is missing an `x` or `y` property, or the properties can not be converted into numbers, an exception will be raised.
destinationView	Titanium.UI.View	View that specifies the destination coordinate system to convert to. If this argument is not a view, an exception will be raised.

Parameters	Type	Description
callback?	Callback<Titanium.Blob>	Function to be invoked upon completion. If non-null, this method will be performed asynchronously. If null, it will be performed immediately.
honorScaleFactor?	Boolean	Determines whether the image is scaled based on scale factor of main screen. (iOS only) When set to true, image is scale factor is honored. When set to false, the image in the blob has the same dimensions for retina and non-retina devices.

Event properties	Type	Description
x	Number	X coordinate of the event from the `source` view's coordinate system.
y	Number	Y coordinate of the event from the `source` view's coordinate system.
obscured	Boolean	Returns `true` if the click passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Event properties	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.

Event properties	Type	Description
scale	Number	The scale factor relative to the points of the two touches in screen coordinates.
velocity	Number	The velocity of the pinch in scale factor per second.
time	Number	The event time of the current event being processed.
timeDelta	Number	The time difference in milliseconds between the previous accepted scaling event and the current scaling event.
currentSpan	Number	The average distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanX	Number	The average X distance between each of the pointers forming the gesture in progress through the focal point.
currentSpanY	Number	The average Y distance between each of the pointers forming the gesture in progress through the focal point.
previousSpan	Number	The previous average distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanX	Number	The previous average X distance between each of the pointers forming the gesture in progress through the focal point.
previousSpanY	Number	The previous average Y distance between each of the pointers forming the gesture in progress through the focal point.
focusX	Number	The X coordinate of the current gesture's focal point.
focusY	Number	The Y coordinate of the current gesture's focal point.
inProgress	Boolean	Returns `true` if a scale gesture is in progress, `false` otherwise.

Event properties	Type	Description
direction	String	Direction of the swipe--either 'left', 'right', 'up', or 'down'.
x	Number	X coordinate of the event's endpoint from the `source` view's coordinate system.
y	Number	Y coordinate of the event's endpoint from the `source` view's coordinate system.
obscured	Boolean	Returns `true` if the swipe passed through an overlapping window belonging to another app. This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Examples

Basic Image View

Button with Nine-patch Background Image

Alloy XML Markup

Properties 87

Linear and Radial Gradients

Methods 19

Events 23