Example Serpentine Programs

This directory contains examples written in the Serpentine language that need to be run on a device with the Dalvik or ART virtual machines. They are also used as simple regression tests for any API or compiler breakage since changes to either of these may cause compilation to fail completely.

To compile the examples, invoke the buildall.py script, making sure that the Compiler package directory is in the PYTHONPATH. For example, from the root of the distribution type the following, remembering to substitute your own key and certificate files for the placeholders used:

PYTHONPATH=. Examples/Serpentine/buildall.py <key.pem> <cert.pem> /tmp/packages

Examples can also be built individually. For example:

PYTHONPATH=. Examples/Serpentine/Timers/build.py <key.pem> <cert.pem> \
             /tmp/Timers.apk

Some of these examples are simple tests of functionality; others were written to show how to access the Java and Android APIs using the syntax of the Serpentine language.

More complex examples may be moved to the Demos directory in the future.

Examples

It might be worth starting with the following examples that introduce aspects of the language as well as describing how the Java and Android API are used:

• Minimal is the minimal amount of code required for an activity.
• Hello is a simple activity that displays the text, "Hello World!"
• Clicker responds to clicks on a button by updating a text label, showing how to implement an interface.
• Buttons showcases some of the buttons available in the Android GUI.
• Icons demonstrates how to display images that are packaged with an application.
• Scroll Icons shows how to display a grid of icons in a scrolling view.
• List View shows how to expose an array of strings to a ListView using a custom adapter class.
• String List View shows how to expose an list of strings to a ListView using a custom adapter class.
• Spinner displays a widget that allows the user to select an option in a drop-down list. As in the previous example, the list is exposed via an adapter.
• Views explains how custom views are created.
• Bitmaps shows how to display a bitmap from the application's packaged resources and respond to touch events.
• Mandelbrot shows how to create a custom view class and draw on it.
• Timers demonstrates the use of a timer to periodically update a user interface.
• XML Layout shows how to refer to an XML-like description of an activity's layout.
• XML Layout References shows how to update a user interface defined using an XML-like layout description.
• View Switcher demonstrates the use of a view switcher to display alternating views.

The following examples use more features of the Android API:

• Accelerometer shows how to read values from an accelerometer if a device contains one. It also shows how to implement callback methods described by an interface.
• Action Bar requests an action bar for the application.
• Action Bar List shows how to add a drop-down list to an action bar.
• Action Bar Tabs uses an alternative form of navigation within an activity based on tabs of content.
• Audio Record records sounds using the Android media APIs and saves them to files in a device's external storage.
• Audio Sampler records sounds in the same way as the Audio Record example, but allows the user to specify the audio parameters.
• Audio Track plays a sound using the Android media APIs when the user clicks on a button.
• Async Task uses a custom class to perform processing in the background.
• Bluetooth Devices displays information about a device's Bluetooth adapter and can scan for other devices. It listens for broadcast intents to find out when Bluetooth is enabled and obtain information about other devices.
• Camera shows how to display preview images from a camera if a device contains one. It also shows how to implement callback methods described by an interface.
• Camera Intent requests a camera picture from another component using an intent.
• Camera Picture shows how to take a picture using a device's camera and save it as a file.
• Camera Snap is another example showing how to take a picture using a device's camera.
• Class Loader uses a class loader to import a standard class and examine its methods.
• Class Loader Method Call shows how to use a class loader to call methods of a class.
• Clocks showcases some of the widgets available for displaying the time.
• Compass shows one way to obtain orientation information by combining inputs from two sensors.
• Environment demonstrates how to access the application's environment in order to access the external public storage directory of a device.
• Export Calendar shows how to access the user's calendar and export individual events to files.
• Export Call Log shows how to access the user's call log and export individual entries to files.
• Export Contacts shows how to access the user's contacts and export individual entries to files.
• Export SMS shows how to access the user's SMS messages and export individual messages to files.
• Files shows how to access external storage. It also uses an additional module that provides a custom adapter class.
• GPS uses the Android location APIs to access a device's GPS receiver in order to report its current location.
• GPS File allows the user to write the current location to a file in the external storage area of a device.
• HTTP Get shows how to use the connectivity service to download a file from the Internet.
• Light Meter uses a light sensor to measure the ambient light level.
• Network Info displays information about the available network interfaces on a device.
• Options Menu shows how to attach a menu to a device's menu button, if it has one.
• Orientation Compass shows one way to present information from an orientation sensor.
• OS Info is a simple tool to display information about the operating system on a device.
• Pop-up Window shows how to open, resize and dismiss pop-up windows.
• Process runs a background process and collects the output for display in the GUI.
• Proximity uses the Android Sensor APIs to measure the proximity of a device to its surroundings.
• Send SMS can be used to send SMS messages on devices with access to a cellular network.
• Send SMS Notify shows how to send SMS messages with notifications.
• Sensor List shows how to query the system services to obtain a sensor manager, using a type cast to access the methods of the SensorManager class and list the available sensors on a device.
• Telephony Info displays information about the telephony features of a device, if present.
• Widget is a simple widget that can be installed on the home screen of a device.
• Widget Service is a simple widget that uses a service to update itself periodically.
• Widget Updates and Widget Intent Updates show two additional ways to update a widget periodically.

Documentation

Some of the examples are documented using inline docstrings. These are processed when the examples are built if the DOCS_DIR environment variable is set to the name of a directory. If an absolute path is not used, the name is interpreted as a subdirectory of the relevant example directory, as in the following example:

DOCS_DIR=docs PYTHONPATH=. Examples/Serpentine/Compass/build.py \
                           <key.pem> <cert.pem> /tmp/Compass.apk

This requires the example's build script to have been written so that it reads the DOCS_DIR environment variable and passes it to the buildhelper.main function. The script uses the gendocs module to create an HTML file in the documentation directory.