Android Pre-Release Deployment Release Notes (R2)

Android Pre-Release Deployment Release Notes (R2) Table of Contents Overview...2 Bug reports and feedback...2 Getting Started...3 Prerequisites...3 The Android Deployment Plugin...3 Configuring an emulated device...5 Configuring a real device...5 A First Project...6 Android Plugin Features...7 Projects and Files...7 Non-Test Deployment...7 Debugging...7 General engine features...8 Engine version...8 What doesn't work...8 What does work...8 Windowing and Stacks...9 System Dialogs answer...9 Android Specific Engine Features...10 Limitations...10 Multi-touch events...10 Mouse events...11 Motion events...11 Resolution handling...11 File and folder handling...12 Hardware and system version query support...12 Change Logs and History...13 Engine Change History...13 Plugin Change History...13 Document Change History...13 1

Overview Welcome to the first pre-release of the LiveCode deployment pack for Android. This release consists of the first version of the LiveCode Android engine together with a simple IDE plugin that you can use to launch stacks in the Android emulator, or on a real Android device. Being the first pre-release the current feature-set of the Android engine is quite limited, although will still allow many self-contained stacks to run well. We will be working hard to bring the Android engine up to a similar level of feature-set as the current ios engine over the current months. For more details of what does work, and what limitations current exist please see the What Works section. Note: In order to use the Android pre-release you need to have an Android deployment license. Note: This version of the deployment pack supports only Mac and Windows development, Linux support will be added in a later release. Important: The LiveCode Android engine currently supports Android devices running version 2.2 and higher. We are currently investigating the possibility of supporting version 2.1 also. Bug reports and feedback Being a pre-release, the Android engine is still a work-in-progress. As such, there will be bugs, unimplemented features and things that don't work quite as expected. We are working hard to bring the engine up to parity with the current ios engine and, in particular, to a point where it can be integrated into the IDE as a release-quality deployment pack. Please direct any feedback or bug reports to livecode_mobile@runrev.com. We can't guarantee we will answer every email at this stage of development, but any such reports will be read and help influence our development priorities while the Android engine is in pre-release form. Important: Do not post Android related bugs or feature requests in the RQCC any such reports will be immediately closed with a request that they be sent to the above email address instead. 2

Getting Started Before you can use the Android plugin, you need to ensure you have set up your system appropriately. This section contains all the salient details you need to setup your system, but there are step-by-step lessons taking you through this in more detail for each platform here: http://www.runrev.com/links/setup-android-mac http://www.runrev.com/links/setup-android-windows Prerequisites If you are intending to use the Android deployment pack on Windows, you will need: Windows XP/Vista or Windows 7 LiveCode 4.5.3 or later The Java SDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html The Android SDK: http://developer.android.com/sdk/index.html If you are intending to use the Android deployment pack on Mac, you will need: Mac OS 10.5.x or later LiveCode 4.5.3 or later The Android SDK: http://developer.android.com/sdk/index.html After you have installed the pre-requisites make sure you run the Android SDK Manager and have installed the 'SDK Platform Android 2.2, API 8, revision 2' package. Additionally, place the revandroidplugin.rev in your LiveCode Plugins customization folder and restart your LiveCode IDE. The place to install the plugin is typically in: (Windows) : My Documents/My LiveCode/Plugins (Mac) : Documents/My LiveCode/Plugins Note: You will need to create folders in the above locations if they do not already exist. The Android Deployment Plugin Once you have all the pre-requisites installed, launch your IDE and you should revandroidplugin in the Development > Plugins menu. Choosing this item will load the plugin. 3

