Case Study: Cool Clock - An Intro to Android Development

Cool Clock Helping children to read analog clocks

An introduction to developing custom 2D graphics Android applications

Richard Creamer 2to32minus1 @gmail.com

1

Copyright (c) Richard Creamer 2011 - All Rights Reserved

Links Home Page

LinkedIn Profile Android Market Cool Clock Product Listing

External Cool Apps Software Website External Cool Clock Product Details Page

http://sites.google.com/site/rickcreamer


http://www.linkedin.com/in/rickcreamer

http://market.android.com/details?id=net.maxuint32.coolapps

http://sites.google.com/site/coolappssoftware

http://sites.google.com/site/coolappssoftware/products/cool-clock

2

What are 2D Custom Graphics Components?

Copyright (c) Richard Creamer 2002 - 2011 - All Rights Reserved

Below are several examples of 2D components previously developed by the author in Java/Swing:

3

What are 2D Custom Graphics Components?


“Gel” button

Custom keypad

Joystick for games, robotics

Process Editor

Least-squares data/curve

fitting

Spring force graph layout of UML-like

OO diagram showing classes &

interrelationships

Tiger Line map of states, counties

and air fields

Binary Search Tree compact graph

layout & visualization

Below are several examples of 2D components previously developed by author in Java/Swing:

The Cool Clock Application

4


Learn Mode

Hands can be interactively dragged. Includes dynamic

“Before” and “After” circular arrows.

Clock Mode

Traditional running clock - no hand dragging, but supports

optional dynamic circular arrows.

Modern Clock

A simple “modern” running clock. No numerals, minute

ticks, etc.

Android Intro...

5

Android - Getting Started • Getting started with Android development and the Eclipse plug-in:

• Install the Java SE JDK and Java documentation: • www.oracle.com/technetwork/java/javase/downloads/index.html

• Install Eclipse, the most efficient IDE for Android development: • www.eclipse.org

• Install the Android SDK and the Android Eclipse Plug-In: • www.developer.android.com/sdk

• After Java SE, Eclipse and the Android SDK are installed: • Set up your PATH environment variable to include:

• AndroidInstallDir\platform-tools, AndroidInstallDir\tools • JavaSeInstallDir\bin

• Use Eclipse to create a “Hello, Android!” application. • Android development book suggestions:

• Hello, Android by Burnette ( 1934356565 ) • Android Wireless Development by Darcy and Conder ( 0321743016 ) • Professional Android 2 Application Development by Meier ( 0470565520 )

6


http://www.oracle.com/technetwork/java/javase/downloads/index.html

http://www.eclipse.org/

http://www.developer.android.com/sdk

Android Introduction • Android is a Linux-based platform/OS for mobile devices from Google.

• Android is not the same as the Chrome OS. • Android programming: http://developer.android.com/

• High-level programming is done in Java SE. • Low-level programming ( NDK ) is done in C/C++.

• Android NDK URL: http://developer.android.com/sdk/ndk/ • Android enforces aggressive resource management • Resources such as strings, menu and view layouts can be defined in XML or in code.

• Google recommends defining resources in XML vs. in code. • Android programs have direct, programmatic access to:

• GPS and other sensors ( compass, accelerometer, orientation ) • Multi-touch input, internal & external storage • Web, e-mail, SMS, Google Maps • Camera & multi-media playing/recording • Open GL ES 1.1 and 2.0

• Android apps must declare needed privileges and minimum Android version. • Android includes a rich set of UI widgets/components and a basic SQLite database. • Android app lifecycle diagram:

• http://developer.android.com/reference/android/app/Activity.html#Lifecycle 7


http://developer.android.com/

http://developer.android.com/sdk/ndk/

http://developer.android.com/reference/android/app/Activity.html

Android Tools and App Categories • Useful tools:

• adb.exe - useful command lines: • C:>adb logcat ( prints event log ) • C:>adb logcat -c ( clears the logcat history ) • C:>adb install Clock.apk ( installs an app on a device or emulator )

• Dalvic Debug Monitor ( located in sdkDir\tools\ ) • Run ddms.bat to launch this useful console application • Explore Android file system, take app screenshots and much more

• Android Virtual Device Manager ( AVD Manager ) • Create multiple virtual devices w/ various Android OS/HW configurations. • Enables testing on a range of HW configurations which may be unavailable • WindowAndroid SDK and AVD Manager

• Sampling of Android app types: • Activity - A user interface screen • Intent - An action ( e.g., launch Help screen or send e-mail ) • Service - A long-running background task • Content Provider - Data accessed via a custom API ( e.g. Contacts ) • Widget - Mini home-screen applications ( e.g. Weather ) • Wallpaper - Static or animated backgrounds

8


Java SE Intro...

9

Java Introduction • The Cool Clock project was coded entirely in Java SE and XML. • Java attributes:

• Fast, mature, portable, object-oriented language with bright future • Extensive I/O, Concurrency, Collections, Reflection and Generics support • Source code is compiled into platform-independent byte code files

• Note: Android byte codes are not compatible with standard Java byte codes • A platform-specific program called a Java Virtual Machine ( JVM ) is used to execute Java applications. Some JVMs perform JIT compilation. • On the Android platform, a special JVM, the Dalvic Virtual Machine, is used.

• Large websites such as Amazon rely on/use Java extensively • Unlike C/C++, only the JVM needs to be ported and recompiled for different platforms • A basic Java program: ( note that Java now has a printf() method ) • Compiling a program: ( javac is the compiler )

C:> javac MyProgram.java MyProgram.class • If a class has a main() method, it can be run from the command line: ( java.exe is the JVM )

C:> java MyProgram

Hello, Introductory 2D Android PPT!

10


MyProgram.java public class MyProgram {

public static void main( String [] args ) {

System.out.printf( "%s\n", "Hello, Introductory 2D Android PPT!" );

}

}

