Architecting a single apk app to handle phones and tablets on Android

Update: There is a problem with this method. It appears that the Android framework will not pickup the bool values using any type screen size modifier (e.g. sw600dp or xlarge) because they can change at runtime. It won’t give you an error, instead it’ll just completely ignore the resource and default to true. You can of course achieve the same results in other ways but unfortunately they’re not quite as clean as what i had hoped to achieve below. Sorry!

I already created a tablet app a while back when Honeycomb was first released but since then I’ve been working on phone only applications. Between then and now, the compatibility library has been released and a new way of handling screen sizes has been introduced into the Android framework. Below is a recipe on how to use these features to architect a single apk app that will run on both phone and tablets. Credit to Nick Butcher for inspiration from his talk at Droidcon UK 2011.

1) Encapsulate the functionality that you had (or would have) in your activities into Fragments
A Fragment is, generally, a chunk of a user interface with it’s own lifecycle.  This sounds similar to how you might describe an activity doesn’t it? In fact, if you’re adapting an existing app, you can pretty much cut and paste your code from your old activity into your new Fragment. Then your old activity is only responsible for instantiating your new Fragment and listening to any events that it might trigger.

2) Create completely separate Activities to handle single pane layouts vs dual pane layouts (i.e. phone vs tablet)
Don’t think about hdpi, large or xlarge buckets any more. Think more like a responsive web designer e.g. here is my single pane layout for screens less than 600dp and here is my dual pane layout for screens wider than 600dp.

By way of example, an imdb style app might have two fragments: MovieListFragment (to show a list of movies) and MovieDetailFragment (to show the movie detail).

When designing for the single pane layout (e.g. for phones) you would most likely have two activities:

• SingleMovieListActivity – which is where the MovieListFragment would live and
• SingleMovieDetailActivity - which is where the MovieDetailFragment would live

Pretty simple eh? For the dual pane layout (e.g. tablets) you would have something like:

• DualHomeActivity – which would house both Fragments; MovieListFragment (on the left) and MovieDetailFragment (on the right).

Keeping them separate means that you don’t have messy code within your activites to detect which screen mode you are in before you can show or act on anything.

3) Use the (force) framework
You don’t need a splash activity to detect how many pixels are on screen before you forward to an appropriate starter activity. Simply add something like android:enabled=”@bool/single_pane” to any single pane activity elements within your Android Manifest. Then create the file res/values/bools.xml with the following contents:

<?xml version="1.0" encoding="utf-8"?>
<resources>
<bool name="dual_pane">false</bool>
<bool name="single_pane">true</bool>
</resources>

Handling the dual screen activities is also quite simple. Add android:enabled=”@bool/dual_pane” to any dual screen activity elements within your Android manifest. Then create the file res/values-sw600dp/bools.xml with the following contents:

<?xml version="1.0" encoding="utf-8"?>
<resources>
<bool name="dual_pane">true</bool>
<bool name="single_pane">false</bool>
</resources>

Now if your app is started on a device that has a width of at least 600dp (e.g. a tablet) then the framework will enable all of your dual pane activities and disable all of the single pane ones. Conversely, if your app is started on a device with less than 600dp then all single pane activities will be enabled and the dual pane ones will be disabled.

Note that the sw600dp modifier will only work for Android 3.2 and above so you should also copy the above bools.xml to res/values-xlarge/bools.xml to cater for the extra large screens in older versions of Android.

4) Decouple communication
So you have all these reusable fragments…but they can exist in different activities depending on whether you’re running on a device that has a width of more or less than 600dp. How does your fragment know whether to transition to a new screen or whether to animate in a new fragment when a movie is selected? The answer of course is that it doesn’t and shouldn’t.

The enclosing activity knows whether you are in single vs dual pane mode so you need a clean way to communicate your event (e.g. movie selected) to this enclosing activity. There are a few ways to do this but my favoured way is to use Broadcast Intents. Your enclosing activity (which is listening for these defined events) can intercept a broadcast intent and associated parameters and then decide whether to transition to a new activity (if in a single pane activity) or whether to replace the currently showing MovieDetailFragment (if in a dual pane activity).

Simples.

Show right-to-left Activity Animation when you click Home icon in your Android App (Dashboard Pattern)

Want to animate your activity from right to left when you click the home icon in the top left corner of your app?

Simples:

public static void goHomeTop(Activity context) {

final Intent intent = new Intent(context, HomeActivity.class);

intent.setFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);

