Wednesday, September 4, 2013

How to Run the Android Support Library Samples (Eclipse Version)


 How to Run the Android Support Library Samples (such as ActionBar) in Eclipse

Prerequisite:
First, make sure you have installed the necessary plugins for Android Development such as ADT.  Here is the official information from Google on how to get the plugins installed in Eclipse.

What are the Android support libraries?  They are .jar files or eclipse projects that let you access the latest features in the Android SDK on older devices such as Fragments (v4) or ActionBar (v7) support.  The v4 library requires a minimum SDK of 4 or Android 1.6, the v7 library requires a minimum SDK of 7 or Android 2.1, and so on.

So you want to support the older Android phones and start by running the support library samples (v4, v7, v13, AppNavigation, ActionBar, etc), but can't find the instructions from Google?  You'll need to download the Android Support Library, create a blank library project, import the existing android code (for v7 support), fix up the created library projects, create a blank project, import the sample demo code, and finally link the support library to your demo.

Also, there is a gotcha to watch out for when using the ActionBar that I experienced where the android:showAsAction values in your menu.xml are ignored and must be set at runtime.  See below for details.

Get the Support Library


Load the support package (and at least API 19) through the Android SDK Manager



After the download is finished, this will be in:{android_sdk}\extras\android\support\
The {android_sdk}\extras\android\support\samples\ folder contains the samples that we will import.  The path to your SDK is listed under SDK Path in the Android SDK Manager tool.
The v4, v7, v13 include the support library for whichever minimum SDK you are willing to support.  i.e. when using the v7 library, the min SDK should be set to 7.  The min SDK should be 13 when using the v13 library.

To install the Android Support v4 Sample Demo


Follow this excellent guide by Tek Eye.  The guide by Tek Eye allowed me to install the samples and get them going, but it did not have an entry for the Android Support v7 Demos, which are a bit trickier to get going.
NOTE: The latest copy of the Android Samples v4 required setting the build target to API 19 or removing the attribute in the Support4Demos/res/drawable/ic_drawer.xml marked "android:autoMirrored='true'"

To install the Android Support v7  Samples Demo

Create a New Eclipse Project to Store the v7 Support Library

You'll be creating a blank project and using this to import the support library as an android library project.  Choose File / New / Android Application Project



Uncheck the 'Create custom launcher' and the 'Create activity' icon, but
Check the 'Mark this project as a Library'



Now, load the support library.  Select File / Import... and choose 'Existing Android Code into Workspace'
Browse to the {android-sdk}\extras\android\support\v7 folder and select Copy projects into workspace if you want.



That will give you 4 new projects in your Eclipse workspace.  But they are not quite ready to use yet.  Also the android-support-v7-mediarouter will have an error that you will need to resolve.

To Fix Up the Android Support Library v7 Dependancies

You should now have 4 new projects:
android-support-v7-appcompat
android-support-v7-gridlayout
android-support-v7-mediarouter
AndroidSupportV7

Expand the libs folder of each library, right-click on each jar and select Build Path / Add to Build Path

Now you will also need to export the jars when projects are linked against this library



Go to Build Path / Configure Build Path and on the 'Order and Export' tab, check the support jars and uncheck Android Dependencies.  Do this for each library: android-support-v7-appcompat, android-support-v7-gridlayout, & android-support-v7-mediarouter.

Now, at this point, android-support-v7-mediarouter will still have a red mark on it with the error: error: Error retrieving parent for item: No resource found that matches the given name 'Widget.AppCompat.ActionButton'.

Link the android-support-v7-appcompat library to the android-support-v7-mediarouter


The android-support-v7-mediarouter has some dependencies on the android-support-v7-appcompat library, so we will need to link the projects.

Click on properties of the android-support-v7-mediarouter project. 
Select the Android page
Add... the android-support-v7-appcompat library

Now do a Project / Clean / All and the Support Library v7 should be clean of errors and your support library is ready to go.

NOTE:  The support library install instructions were adapted from the Android developer page here.
 

Create a New Eclipse Project to Store the v7 Demo Sample


Choose File / New / Android Application Project



Uncheck the 'Create custom launcher' and the 'Create activity' icon.



Right Click on the project and select Import...  
Pick General / File System

Select the {android-sdk}\extras\android\support\samples\Support7Demos
Check the res, src, and manifest files.

Link the project to the Android Support Library v7:
Click on properties of the SupportV7Demo project. 
Select the Android page
Add... the android-support-v7-appcompat library
Add... the android-support-v7-gridlayout library
Add... the android-support-v7-mediarouter library

Wow, now that all those steps are completed you should be able to compile and install the Android Support Samples to your Android device.

That's it!  The same technique can be used to install the Android Support v4 Library and Samples or the App Navigation Samples.

Note: As one observant reader noticed below, this leaves you with an extra AndroidSupportV7 library project that Eclipse created during the import process that is not used.  You can delete it, or add the libraries above (appcompat/gridlayout/mediarouter) into it so that you only need to import one combined project instead of three separate ones.

General Support Library Notes:

One anonymous comment noted if you are having troubles with a project, check that you have the Target SDK Version in the manifest set to at least 19.  This is found in Eclipse under Project properties / Android / Project Build Target to API 19 or higher.

To use the v7 files, copy these to your project's /libs folder.
  •     android-support-v4.jar
  •     android-support-v7-appcompat.jar
  •     android-support-v7-gridlayout.jar (*if needed)
  •     android-support-v7-mediarouter.jar (*if needed)

Typical gotchas for people:
  •     Make sure the min SDK is at least API 7
  •     Make sure the project target build is at least API 19

What to do next:


To learn more about database and network usage with android, check out the WorxForUs Android Database and Networking framework tutorial that assists database access and network access and addresses several common pitfalls.

Hope you found this guide useful, please drop a note, funny internet cat picture, or +1 if it helped.

ActionBar Gotcha Notes:

If you have trouble getting the ActionBar to display icons instead of just overflowing, check where you are setting the showAsAction values.  In the menu_layout.xml, the showAsAction attribute is ignored when using the support library and won't work.    <item
        android:icon="@drawable/ic_action_add"
        android:id="@+id/rci_action_add_mitem"
        android:title="@string/rci_action_add"
        android:showAsAction="ifRoom" //this will not work
    />


To fix this, add the show as action items in the options menu creation function
    @Override
    public void onCreateOptionsMenu(Menu menu, MenuInflater inflater) {
        inflater.inflate(R.menu.menu_layout, menu);
        MenuItem add = menu.getItem(0);

        //Set the show as action value here at runtime
        MenuItemCompat.setShowAsAction(add, MenuItemCompat.SHOW_AS_ACTION_IF_ROOM);
    }