Coronaâ„¢ SDK 2.0 Beta Guide - Corona Developer Portal

June 9, 2010 | © 2009 Ansca Inc. All Rights Reserved. 1

Corona™ SDK2.0 Beta Guide

Ansca Inc. © 2010 Ansca Inc. All rights reserved.

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 Ansca 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 Ansca’s copyright notice.

The Ansca logo is a trademark of Ansca Inc.

No licenses, express or implied, are granted with respect to any of the technology described in this document. Ansca retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications using Ansca software. Every effort has been made to ensure that the information in this document is accurate. Ansca is not responsible for typographical errors.

Even though Ansca has reviewed this document, ANSCA 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 ANSCA 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 Ansca dealer, agent, or employee is authorized to make any modi"cation, 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 speci"c legal rights, and you may also have other rights which vary from state to state.

Lua 5.1 Copyright © 1994-2008 Lua.org, PUC-Rio.

iPhone™, App Store™ and Mac OS® are trademarks of Apple, Inc.

OpenGL® ES is a trademark of Khronos Group.

Photoshop® and Illustrator® are registered trademarks of Adobe, Inc.

Ansca™, Corona™ and Corona SDK™ are trademark of Ansca, Inc.

lsqlite3: Copyright (C) 2002-2007 Tiago Dionizio, Doug Currie All rights reserved. Author: Tiago Dionizio <[email protected]> Author: Doug Currie <[email protected]> Library: lsqlite3 - a SQLite 3 database binding for Lua 5 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation "les (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


mailto:[email protected]




Contents

Preface 6

What’s New In Beta 5? 6

What’s New In Beta 4? 6

A Note About Beta 3 and Multitouch 6

A Note About Android 1.5 versus 1.6 7

Limitations 7

See Also 7

Simulator 8

Cross-Platform Development 8

iPad 9

Android 10

Device Builds 10

Signing Your App 11

Application Icons 12

Installing Your App 12

Additional Notes 12

Differences Between Android and iPhone Features 13

Graphics and Drawing 14

Polylines (all platforms) 14

Movieclips (all platforms) 14

Movieclip functions 15


Differences between movieclips and sprite sheets 18

Image Autoscaling Override 18

User Interface 20

Multitouch (iPhone/iPad) 20

New Keyboard Types (iPhone/iPad) 20

Improved Webpopups (iPhone/iPad) 21

Application Con!guration Options 22

Dynamic Content Scaling (all platforms) 22

Runtime Con"guration: con"g.lua 22

Build Con"guration: build.settings 23

Info.plist Values (iPhone/iPad) 24

Orientation Support (iPhone/iPad) 25

Auto-rotation 25

Landscape orientation 26

Orientation of native UI only 26

Orientation naming conventions 27

Detecting current device orientation 28

Orientation Support (Android) 28

Version Code (Android) 29

Application Permissions (Android) 29

Data Storage 30

SQLite (all platforms) 30

Improved Sound API (all platforms) 31

Completion listener 31

Loop parameter 31


Event sound completion listener 31

Volume control 32

Revision History 33


Preface

Welcome to the Corona™ SDK 2.0 beta!

This document highlights the features added to Corona since the 1.1 release in February 2010. It is a work in progress, and will be merged with the general Corona documentation. For overall Corona information, see the other documents included with this release.

Corona SDK 2.0 adds support for iPad and Android development, including new Simulators for the iPad, the Motorola Droid, the HTC Nexus One and the older HTC myTouch.

Also, since all new Corona features and bug !xes are now being delivered via the betas, we recommend using the current beta release, rather than Corona 1.1, for iPhone production work.

What’s New In Beta 5?

For the most important additions to Beta 5, see the “Build Con!guration” section, which now includes new Android features like orientation and GPS support, new bug !xes for iPhone, and new custom-build settings.

What’s New In Beta 4?

If you are already familiar with Corona SDK 2.0 Beta 3 and earlier, the most important sections to read for Beta 4 are “Orientation Support” and “Improved Sound API”.

A Note About Beta 3 and Multitouch

Multitouch behavior changed between Beta 3 and Beta 4, speci!cally in the area of handling simultaneous single touches to multiple objects (such as buttons).

In Beta 4 and 5, an object with focus traps all further touches until it loses focus. This is the behavior you want when detecting gestures on a single object, but not the behavior you want when trying to read multiple button presses in different objects at the same time, such as in a simultaneous multiplayer game.

We are working on supporting both cases in a uni!ed way, but in the meantime, developers with Beta 3-based projects that require the old multi-button behavior can continue to make device builds in Beta 3 code by using the following parameter in a build.settings !le:

