Titanium Mobile: API Reference - Amazon Web Servicesassets.appcelerator.com.s3.amazonaws.com/docs/API_UIViewClass.pdf · Titanium.UI.View Class 7 Appcelerator Titanium API Reference

Titanium Mobile:API Reference

October 6, 2010

API

Titanium.UI.View Class

Appcelerator Titanium API Reference

Copyright © 2010 Appcelerator, Inc. All rights reserved.Appcelerator, Inc. 444 Castro Street, Suite 818, Mountain View, California 94041

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, elec-tronic, photocopying, recording, or otherwise, without prior written permission of Appcelerator, Inc., with the following exceptions: Any per-son is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Appcelerator's copyright notice.

The Appcelerator name and logo are registered trademarks of Appcelerator, Inc. Appcelerator Titanium is a trademark of Appcelerator, Inc. All other trademarks are the property of their respective owners.

No licenses, express or implied, are granted with respect to any of the technology described in this document. Appcelerator retains all intellectual property rights associated with the technology described in this document. Every effort has been made to ensure that the information in this document is accurate. Appcelerator is not responsible for typographical or technical errors. Even though Appcelerator has reviewed this document, APPCELERATOR MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED "AS IS," AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPCELERATOR BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Appcelerator dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

2 API, 10/6/10

ContentsAppcelerator Titanium API Reference

ContentsOverview ...................................................................................................................... 5

Titanium.UI.View Class ............................................................................................... 6Instance Methods Summary ......................................................................................................6Object Properties .......................................................................................................................6Events ........................................................................................................................................7Event Properties ........................................................................................................................7Methods .....................................................................................................................................8

Example Programs ................................................................................................... 12Generic Use of View ................................................................................................................12Single Image View ...................................................................................................................13Two Image View .......................................................................................................................14Two Image Manipulation Game ...............................................................................................16

3API, 10/6/10

Appcelerator Titanium API ReferenceContents

4 API, 10/6/10

OverviewAppcelerator Titanium API Reference

OverviewA View object is created by Titanium.UI.createView and represents a generalized drawing surface or container. Many other Titanium classes are subclasses of View, including among others TableView, ImageView, Label, Button. Although these classes are specialized for different types of display elements, they all share some sim-ilarities. For example, you'll notice some overlap among instance methods, object properties, events and event properties.

You can use a View in a very general way. Even if you're planning to use a TableView, ImageView, or another subclass of View, it's helpful to understand the functionality available with the generic View class.

You can think of views as being arranged in a vertical stack, like papers on a desk. In general, the topmost view will be displayed, possibly obscuring views below it. For example, if you have two views arranged side-by-size, they would both be visible. However, if one view partially overlaps the other, then it's the topmost view that will be fully visible; the other view(s) would be partly blocked. You can use the zIndex property to arrange multiple views within this conceptual vertical stack. The view with the highest zIndex will be topmost. If you don't explicitly specify the zIndex, then Titanium assumes zIndex to be 0. For views with the same zIndex value, the most recently added one will be topmost.

5API, 10/6/10

Appcelerator Titanium API ReferenceTitanium.UI.View Class

Titanium.UI.View ClassThe View is an empty drawing surface or container. The View is created by the Titanium.UI.createView method.

Instance Methods Summary

Object Properties

Name Descriptionadd add a child to the view hierarchy addEventListener add an event listener for the instance to receive view triggered events animate animate the view fireEvent fire a synthesized event to the views listener hide hide the view remove remove a previously added view from the view hiearchy removeEventListener remove a previously added event listener show make the view visible toImage return a Blob image of the rendered view

Name Type DescriptionanchorPoint object A dictionary with properties x and y to indicate the anchor point value. Anchor

specifies the position by which animation should occur. Center is 0.5, 0.5.animatedCenterPoint object read-only object with x and y properties of where the view is during animationbackgroundColor string the background color of the table viewbackgroundGradient object a background gradient for the view with the properties: type,startPoint,end-