http://numericalmethod.com/blog/2011/07/09/java-vs-c-performance/

http://www.oracle.com/us/corporate/press/512956

Java Introduction • IDEs

• Popular IDEs for Java include Eclipse and NetBeans. Both are free. • Eclipse is usually used for Android development because it has a highly-integrated plug-in for Android.

• Books • Many good introductory Java books exist, here are a few:

• Learning Java by Niemeyer and Knudsen ( 0596008732 ) • Core Java, Vols. I and II by Horstmann and Cornell ( 0132354764 )

• More advanced books: • Effective Java by Bloch, 2nd Edition ( 0321356683 ) ( essential ) • Java Concurrency in Practice by Goetz ( 0321349601 ) • Concurrent Programming in Java by Lea ( 0201310090 ) • Java Threads by Oakes and Wong ( 0596007829 ) • Java Generics and Collections by Naftalin & Wadler ( 0596527756 ) • Java NIO by Hitchens ( 0596002882 ) • Java Network Programming by Harold, 3rd Edition ( 0596007218 )

11


Android App Components

12

Components of an Android App

Main Activity Class • Handles initialization tasks in onCreate() • Sets app View component ( app content view ) • Handles menu events • Launches other Activities • Handles configuration change events ( orientation ) • Responds to Android app lifecycle state changes

Manifest XML File • Declares minimum Android OS version • Declares app version ID • Declares configuration changes handled by app • Declares all Activities in app

Resources • drawable ( bitmaps, icons ) • layout ( GUI layout/content ) • menu ( menu content ) • values ( strings, arrays ) • xml ( Preferences screen layout & content, etc. )

Auto-Generated Java Files • A Java class named “R” • R.java contains static final int IDs for all resources

Android App

Main View Class • Extends android.view.View class • Handles presentation ( drawing, widgets, forms ) • Handles touch events • Example: ClockPanel.java

Other Activity Classes • Sub-activities such as:

• PrefsActivity.java ( Preferences screen ) • AboutActivity.java ( About screen ) • HelpActivity.java ( Help screen )

Other Utility Classes • Other classes such as:

• Vector2d.java 13


Android App Lifecycle

14

Android Application Lifecycle

App Launch onCreate()

onStop() onPause()

onResume() onStart() Activity is

visible

onDestroy()

Process killed Event Event

Activity invisible

Free resources and persist

state

Fetch prior state, instantiate app elements, call

setContentView() Resume worker

threads

Pause worker threads & persist state

Another Activity to

foreground, e.g.

15


• Android can pause or destroy applications at any time • Android sends various lifecycle state-change notifications to applications including:

• onCreate() • onRestoreInstanceState() is called right after onCreate()

• onStart() • onPause()

• onSaveInstanceState() is called right before onPause() • onResume() • onStop() • onDestroy()

• Applications should override and respond appropriately to most of these notifications to preserve state and to minimize resource and CPU use when not actively running

Actual logcat Trace of Cool Clock State Notifications Stopping worker threads is one example of how apps should respond to lifecycle notifications

I/ActivityManager( 69): Start proc net.maxuint32.coolapps for activity net.maxuint32.coolapps/.CoolClock: pid=279 uid=10041 gids={} I/System.out( 279): >>>>>>>>>>>> CoolClock.onCreate() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> ClockPanel Constructor <<<<<<<<<<< ( called by CoolClock ) I/System.out( 279): >>>>>>>>>>>> CoolClock.onStart() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> CoolClock.onResume() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> ClockPanel.resume() <<<<<<<<<<< ( called by CoolClock ) I/System.out( 279): >>>>>>>>>>>> ClockPanel.resume() <<<<<<<<<<< ( called by CoolClock ) I/ActivityManager( 69): Displayed activity net.maxuint32.coolapps/.CoolClock: 4724 ms (total 4724 ms) I/System.out( 279): ClockRunThread threadState: Running I/System.out( 279): ClockRunThread threadState: Running

Start Cool Clock

Press Phone Menu Button

I/System.out( 279): >>>>>>>>>>>> CoolClock.onCreateOptionsMenu() <<<<<<<<<<< I/System.out( 279): ClockRunThread threadState: Running I/System.out( 279): ClockRunThread threadState: Running

Press Settings Button

I/ActivityManager( 69): Starting activity: Intent { cmp=net.maxuint32.coolapps/.PrefsActivity } I/System.out( 279): >>>>>>>>>>>> CoolClock.onOptionsMenuClosed() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> CoolClock.onPause() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> ClockPanel.pause() <<<<<<<<<<< ( called by CoolClock ) I/ActivityManager( 69): Displayed activity net.maxuint32.coolapps/.PrefsActivity: 1970 ms (total) I/System.out( 279): ClockRunThread threadState: Suspended I/System.out( 279): ClockRunThread threadState: Suspended

Exit Preferences

Screen

I/System.out( 279): >>>>>>>>>>>> ClockPanel.notifyClockPrefsChanged() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> CoolClock.onResume() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> ClockPanel.resume() <<<<<<<<<<< ( called by CoolClock ) I/System.out( 279): ClockRunThread threadState: Running I/System.out( 279): ClockRunThread threadState: Running

Press Back Button to show

Home Screen

I/System.out( 279): >>>>>>>>>>>> CoolClock.onPause() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> ClockPanel.pause() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> CoolClock.onStop() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> ClockPanel.stop() <<<<<<<<<<< I/System.out( 279): >>>>>>>>>>>> CoolClock.onDestroy() <<<<<<<<<<<

After any onPause() event, clock run thread is suspended

and is not consuming CPU time for drawing

Initially, clock run thread is active

When Main Menu is displayed, clock run

thread remains active

After PrefsActivity has exited, clock is again

visible and run thread state is active

16


How Cool Clock Responds to State Changes

App Launch

• Android starts CoolClock Activity • CoolClock.onCreate() • CoolClock.onStart() • CoolClock.onResume() • Clock now Running and visible