settings = { build = { custom = "4832a99408fe61baaaae747262977616"


}}

This setting is temporary, and we recommend only using it when absolutely necessary, since it also means that none of the bug !xes or features in Beta 4 or 5 will be present in your build.

See the Application Con!guration Options section of this document for more information on build.settings syntax.

A Note About Android 1.5 versus 1.6

Currently, Android 1.6 is supported in Corona via Android 1.5 builds. However, there are a number of important differences between 1.5 and 1.6.

According to the Android SDK, the OpenGL ES 1.x Library was introduced in Android 1.6, not 1.5. Furthermore, it includes the following warnings:

• OpenGL ES 1.1 is fully supported only on speci!c devices that have a compatible GPU.

• OpenGL ES 1.0 is supported on all Android-based devices, because Android comes with a 1.0-capable software renderer that can be used on non-GPU devices.

In our experience, Corona builds in Android 1.5 generally seem to work, despite these warnings, but may encounter unimplemented OpenGL features, and early 1.5 devices may lack GPU hardware entirely. For these reasons, graphics performance may be poor, and we invite feedback as to whether Corona features work sufficiently well on Android 1.5 devices to continue this support.

We will also be adding a speci!c Android 1.6 build option to help address these issues, since 1.6 offers better performance and appears to be the lowest version of Android currently shipping with new devices (such as the Sony Xperia X10).

Limitations

Currently, the iPhone/iPad features are not fully implemented for Android, although they are converging with each release. See the Android section for further details.

See Also

• For details of the features and bug !xes added in each release, see the release notes page: http://developer.anscamobile.com/downloads/beta (user registration required).

• For the ongoing Corona development roadmap, see http://www.anscamobile.com/corona/roadmap


http://developer.anscamobile.com/downloads/beta

http://developer.anscamobile.com/downloads/beta

http://www.anscamobile.com/corona/roadmap




Simulator

The Corona Simulator now includes the ability to simulate iPad and Android apps, along with iPhone apps. The Simulator will also produce device builds for all supported platforms.

While building for iPhone/iPad requires Apple’s iPhone SDK, you do not need to install the Android SDK to build for Android.

Cross-Platform Development

The File > Open dialog allows you to choose the initial device to simulate:

Similarly, the File > Open for Build dialog contains new platform options:

Finally, new menu options have been added to switch device views, and to zoom in and out. Allowed magni!cations are 100%, 50%, 25% and 12.5%.


iPad

The iPad Simulator is very large at its native size, and on most monitors will open at 50% magni!cation by default.

Note that the physical size of the iPad will generally be larger than the Simulator at 50% and smaller than the Simulator at 100%. Take this into account when designing your interfaces, and test your applications frequently on a real iPad.

In general, iPad development is quite similar to iPhone development. If you have already done Corona development for iPhone, then you can jump into iPad development immediately.

Also, the device build process is exactly the same: for example, the same Provisioning Pro!les are used for testing. See the Corona Device Build Guide for instructions on compiling and installing on iPhoneOS devices, and also see the “Improved Orientation Support” section of this document for a discussion of the speci!c orientation demands of the iPad App Store.


Android

The Android simulators are also quite large at native size, and on most monitors will open at 50% magni!cation by default.

Note that the physical screen size of current Android devices are roughly the same as the iPhone, despite the higher pixel resolution. In other words, the Android simulators may appear misleadingly large at 100% magni!cation. Take this into account when designing your interfaces, and test your applications on your target devices whenever possible.

Device Builds

Select Open for Build from the File menu, and choose "Android" as the platform at the bottom of the dialog. This generates a standard .apk !le. The build process is a little slower than for iPhone, as it is more complex internally.

Note we have greatly simpli!ed the Android build process, as compared to the Android SDK. In particular, you do not need to install the Android SDK! Also, you do not need to use jarsigner or zipalign.

However, you do need to provide a suitable certi!cate for signing. See below for details.

Currently, we support Android 2.0.1, which should be fully compatible with 2.1; we also support Android 1.5 builds, due to the large number of Android devices still running older OS versions.


Your package name can be anything you like, but it must be chosen carefully, because it should be unique to your application. The traditional Java scheme is to use the reverse of your domain name, e.g. "com.acme", then append the name of a division or product line, and then possibly append the name of a speci!c app. For example, "com.acme.games.catcha!sh" would be a good package name, assuming you owned the "acme.com" domain name.

Signing Your App

In order to Build for Android Device, you will need to sign your application using a different signing process than you use for iPhone.

For debug builds, you may use a developer key. The Corona SDK includes a !le named "debug.keystore", in the Resource Library directory, which you can use to test your apps. This !le contains the following standard Android debug key:

Keystore name: "debug.keystore"Keystore password: "android"Key alias: "androiddebugkey"Key password: "android"CN: "CN=Android Debug,O=Android,C=US"

However, for release builds, you must sign with your private key. You can generate this key using the command line program Keytool. See the Android documentation for details.

For further information, please review the Android documentation available at: http://developer.android.com/intl/de/guide/publishing/app-signing.html


http://developer.android.com/intl/de/guide/publishing/app-signing.html




Application Icons

Icon !les named “Icon-hdpi.png”, “Icon-mdpi.png”, and “Icon-ldpi.png” will be copied into the .apk during the build, if they are available in your project folder. These icons should be created in the standard Android icon sizes (72x72, 48x48, 36x36) and follow the Android Icon Design Guidelines, which are available at http://developer.android.com/intl/de/guide/practices/ui_guidelines/icon_design.html.

Installing Your App

Method 1: if you have already installed the Android SDK, use "adb install <your-app>.apk".

Method 2: Upload the apk to a web server. Point your Android device's web browser at the !le’s URL to download the APK to your phone. Finally, click on the !le in the Download History to install it on the phone.

If Method 2 fails, and the phone downloads the application as a text!le instead, you may need to add the following con!guration line to an .htaccess !le in the application’s directory on the web server:

AddType application/vnd.android.package-archive .apk

Also, you should set your device to install non-Market applications if you are using debug.keystore. Click the Settings icon on the device, then click "Applications", then check the box next to "Unknown Sources".

Note: to reinstall an app, you may !rst have to uninstall the previous version of the app. To do this, Click the Settings icon on the device, then choose "Applications", then "Manage Applications", then scroll to the application you wish to uninstall, click on it, and press the "Uninstall" button on the next screen.

Additional Notes

You can use our provided "debug.keystore" for testing, if you have not generated your own. The password is "android". However, for shipping an app to the Android Marketplace, you must use your own keystore.

Android devices have higher resolution than iPhone, and slightly different resolutions among themselves. The Nexus One is 480x800, and the Droid is 480x854. Use the "Zoom Out" feature to shrink the Simulator for smaller displays.

Many Android 1.5 phones have no $oating point unit and a much slower processor, so some animations may not run well on older Android devices. We will also be adding the ability to target Android 1.6 speci!cally, since 1.5 lacks full OpenGL ES 1.1 support.


http://developer.android.com/intl/de/guide/practices/ui_guidelines/icon_design.html




Android does not support the same !le formats as iPhone. For example, .caf sound !les will not work. We suggest converting them to .mp3 or .ogg. One option to convert them is the SoundConverter utility. .JET audio is not supported yet.

The status bar is not supported on Android. Currently we set all apps to full screen.

Android applications do not use “Default.png” splash screens, or any equivalent; this is a convention of the iPhoneOS.

Differences Between Android and iPhone Features

The Corona SDK for Android was originally based on the Corona 1.0 code base, with 1.1 and 2.0 features being added over time. This means that a number of newer features and bug !xes may not be available.

Recently added Android features include Compass (aka “heading” events), GPS support, landscape support, and native font listings via native.getFontNames(). However, the following items are not yet implemented for Android:

• Orientation events

• Camera

• Network

• Multiline text !elds

• Text input with keyboard

• Webpopups


Graphics and Drawing

Polylines (all platforms)

The Polylines API draws connected line segments, with any color and stroke width, using the Corona vector engine. The resulting object is a standard Corona display object, and can be independently moved and scaled like any other display object. The stroke and color properties can also be changed after the object has been drawn.

Polylines are a series of vertices specifying endpoints of line segments. The lines have a stroke width, speci!ed in a "width" parameter. Currently, multiple line segments have miter joins. In other words, an angle joint comes to a point, as opposed to being rounded. The start and end have butt caps.

(This API is under development, and may evolve.)

The current API is as follows:

local a = display.newLine( [parent,] x1,y1, x2,y2 )

a:setColor( r, g, b, a )

a:append( x, y [,... ] )

a.width = strokeWidth

Code example:

local star = display.newLine( 0,-110, 27,-35 )star:append( 105,-35, 43,16, 65,90, 0,45, -65,90, -43,15, -105,-35, -27,-35, 0,-110 )star:setColor( 255, 102, 102, 255 )star.width = 3

See the Graphics/PolyLines sample code for an animated demo that runs on iPhone and iPad.

Movieclips (all platforms)

The external movieclip library allows you to create animated sprites (sometimes called “movieclips”) from sequences of images, which can then be moved around the screen using