Point,startRadius,endRadius,backfillStart,backfillEnd,colors.backgroundImage string the background image to render in the background of the table viewborderColor string the border color of the viewborderRadius float the border radius of the viewborderWidth float the border width of the viewbottom float, string Property for the view bottom position. This position is relative to the views par-

ent. can be either a float value or a string of the width.center object a dictionary with properties x and y to indicate the center of the views position

relative to the parent viewheight float, string Property for the view height. Can be either float value or a string of the width.left float, string Property for the view left position. This position is relative to the views parent.

can be either a float value or a string of the width.opacity float the opacity from 0.0-1.0right float, string Property for the view right position. This position is relative to the views parent.

Can be either a float value or a string of the width.size object the size of the view as a dictionary of width and height propertiestop float, string Property for the view top position. This position is relative to the views parent.

Can be either a float value or a string of the width.touchEnabled boolean a boolean indicating if the view should receive touch events (true, default) or

forward them to peers (false)transform object the transformation matrix to apply to the viewvisible boolean a boolean of the visibility of the view

6 API, 10/6/10

Titanium.UI.View ClassAppcelerator Titanium API Reference

EventsEvent properties provide detail about the specific event. Note that not all properties apply to every event type.

Event Properties

width float,string Property for the view width. Can either be `auto`, a float value or a string of the width.

zIndex int the z index position relative to other sibling views; largest is topmost

Event Type When firedclick fired when the device detects a click (longer than touch) against the viewdblclick the device detects a double click against the viewdoubletap the device detects a double tap against the viewsingletap the device detects a single tap against the viewswipe the device detects a swipe (left or right) against the viewtouchcancel a touch event is interrupted by the device (for example, in circumstances such as an incoming call to

allow the UI to clean up state)touchend a touch event is completedtouchmove as soon as the device detects movement of a touch; event coordinates are always relative to the view in

which the initial touch occurredtouchstart as soon as the device detects a gesturetwofingertap the device detects a two-finger tap against the view

Event Description Triggered Event Typesdirection direction of the swipe - either left or right swipeglobalPoint a dictionary with properties x and y describing the point of the

event in screen coordinatesall

source the source object that fired the event alltype the name of the event fired allx the x point of the event, in receiving view coordinates ally the y point of the event, in receiving view coordinates all

Name Type Description

7API, 10/6/10


Methods

addAdd a child to the view hierarchy.

Arguments

Returns

void

ExamplemyView.add(anotherView);

myView.add(myTableView);

addEventListenerAdd an event listener for the instance to receive view triggered events.

Arguments

Returns

void

ExamplemyView.addEventListener('click', function(e) {

alert('Click at index: '+e.index);

});

animateAnimate the view.

Name Type Descriptionview object the view to add to this views hiearchy

Name Type Descriptionname string name of the eventcallback function callback function to invoke when the event is fired

8 API, 10/6/10


Arguments

Returns

void

ExamplemyView.animate({opacity:0,top:10,left:10,width:100,height:100,delay:150,duration:1100});

fireEventFire a synthesized event to the views listener.

Arguments

Returns

void

ExamplemyView.fireEvent('click',{index:2});

hideHide the view.

Arguments

This function takes no arguments.

Returns

void

ExamplemyView.hide();

removeRemove a previously added view from the view hiearchy.

Name Type Descriptionobj object either a dictionary of animation properties or an Animation objectcallback function function to be invoked upon completion of the animation

Name Type Descriptionname string name of the eventevent object event object

9API, 10/6/10


Arguments

Returns

void

ExamplemyView.remove(myScreen1);

removeEventListenerRemove a previously added event listener.

Arguments

Returns

void

showMake the view visible.

Arguments

This function takes no arguments.

Returns

void

ExamplemyView.show();

toImageReturn a Blob image of the rendered view.

Name Type Descriptionview object the view to remove from this views hiearchy

Name Type Descriptionname string name of the eventcallback function callback function passed in addEventListener

10 API, 10/6/10