• Calls ClockPanel.resume(): • Sets clock run thread state to Running

• Instantiates ClockPanel • Calls Activity.setContentView( clockPanel )

Press phone menu button

• CoolClock.onCreateOptionsMenu() • Clock run thread still Running

Press Settings button on Main

Menu

• Android starts PrefsActivity • CoolClock.onOptionsMenuClosed() • CoolClock.onPause() • PrefsAcvitivity is made visible • Clock is now behind Settings screen • Clock run thread is Suspended

• Calls ClockPanel.pause(): • Sets clock run thread state to Suspended

User exits PrefsActivity

• ClockPanel .onActivityResult () •ClockPanel.notifyClockPrefsChange() • CoolClock.onResume() • Clock now Running and visible again

• Calls ClockPanel.resume(): • Sets clock run thread state to Running

• Calls ClockPanel.notifyClockPrefsChange(): • Reloads user preference values from Android • Redraws clock with updated preferences

User presses phone Back

button

• CoolClock.onPause() • CoolClock.onStop() • CoolClock.onDestroy() • CoolClock now destroyed

• Calls ClockPanel.pause(): • Sets clock run thread state to Suspended

• Calls ClockPanel.stop(): • Stops clock run thread

Android Event Stream

17


How to reference Android resources

18

Resources • drawable ( bitmaps, icons ) • layout ( Activities ) • menu ( menu content ) • values ( strings, arrays ) • xml ( Preference screen layout & content, etc. )

Excerpt from CoolClock.java public boolean onCreateOptionsMenu( Menu menu ) { super.onCreateOptionsMenu( menu ); MenuInflater inflater = getMenuInflater(); inflater.inflate( R.menu.menu, menu ); return true; }

Excerpt from Clock\res\xml\settings.xml <CheckBoxPreference android:key="hide_circular_arrows" android:title="@string/hide_circular_arrows_title" android:summary="@string/hide_circular_arrows_summary" android:defaultValue="true" />

How Android resources are referenced From Java From XML

Clock\res\values\strings.xml Excerpt

<string name="hide_circular_arrows_title">Hide Circular Arrows</string>

Clock\res\menu\menu.xml

Recall resource types include From Java

Recall that R is an auto-generated

Java class

1

2 From XML

1 2

19


Creating Main Menus

20