the same techniques as any other Corona display object. Functions are available to play these animation frames, or partial sequences of these frames, in either the forward or reverse direction; to jump to speci!ed frames; to skip to the next or previous frame; to automatically delete the animation on completion of a sequence; and to make the animation draggable, complete with press, drag, and release events.

This framework provides an quick and lightweight way to create animations, and also helps when porting existing Flash content to Corona.

The movieclip library is an external module, movieclip.lua, that can be included with your projects and loaded using the require command (see the Module section of the API Reference for further details on require).

Note that while this library is based on the older “sprite” library, the library name has been changed to “movieclip” , because the name “sprite” is now reserved for the upcoming sprite-sheet feature in Corona Game Edition. A discussion of the differences is below.

For a sample project using the previous movieclip library, see the Graphics/Movieclip project in the Sample Code directory of the Corona SDK, or download the latest version from this page:

http://developer.anscamobile.com/sample-code/graphics

This line makes the movieclip features available under the “movieclip” namespace:

local movieclip = require "movieclip"

Movieclip functions

movieclip.newAnim( frames )Creates an animated sprite using an array of image !lenames provided in the frames table:

myAnim = movieclip.newAnim{ "img1.png", "img2.png", "img3.png", "img4.png" }

object:play()Starts the animated sprite playing in the forward direction. When the end of the image set is reached, it will cycle back to the !rst image and continue playing. If a speci!c frame sequence has already been constructed, calling play() with no parameters will simply resume playing within that sequence.

object:play{ startFrame=a, endFrame=b, loop=c, remove=shouldRemove } Starts the animated sprite playing in the forward direction. When the frame of number given by “endFrame” is reached, it will cycle back to the frame number given by “startFrame” and continue playing.

myAnim:play{ startFrame=1, endFrame=6, loop=3, remove=true }


The “loop” parameter accepts a number of times to loop the sequence, with zero (the default) indicating that it should loop forever.

The “remove” parameter is a boolean $ag, and if set to “true”, the movieclip will automatically delete itself when the given sequence is complete. This is useful for things like animated explosions and other single-use cases. Note that the object will only be garbage-collected if there are no other remaining references to it in your Lua code. The default value is “false”.

All parameters are optional, but startFrame and endFrame will default to the !rst and last images provided in newAnim(), so it is a good practice to provide both values explicitly to avoid unexpected behavior.

Passing any parameters to play() indicates that a new sequence should be constructed, and any current sequence information will be reset. Call play() with no parameters if you simply want to resume the current sequence.

object:reverse()Starts the animated sprite playing in the reverse direction. When the beginning of the image set is reached, it will cycle back to the last image and continue playing backwards. If a speci!c frame sequence has already been constructed, calling reverse() with no parameters will simply resume playing backwards within that sequence.

object:reverse{ startFrame=a, endFrame=b, loop=c, remove=shouldRemove } Starts the animated sprite playing in the reverse direction. When the frame of number given by “endFrame” is reached, it will cycle back to the frame number given by “startFrame” and continue playing.

The “loop” parameter accepts a number of times to loop the sequence, with zero (the default) indicating that it should loop forever.

The “remove” parameter is a boolean $ag, and if set to “true”, the movieclip will automatically delete itself when the given sequence is complete. This is useful for things like animated explosions and other single-use cases. Note that the object will only be garbage-collected if there are no other remaining references to it in your Lua code. The default value is “false”.

All parameters are optional, but startFrame and endFrame will default to the last and !rst images provided in newAnim(), so it is a good practice to always provide both values explicitly to avoid unexpected behavior.

Passing any parameters to reverse() indicates that a new sequence should be constructed, and any current sequence information will be reset. Call reverse() with no parameters if you simply want to resume the current sequence.

object:nextFrame()Resets any animation sequence in progress, moves the animation to the next image in the total sequence, and stops. This can be used with a two-frame movieclip to make an image toggle between two states

object:previousFrame()Resets any animation sequence in progress, moves the animation to the previous image in the total sequence, and stops.


object:currentFrame()Returns the numerical index of the current frame.

object:totalFrames()Returns the total number of frames in the animated sprite.

object:stop()Stops the animation of the sprite at its current frame.

object:stopAtFrame( frame )Jumps the animation to the speci!ed frame, given either as a frame number or by an optional frame label (see setLabels function below).

Note: to perform the equivalent of a “go to and play” from a speci!ed frame, simply issue a stopAtFrame command followed by a play or reverse command. Both commands will execute before the display updates again, and so the transition will be immediate:

myAnim:stopAtFrame(4)myAnim:play()

myAnim:stopAtFrame("label")myAnim:reverse()

object:setLabels( labels )Adds optional labels to an Anim object previously created, using a table to assign label names to selected frame numbers:

myAnim:setLabels{ firstLabel=1, anotherLabel=3 }

object:setDragTurns any movieclip into a draggable object when “drag” is set as true. The “limitX” and “limitY” parameters limit the dragging to either the x or y axis, and the “bounds” parameter can be used to specify drag boundaries for the object.

The “onPress”, “onDrag” and “onRelease” parameters take the names of functions to be called when those events occur. All parameters are optional.

myAnim:setDrag{ drag=true, limitX=false, limitY=false, onPress=myPressFunction, onDrag=myDragFunction, onRelease=myReleaseFunction, bounds={ 10, 10, 200, 50 } }

To turn off the draggable property again, set “drag” to false:

myAnim:setDrag{ drag=false }


Note that the examples above with curly brackets are using the Lua “shorthand” notation for passing a table of named values directly to a function. In other words, the function is actually receiving a single value that happens to be a Lua table, like this: function( { values } ). The shorthand notation allows the outer parentheses to be eliminated, to make the code more readable.

Differences between movieclips and sprite sheets

The upcoming Corona Game Edition will include a “sprite sheet” feature for constructing animated sprites by copying rectangular areas from a single large texture in memory.

Sprite sheets are a much more efficient use of texture memory, since OpenGL-ES allocates all textures in dimensions equal to the next power-of-two, no matter what the size of the source image is. For example, a single image with dimensions of 80x300 will require a texture memory allocation of 128x512 pixels.

Therefore, sprite sheets are recommended for complex character animation, or any case in which there are a large number of animation states.

However, sprite sheets will require more coding and are more complex to set up; for example, you must !rst construct a large sheet of animation frames. The movieclip library is easier to get started with, and can be more rapidly used to port Flash content, since movieclip frames can be exported from Flash as PNG sequences.

Image Autoscaling Override

The default behavior of display.newImage() is to auto-scale large images. This is to conserve texture memory. However, there are times when you do not want to have images auto-scaled. We have added an additional boolean $ag to the parameter list to enable you to control this:

To show the image at its full-resolution, use the optional isFullResolution parameter. By default, it is false, but if you specify true, then the new image is loaded at its full resolution:

display.newImage( [parentGroup,] !lename [, baseDirectory] [, x, y] [,isFullResolution] )

myImage = display.newImage( “image.png”, 10, 20, true )

Limitations:

• Images will still be autoscaled if they are larger than the maximum possible texture dimensions of the device. This is usually 1024x1024 (iPhone 3G) or 2048x2048 (iPhone 3GS, iPad).

• If you reload the same image multiple times, the subsequent calls to display.newImage ignore the isFullResolution parameter and take on the value passed the !rst time. In other words, the way you load an image !le the !rst time affects the auto-scaling setting the next time you load that same !le. This is because Corona conserves texture memory by


automatically re-using a texture that has already been loaded. As a result, you can use the same images as many times as you want without consuming additional texture memory.


User Interface

Multitouch (iPhone/iPad)

All versions of the Corona 2.0 beta support multitouch events. See the Multitouch sample code in the iPad sample code directory for an example of how to implement a pinch/zoom gesture.

We intend to provide additional framework libraries to make gesture recognition easier, but we encourage you to experiment with multitouch in the meantime.

Also see “A Note About Beta 3 and Multitouch” in the Preface section of this document to learn how to temporarily restore Beta 3 behavior in the newer SDKs.

New Keyboard Types (iPhone/iPad)

Five iPhoneOS keyboard types are now supported in the input text!eld, using a new property named "inputType". This property is optional. See the Interface/NativeKeyboard sample code for a demo of the various available types.

Example:

numericField = native.newTextField( 50, 150, 220, 36, handlerFunction )numericField.inputType = "number"

The !ve possible values for the “inputType” property are:

"default" - the default keyboard, supporting general text, numbers and punctuation

"number" - a numeric keypad

"phone" - a keypad for entering phone numbers

"url" - a keyboard for entering website URLs

"email" - a keyboard for entering email addresses

As before, you can set the “isSecure” boolean to create a password-entry !eld:

passwordField.isSecure = true


Improved Webpopups (iPhone/iPad)

Webpopups (embedded WebKit views) can now occupy any part of the screen, in addition to the previous full-screen mode. The boundaries of the webpopup are given in four optional numerical parameters. See the API Reference for more information on webpopups.

native.showWebPopup( 10, 10, 300, 300, "http://www.anscamobile.com", {urlRequest=listener} )