Arguments

Returns

object

Examplevar myImage = myView.toImage();

Name Type Descriptionf function Function to be invoked upon completion. If non-null, this method will be performed

asynchronously. if null, it will be performed immediately.

11API, 10/6/10

Appcelerator Titanium API ReferenceExample Programs

Example ProgramsThe following example programs illustrate View. Each of these programs replaces your app.js file in your Resources folder. You can make changes to these programs to experiment with the View, and the related classes and methods.

• Generic Use of View on page 12

• Single Image View on page 13

• Two Image View on page 14

• Two Image Manipulation Game on page 16

Generic Use of ViewThis following code shows a generic usage of the View class. It uses a combination of three views: a container, a content view (in which we would place other UI elements), and a drop shadow view.

This app works for iPhone 4.0 and Android APIs 1.6.

// app.js

// Create a container view

var container = Titanium.UI.createView({

width:200,

height:200,

top:10,

left:10

});

// Create a drop shadow view which we will place in the lower right corner

// of the container

var shadow = Titanium.UI.createView({

width:195,

height:195,

right:0,

bottom:0,

borderRadius:5,

opacity:0.5,

backgroundColor:"#787878"

});

container.add(shadow);

// Add a view to our container. Since this view is added to the parent last

// it is z-indexed above the drop shadow view we just added.

var content = Titanium.UI.createView({

width:195,

height:195,

top:0,

left:0,

borderRadius:5,

backgroundColor:"#cdcdcd"

12 API, 10/6/10

Example ProgramsAppcelerator Titanium API Reference

});

content.add(Titanium.UI.createLabel({

text:"Here is some content",

textAlign:"center",

color:"#000"

}));

container.add(content);

// Add it to a window, then open our app’s main window

var win = Titanium.UI.createWindow({

backgroundColor:"#fff"

});

win.add(container);

win.open();

Single Image ViewThis is a minimal program that demonstrates a view. This app works for iPhone 4.0 and Android APIs 1.6.

// app.js

// Create a container view for the image

var container = Titanium.UI.createView({

Generic Views, for iPhone

Generic Views, for Android

13API, 10/6/10


width:100,

height:100,

top:10,

left:10,

backgroundColor:"#2aaaad",

backgroundImage:"myphoto1.jpg"

});

// Create a window

var myWindow = Titanium.UI.createWindow({


});

// Add the image to the window and open it

myWindow.add(container);

myWindow.open();

Two Image ViewThis example shows how you can add two views to a window. Each view uses a JPEG as a background image. This program assumes that you have two image files named myphoto1.jpg and myphoto2.jpg in your Resources directory. (This is the same directory where your app.js is located.)

This app works for iPhone 4.0 and Android APIs 1.6.

Single Image View, for iPhone

Single Image View, for Android

14 API, 10/6/10


// app.js

// Create container views for each image

var container1 = Titanium.UI.createView({

width:100,

height:100,

top:10,

left:10,



});

var container2 = Titanium.UI.createView({

width:100,

height:100,

top:10,

left:200,



});

// Create a window

var myWindow = Titanium.UI.createWindow({


});

//Add the images to the window and open

myWindow.add(container1);

myWindow.add(container2);

myWindow.open();

15API, 10/6/10


Two Image Manipulation GameThis example uses several View methods (addEventlistener, animate, hide) to manipulate two images in a sim-ple game called 2 Pic Monte. We also change some of the image properties as we shuffle them. The game can easily be enhanced by adding logic and more images. Two image files are used: myphoto1.jpg and myphoto2.jpg. Read the comments for more details.

This app works for iPhone 4.0.

// app.js

// 2 Pic Monte

// Simple example of manipulating two images using views inside a window.

//

// Instructions: Using an image, create duplicates named mypic1.jpg and mypic2.jpg.

// Put some type of mark on pic 2 so you can identify it but other players cannot.

// Launch the app and have players try to choose the image that has the mark.

// For this example, the images are the same except pic 1 is color and pic 2 is