CoolClock.java: @Override public boolean onCreateOptionsMenu( Menu menu ) { super.onCreateOptionsMenu( menu ); // Call base class first MenuInflater inflater = getMenuInflater(); inflater.inflate( R.menu.menu, menu ); return true; } CoolClock.java: @Override public boolean onOptionsItemSelected( MenuItem mi ) { super.onOptionsItemSelected( mi ); // Called first switch ( mi.getItemId() ) { case R.id.help: startActivity( new Intent( this, HelpActivity.class ) ); return true; case R.id.settings: startActivityForResult( new Intent( this, PrefsActiviy.class ), PREFS_ACTIVITY_ID ); return true; case R.id.about: startActivity( new Intent( this, AboutActivity.class ) ); return true; case R.id.exit: finish(); return true; } return false; }

Creating Main Menus

Clock\res\menu\menu.xml <?xml version="1.0" encoding="utf-8"?> <menu xmlns:android="http://schemas.android.com/apk/res/android"> <item android:id="@+id/settings" android:title="@string/settings_label" android:alphabeticShortcut="@string/settings_shortcut" /> <item android:id="@+id/help" android:title="@string/help_option" android:alphabeticShortcut="@string/help_shortcut" /> <item android:id="@+id/about" android:title="@string/about_label" android:alphabeticShortcut="@string/about_shortcut" /> <item android:id="@+id/exit" android:title="@string/exit_label" android:alphabeticShortcut="@string/exit_shortcut" /> </menu>

Define Main Menu GUI

Handle Main Menu Creation

Handle Main Menu Button Presses

Result: Main Menu Screenshot

2 1

3

About Menu “Inflation” In this line of code:

inflater.inflate( R.menu.menu, menu ); The MenuInflater reads menu.xml and then

programmatically adds the MenuItems to the method argument: menu 21


Introduction to Android Preferences

22

Android Preferences Overview

The main menu is displayed when the

user presses the device’s Menu button

• Android includes an easy-to-use Preferences sub-system that allows end users to customize an application’s settings. • Preferences are roughly equivalent to ToolsOptions for desktop applications.

Pressing the Settings button displays the

Preferences/Settings menu

The Preferences screen GUI layout/content is

defined in settings.xml ( see slide 25 )

23


Android Preferences • The Android Preferences sub-system provides:

• XML-based declarative GUI layout definition of Preferences menus/screens • Automatic launching of Preferences screens and their lifecycle management • Transparent persistence of user changes • Easy-to-use API for retrieving persisted Preferences parameter values

• The Cool Clock Preferences screens:

24


Primary Preferences Screen

Clock Mode Options Minute Display Mode

Options Hand Linked to Circular

Arrows Options

settings.xml ( Defines Preferences GUI layout and content* )

<?xml version="1.0" encoding="utf-8"?> <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> <CheckBoxPreference android:key="hide_sec_hand" android:title="@string/hide_sec_hand_title" android:summary="@string/hide_sec_hand_summary" android:defaultValue="true" /> <CheckBoxPreference android:key="hide_circular_arrows" android:title="@string/hide_circular_arrows_title" android:summary="@string/hide_circular_arrows_summary" android:defaultValue="true" /> <CheckBoxPreference android:key="hide_digital_time" android:title="@string/hide_digital_time" android:summary="@string/hide_digital_time_summary" android:defaultValue="true" /> <CheckBoxPreference android:key="hide_phrase_time" android:title="@string/hide_phrase_time" android:summary="@string/hide_phrase_time_summary" android:defaultValue="true" />

<ListPreference android:key="clock_modes" android:title="@string/clock_mode_label" android:summary="@string/clock_mode_summary" android:defaultValue="@string/clock_mode_label" android:entries="@array/clock_modes" android:entryValues="@array/clock_mode_values" /> <ListPreference android:key="minute_display_modes" android:title="@string/minute_display_mode_title" android:summary="@string/minute_display_mode_summary" android:defaultValue="@string/every_five_minutes" android:entries="@array/minute_display_modes" android:entryValues="@array/minute_display_mode_values" /> <ListPreference android:key="arc_modes" android:title="@string/arc_mode_label" android:summary="@string/arc_mode_summary" android:defaultValue="@string/arc_mode_minutes" android:entries="@array/arc_modes" android:entryValues="@array/arc_modes_values" /> </PreferenceScreen>

25


*Multiple-choice widget values are stored in res\values\arrays.xml

How Preferences Menus Work - Details Presses

In main activity ( CoolClock.java ) public boolean onCreateOptionsMenu( Menu menu ) { super.onCreateOptionsMenu( menu ); MenuInflater inflater = getMenuInflater(); inflater.inflate( R.menu.menu, menu ); return true; }

User

Android

Phone Menu button

Calls (1st time)

Android Displays

Main menu

Presses User Settings button In main activity ( CoolClock.java )

public boolean onOptionsItemSelected( MenuItem mi ) { switch ( mi.getItemId() ) { ... cases for other main menu items ... case R.id.settings: startActivityForResult( new Intent( this, PrefsActivity.class ), PREFS_ACTIVITY_ID ); return true; ... } return false; }

Android Calls

Android Displays

Preferences screen

The “inflater” reads the defined main menu items defined in menu.xml and programmatically adds these

menu items to the method argument’s Menu object

( R.menu.menu )

Tells Android to launch Preferences screen

Closes User Preferences screen

Android Calls

In main activity ( CoolClock.java ) protected void onActivityResult( int requestCode, int resultCode, Intent data ) { if ( requestCode == PREFS_ACTIVITY_ID ) { final ClockState newCs = PrefsActivity.getStoredPrefs( this ); clockPanel.notifyClockPrefsChanged( newCs ); } }

Notifies ClockPanel of user Preferences state changes

Reads updated Preferences

User Interacts with

Preferences screen

26


Time

• Stored Preferences values are read using { ParamKey, DefaultValue } pairs. • Example of how to retrieve Android-persisted Preferences values:

Retrieving Preferences Values

PrefsActivity.java ( excerpts ) public final class PrefsActivity extends PreferenceActivity { public static final boolean HIDE_SECOND_HAND_DEFAULT = true; // Key values for accessing parameters from standard Android Preferences/Settings sub-system private static final String HIDE_SEC_HAND_KEY = "hide_sec_hand"; private static final String ARC_MODES_KEY = "arc_modes"; @Override protected void onCreate( Bundle savedInstanceState ) { super.onCreate( savedInstanceState ); addPreferencesFromResource( R.xml.settings ); } ...retrieving Preferences parameter values... // Get a SharedPreferences object SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences( cc ); // Grab actual Preferences/Settings VALUES boolean hideSecondHand = sp.getBoolean( HIDE_SEC_HAND_KEY, HIDE_SECOND_HAND_DEFAULT ); String arcModeString = sp.getString( ARC_MODES_KEY, defaultArcModeMenuString ); }

Reference to settings.xml

Default parameter value

Parameter key

{ ParamKey, DefaultValue } pair

27


Creating Simple TextView Based Activities

28

android.widget.TextView TextView extends android.view.View

CoolClock.java (excerpt) @Override public boolean onOptionsItemSelected( MenuItem mi ) { ... switch ( mi.getItemId() ) { case R.id.about: startActivity( new Intent( this, AboutActivity.class ) ); return true; } .... return false; }

Creating a Simple TextView Activity About Panel

AboutActivity.java package net.maxuint32.coolapps; import android.app.Activity; import android.os.Bundle; public class AboutActivity extends Activity { @Override protected void onCreate( Bundle savedInstanceState ) { super.onCreate( savedInstanceState ); setContentView( R.layout.about ); } }

about.xml <?xml version="1.0" encoding="utf-8"?> <ScrollView xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="fill_parent" android:padding="10dip"> <TextView android:id="@+id/about_content" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@string/about_text" /> </ScrollView>

Define GUI layout

Start activity

Define activity class

Activity’s GUI layout

Here we are starting the AboutActivity when a main menu item is pressed, but Activities can be started at

any time.

About panel’s text content

Note nesting of GUI components

strings.xml (excerpt) <string name="about_text">\ CoolClock v0.8\n\ Copyright (c) Richard Creamer 2011\n\ All Rights Reserved\n\ Email: [email protected]\n\n\ CoolClock can run in three modes:\n\n\ 1. Learn Mode:\n\n\ This mode helps teach children how to read an analog clock.\n\n\ Children can drag clock hands and watch:\n\n\ - The other hands move\n\ - How the digital time changes\n\ - How the "phrase" time changes\n\ - \"Before\" and \"after\" circular arrows\n\n\ 2. Clock Mode:\n\n\ In this mode, CoolClock is just a normal analog clock - it displays the current time and runs.\n\n\ 3. Modern Clock:\n\n\ In this mode, a more modern clock is drawn, without numbers or minute ticks. </string>

1

2

3

4 Define text content 29


Custom 2D Graphical Components

30

A Basic Custom 2D Graphics App/Component • GraphicsTest1 is a very simple custom-drawn 2D component • It draws a gradient background with a random number of spheres of random color and opacity • It ignores many best practices such as avoiding expensive computations in the GUI thread

31


GraphicsTest1 - Salient Java Source Code Elements package ... import ... public class GraphicsTest1 extends Activity { ... attributes... @Override public void onCreate( Bundle savedInstanceState ) { super.onCreate( savedInstanceState ); requestWindowFeature( Window.FEATURE_NO_TITLE ); setContentView( new GraphicsView( this ) ); } // Nested class that fills its bounds with random spheres private static class GraphicsView extends View { ... attributes... public GraphicsView( Context context ) { super( context ); } @Override protected void onDraw( Canvas canvas ) { // Do all drawing } } // End nested GraphicsView class } // End GraphicsTest1 class

GraphicsTest1 sets its content view to

an instance of GraphicsView

GraphicsView overrides onDraw()

1

2

3

Steps for creating a custom 2D component Activity

1. Create new class which extends android.view.View 2. New class must override onDraw() 3. onDraw() does all drawing 4. Call Activity.setContentView( custom 2D component )

4

Note: The GraphicsView class does not have to be a nested class - it was only done this way so the entire Activity + View would fit

into a single Java file... Do all drawing: background +

spheres/graphics

32


private void drawRandSpheresAndBkg( Canvas canvas ) { int numCircles = rand.nextInt( maxCircles ); if ( numCircles < minCircles ) numCircles = minCircles; int w = this.getWidth(); int h = this.getHeight(); Paint bkgPaint = new Paint(); bkgPaint.setShader( new LinearGradient( 0, 0, w, h, c1, c2, Shader.TileMode.MIRROR ) ); canvas.drawPaint( bkgPaint ); // This fills Canvas with background gradient paint for ( int i = 0; i < numCircles; ++i ) { int xc = rand.nextInt( w ); int yc = rand.nextInt( h ); int r = rand.nextInt( ( w + h )/16 ); int red = rand.nextInt( 255 ); int green = rand.nextInt( 255 ); int blue = rand.nextInt( 255 ); int alpha = rand.nextInt( 255 ); int color = Color.argb( alpha, red, green, blue ); drawSphereImage( canvas, xc, yc, r, color ); // Draw the sphere } } public void drawSphereImage( Canvas canvas, float xc, float yc, float radius, int color ) { if ( radius < 3.0f ) radius = 3.0f; Paint paint = new Paint( Paint.ANTI_ALIAS_FLAG ); final float highlightOffsetInPct = 0.4f; float highlightOffset = highlightOffsetInPct * radius; float highlightXc = xc - highlightOffset; float highlightYc = yc - highlightOffset; final float radiusScaleFactor = 3; float highlightRadius = radiusScaleFactor * highlightOffset; RadialGradient rg = new RadialGradient( highlightXc, highlightYc, highlightRadius, 0xffffffff, color, Shader.TileMode.MIRROR ); paint.setShader( rg ); canvas.drawCircle( xc, yc, radius, paint ); } } // End GraphicsView class } // End GraphicsTest1 class

GraphicsTest1 - Complete Java Source Code

package org.example.graphics; import java.util.Random; import android.app.Activity; import android.content.Context; import android.os.Bundle; import android.view.View; import android.view.Window; import android.graphics.Canvas; import android.graphics.LinearGradient; import android.graphics.Paint; import android.graphics.RadialGradient; import android.graphics.Shader; public class GraphicsTest1 extends Activity { @Override public void onCreate( Bundle savedInstanceState ) { super.onCreate( savedInstanceState ); requestWindowFeature( Window.FEATURE_NO_TITLE ); setContentView( new GraphicsView( this ) ); } // Nested class that fills its bounds with random spheres private static class GraphicsView extends View { private final int maxCircles = 150, minCircles = 5; private final int c1 = 0xff4466aa, c2 = 0xff112244; private final Random rand = new Random( System.currentTimeMillis() ); public GraphicsView( Context context ) { super( context ); } @Override protected void onDraw( Canvas canvas ) { drawRandSpheresAndBkg( canvas ); }

GraphicsTest1 sets its content view to be an

instance of GraphicsView

GraphicsView overrides onDraw() 2

1

3

Such methods can be computationally expensive and should not be done in the main GUI thread! Run expensive tasks in another thread! Then, post results back to GUI thread using a Handler.

4

Do all drawing: gradient paint background +

spheres

33


Class should extend View

Custom 2D View Components - Overview

34


Creating the basic GraphicsTest1 class was pretty simple: • Create a class that extends android.view.View ( GraphicsView ) • GraphicsView must override View.onDraw( Canvas canvas ) • In onDraw(), perform all the necessary drawing ( images, shapes, primitives ) • Main Activity calls setContentView() with an instance of GraphicsView

When creating non-trivial components, other details become important, including: • Never allow direct access to a GUI’s state from a non-GUI thread ( thread-safe design ) • Appropriately respond to lifecycle events • Use background/worker threads to perform long-running, computationally-expensive tasks

• Methods to return results from non-GUI threads to the main GUI thread include: • Call Activity.runOnUiThread( Runnable ) • Call the android.os.Handler.post( Runnable ) method of a Handler object

• The Handler must be instantiated in the GUI thread • If user touch input is required the View-derived class should:

• Implement the OnTouchListener interface • Implement View.onTouch() • Handle all touch events and object hit testing if applicable

• Minimize use of system resources • Call base class methods at the appropriate point when overriding methods

Handling Touch Events

35

Implement OnTouchListener.onTouch() public boolean onTouch( View v, MotionEvent me ) { if ( curPrefs.clockOperationMode != E.ClockOperationMode.LearnMode ) return false; if ( !curPrefs.enableHandDragging || me.getPointerCount() > 1 ) // Only handle 1 finger at this time return false; float x = me.getX(); float y = me.getY(); int action = me.getAction() & MotionEvent.ACTION_MASK; switch ( action ) { case MotionEvent.ACTION_DOWN: case MotionEvent.ACTION_POINTER_DOWN: E.ClockHands hand = isCloseToHand( x, y ); if ( hand == E.ClockHands.None ) return false; inDrag = true; dragHand = hand; return true; case MotionEvent.ACTION_UP: case MotionEvent.ACTION_POINTER_UP: inDrag = false; dragHand = E.ClockHands.None; return true; case MotionEvent.ACTION_MOVE: processMove( x, y ); return true; } return false; }

36


Begin a hand drag...

Terminate a hand drag...

Move the current drag hand...

ClockPanel implements the OnTouchListener interface in order to

receive touch input

Graphics techniques used in Cool Clock

37

Cool Clock’s Graphics Layers Background

LinearGradient shader mirroring = true

Fill clock oval Fill clock oval, clipped, with LinearGradient

shader

Add hour and minute numbers + minute ticks

• Hands (LinearGradient shader) • Hands are drawn via Path objects • Center dot (RadialGradient shader)

Upper-left highlight (LinearGradient)

Lower-right highlight (LinearGradient)

Digital time, Phrase time

( This is what is cached )

38


• Circular arrows fill/edges • Circular arrow labels

//Copyright (c) Richard Creamer 2002 - 2011 - All Rights Reserved package net.maxuint32.coolapps; import android.graphics.PointF; public final class Vector2d { public float x, y; public Vector2d( final float x, final float y ) { this.x = x; this.y = y; } public synchronized Vector2d rotateClockwise( final float angle ) { rotateCounterClockwise( -angle ); return this; } public synchronized Vector2d rotateCounterClockwise( final float angle ) { float cos = ( float ) Math.cos( angle ); float sin = ( float ) Math.sin( angle ); float newX = cos * x + sin * y; float newY = -sin * x + cos * y; x = newX; y = newY; return this; } public synchronized Vector2d setLength( final float length ) { normalize(); x = x * length; y = y * length; return this; } public synchronized Vector2d normalize() { float length = length(); if ( length == 0f ) throw new IllegalStateException( "Vector length is zero! Cannot divide by zero!" ); x = x / length; y = y / length; return this; } public synchronized float length() { return ( float ) Math.sqrt( x * x + y * y ); } }

Utility Class: Vector2d (selected methods)

Complete Vector2d public interface: public float x, y; public Vector2d(); public Vector2d( final float x, final float y ); public Vector2d( final Vector2d v ); public Vector2d( final PointF p1, final PointF p2 ); public Vector2d setComponents( final float x,final float y ); public float length(); public float dotProduct( final Vector2d v ); public float cosAngle( final Vector2d v ); public Vector2d zero(); public Vector2d add( final Vector2d v ); public Vector2d mult( final float factor ); public Vector2d div( final float quotient ); public Vector2d rotateClockwise( final float angle ); public Vector2d rotateCounterClockwise( final float angle ); public Vector2d setLength( final float length ); public Vector2d normalize(); public Vector2d parallelOfLength( final float length );

CG Rotation Matrix x’ y’

x y =

cos ѳ sin ѳ -sin ѳ cos ѳ

39


1. Create a Path object p ( see below for details ) 2. Call p.moveTo() for starting point 0 3. Call p.lineTo() or p.arcTo() points 1 - 9 in clockwise order 4. Call p.close() 5. Configure canvas paint or shader ( can be fill or stroke mode ) 6. Call canvas.drawPath( p )

private Path getRhsArrow( float a1, float a2 ) { // Almost complete & accurate... float r1 = Innermost arrowhead side point radius float r2 = Annulus inner radius float r3 = Annulus center radius float r4 = Annulus outer radius float r5 = Outermost arrowhead side point radius float deltaAInDeg = toDegrees( F.abs( a1 - a2 ) ); Path p = new Path(); Vector2d v = new Vector2d( 0, -r3 ); p.moveTo( xc + v.x, yc + v.y ); v.rotateClockwise( arrowheadAngle ).setLength( r5 ); p.lineTo( xc + v.x, yc + v.y ); v.setLength( r4 ); p.lineTo( xc + v.x, yc + v.y ); p.arcTo( new RectF( xc - r4, yc - r4, xc + r4, yc + r4 ), -90 + arrowheadAngle, deltaAInDeg - 2f * arrowheadAngle ); p.lineTo( xc + v.x, yc + v.y ); v.rotateClockwise (arrowheadAngle ).setLength( r3 ); // We can chain method calls because most Vector2d methods return this p.lineTo( xc + v.x, yc + v.y ); v.rotateCounterClockwise( arrowheadAngle ).setLength( r1 ); p.lineTo( xc + v.x, yc + v.y ); v.setLength( r2 ); p.lineTo( xc + v.x, yc + v.y ); p.arcTo( new RectF( xc - r2, yc - r2, xc + r2, yc + r2 ), -90 + deltaAInDeg - arrowheadAngle, -( deltaAInDeg - 2f * arrowheadAngle ) ); v.rotateCounterClockwise( F.abs( a1 - a2 ) - 2 * arrowheadAngle ).setLength( r1 ); p.lineTo( xc + v.x, yc + v.y ); p.close(); return p; }

Drawing Shapes Using Paths 0

1 2

4 3

5

6

7

8

9

( xc, yc ) Use Vector2d class

to handle math ( previous slide )

method = Path methods method = Vector2d methods

Yellow arrows are Vector2d

rotation angles

40


Drawing Text

41

The FontMetrics Class and Paint.getTextBounds() • Android provides the android.graphics.Paint.FontMetrics class:

• Provides Typeface dimensions useful for correctly positioning text • FontMetrics class attributes:

• ascent - “Recommended” distance above baseline • bottom - Maximum distance below the base line for lowest glyph • descent - “Recommended” distance below baseline • leading - “Recommended” space between lines of text • top - Maximum distance above baseline for tallest glyph

• Important: • Attribute values pertaining to distance above the baseline are NEGATIVE

42


Glyph baseline

(-) top

bottom ( bottom - top )

Most Useful Attributes

• Note: Paint.getTextBounds() often provides sufficient information ( FontMetrics object not always needed - see following examples... )

Drawing Text - Code General-purpose text drawing method supporting horizontal and vertical alignment

43


public enum TextVertAlign { Top, Middle, Baseline, Bottom }; // Enumeration representing vertical alignment positions public static void drawHvAlignedText( Canvas canvas, float x, float y, String s, Paint p, Paint.Align horizAlign, TextVertAlign vertAlign ) { // Set horizontal alignment p.setTextAlign( horizAlign ); // Get bounding rectangle which we’ll need below... Rect r = new Rect(); p.getTextBounds( s, 0, s.length(), r ); // Note: r.top will be negative // Compute y-coordinate we'll need for drawing text for specified vertical alignment float textX = x; float textY = y; switch ( vertAlign ) { case Top: textY = y - r.top; // Recall that r.top is negative break; case Middle: textY = y - r.top - r.height()/2; break; case Baseline: // Default behavior - no changes to y-coordinate break; case Bottom: textY = y - ( r.height() + r.top ); break; } canvas.drawText( s, textX, textY, p ); // Now we can draw the text with the proper ( x, y ) coordinates }

Also, look at: • Paint.measureText() • Paint.getFontMetrics()

• android.text.StaticLayout • android.widget.FrameLayout

Text Drawing Example

44


// Excerpts from TextDrawing demo... public enum TextVertAlign { Top, Middle, Baseline, Bottom }; private float fontScaleFactor = 0.08f; // Crude scaling to display private float crosshairScaleFactor = 0.05f; // Crude scaling to display private int numTextColumns = Paint.Align.values().length; private int numTextRows = TextVertAlign.values().length; private float crosshairSize = 10f; @Override protected void onDraw( Canvas canvas ) { canvas.drawPaint( bkgPaint ); // Clear background // Compute some variables we'll need float w = getWidth(); float h = getHeight(); crosshairSize = ( w < h ) ? w * crosshairScaleFactor : h * crosshairScaleFactor; float textSize = ( w < h ) ? w * fontScaleFactor : h * fontScaleFactor; textPaint.setTextSize( textSize ); float colWidth = ( w - 4 * crosshairSize ) / ( numTextColumns - 1 ); float lineSep = h / ( numTextRows + 1f ); float x = 2f * crosshairSize; // Loop over horizontal and vertical alignment enum values // Draw string using loop values for horiz and vert alignment for ( Paint.Align ha : Paint.Align.values() ) { float y = lineSep; for ( TextVertAlign va : TextVertAlign.values() ) { drawHvAlignedText( canvas, x, y, s, textPaint, ha, va ); drawCrosshairs( canvas, x, y ); y += lineSep; } x += colWidth; } }

Top

Middle

Baseline

Bottom

Left Center Right

Optimization &Threading Considerations

45

Optimization • Because onDraw() is called frequently and because much of the Cool Clock graphics drawing is repetitive and computationally expensive, two techniques were used to reduce CPU usage and to maintain a responsive GUI:

• Cache the screen bitmap ( background + clock face + ticks + numbers ) • The clock face only changes if:

• The user modifies certain Preferences settings • The device orientation changes

• As a result, the background and clock face are computed once into cached bitmaps, one for each orientation, until Preferences changes require updates. • Each time onDraw() is called, a cached bitmap is efficiently copied to the screen, then only the hands, circular arrows, highlights, and time text fields are drawn.

• Compute the screen bitmap in a background thread: • To keep the GUI responsive, the long-running task of drawing the background and clock face are performed in a background thread - not in the GUI thread. • While a bitmap is not ready, onDraw() simply fills the screen with the background paint. • When the bitmap computation is completed and the background worker thread terminates, a new Runnable is posted to the GUI Handler which adopts the new Bitmap and then calls invalidate(). • invalidate() queues up a future call to onDraw()

46


private static class ClockFaceRendererTask extends Thread { // Fields containing final defensive copies of a snapshot of ClockPanel fields required for rendering clock face bitmap ... private final Bitmap bm; // The output of this worker thread public ClockFaceRendererTask( final ClockPanel clockPanel ) { // Make final defensive copies of ClockPanel state data bm = rp.bm.getAndSet( null ); // Use AtomicReference<Bitmap> to atomically assume exclusive ownership of Bitmap } public void run() { // Validate remaining input data renderClockFace(); // Thread terminates when run() completes } public Bitmap getFinalBitmap() { // Ensure renderingCompleted == true return bm; } private void renderClockFace() { // Draw background, clock face // Draw numbers, ticks renderingCompleted = true; } private void drawNumbers( Canvas canvas, float xc, float yc, float radius ) { ... } private void drawTicks( Canvas canvas, float xc, float yc, float radius ) { ... } }

Skeleton Definition of Background Worker Thread


47

Invoking the ClockFaceRendererTask

48


• In order to create and run a clock renderer task in a background thread, we need to create an outer “monitor” thread to:

• Instantiate and start a renderer task • Wait for the renderer sub-task to complete • After the renderer has finished computing a new bitmap, we need to define and post a Runnable task to the GUI handler which will run in the GUI thread and safely adopt the new Bitmap “later”

• This is a bit complex for those new to threads ( consult the books listed on slide 11 for more details ) • Below is a diagram of what the next page’s callRenderer() method is doing...

Non-GUI Worker Thread

Instantiates ClockFaceRendererTask

Starts the ClockFaceRendererTask

Waits for the ClockFaceRendererTask to complete/terminate

Defines a Runnable which must be run in the GUI thread which adopts the newly

computed Bitmap

Posts the above Bitmap adoption Runnable to the GUI Handler which will run “later”

callRenderer() Defines complex thread

callRenderer() Starts outer thread and

returns immediately 2

1

private void callRenderer() { // Called only in onDraw() - returns immediately after defining and starting background worker thread final ClockPanel cp = this; Thread t = new Thread( new Runnable() { public void run() { clockFaceRenderer = new ClockFaceRendererTask( cp ); // ClockFaceRendererTask extends Thread clockFaceRenderer.start(); // Start background renderer task asynchronously ( not in GUI thread ) // Wait for the renderer thread to terminate while ( true ) { try { clockFaceRenderer.join(); // join() waits for thread to terminate break; } catch ( InterruptedException ie ) { } } // New bitmap now computed - now have GUI thread adopt new bitmap reference and redraw itself final Bitmap newBitmap = clockFaceRenderer.getFinalBitmap(); if ( newBitmap == null ) throw new IllegalStateException( "Null bitmap returned from ClockFaceRendererTask!" ); guiThreadHandler.post( new Runnable() { public void run() { RenderParams rp = getCurRp(); rp.bm.set( newBitmap ); computingBitmap = false; invalidate(); } } ); } } ); // End outer thread definition // Start the thread we just defined - then return immediately t.start(); }

Invoking the ClockFaceRendererTask A worker thread launched and managed from within an outer monitor thread

Instantiate and start renderer task thread

Outer thread waits for renderer thread to complete

Outer thread posts a sub-task to GUI Handler to adopt newly computed bitmap which will run

“at a later time” in the GUI thread

49


2

1

3

4

5

Define an outer thread to run in background which, in turn, starts and monitors a nested ClockFaceRendererTask thread

After defining the outer thread, we start it and return immediately

The Builder Pattern

50

Builder Pattern Use

• The ClockPanel attributes can be initialized in many different ways depending on use context. • As a result, providing a Builder pattern to construct ClockPanel objects was implemented. • The main CoolClock Activity creates its ClockPanel component using this code:

ClockState cs = PrefsActivity.getStoredPrefs( this ); // Get settings from previous Cool Clock execution clockPanel = new ClockPanel.ClockPanelBuilder(). // Construct a Builder object

context( this ). // Set desired field values hideSecondHand( cs.hideSecondHand ). hideArcs( cs.hideCircularArrows ). hideDigitalTime( cs.hideDigitalTime ). hideTextTime( cs.hidePhraseTime ). clockOperationMode( cs.clockOperationMode ). minuteNumDisplayMode( cs.minuteNumDisplayMode ). arcMode( cs.arcMode ). buildClockPanel(); // Ask Builder to construct a ClockPanel object

Reinstate the previous field values, then call buildClockPanel() to construct ClockPanel

instance.

Calls private ClockPanel constructor

Note “dot” operator use

51


The ClockPanel Constructor

private ClockPanel( ClockPanelBuilder cpb ) { super( cpb.context ); // Call base class this.curPrefs = cpb.cs; // Data class encapsulating Preferences settings rpLand.orientation = E.Orientation.Landscape; // Data class encapsulating drawing geometry params rpPort.orientation = E.Orientation.Portrait; // Separate RenderParam object for both orientations guiThreadHandler = new Handler(); // Create Handler in the GUI thread curPrefs.enableHandDragging = ( curPrefs.clockOperationMode == E.ClockOperationMode.LearnMode ); setOnTouchListener( this ); // Subscribe to touch events }

52


The only ClockPanel constructor accepts a ClockPanelBuilder argument:

Builder Pattern Implementation public static class ClockPanelBuilder { // Nested static class in ClockPanel.java // Reference to CoolClock Activity ( needed by ClockPanel ) private Context context; // Start with default clock param values public ClockPrefs cs = ClockPrefs.defaultClockPrefs(); public ClockPanelBuilder() { } public ClockPanelBuilder context( Context context ) { this.context = context; return this; } public ClockPanelBuilder hideHourHand( boolean hideHourHand ) { cs.hideHourHand = hideHourHand; return this; } public ClockPanelBuilder hideMinuteHand( boolean hideMinuteHand ) { cs.hideMinuteHand = hideMinuteHand; return this; } public ClockPanelBuilder hideSecondHand( boolean hideSecondHand ) { cs.hideSecondHand = hideSecondHand; return this; } public ClockPanelBuilder enableHandDragging( boolean enableHandDragging ) { cs.enableHandDragging = enableHandDragging; return this; } public ClockPanelBuilder hideDigitalTime( boolean hideDigitalTime ) { cs.hideDigitalTime = hideDigitalTime; return this; }

public ClockPanelBuilder hidePhraseTime( boolean hidePhraseTime ) { cs.hidePhraseTime = hidePhraseTime; return this; } public ClockPanelBuilder hideCircularArrows( boolean hideCircularArrows ) { cs.hideCircularArrows = hideCircularArrows; return this; } public ClockPanelBuilder minuteNumDisplayMode( E.MinuteNumDisplayMode minuteNumDisplayMode ) { cs.minuteNumDisplayMode = minuteNumDisplayMode; return this; } public ClockPanelBuilder arcMode( E.ArcMode arcMode ) { cs.arcMode = arcMode; return this; } public ClockPanelBuilder digitalTimeMode( E.DigitalTimeMode digitalTimeMode ) { cs.digitalTimeMode = digitalTimeMode; return this; } public ClockPanelBuilder clockOperationMode( E.ClockOperationMode clockOperationMode) { cs.clockOperationMode = clockOperationMode; return this; } public ClockPanel buildClockPanel() { if ( context == null ) throw new IllegalStateException( "Context field must be non-null before calling buildClockPanel()!" ); return new ClockPanel( this ); // Call private constructor } }

53


Cool Clock Helping children to read analog clocks

An introduction to developing custom 2D graphics Android applications

Richard Creamer 2to32minus1 @gmail.com

54


Links Home Page

LinkedIn Profile Android Market Cool Clock Product Listing

External Cool Apps Software Website External Cool Clock Product Details Page



http://www.linkedin.com/in/rickcreamer

http://market.android.com/details?id=net.maxuint32.coolapps

http://sites.google.com/site/coolappssoftware

http://sites.google.com/site/coolappssoftware/products/cool-clock

Technology

Case Study: Cool Clock - An Intro to Android Development