As before, the optional “urlRequest” parameter provides a function that should intercept any URL requests coming from the webpopup. This is a standard method for passing information back from the web using pseudo-URLs. For example, the Social/Facebook sample code receives a successful Facebook Connect event by detecting a pseudo-URL of “fbconnect:success”.

Note: As of Beta 5, landscape-oriented webpopups should work as expected.


http://www.anscamobile.com

http://www.anscamobile.com

Application Con!guration Options

Dynamic Content Scaling (all platforms)

The basic idea behind dynamic content scaling is that you can tell Corona that your content was originally authored for a particular screen size; we call this the virtual screen size. Then you can specify how your app should be scaled if it runs on a device whose physical screen size is different from the original.

To activate dynamic content scaling, create a config.lua !le (see next section) and use a scale other than "none"

The content width and height allow you to choose a virtual screen size that is independent of the physical device screen size. You are then free to code as if you are positioning objects to the virtual screen. Touch events (and other hit events) will be remapped to the correct location on the virtual screen when dynamic content scaling is active.

These virtual (i.e., content) dimensions are accessible via display.contentWidth and display.contentHeight. Because of this, the concept of stage width and height, e.g., display.stageWidth and display.stageHeight, has been deprecated in favor of content width and height. You will receive a warning in Corona Terminal if you use these older properties.

By default, the content width and height will be the same as the physical screen width and height of the device. If you are specify a different content width and height in con!g.lua (see next section), the content width and height will take on those values.

When a scale is set in con!g.lua, the content will be rescaled to !t the screen. As far as your code is concerned, however, positions should still be speci!ed in terms of virtual screen coordinates.

For example, in the Fishies sample code (SampleCode/iPhone/Graphics/Fishies in the Beta dmg), there is a con!g.lua in which the content width is 320, the height is 480, and the scale is "zoomEven". If you were to view this in iPad, all the content (the background image and the images of the !sh) would be scaled to !t the iPad's screen size (1024x768) even though the images were intended for the smaller iPhone screen (320x480).

Depending on which dynamic scaling mode is used, and the aspect ratio of the device used to view the content, some of the original content may be scaled in such a way that portions are offscreen. Therefore, display.viewableContentWidth and display.viewableContentHeight have been provided. These properties give you the currently viewable area of the screen, within the coordinate system of the original content. The Fishies sample leverages this so that the !sh continue to swim only on the visible portions of the virtual screen.

Runtime Con!guration: con!g.lua

Runtime properties can be speci!ed in a con!g.lua !le. These include content scaling features for multi-screen development.


Example:

application = { content = { width = 320, height = 480, scale = "zoomEven" },}

The key-value pairs in "application" are:

Key Value

content (optional) A table containing the following key-value pairs:

width (number) width in pixels

height (number) height in pixels

scale (string) speci!es the kind of dynamic auto-scaling done:

The "scale" property can be one of:

"none" - turns off dynamic content scaling

"zoomEven" - uniformly scales up content to !ll screen preserving aspect ratio. Some content may appear offscreen

"zoomStretch" - non-uniformly scales up content to !ll screen.

"letterbox" - uniformly scales up content as much as possible, but still showing all content on the screen.

Build Con!guration: build.settings

Build-time properties can be provided in an optional build.settings !le, which uses Lua syntax. An example of a build.settings !le:


settings ={ orientation = { default = "portrait", },

iphone = { plist = { UIRequiredDeviceCapabilities = "magnetometer", UIPrerenderedIcon = true, },

},

build = { custom = "a1234", }}

The build.settings !le is used to set application orientation and auto-rotation behavior, along with a variety of platform-speci!c build parameters.

In addition, there is a custom build parameter for creating device builds with speci!c test versions of Corona. Currently, the only publicly available option is the temporary Beta 3 compatibility setting discussed in the Preface to this document.

Info.plist Values (iPhone/iPad)

Within build.settings, the optional “plist” table, within the “iphone” table (as shown above), can be used to set values in the compiled application’s Info.plist !le.

This has a number of uses, such as specifying device requirements or capabilities for the App Store. In the above example, the UIRequiredDeviceCapabilities key is set to “magnetometer”, which is required for apps using the Compass API to indicate to the App Store that they require devices with a compass. Also, the UIPrenderedIcon key is set to true, which prevents the iPhoneOS from adding the “shiny” highlight to the application icon.

• For boolean values in Info.plist keys, use Lua-style booleans (true and false, without quotes) rather than Objective-C booleans (“YES” and “NO”).

• The table name “iphone” refers to the iPhoneOS platform, (recently renamed iOS) which also includes the iPad.

See http://developer.apple.com/iphone/library/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html for more information on supported Info.plist values and what you can do with them.


http://developer.apple.com/iphone/library/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html