// grayscale. Pick grayscale (pic 2) and you're always the winner.

// Initialize variables to be used with positioning and scoring

Two Image View, for iPhone

Two Image View, for Android

16 API, 10/6/10


var left1 = 10;

var left2 = 200;

var numberLost = 0;

var numberTries = 0;

// Create views for each image

var view1 = Titanium.UI.createView({

width:100,

height:100,

top:10,

left:left1,

backgroundImage:"pic1.jpg"

});

var view2 = Titanium.UI.createView({

width:100,

height:100,

top:10,

left:left2,

backgroundImage:"pic2.jpg"

});

// Add instructions using another view with a gray background

var instructions = Titanium.UI.createView({

width:100,

height:230,

top:200,

left:125,

backgroundColor:"#a1adad"

});

// ... and here is the label with the instructions

instructions.add(Titanium.UI.createLabel({

text:"2 Pic Monte. Click the correct pic and you're a winner!",

textAlign:"center",

color:"#000411"

}));

// Create a window to hold the 2 images and the instructions

var win = Titanium.UI.createWindow({

fullscreen:false,


});

// Add the views to the window and open

win.add(view1);

win.add(view2);

win.add(instructions);

win.open();

17API, 10/6/10


// Add an event listener to move the images with animation, and keep score

view1.addEventListener('click', function() {

// Simple score-keeping

numberLost = numberLost+1;

numberTries = numberTries+1;

// Shuffle first -- the "shuffling" is pretty simple

for (i=0; i<=4; i++) {

// Logic to determine if images have been switched

// Change some of the properties during animation

if (left1 == 10) {

left1 = 200;

left2 = 10;

myDuration = 200;

myDelay = 300;

myOpacity = 20;

}

else {

left1 = 10;

left2 = 200;

myDuration = 1200;

myDelay = 200;

myOpacity = 0;

}

if (i == 4) {

myOpacity = 100;

}

// Assemble a "you didn't win yet" message, and display an alert

if (i == 0) {

if (numberTries == 1) {

myMessageText = "You lose. You've tried "+numberTries+" time.";

}

else {

myMessageText = "You lose. You've tried "+numberTries+" times.";

}

}

else {

myMessageText = "Keep clicking OK while I reshuffle and distract you.";

}

Titanium.UI.createAlertDialog({

title:'Alert',

message:myMessageText

}).show();

// switch images for view 1

view1.animate({

18 API, 10/6/10


opacity:myOpacity,

top:10,

left:left1,

width:100,

height:100,

delay:myDelay,

duration:myDuration

});

// switch images for view 2

view2.animate({

opacity:myOpacity,

top:10,

left:left2,

width:100,

height:100,

delay:myDelay,

duration:myDuration

});

}

});

// This function gets called when the user clicks on the winning image.

// The non-winning image is hidden, the instructions disappear, and the winning

// message is displayed along with the score.

function winner () {

view1.hide();

win.remove(instructions);

// You can add some logic here to increase functionality

// (e.g., return to initial view).

Titanium.UI.createAlertDialog({

title:'Alert',

message:"You're a winner! Score: "+100*(numberTries-numberLost)/numberTries+" %"

}).show();

}

// This event listener monitors clicks on the 2nd image, which is the winning image.

// The image is exapnded with an animation, and then the winning message is displayed.

view2.addEventListener('click',function() {

numberTries = numberTries+1;

view2.animate({

opacity:100,

top:10,

left:40,

delay:0,

width:250,

height:400,

19API, 10/6/10


duration:3000

}, winner);

});

Screenshots of the 2 Pic Monte app, for iPhone

20 API, 10/6/10


Revision History

10/06/2010 Initial release

21API, 10/6/10


22 API, 10/6/10

Documents

Titanium Mobile: API Reference - Amazon Web Servicesassets.appcelerator.com.s3.amazonaws.com/docs/API_UIViewClass.pdf · Titanium.UI.View Class 7 Appcelerator Titanium API Reference