Titanium.UI.View Class API

Transcription

1 Titanium Mobile: API Reference Titanium.UI.View Class API October 6, 2010

2 Copyright 2010 Appcelerator, Inc. All rights reserved. Appcelerator, Inc. 444 Castro Street, Suite 818, Mountain View, California No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Appcelerator, Inc., with the following exceptions: Any person 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

3 Contents Contents Overview... 5 Titanium.UI.View Class... 6 Instance Methods Summary...6 Object Properties...6 Events...7 Event Properties...7 Methods...8 Example Programs Generic Use of View...12 Single Image View...13 Two Image View...14 Two Image Manipulation Game...16 API, 10/6/10 3

4 Contents Appcelerator Titanium API Reference 4 API, 10/6/10

5 Overview Overview A 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 similarities. 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-bysize, 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. API, 10/6/10 5

6 Titanium.UI.View Class Appcelerator Titanium API Reference Titanium.UI.View Class The View is an empty drawing surface or container. The View is created by the Titanium.UI.createView method. Instance Methods Summary Name add addeventlistener animate fireevent hide remove removeeventlistener show toimage Description add a child to the view hierarchy add an event listener for the instance to receive view triggered events animate the view fire a synthesized event to the views listener hide the view remove a previously added view from the view hiearchy remove a previously added event listener make the view visible return a Blob image of the rendered view Object Properties Name Type Description anchorpoint 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 animation backgroundcolor string the background color of the table view backgroundgradient 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 view bordercolor string the border color of the view borderradius float the border radius of the view borderwidth float the border width of the view bottom float, string Property for the view bottom position. This position is relative to the views parent. 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 view height 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 right 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 properties top 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 view visible boolean a boolean of the visibility of the view 6 API, 10/6/10

7 Titanium.UI.View Class Name Type Description 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 Events Event properties provide detail about the specific event. Note that not all properties apply to every event type. Event Type click dblclick doubletap singletap swipe touchcancel touchend touchmove touchstart twofingertap When fired fired when the device detects a click (longer than touch) against the view the device detects a double click against the view the device detects a double tap against the view the device detects a single tap against the view the device detects a swipe (left or right) against the view 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) a touch event is completed as soon as the device detects movement of a touch; event coordinates are always relative to the view in which the initial touch occurred as soon as the device detects a gesture the device detects a two-finger tap against the view Event Properties Event Description Triggered Event Types direction direction of the swipe - either left or right swipe globalpoint a dictionary with properties x and y describing the point of the all event in screen coordinates source the source object that fired the event all type the name of the event fired all x the x point of the event, in receiving view coordinates all y the y point of the event, in receiving view coordinates all API, 10/6/10 7

8 Titanium.UI.View Class Appcelerator Titanium API Reference Methods add Add a child to the view hierarchy. Arguments Name Type Description view object the view to add to this views hiearchy Returns void Example myview.add(anotherview); myview.add(mytableview); addeventlistener Add an event listener for the instance to receive view triggered events. Arguments Name Type Description name string name of the event callback function callback function to invoke when the event is fired Returns void Example myview.addeventlistener('click', function(e) { alert('click at index: '+e.index); animate Animate the view. 8 API, 10/6/10

9 Titanium.UI.View Class Arguments Name Type Description obj object either a dictionary of animation properties or an Animation object callback function function to be invoked upon completion of the animation Returns void Example myview.animate({opacity:0,top:10,left:10,width:100,height:100,delay:150,duration:1100 fireevent Fire a synthesized event to the views listener. Arguments Name Type Description name string name of the event event object event object Returns void Example myview.fireevent('click',{index:2 hide Hide the view. Arguments This function takes no arguments. Returns void Example myview.hide(); remove Remove a previously added view from the view hiearchy. API, 10/6/10 9

10 Titanium.UI.View Class Appcelerator Titanium API Reference Arguments Name Type Description view object the view to remove from this views hiearchy Returns void Example myview.remove(myscreen1); removeeventlistener Remove a previously added event listener. Arguments Name Type Description name string name of the event callback function callback function passed in addeventlistener Returns void show Make the view visible. Arguments This function takes no arguments. Returns void Example myview.show(); toimage Return a Blob image of the rendered view. 10 API, 10/6/10

11 Titanium.UI.View Class Arguments Name Type Description f function Function to be invoked upon completion. If non-null, this method will be performed asynchronously. if null, it will be performed immediately. Returns object Example var myimage = myview.toimage(); API, 10/6/10 11

12 Example Programs Appcelerator Titanium API Reference Example Programs The 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 View This 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

13 Example Programs 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(); Generic Views, for Android Generic Views, for iphone Single Image View This 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({ API, 10/6/10 13

14 Example Programs Appcelerator Titanium API Reference width:100, height:100, top:10, left:10, backgroundcolor:"#2aaaad", backgroundimage:"myphoto1.jpg" // Create a window var mywindow = Titanium.UI.createWindow({ backgroundcolor:"#fff" // Add the image to the window and open it mywindow.add(container); mywindow.open(); Single Image View, for Android Single Image View, for iphone Two Image View This 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 API, 10/6/10

15 Example Programs // app.js // Create container views for each image var container1 = Titanium.UI.createView({ width:100, height:100, top:10, left:10, backgroundcolor:"#2aaaad", backgroundimage:"myphoto1.jpg" var container2 = Titanium.UI.createView({ width:100, height:100, top:10, left:200, backgroundcolor:"#2aaaad", backgroundimage:"myphoto2.jpg" // Create a window var mywindow = Titanium.UI.createWindow({ backgroundcolor:"#fff" //Add the images to the window and open mywindow.add(container1); mywindow.add(container2); mywindow.open(); API, 10/6/10 15

16 Example Programs Appcelerator Titanium API Reference Two Image View, for Android Two Image View, for iphone Two Image Manipulation Game This example uses several View methods (addeventlistener, animate, hide) to manipulate two images in a simple 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 16 API, 10/6/10

17 Example Programs 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, backgroundcolor:"#fff" // Add the views to the window and open win.add(view1); win.add(view2); win.add(instructions); win.open(); API, 10/6/10 17

18 Example Programs Appcelerator Titanium API Reference // 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

19 Example Programs 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, API, 10/6/10 19

20 Example Programs Appcelerator Titanium API Reference duration:3000 }, winner); Screenshots of the 2 Pic Monte app, for iphone 20 API, 10/6/10

21 Revision History 10/06/2010 Initial release API, 10/6/10 21

22 22 API, 10/6/10