Orientation Support (iPhone/iPad)

The build.settings !le can be used to set application orientation, including auto-orientation with the accelerometer.

On iPhone and iPad, it is important to understand that there are three different things that are subject to orientation:

(1) The splash screen image

(2) The native UI elements, such as the keyboard and alert popups

(3) The Corona canvas itself

In many cases, you may want (2) and (3) to have the same orientation, but note that there are also cases in which you want to orient them separately.

For example, you might create an iPad game with no “correct” orientation, but still want the iPhoneOS noti!cation dialogs to appear right side up from the current player’s point of view. Alternatively, you might want to lock the orientation of the Corona canvas, because you are performing your own orientation changes using Corona animation (as shown in the Fishies sample code), but you still want the native UI elements to appear in the current orientation.

To control these various scenarios, there are now three optional key/value pairs within the orientation table in build.settings: default, supported, and content. The following scenarios demonstrate usage by example.

Auto-rotation

To auto-rotate to all four orientations, you could use the following build.settings !le:

settings ={ orientation = { default = "landscapeRight", supported = { "landscapeLeft", "landscapeRight", "portrait", "portraitUpsideDown", }, },}

The default orientation setting determines the initial launch orientation on the iPhone, and also the initial orientation of the Corona simulator.

When you change the device or simulator orientation, the Corona view will auto-rotate, within the orientations supported. In addition, native UI (on the device) will auto-rotate. The auto-rotation is such that to the user, the content appears "upright". Also, the position (0,0) within Corona will correspond to the upper left-hand corner of the current screen orientation.


Note that the iPad ignores the default setting, and attempts to launch in the current physical orientation of the device, assuming that orientation is found on the supported list. If you are writing an iPad app that supports multiple orientations, you should also provide a splash screen for each of the orientations, or the App Store reviewers may reject your app. The iPad supports the following naming conventions for orientation-speci!c splash screen !les:

Default-Portrait.png

Default-PortraitUpsideDown.png

Default-Landscape.png

Default-LandscapeLeft.png

Default-LandscapeRight.png

Landscape orientation

To support a single orientation (for example, landscape-only), build.settings should look like this:

settings ={ orientation = { default = "landscapeRight", supported = { "landscapeLeft", "landscapeRight" }, },}

In this sample, both landscape orientations are supported (landscapeRight and landscapeLeft). It has become fairly common for iPhone apps to only support one orientation, but Apple encourages iPad developers to support all equivalent orientations: for example, a landscape app should support both landscapeLeft and landscapeRight, and a portrait app should support both portrait and portraitUpsideDown.

Again, the position (0,0) within Corona will correspond to the upper left-hand corner of each screen orientation.

Orientation of native UI only

There are scenarios in which you want the native UI elements to auto-rotate, or to be oriented in a speci!c way, but you also want to maintain a !xed coordinate system within Corona (which matches the previous behavior in Corona SDK 1.x).


For example, you may have a multiplayer game where any orientation is equally valid, or you may want to manually de!ne the animation that occurs on orientation change (e.g., animate a dissolve and/or rotation between the sideways and upright interface layouts). The only way to do this is through a !xed Corona coordinate system where you manage the rotation behavior in Lua. Because Corona renders its graphics to an OpenGL canvas that is separate from the other native elements, it is possible to control its rotation behavior independently.

To lock Corona’s orientation while allowing native iPhone UI elements to rotate, add a content parameter in build.settings:

settings ={ orientation = { default = "portrait", content = "portrait", supported = { "landscapeLeft", "landscapeRight", "portrait", "portraitUpsideDown", }, },}

Similarly, to lock Corona’s internal coordinate system to portrait orientation (e.g., for compatibility with your older Corona code) while locking iPhone UI elements to landscape orientation, you could do the following in build.settings:

settings ={ orientation = { default = "landscapeRight", content = "portrait", supported = { "landscapeRight", }, },}

Orientation naming conventions

Orientations follow the UIInterfaceOrientation conventions on the iPhone (not to be confused with UIDeviceOrientation). These are de!ned as follows:

• portrait: device in the upright position with the Home button on the bottom

• landscapeRight: device in the sideways position with the Home button on the right


• landscapeLeft: device in the sideways position with the Home button on the left

• portraitUpsideDown: device in the upside down position with the Home button on the top

Detecting current device orientation

The current device orientation can be read from system.orientation. This property will return one of six possible string values, from a set consisting of the four orientations above plus faceUp and faceDown.

To get more detailed information about the device’s speci!c x, y, and z angle in space, see the section on accelerometer events in the API Reference.

Orientation Support (Android)