context.startActivity(intent);

context.overridePendingTransition(android.R.anim.slide_in_left, android.R.anim.slide_out_right);

}

Resetting OS X Lion back to factory settings

There seems to be a lot of confusion about how do this. Actually it’s pretty easy:

1. Reboot your machine and hold down CMD+R.
2. Choose the option relating to Disk Utility and erase the Macintosh HD.
3. Close Disk Utility and from the list of options, reinstall Lion.

(Note, you’ll need to hook up your machine to a wifi Hotspot so that it can download the entire Lion image from the internet…zzzzzzz)

 

Install sqlite3 on your rooted Google Nexus One / Nexus S

Please note that all credit goes to Sun Chen for this solution (blogpost here: http://chensun.net/android-development/install-sqlite3-on-google-nexus-one/54/).

I simply applied the same technique to my Nexus S and have reproduced the steps below for my own future benefit.

[Notice! You must have root access on your Nexus One / Nexus S.]

1. Download sqlite3, which comes with SuperOneClickv1.7-ShortFuse, and copy it to your SD card.

2. Connect your phone to your computer. Open a Command Prompt, and type the following commands:

adb shell
$ su
# mount -o remount,rw -t yaffs2 /dev/block/mtdblock3 /system
# dd if=/sdcard/sqlite3 of=/system/bin/sqlite3
# chmod 4755 /system/bin/sqlite3
# mount -o remount,ro -t yaffs2 /dev/block/mtdblock3 /system

Done! Now you can use sqlite3 to examine database on your Nexus One / Nexus S from a Remote Shell or even from an Android Terminal Emulator.

Integrate zxing barcode scanner into your Android app natively using Eclipse

Update: Please note that this tutorial was written over a year ago. ZXing has moved on quite a bit since then as have the Android Developer Tools. I haven’t had time to revisit and update the post but it should give you a good steer in the right direction. Some of the comments at the bottom may be able to help you out if you encounter any troubles.

Edit: Sean Owen, one of the developers for ZXing has posted a comment to this blog warning of the pitfalls of integrating ZXing into your own app; doing so just to avoid having your users take that extra step of installing from the market is not a good reason. I completely agree with this. There are many advantages to using the intent based approach as outlined in his comments. My motivation is for an enterprise app that does not have access to the Android market and involves my client installing zxing manually on thousands of devices before they are able to distribute to its business customers.

So to be clear, do not use this method unless it is absolutely necessary, and if you do have to – make sure that override your intent filters so that other apps that want to use zxing do not end up calling your modified version. Also, if zxing is already installed, then you should use that by default instead of your modified version.

ZXing is one of the most popular barcode scanning applications on the market. They make it very easy for you to integrate into your application via an intent but this means that your users must manually install the application from the market.

Fortunately, the app is also open source so I will show you how to cleanly build this capability into your project.

Please note that the awesome developers of this product have released the src under the Apache v2.o license so please be sure to adhere to the terms of this license and give them full credit for their work. http://www.apache.org/licenses/LICENSE-2.0

Step One: Obtain the zxing src code
The src can be found at http://code.google.com/p/zxing/source/browse/trunk. Specifically you only need the android/ and the core/ projects. Use svn to checkout these to your local hard-drive.

Step Two: Build zxing core using Apache Ant
You will need to build the core project into a jar file using apache ant (download from here http://ant.apache.org/ivy/download.cgi). Using a shell or cmd prompt navigate to the root directory of the downloaded zxing src and execute ”ant -f core/build.xml”. This will produce a file core/core.jar which we will use in the next step.

Step Three: Build ZXing Android using Eclipse
Create a New Android Project (File –> New –> Android Project).
Set the project name to ZXing (or similar).
Select the “Create project from existing source” radio button
Click “Browse” and navigate to the android project that you downloaded from zxing and click “OK”
Select “Finish”

The project will not currently build. We need to add the core.jar file (that we produced in the previous step) into our project. Right-click on ZXing project –> properties –> Java Build Path –> Add External Jars –> Navigate to and select core.jar –> Open –> OK.

Actually, while we’re here we should do one more very important thing! Right-click on ZXing project –> properties –> Android –> Scroll down and check/tick the “Is Library” checkbox –> OK.

Step 4: Include ZXing Android into your project.
Within Eclipse,  Right-click on YOURPROJECTNAMEHERE project –> properties –>Android –> Scroll down to Libraries section –> Click Add –> Select ZXing (which should appear as an option as a result of completing previous step).

Next, in some trigger function e.g. button press within your code you should add:

Intent intent = new Intent("com.google.zxing.client.android.SCAN");
intent.putExtra("SCAN_MODE", "QR_CODE_MODE");
startActivityForResult(intent, 0);

In the same activity you’ll need the following to retrieve the results:

public void onActivityResult(int requestCode, int resultCode, Intent intent) {
   if (requestCode == 0) {
      if (resultCode == RESULT_OK) {
         String contents = intent.getStringExtra("SCAN_RESULT");
         String format = intent.getStringExtra("SCAN_RESULT_FORMAT");
         // Handle successful scan
      } else if (resultCode == RESULT_CANCELED) {
         // Handle cancel
      }
   }
}

Almost there! One of the current limitations of Android Library projects is that it will not pull anything from AndroidManifest.xml into your project.
So if we try to invoke the above code we will receive a runtime exception because your Android app has no idea how to handle the scan intent.
To fix this you just need to copy the following into your AndroidManifest.xml:

<activity android:name="com.google.zxing.client.android.CaptureActivity"
   android:screenOrientation="landscape"
   android:configChanges="orientation|keyboardHidden"
   android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
   android:windowSoftInputMode="stateAlwaysHidden">
   <intent-filter>
      <action android:name="android.intent.action.MAIN"/>
      <category android:name="android.intent.category.DEFAULT"/>
   </intent-filter>
   <intent-filter>
      <action android:name="com.google.zxing.client.android.SCAN"/>
      <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

And as Columbo would say, “Just one more thing!”. Add this permission to the top of your AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA"/>

EDIT: You need to do yet one more thing! You need to add the core.jar (produced in Step two) to your new project (Right-click your project –> Properties –> Java Build Path –> Add External JARS… –> Select core.jar –> OK). Thanks to Marco and Markosys in the comments for spotting and pointing out the omission!

Start animation in onCreate or onResume on Android?

Maybe you’d like to perform a nice subtle animation such as fading some text in as soon as your activity launches? If you try to start this animation in onCreate() or onResume() you’ll be sorely dissapointed.

One possible solution is to set a timer in one of these methods so that the animation will spawn after a fixed interval.  This approach is problematic because if the delay is too short the animation won’t start (as before) and if it’s too long then the user experience will drop. Furthermore, such a delay might not behave quite the same on a G1 compared to a spanking new Samsung Galaxy S II for example.

A better way is to start the animation in the onWindowFocussedChanged method which is called when the current window of the activity gains or loses focus and gives the best indicator whether the activity is visible to the user. You can use the *hasFocus* parameter to distinguish between gaining or losing focus. Example below:

   private TextView myTextView;

   /** Called when the activity is first created. */
   @Override
   public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_home);

        myTextView= (TextView)findViewById(R.id.my_textview);

        anim = AnimationUtils.loadAnimation(this, R.anim.fade_in);
    }

   @Override
   public void onWindowFocusChanged (boolean hasFocus) {
      super.onWindowFocusChanged(hasFocus);
      if (hasFocus)
         myTextView.startAnimation(anim);
   }

The animation itself is defined in an xml file in res/anim/fade_in.xml:

<?xml version="1.0" encoding="utf-8"?>
<alpha xmlns:android="http://schemas.android.com/apk/res/android"
       android:interpolator="@android:anim/accelerate_interpolator"
       android:fromAlpha="0.0" android:toAlpha="1.0"
       android:duration="1500" />

Alternative to strings.xml for storing settings values in Android

This may be obvious to some but not me. ..

Like a good little programmer, I use strings.xml all the time in my Android applications which means that this file can get quite large. For a customer that wanted to be able to modify some settings before recompiling and distributing to their customers, I wanted to extract those variable “settings” into a different file for clarity.

It’s actually extremely easy to do. So easy that I thought it couldn’t possibly be that easy and started exploring more complicated routes.

All you have to do is create a new xml file e.g. “settings.xml” and then move your string value (e.g. <string name=”default_retry_time_value”>10</string>) from “strings.xml” into this new file.  That’s it!

You don’t need to update any views in your layouts to do to something like this android:text=”@settings/default_mcode_value”.

You just need to make sure that your settings.xml file is in res/values (same place as strings.xml) and Android will pick it up.