Android Fragment Tour

The time has come to embrace Android fragments, especially since well over half of devices are now on Android 4.x.  There are many tutorial applications available and here is one more on the pile.  This post and supporting example application demonstrate:

• Use of Android fragments (i.e. Fragment, ListFragment, DialogFragment or PreferenceFragment.
• Navigation between fragments and activities
• Use of the ActionBar, TabListener and menu support.
• Use of Custom ArrayAdapter
• Use of Custom CursorAdapter
• Using a ContentProvider/ContentResolver and Loader
• Use of maven

Complete application sources are available on github, the demonstration application was created on API 16 using Android Studio (thanks, JetBrains) and includes maven support.  This demonstration does not use the compatability libraries so you will need API 14 or later to successfully run.

At application start you should see these:

Tab 1

Tab 2

Tab 3

Tab 4

Tab 1 represents a simple form implemented as a Fragment.  (source)

Tab 2 illustrates a simple scrolling list of US states implemented as a ListFragment (source) with a resource (source) for the data source.  A short press on a row brings up a detail view (source) and a long press prompts for delete.  Short/long press interaction requires the use of a custom listener (source) to dispatch a request to MainActivity (source) for service.  The delete is not actually performed, but does provide an opportunity to illustrate the use of a PreferenceFragment (source)

Tab 3 is another ListFragment (source) example, this time w/a custom ArrayAdapter (source) and multiple row types (you can see from the above image there is a simple row w/a hex string and a more complex row w/radio buttons). The data source for Tab 3 comes from a ContentProvider (source) whose values are randomly generated at application startup (source).  One final feature of this example is that it employs a list header (source) and footer (source).  The footer contains a EditText and Button widgets which can be detected within ThreeFragment.java (source)

Tab 4 is yet another ListFragment example (source), this time w/a custom CursorAdapter (source) which employs a Loader fed from the ContentProvider (source).  As shown in the illustration, the row type consists of an image and a string.

All of these Fragments are "owned" by MainActivity (source) which also provides the ActionBar at the top of the display.  The ActionBar provides the tabs which are used for navigation between Fragments.  The tab navigation code resides within TabHelper (source).

About

Settings

Depending upon your phone, you might see three vertical dots at the top right of the display (or you might have a menu key).  There are two menu options, one for an "About" display and the other for "Settings" (user preferences).  Option menu dispatch is provided by MainActivity which invokes MenuActivity to display the menu fragments.

Note that MenuActivity (source) does not have tab navigation, so when a user selects a menu option the only way to return is the "back" button or by pressing the "FragDemo" icon on the ActionBar (top left). 

The "About" Fragment (source) is implemented as a WebView w/the HTML supplied as part of the application.

The "Settings" Fragment (source) is an example of a PreferenceFragment.

FragmentDemo can be built and deployed entirely from the command line using the Android maven plugin.  I created FragmentDemo using the "Android-QuickStart-Archetype as described here which was quite helpful.

What to code after "Hello, Android"

This post is for those of you who have decided to join the thundering herd of computer nerds who have decided to code for Android.  "Hello, Android" was easy... what happens next?

How about the "Three Activity" project?  The "Three Activity" application demonstrates

• Navigation between three separate displays (each backed by a dedicated Activity)
• How to pass arguments between Activity(s)
• How to create and use a Button
• How to create and use an EditText
• How to use Android log statements
• Special guest appearance w/AndroidManifest.xml

The "Three Activity" project is a simple application consisting of the three Activity(s) shown below.

StartActivity

MiddleActivity

EndActivity

Complete source code for this example is contained on GitHub

Google Web Toolkit - First Steps

Here is a short posting about Google Web Toolkit (GWT) w/a simple example application.  Like any other evolving framework, GWT is a moving target.  This posting was created in December, 2012 using GWT 2.5.0 - hopefully fresh enough for your needs.  The key GWT components I wanted to explore include the Place, Activity and UiBinder classes.

The example GWT application is available from GitHub and should easily import into eclipse (and deploy to Google App Engine).

Below is a screenshot of the sample application, which illustrates a common use case: a banner image along the top and footer along the bottom w/a navigation bar on the left.  The remaining (center space) is for content.  Pressing a button within the navigation bar will cause the content panel to update.

Below is a UML class diagram to introduce the components of the sample application.

You can browse the sources at GitHub.  A brief tour of the sources follows.

GwtDemo1 extends EntryPoint, which is the usual entry point for a GWT module.  I create an instance of AppShell and dispatch control via the run() method.

AppShell must persist for the duration of the application since it holds references to EventBus and various mappers that glue the application together.  The run() method binds RootView to the RootLayoutPanel (as discovered from GwtDemo1) which will cause RootView.ui.xml to be displayed.  (The *.ui.xml files are all XML UiBinder files).  

Creating RootView.ui.xml will also create NavigationBar.ui.xml which contains the Hyperlinks necessary to update the content panel.

At this point the application is displayed and waiting for a Hyperlink event.

The sequence diagram below introduces event flow.

Working from left to right on the sequence diagram, start w/the Hyperlink (contained within NavigationBar.ui.xml).  Pressing a Hyperlink will generate a History frame which is delivered to HistoryHandler for distribution to the PlaceController.  PlaceController causes a PlaceChange event to be delivered to the ActivityManager which consults AppPlaceHistoryMapper and ContentActivityMapper to determine which Activity should be employed to update the content panel.

The diagram only shows "Content1" selection but the same process is simply replicated for Content1..Content4 scenarios.

ContentActivityMapper returns Content1Activity to ActivityManager which in turn invokes start().  This action will cause Content1View (and companion UiBinder) to be instantiated and then applied to RootView which causes the content panel to update.

I hope you find some utility w/the example.  Good luck and enjoy GWT.

(Yet Another) Android NDK Blog Posting

The Android NDK (Native Developers Kit) augments the Android SDK and enables one to create portions of a Android application using C or C++ (you knew that or you would not be reading this).

This blog post provides an introduction to NDK along w/some anecdotes and a working Android application.

Note that I am writing this in March of 2012. The current SDK is version "r16" and the current ndk is version "r7b". My examples should be valid for the current versions. As always, these examples might not age well so YMMV.

Some of you might be surprised to discover that Java existed before Android (relax, it's a joke). Java has always provided a mechanism to integrate with C/C++ applications called JNI (Java Native Interface). Wikipedia provides a decent overview of JNI and Sun (now Oracle) provides a comprehensive introduction to JNI here. Serious developers will want to read the "JNI Specification" (also available of the Oracle web site.

At runtime, your C/C++ objects will be linked and executed using the JVM. There is a cost to transition the Java/C barrier, make sure you do enough work on the C side to make the transition worth while. Of course, if you include JNI then you have excluded portability (because the C/C++ files must be compiled for every target platform). Portability is not much of a concern for Android since most targets are ARM platforms.

In the early days of Java, JNI was a frequent requirement because many vendors had not yet created Java friendly libraries. The usual steps were:

1. Create "native" Java methods to wrap around C functions. I usually collect these in a common class called "JniWrapper" (or "NdkWrapper" for Android).
   
2. Use the "javah" utility to generate a C header file based upon the contents of "JniWrapper" (i.e. "javah -jni java.class")
   
3. Write a C wrapper to act as a bridge between C and Java, the contents of the wrapper correspond to the generated header file (from step 2). Variable conversion, etc. between C/Java is typically performed here.

The above looks rather straight forward (and it is) but in practice some projects were quite difficult to complete and make stable (different threading models, etc). As Java came to dominate, there was better support for Java and less of a reason to employ JNI. Thanks to Android, this issue is receiving much more attention.

When I design a JNI application, I break the functionality down into three use cases:

1. Java invokes C (most common example)
   
2. C invokes Java (frequently asynchronous callbacks)
3. Shared variables (visible to both C and Java)

I have created a sample Android NDK application to illustrate these use cases which can be found on GitHub (more about the example later).

Another design issue relates to using objects as arguments. In general, I try to avoid using complicated containers as arguments. Instead I favor primitive types such as int (not Integer). Strings are the exceptions and JNI provides convenience mechanisms for handling String.

Now create a Java class to act as the interface between Java and C. Your C methods will be invoked by Java methods marked as "native" (these look like "abstract" methods). This class should also contain a call to "System.loadLibrary()" which will cause your C/C++ objects to be loaded within the JVM.

The "javah" utility will generate a C header based upon "native" declarations within a Java class file. The resulting file looks something like this:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class com_digiburo_example_native_demo_NdkWrapper */

#ifndef _Included_com_digiburo_example_native_demo_NdkWrapper
#define _Included_com_digiburo_example_native_demo_NdkWrapper
#ifdef __cplusplus
extern "C" {
#endif
/*
* Class: com_digiburo_example_native_demo_NdkWrapper
* Method: nativeSetup
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_com_digiburo_example_native_1demo_NdkWrapper_nativeSetup(JNIEnv *, jobject);
#ifdef __cplusplus
}
#endif
#endif


Note these important features:

1. The "jni.h" file which is distributed w/the JDK and provides Java data type definitions, etc.
2. JNIEXPORT and JNICALL are macros defined within jni.h
   
3. The C method name looks like a Java signature (i.e. package name, method name).
   
4. The C function will always have at least two arguments: the "JNIEnv" pointer and the "jobject" reference. "JNIEnv" points to the virtual machine and "jobject" points to the Java class which invoked the native method (frequently described as similar to "this").
   
5. Remember the JVM cares about method signatures. Item #2 and item #3 come directly from the "native" declarations in Java and must match exactly or your method will not be invoked.

Android NDK relies upon JNI and also provides Android toolchains, i.e. cross compilers for ARM/Intel targets and related libraries along w/a build environment that easily integrates your compiled C/C++ code into an Android APK. There are also a variety of sample applications which are worth your review.

While designing your NDK application note that only a small collection of libraries are distributed w/the NDK (library population varies w/NDK version). For example, I recently needed JPEG support but libjpeg.so is not part of the NDK. In this case you might have to build the libraries you need (be sure to build them using the appropriate cross compiler, etc). In my case I simply used the libjpeg headers and library from the Android platform sources. The point is: until you are a NDK master be sure to pad the schedule in case there is a surprise.

To integrate JNI w/your Android application is simple enough with recent versions of the NDK. Simply create an Android application in eclipse, then create a "jni" directory. The "jni" directory should be a peer to "src", "res", etc. and acts as the root directory for your C/C++ sources.

Eclipse also provides a C/C++ environment which will be handy for flipping between XML, Java and C/C++. My own preference is to do heavy lifting in emacs and my compiles on the command line.

To continue w/implementation, copy the "javah" generated header file to the "jni" directory and craft a source file to support it.

The Android NDK provides a build system which greatly simplifies integrating w/a Android application. Build directives are contained within the "Android.mk" and an optional "Application.mk" files.


#example Android.mk
LOCAL_PATH := $(call my-dir)
#
include $(CLEAR_VARS)
#
LOCAL_CFLAGS := -fexceptions
#
LOCAL_MODULE := digiburo-bridge
LOCAL_SRC_FILES := NdkWrapper.cpp
#
LOCAL_LDLIBS += -llog
#
include $(BUILD_SHARED_LIBRARY)

Note these import features:

1. LOCAL_MODULE defines the name of your C/C++ library. This must match the name specified in System.loadLibrary().
2. LOCAL_SRC_FILES define source files
   
3. LOCAL_LDLIBS specifies link path (in this case to Android logging).

Compile within the "jni" directory by typing "ndk-build" which is a utility supplied w/the NDK.

Assuming a successful compile, you should see the results within your Android project in the "libs" and "obj" directories.

At this point you should be able to deploy and run your Android application using both Java and C.

I have created a sample Android NDK application called "NativeDemo" which is available from my GitHub repository. NativeDemo provides examples for:

1. Java calls C (NdkWrapper.nativeSetup(), NdkWrapper.nativeString(), NdkWrapper.nativeAdder())
2. C invokes Java (NdkWrapper.nativeVectorDemo() and NdkWrapper.callBack())
3. Shared variables (NdkWrapper._nativeBuffer)
4. Exception handling (NdkWrapper.exceptionDemo())
5. Demonstration of JNI_OnLoad() and JNI_OnUnload()
   

To compile and run NativeDemo:

1. You need all the usual Android development tools such as eclipse, Android SDK, ADT plugin and of course the Android NDK.
2. Import my git repository into your eclipse workspace.
3. From the command line, enter the "jni" directory and type "ndk-build" assuming you have the NDK, etc this should compile NdkWrapper.cpp and place the results in the "libs" and "objs" directories.
4. Now run the application from eclipse, it should deploy like any other application.
5. To see the results, use "adb logcat" - note that log messages are generated both from Java and from NdkWrapper.cpp
   

Hope this saves you some time. Good luck!

BeagleBoard for Android

I wanted to learn more about Android internals without risking my phone. At first, I briefly considered the $399 dev phone offered by Google, but decided it would be more fun to have an evaluation board/kit rather than a complete device.

There were several candidates but I quickly settled on the BeagleBoard-XM as sold by DigiKey for USD 149. (LiquidWare had a booth at the San Mateo Maker Faire, and I was sorely tempted to purchase a Beagle embedded starter kit. Perhaps later...)

The BeagleBoard site is a great resource and there is not much I can add beyond my personal anecdotes.

What you get for $149 is a anti-static bag containing a small (approx 3 inch x 3 inch) PCB and a microSD card. There are no cables supplied.

You can get a quick test of the board w/a RS-232, a USB cable and your trusty PC.

First, install the microSD card which came w/the BeagleBoard.

Second, the USB cable provides power, use the OTG ("On The Go") connector on the BeagleBoard. You should immediately see some LED's light up.

Third, connect the RS-232 cable between the BeagleBoard and your PC. I am using Ubuntu 10.04 LTS w/MiniCom as a console. This step might take some experimentation, but it is working for me at 115200 8N1.

There are two buttons on the PCB next to the USB sockets. (There is a BeagleBoard manual available as a PDF which illustrates the components). Press "reset" to stimulate console activity.

Here is a screen shot of the TI X-Loader starting to boot...

Now that you have at least some interaction w/the BeagleBoard you can start adding additional devices.

I purchased a HDMI cable in order to connect an old monitor to my BeagleBoard. I also use USB keyboard and USB mouse to interact w/the BeagleBoard.

The BeagleBoard readily supports a variety of platforms, right now I am most interested in TI arowboat Android distribution (I expect to describe building arowboat in my next post).

Java Date Math

Daylight savings time happens this weekend which provides a certain moment of truth for applications which must calculate the days between dates.

There are 86400 seconds in 24 hours. A typical solution might be to convert the days to seconds since the epoch, then subtract them yielding the difference between days in seconds, then divide by 86400 to obtain the days.

This algorithm fails because not all days are of the same duration.

Julian dates offer a solution. Each day has a unique integer value and caculating the difference is a simple matter of subtraction. Astronomers also use a "julian date" - which represents time and date as a float. (Note: if an integer julian date triggers your Aspergers, please spare me the email. I know the difference).

Example Gregorian/Julian routines are available in Numerical Recipes. Here is a Java class which performs the same functions.

To calculate the days between two dates:

DateMath dm = new DateMath();
int jd1 = dm.gregorianToJulian(calendar1);
int jd2 = dm.gregorianToJulian(calendar2);
int delta = jd1-jd2;

Junk Or Repair?

I have serveral Princeton monitors, including two VL-1919 monitors on my main LINUX development box.

The power supplies on these monitors do not age gracefully, and I was a little irritated when both of my VL-1919 started to flake out within weeks of each other.

To my surprise, there is someone who repairs these power supplies: go to eBay and search for "resurrectek" - they do a variety of repairs for a fixed rate.

For $29 each I now have two happy monitors instead of $100+ for two new tubes plus the ewaste from my old displays.

Back to work...