The Android platform supports two orientations: portrait and landscapeRight. The orientations “landscapeLeft” and “portraitUpsideDown” have no effect on Android. Also, auto-rotation is not currently supported on Android.

Here is an example of an Android-speci!c build.settings !le (you may also combine Android and iPhone settings in the same !le):

settings ={ android = { versionCode = "3" },

androidPermissions = { "android.permission.ACCESS_FINE_LOCATION", "android.permission.INTERNET" },

orientation = { default = "landscape" },}


Version Code (Android)

The version code can be set within an optional “android” table in build.settings. See the code above for an example.

For more information, see android:versionCode on this page:

http://developer.android.com/guide/topics/manifest/manifest-element.html#vcode

Note that this version code is an internal number used to distinguish application releases, and is different than the version given in the Corona build dialog. The latter determines the version number displayed to the end user, also known as android:versionName.

Application Permissions (Android)

Finally, an optional “androidPermissions” table can be used to specify permissions, using string values as given in the Android Manifest Reference ( ). For example, ACCESS_FINE_LOCATION and INTERNET permissions are speci!ed in the code above.

Developers should choose the permissions that best describe what their application needs.


Data Storage

SQLite (all platforms)

Corona now includes support for sqlite databases on all current Corona platforms. This is based on the built-in sqlite support on the iPhone, and a compiled version of sqlite on Android. Note that this increases the size of the Android binary by 300K.

SQLite should be available in Android 1.5, 2.0, iPhone, and iPad, as well as in the Corona Simulator. However, on Android, access to a prepopulated database inside the APK is not yet supported. Only memory databases and dbs on the local !lesystem may be opened.

The Lua API is provided by luasqlite 3 v0.7, source available from http://luaforge.net/projects/luasqlite/. The documentation for luasqlite3 can be viewed at http://luasqlite.luaforge.net/lsqlite3.html. This documentation also includes test and sample code.

Example code:

require "sqlite3"local db = sqlite3.open_memory()

db:exec[[ CREATE TABLE test (id INTEGER PRIMARY KEY, content); INSERT INTO test VALUES (NULL, 'Hello World'); INSERT INTO test VALUES (NULL, 'Hello Lua'); INSERT INTO test VALUES (NULL, 'Hello Sqlite3')]]

print( "version " .. sqlite3.version() )

for row in db:nrows("SELECT * FROM test") do local t = display.newText(row.content, 20, 30 * row.id, null, 16) t:setTextColor(255,0,255)end


http://luaforge.net/projects/luasqlite/




http://luasqlite.luaforge.net/lsqlite3.html




Improved Sound API (all platforms)

Completion listener

Extended sounds (which are generally in MP3 format on iPhoneOS, and often used to play background music) can now have a completion listener. This is an optional parameter to playSound.

local onComplete

onComplete = function(event) print( "sound play ended" ) media.playSound( "note2.mp3", onComplete )end

media.playSound( "note2.mp3", onComplete )

In this example, the onComplete routine is called when note2.mp3 !nishes. This immediately goes back and re-queues the playSound, so this is a form of looping; however, there is a small gap between the playback of the sounds.

Also, in this example the declaration of onComplete occurs before the function creation, because it needs to exist to be referenced inside the function (otherwise Lua interprets it as a local variable, which isn't set, and so it doesn't do anything).

Loop parameter

media.playSound( "note2.mp3", true )

Setting the !nal parameter to true causes the sound to loop. It will loop until you stop it. This has less overhead than the onComplete method of looping, so there will be less of an audible gap between the end of the sound and the beginning of the next loop.

Event sound completion listener

Similar to the extended sounds discussed above, event sounds now have a completion listener. To call a completion listener each time the sound is played, you can specify the sound listener in playEventSound:


media.playEventSound( "beep.caf", onComplete )

Note that event sound completion listeners are not supported on Android, since the Android API doesn’t allow for this.

Volume control

The volume of extended sounds can now be set and accessed. For example:

media.setSoundVolume( 0.5 ) print( "volume = " .. media.getSoundVolume() )

This setting can be adjusted at any time before or during the extended sound playback. Note that setting the global volume is a different feature, and is not currently supported.

Also note that event sounds do not have volume control. This is a limitation of the event sound API for iPhone and Android.


Revision History

This table describes the changes to 2.0 Beta Guide:

Date Notes

2010-05-13 Initial release for Corona SDK 2.0, Beta 3

2010-05-21 Revised for Corona SDK 2.0, Beta 4

2010-06-01 Revised for release of “movieclip.lua” library update

2010-06-09 Revised for Corona SDK 2.0, Beta 5


Documents

Coronaâ„¢ SDK 2.0 Beta Guide - Corona Developer Portal