The first time the plugin runs you will be presented with the following dialog: Revision 2 2011-02-23 Mark Waddingham This dialog allows you to configure the path to the Android SDK which you should already have installed. Simply click the ' ' button and choose the folder containing it. Clicking Cancel will skip the configuration, however if no SDK path is configured, you will not be able to use the plugin. When the dialog has been dismissed, or if you have previously configured the SDK path, you will be presented with the Plugin window proper: The labelled items are as follows: 1. LiveCode logo. Double-click here to reconfigure the SDK path, or configure one if you haven't yet done so. 2. The currently active 'project' menu. This drop-down allows you to choose between currently loaded LiveCode Android projects. 3. The new project button. Clicking this button will allow you to choose a mainstack to mark as a LiveCode Android project. 4. The application name. This is the label of the app on the Android home screen. 5. The application identifier. Used to uniquely identify the app in the Android ecosystem. This feature is not implemented in pre-release-1. 6. The project file list and related buttons. This feature is not implemented in pre-release-1. 7. The currently active 'device' menu. This drop-down allows you to choose between the currently connected Android devices, both emulated and real. 8. The 'Use SD Card' option. If this is checked the LiveCode Android project will be built and installed on the currently selected device's SD Card (if it has one) as opposed to its internal 4

storage. Revision 2 2011-02-23 Mark Waddingham 9. The 'Show Log' button. Clicking this button will display the device system log, see the debugging section for more information. 10. The 'Launch' button. Clicking this button will cause the currently active project to be built, installed and run on the currently selected device. Configuring an emulated device In order to run an Android project, you need either an emulated device running, or a real device configured for debugging connected. Creating an emulated device is easily done using the Android SDK Manager that you will have previously installed: Make sure the SDK Manager is running. Choose 'Virtual Devices' from the left-hand list Click 'New...' Choose a name for your device Set the Target to at least Android 2.2 API Level 8 Fill in an SD Card size. Enable the Snapshot option (this isn't essentially but significantly speeds up subsequent launches of the emulator!) Then click Create AVD After you have performed these steps, your newly created device should appear in the list of existing Virtual Devices, from which you can click Start... to launch it. Any running Virtual Devices will appear in the Android Plugin's device list (assuming you have correctly configured the SDK root). Configuring a real device Instead of using the emulator, you can also launch LiveCode Android projects on real Android devices after they have been appropriately configured for debugging. If you are running on Windows then before you can connect to a real device, you need to ensure the appropriate device driver is installed on your development machine. For details of how to do this see here: http://developer.android.com/sdk/win-usb.html If you are running on Mac, there is no need to install any drivers as it 'just works'. Once you have any necessary drivers installed, you must then put your device into debugging mode. To do this, go to the home screen, press MENU, select Applications > Development and enable USB debugging. Finally, simply connect your device via USB to your machine and it should (after a few moments) be available in the Android Plugin's device list (assuming you have correctly configured the SDK root). 5

A First Project Once you have the plugin up and running, its easy to create your first project: 1. Create a new main stack via File > New Mainstack. 2. Rename your new main stack to Hello World 3. Drag and drop a button onto the new main stack, and call it Click Me 4. Edit the Click Me button script and enter the following: on mouseup answer "Hello World!" with "Ok" end mouseup Revision 2 2011-02-23 Mark Waddingham 5. Save the Hello World stack (a stack has to be saved to disk to be usable by the revmobile plugin). 6. Switch to the Android plugin, and use the New Project (3) button to choose the Hello World main stack. 7. To test your stack out make sure you have an Android emulator running (or an Android device connected) and choose a target device using the drop-down list (5) 8. Click the Launch (8) button and after a few moments the necessary files will be transferred and the engine launched. 9. Click/touch the Click Me button on the device's screen and see you script in action! 6

Android Plugin Features Projects and Files The Android plugin's idea of a project is very simple it is simply a (saved) main-stack together with a list of anciallary files referred to as assets. In a later pre-release, you will be able to configure a list of files and folders that should be bundled together with your main-stack as assets. These will be accessible by the engine when running on the device using the standard set of engine file and folder handling commands. Note: Support for assets is not yet implemented, at the moment your project must be entirely selfcontained and consist of a single stackfile. Non-Test Deployment At the moment, the packages built by the Android plugin are not suitable for anything other deploying on test devices. Support for building packages suitable for general distribution will be added in a later pre-release. Debugging To assist with basic debugging needs, the Android plugin provides easy access to the currently selected device's system log. To show the log click the Show Log button when you have a device selected: The log window will continuously update with any new messages the device outputs to its log. You can toggle this updating by clicking the Pause (Resume) button. By default, you won't see any messages other than those output but a running LiveCode Android engine. To see all the messages the device is generating, simply click the All messages button. To output a message that can be seen in the Log Viewer from a LiveCode stack, simply use: put string When executed, this command will cause a line in the log of the form: I/LiveCode(<pid>): <message> Where <pid> is the engine's process id, and <message> is the string you passed to the put command. 7

General engine features Engine version The current pre-release of the Android engine was derived from the 4.0 version of the desktop engine. This means that features present in 4.5.x that you might expect to work in the Android engine will not be present at this time. In particular, the engine version is fixed at 4.0.0 and the build number at 950. We are working on reintegrating the Android and ios ports of the engine with the main desktop engine, and versioning will once again become unified in a future release. What doesn't work The following features have no effect: clipboard related syntax and functionality (planned for a future release) drag-drop related syntax and functionality (no support on mobile devices) printing syntax and functionality (planned for a future release) setting the mouseloc (no support on mobile devices) backdrop related syntax and functionality (no support on mobile devices) cursor related syntax and functionality (no support on mobile devices) socket syntax and functionality (planned for a future release) audioclips/videoclips/player/play functionality (planned for a future release) strong encryption support (planned for a future release) externals and database access (planned for a future release) paint tools (planned for a future release) non-file URL access (planned for a future release) ask command (planned for a future release) full screen snapshot commands (planned for a future release) visual effects (planned for a future release) font querying support (planned for a future release) What does work The following things do work as expected: rendering of controls with non-system themes (default is Motif theme) date and time handling gradients, graphic effects and blending 8

any non-platform, non-system dependent syntax (maths functions, string processing functions, behaviors etc.) object snapshot commands Windowing and Stacks The Android engine uses a very simple model for window management: only one stack can be displayed at a time. The stack that is displayed is the most recent one that has been targeted with the go command. The currently active stack will be the target for all mouse and keyboard input, as well as be in receipt of a resizestack message should the orientation or layout of the screen change. The modal command can also still be used, and will cause the calling handler to block until the modal'ed stack is closed as with the normal engine. Note, however, that performing a further go stack from a modal'ed stack will cause the new stack to layer above the modal stack this will likely cause many headaches, so it is probably best to avoid this case! At this time menus and other related popups will not work correctly, as these are implemented in the engine (essentially) as a specialized form of go stack they will cause the current stack to be overlaid completely, with various undesirable side-effects. Note: The 'go in window' form of the 'go stack' command will not work correctly in the Android engine and must not be used. Since there is only one stack/window displayed at once on this platform, a generic 'go stack' should be used instead. System Dialogs answer The Android engine supports a restricted version of the answer commands using the standard Android AlertDialog class. The answer command can be used in this form: answer message [ with button and ] [ titled title ] This will use the Android standard alert popup with the given buttons and title. The last button specified will be marked as the default button. Note: You cannot nest calls to answer on Android. If you attempt to open an answer dialog while one is showing, the command will return immediately as if the dialog had been cancelled. Cross-Mobile Note: The answer command works the same way on both ios and Android. 9

Android Specific Engine Features This version of the LiveCode Android engine includes a number of features specified to Android devices. These are described in the following sections. Limitations Apart from the list of general engine features that do not currently work in the LiveCode Android environment, the current pre-release has the following limitations that we are looking to lift in future releases: only a self-contained stackfile is supported, no auxillary files can be included with a project only one LiveCode Android application can be installed on a device at once (it will be overwritten on each Launch from the plugin) only portrait orientation is supported no ability to configure the status bar visibility no access to the accelerometer no access to gps no access to the camera no access to email no keyboard support no (shake) motion support no native control support no support for clearing pending interactions Multi-touch events Touches can be tracked in an application by responding to the following messages: touchstart id touchmove id, x, y touchend id touchrelease id The id parameter is a number which uniquely identifies a sequence of touch messages corresponding to an individual, physical touch action. All such sequences start with a touchstart message, have one or more touchmove messages and finish with either a touchend or a touchrelease message. A touchrelease message is sent instead of a touchend message if the touch is cancelled due to an incoming event such as a phone-call. No two touch sequences will have the same id, and it is possible to have multiple (interleaving) such sequences occurring at once. This allows handling of more than one physical touch at once 10

and, for example, allows you to track two fingers moving on the device's screen. Revision 2 2011-02-23 Mark Waddingham The sequence of touch messages is tied to the control in which the touch started, in much the same way mouse messages are tied to the object a mouse down starts in. The test used to determine what object a touch starts in is identical to that used to determine whether the pointer is inside a control. In particular, invisible and disabled controls will not considered viable candidates. Cross-Mobile Note: Touch messages work the same way on both Android and ios platforms. Mouse events The engine will interpret the first touch sequence in any particular time period as mouse events in the obvious way: the start of a touch corresponding to pressing the primary mouse button, and the end of a touch corresponding to releasing the primary mouse button. This means that all the standard LiveCode controls will respond in a similar way as they do in the desktop version in particular, you will receive the standard mouse events and the mouseloc will be kept updated appropriately. Note that touch messages will still be sent, allowing you to choose how to handle input on a percontrol basis. Cross-Mobile Note: Mouse messages work the same way on both Android and ios platforms. Motion events An application can respond to any motion events by using the following messages: motionstart motion motionend motion motionrelease motion Here motion is the type of motion detected by the device. At present, the only motion that is generated is shake. When the motion starts, the current card of the defaultstack will receive motionstart and when the motion ends it will receive motionend. In the same vein as the touch events, motionrelease is sent instead of motionend if an event occurs that interrupts the motion (such as a phone call). Cross-Mobile Note: Motion messages work the same way on both Android and ios platforms. Resolution handling The engine makes no attempt to scale or adjust layout of stacks based on the resolution or density of the display the application is running on. A single pixel on the desktop maps to a single screen pixel on Android, giving you full access to all the pixels on a device's display regardless of what dpi it might have. When a stack is displayed, it will receive a resizestack message resizing to the full area of the screen (minus status bar). You can use the screenrect and the working screenrect properties to find out the current full size of the screen, and the area not including the status bar. 11

File and folder handling Revision 2 2011-02-23 Mark Waddingham In general the low-level support for handling files and folders in the Android engine is the same as that on the desktop. All the usual syntax associated with such operations will work. Including: open file/read/write/seek/close file delete file create folder/delete folder setting and getting the folder listing files and folders using the [ detailed ] files and the [ detailed ] folders storing and fetching binfile: and file: urls However, it is important to be aware that the Android imposes strict controls over what you can and cannot access. Note: The Android filesystem is case-sensitive this is different from (most) Mac installs and Windows so take care to ensure that you consistently use the same casing of filenames when constructing them. Hardware and system version query support You can fetch information about the current hardware and system version using the standard LiveCode syntax in the following ways. To determine what processor an application is running on use the processor. For the Android engine this will always be ARM, regardless of whether running on a virtual or real device. To determine the type of device an application is running on use the machine. This will return the (manufacturer's name) for the device. For example, if running on a Google Nexus One, the string will be Nexus One. To determine the version of Android the application is running on, use the systemversion. For example, if the device has Android 2.2 installed, this property will return 2.2; if the device has Android 2.3.1 installed, this property will return 2.3.1. 12

Change Logs and History Engine Change History pre-release-1 (2011-02-21) pre-release-2 (2011-02-23) Plugin Change History pre-release-1 (2011-02-21) MW Initial version. pre-release-2 (2011-02-23) MW No changes. Document Change History Revision 1 (2011-02-21) MW Initial version. Revision 2 (2011-02-23) MW No changes. MW Initial version. MW Fixed bug initial touch ignored Fixed bug multiple touches not reported correctly 13