Android Adapters: an introduction

An Adapter object acts as a bridge between an AdapterView and the underlying data for that view. The Adapter provides access to the data items. The Adapter is also responsible for making a View for each item in the data set.

An AdapterView is a view whose children are determined by an Adapter.

Some examples of AdapterViews are ListView, GridView, Spinner and Gallery.

There are several types or sub-classes of Adapter:

ListAdapter: Extended Adapter that is the bridge between a ListView and the data that backs the list. Frequently that data comes from a Cursor, but that is not required. The ListView can display any data provided that it is wrapped in a ListAdapter.


ArrayAdapter: A ListAdapter that manages a ListView backed by an array of arbitrary objects. By default this class expects that the provided resource id references a single TextView.


CursorAdapter: Adapter that exposes data from a Cursor to a ListView widget. The Cursor must include a column named "_id" or this class will not work.


HeaderViewListAdapter: ListAdapter used when a ListView has header views. This ListAdapter wraps another one and also keeps track of the header views and their associated data objects.
This is intended as a base class; you will probably not need to use this class directly in your own code.


ResourceCursorAdapter: An easy adapter that creates views defined in an XML file. You can specify the XML file that defines the appearance of the views.


SimpleAdapter: An easy adapter to map static data to views defined in an XML file. You can specify the data backing the list as an ArrayList of Maps. Each entry in the ArrayList corresponds to one row in the list.


SimpleCursorAdapter: An easy adapter to map columns from a cursor to TextViews or ImageViews defined in an XML file. You can specify which columns you want, which views you want to display the columns, and the XML file that defines the appearance of these views.


SpinnerAdapter: Extended Adapter that is the bridge between a Spinner and its data. A spinner adapter allows to define two different views: one that shows the data in the spinner itself and one that shows the data in the drop down list when the spinner is pressed.


WrapperListAdapter: List adapter that wraps another list adapter. The wrapped adapter can be retrieved by calling getWrappedAdapter().

Android applications: Components and Structure

Android extends the standard views/data model, providing a new model that is suitable for equipment activated at all times.

The structure of an Android application is defined as follows:

The file AndroidManifest.xml

This defines the components of the application and their relationships. It gives the permissions to application as to what it can do with users. It can also give permission to components of the application.

The views (Class android.view.View)

The interface of a program for Android is a tree of views.

Activity (android.app.Activity class)
This is something that the user can do, translated into program. It corresponds to a screen, but can have multiple views.

Intent (android.content.Intent class)
Describes an action which must be performed.

Service (android.app.Service )
Program that operates in background.

Content Provider (android.content.ContentProvider class)
Encapsulates data and provides them commonly to several programs.

Notification (android.app.NotificationManager and android.app.Notification classes)
Class which informs the user about what is happening.

Besides components, there are also resources that can be XML files, image files as jpeg, etc. These use the android.content.Resources interface and are stored in the res directory.

Components of an Android application

Each component is included in a list stored in the manifest file AndroidManifest.xml of each application.

Activity

An activity corresponds to a screen. If an application is composed of several screens, it has an activity for each screen. Each activity is a class that extends the base class Activity. It has a graphical user interface made of views, and it responds to events. When you change screen, a new activity is launched.
It can return a value. For example, if an activity can choose something, text, image, it returns what is chosen.

The graphical interface of an activity is described by a Layout:
- Full screen.
- Float: dialogue or alert.
- None. In this case it works in background and is invisible. It is maked visible by giving it a layout.

Note that the graphical user interface is described in XML as XUL and XAML.

Intent

The intents are the goals of applications and are made effective by a new screen. An intent is made up of an action and data that are URI.

Examples of actions: MAIN, VIEW, EDIT, PICK.
If one wants to see a card about a person, an intent is defined. The action is VIEW and the data is the URI which enables access to this card.

IntentFilters describes how the action should apply.

IntentReceiver is an object that responds to external events. It can operate in the application or it can start an application.

Example of intent, view a webpage: VIEW for action and for data http://www.linkToStuff.org.

Service

A service is designed to operate independently of the screen, thus of activities. The best example is the music player that can works while moving from one screen to another.

Content Provider

Data stored by a computer program, in the form of files or SQLite databases are private and may not be used by other applications.
But Content Provider may be used to share data among several applications. The interface ContentResolver is the interface that provides data to other objects.

Notification

The class android.app.Notification defines how an event must be notified to user: displaying an icon, changing state of a led, vibration, or others. While the class android.app.NotificationManager sends the message in the form so defined.

Creating multiple sqlite database tables in Android

Most of the Android database examples you will find on the web will usually contain only one table to demonstrate the basic database concepts.

That's great, the only problem with this is that most non-trivial database implementations will contain more than one table.

The standard database creation string for a single table will probably look a lot like the below:


private static final String CREATE_TABLE_1 =
" create table " + table1 +
" (_id integer primary key autoincrement," +
" title text not null, body text not null);";

Which is called in your DB Adapter class like this:


@Override
public void onCreate(SQLiteDatabase db) {

db.execSQL(CREATE_TABLE_1);
}

So what to do if you want to create more than one table?
You may do the below.. but will it work?
Note that this is one big string containing three separate create statements...


private static final String DATABASE_CREATE_MULTIPLE_TABLES =
" create table " + ITEMS_TABLE +
" (_id integer primary key autoincrement," +
" title text not null)" +

" create table " + TAGS_TABLE +
" (_id integer primary key autoincrement," +
" tagName text not null)" +

" create table " + LOCATIONS_TABLE +
" (_id integer primary key autoincrement," +
" locationName text not null, gpsCoOrds text);"
;

And then you try calling them in your DB Adapter class like so:


@Override
public void onCreate(SQLiteDatabase db) {

db.execSQL(DATABASE_CREATE_MULTIPLE_TABLES);
}

So you're trying to create the three tables in one call to db.execSQL.


This appears to compile and run successfully, you can even read and write to the FIRST table that is created, but..

..when you try to read or write to any other table you will see the dreaded

'Sorry! The application Kdkddfblah (process test.Kdkddfblah) has stopped unexpectedly. Please try again'

..error message.

Uh-oh.

If you debug your application, you might see references to syntax errors 'near create', and possible a reference that the table doesn't exist.

Hmm... What went wrong?

The answer is that sqlite, and therefore the db.exec method, only lets you execute one sql command at a time. We were trying to run three sql statements in one go in db.execSQL(DATABASE_CREATE_MULTIPLE_TABLES);.

So what you need to do to fix this is move each of the above table create statements into their own strings, like this (Note that this now creates three seperate strings, unlike above):


private static final String CREATE_TABLE_1 =
" create table " + table1 +
" (_id integer primary key autoincrement," +
" title text not null, body text not null);";

private static final String CREATE_TABLE_2 =
" create table " + TAGS_TABLE +
" (_id integer primary key autoincrement," +
" tagName text not null)";

private static final String CREATE_TABLE_3 =
" create table " + LOCATIONS_TABLE +
" (_id integer primary key autoincrement," +
" locationName text not null, gpsCoOrds text);";

.. and then use these strings in your onCreate method like below, this then works.


@Override
public void onCreate(SQLiteDatabase db) {

db.execSQL(CREATE_TABLE_1);
db.execSQL(CREATE_TABLE_2);
db.execSQL(CREATE_TABLE_3);
}

If you find this doesn't work for you, try dropping all the tables in your database and try again, or give the database a different name, or different version number. The SQLiteOpenHelper seems to have some troubles registering that the database is to be changed. It finds a db with the same name and version number, goes 'meh' and doesn't look to see if the structure is different at all.

You can also pull the sqlite db file right off your device (or emulator) by going into the DDMS perspective in Eclipse (Window menu\ Open perspective \ Other \ DDMS), navigating to the database file which will probably be at \data\data\*Your Application Name*\databases.

There's a 'pull file' button on the top left as seen highlighted below:



.. You can then open the DB in your favourite sqlite manager (I like Sqliteman) and play around. Can can also of course, push the file back to the device if you wish.

Psst..Remember that your layout files must have lowercase names..

Remember that your layout files must have lowercase names, or they won't show up in your autoComplete list of options after 'R.layout' in Eclipse when you try this :

setContentView(R.layout.test_db);


The file won't actually show up as having any errors in your package explorer (on the right by default in the IDE), but if you look down in the console (by default down the bottom), you'll see this:

Invalid file name: must contain only [a-z0-9_.]


You might see an error on your project name, but with all the folders and files it can be hard to track down the cause.

When you try to run your application you will see:

'Your project contains error(s) please fix them before running your application'


.. and it won't be happy until you delete the offending file, even if you're not actively referencing it in your code.



Hope that helps.. Happy coding!

Errors trying to run ADB (Android Debug Bridge)?

The Android Debug Bridge (adb) is a tool lets you manage the state of an emulator instance or Android-powered device.

I was trying to run it for the first time on my ubuntu 9.10 box and I kept getting this error:


desktop:~/dev/Android/android-sdk-linux/tools$ adb
No command 'adb' found, did you mean:
Command 'cdb' from package 'tinycdb' (main)
Command 'gdb' from package 'gdb' (main)
Command 'aub' from package 'aub' (universe)
Command 'dab' from package 'bsdgames' (universe)
Command 'mdb' from package 'mono-debugger' (universe)
Command 'arb' from package 'arb' (multiverse)
Command 'tdb' from package 'tads2-dev' (multiverse)
Command 'pdb' from package 'python' (main)
Command 'jdb' from package 'openjdk-6-jdk' (main)
Command 'jdb' from package 'sun-java6-jdk' (multiverse)
Command 'ab' from package 'apache2-utils' (main)
adb: command not found

What was I doing wrong?

A quick google search shows me the error of my ways.. I haven't added my Android SDK tools directory to my system path!


It should go something like this...

open a terminal window and type:

$ echo $PATH
---(should return the directories associated with $PATH)

$ export PATH=$PATH:/home/YOUR-USERNAME/sdk/tools
---(replace with path to your tools directory, you may need to add 'sudo' to the beginning of this cmd)
Update: later versions of the SDK have ADB moved to the platform-tools directory, so adjust the above accordingly.


$ echo $PATH
---(you should now see your tools directory added to the end of the $PATH variable)

$ adb devices
---(now adb should do something, if nothing else at least error, no devices)


And now I get:

List of devices attached
emulator-5554 device

Sweet Success!

p.s. Adding to the system path in Windows is along the lines of :

1. right-click '(My) Computer'
2. Select 'Properties'
3. Go to 'Advanced' or whatever tab you find 'Environment Variables'
4. Select 'Path' then 'Edit' and add your new path in.

Update: if you are using 64-bit linux you may need to also install the ia32-libs package like so:

sudo apt-get install ia32-libs





Including layouts: a working example

Here's a working example of including one layout inside another.

Let me know if you have any issues or questions.
This works with, and probably requires, a AVD version of 2.1 or thereabouts.



contents of droidTest1.java:

package androidforbeginners.droidTest1;

import android.app.Activity;
import android.os.Bundle;

public class droidTest1 extends Activity {
/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
}
}


contents of main.xml:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
>
<TextView
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="combining layouts"
/>

<include android:id="@+id/cell1" layout="@layout/layout2" />
<include android:id="@+id/cell2" layout="@layout/layout3" />


</LinearLayout>



Contents of layout2.xml:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="100px"
android:background="#0033cc"
>
<TextView
android:layout_width="fill_parent"
android:layout_height="40px"
android:text="layout2"
/>
<CheckBox
android:layout_width="fill_parent"
android:layout_height="40px"
/>
</LinearLayout>


Contents of layout3.xml:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="100px"
android:background="#0066cc"
>
<TextView
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="layout3"
/>
<CheckBox
android:layout_width="fill_parent"
android:layout_height="wrap_content"
/>
</LinearLayout>


Output:



You could also include multiple occurrences of the one layout in your main.xml like this if you wanted:

contents of main.xml (revised):

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
>
<TextView
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="combining layouts"
/>

<include android:id="@+id/cell1" layout="@layout/layout2" />
<include android:id="@+id/cell2" layout="@layout/layout2" />
<include android:id="@+id/cell3" layout="@layout/layout2" />
<include android:id="@+id/cell4" layout="@layout/layout2" />


</LinearLayout>


Although if you do this, I can't see a way to reference individual repeating items.

I think include is more including a single layout across multiple Activities.

Let me know in the comments if you know a way.

Till next time: Enjoy!

Layout Tricks: Creating Reusable UI Components

The Android platform offers a wide variety of UI widgets, small visual construction blocks that you can glue together to present users with complex and useful interfaces. However applications often need higher-level visual components. To meet that need, and to do so efficiently, you can combine multiple standard widgets into a single, reusable component.

For example, you could create a reusable component that contains a progress bar and a cancel button, a panel containing two buttons (positive and negative actions), a panel with an icon, a title and a description, and so on. You can create UI components easily by writing a custom View, but you can do it even more easily using only XML.

In Android XML layout files, each tag is mapped to an actual class instance (the class is always a subclass of View, The UI toolkit lets you also use three special tags that are not mapped to a View instance: <requestFocus />, <merge /> and <include />. This article shows how to use <include /> to create pure XML visual components.

The <include /> element does exactly what its name suggests; it includes another XML layout. Using this tag is straightforward as shown in the following example:


<com.android.launcher.Workspace
android:id="@+id/workspace"
android:layout_width="fill_parent"
android:layout_height="fill_parent"

launcher:defaultScreen="1">

<include android:id="@+id/cell1" layout="@layout/workspace_screen" />
<include android:id="@+id/cell2" layout="@layout/workspace_screen" />
<include android:id="@+id/cell3" layout="@layout/workspace_screen" />

</com.android.launcher.Workspace>


In the <include /> only the layout attribute is required. This attribute, without the android namespace prefix, is a reference to the layout file you wish to include. In this example, the same layout is included three times in a row. This tag also lets you override a few attributes of the included layout. The above example shows that you can use android:id to specify the id of the root view of the included layout; it will also override the id of the included layout if one is defined. Similarly, you can override all the layout parameters. This means that any android:layout_* attribute can be used with the <include /> tag. Here is an example:



<include android:layout_width="fill_parent" layout="@layout/image_holder" />
<include android:layout_width="256dip" layout="@layout/image_holder" />



Getting started with Android Development using Eclipse

The Google Android platform offers a easy and quick way to develop applications for the mobile device. First of all, lets start with the tools we will need to start developing our own Android applications.

The best IDE (Integrated development environment) t to develop Android is Eclipse.



The Android SDK

We will need another tool to work with Android. This tool is called the SDK (Software Development Kit), we have download it from here and place in somewhere handy on your computer (C:/Android/SDK if we are on Windows, for example, or ./home/YOURUSERNAME/Android/SDK if we use a *nix system).

It doesn't really matter where you put it, just don't forget where, because in next steps we will have to enter the path to the SDK into the Eclipse environment.


Eclipse

Once we have downloaded the SDK we will need the Android plugin for Eclipse. There are a couple of different ways of doing this, depending of the version of Eclipse you are using:

For Eclipse Ganymede :

* Start Eclipse.
* In the Menu, select "Help" and then "Software Updates".
* In the new pop-up window, push the button "Add site ... " and enter the following address and click Ok:

https://dl-ssl.google.com/android/eclipse/

*
* Once this is done, you have to go back to the Updates and Add ons menu. The location we have entered before should appear, click on it, check the "Developer Tools" and click Install.
* Follow the steps to install the plugin.

For Eclipse Europa version

* Start Eclipse
* In the Menu, select "Help" , "Software Updates" and then "Find and Install".
* Click on New Remote Site
* In the new pop-up window, paste 'https://dl-ssl.google.com/android/eclipse/', and click Ok:

* One this is done, the new site should appear in the Add ons list. Click on it and check both “Android Developer Tools” and “Android Editor”.
* Follow the steps to install the plugin.

Hint: If the https://dl-ssl.google.com/android/eclipse/ doest work try "http" instead of "https".

Once we have installed the Eclipse plugin we have to restart the IDE. Now, its time to point to the plugin where the SDK is in our system.

In the Menu, “Window”, select “Preferences”. Select Android from the left panel, click the “Browse” button and locate the SDK directory in your computer, then click OK.

Now we are able to create Android applications on our Eclipse IDE.

How to Install .Apk Apps on you Google Android Phones

1. Install and open the Apps Installer application from the "Android Market".

2. This opens a view showing *.apk application names in the sdcard root directory.(note, if no AppNames are listed you have no .apk files in the root directory of the SDCard)

3. Touch the app name to initiate installation of the app.

4. The app is now installed

How to Non-Market .Apk Application on your Google Android Phones

1. Download and install Google Android SDK. The tool you need is adb.exe.

2. Now type adb in a command shell will display all the options, adb.exe is SDK tool used to install applications and interface with the device.

3. Now Connect Your Android Phone to your computer using USB cable. You need to install Drivers for this. Download Android USB drivers from here. This driver is required for adb to interface with an android phone using USB cable.

4. Go to Android Settings/SD card & phone storage and disable Use for USB storage. You can enable it again later after you installed your third-party application.

5. Go to Settings/Application settings and enable Unknown sources.

6. Connect the G1 to your computer using the USB cable and install the driver you downloaded in step 3. After installing the driver you should see ADB Inteface in Windows Device Manager.

7. If you made it this far, download the APK file to a local folder on your computer, something like C:\MyAPKs will work fine and install it using ADB. The command would be adb install c:\myapks\ and that’s about it.

Anyway, the apk files refers to the Android Package files; and there are numbers of freeware you can try.

The difference between @+id and @android:id

Sometimes you see references in your layout files like:

<listview id="@+id/android:list">

and

<listview id="@android:id/list">

What's the difference?
.. I'm glad you asked ☺

@+id/foo means you are creating an id named foo in the namespace of your application.
You can refer to it using @id/foo.
@android:id/foo means you are referring to an id defined in the android namespace.

The '+' means to create the symbol if it doesn't already exist. You don't need it (and shouldn't use it) when referencing android: symbols, because those are already defined for you by the platform and you can't make your own in that namespace anyway.

This namespace is the namespace of the framework.
for example, you need to use @android:id/list because this the id the framework expects to find.. (the framework knows only about the ids in the android namespace.)

Android Activities

An activity presents a visual user interface for one focused endeavor the user can undertake.

For example, an activity might present a list of menu items users can choose from or it might display photographs along with their captions. A text messaging application might have one activity that shows a list of contacts to send messages to, a second activity to write the message to the chosen contact, and other activities to review old messages or change settings.

Though they work together to form a cohesive user interface, each activity is independent of the others. Each one is implemented as a subclass of the Activity base class.

An application might consist of just one activity or, like the text messaging application just mentioned, it may contain several. What the activities are, and how many there are depends, of course, on the application and its design.

Typically, one of the activities is marked as the first one that should be presented to the user when the application is launched. Moving from one activity to another is accomplished by having the current activity start the next one.

Each activity is given a default window to draw in. Typically, the window fills the screen, but it might be smaller than the screen and float on top of other windows.

An activity can also make use of additional windows — for example, a pop-up dialog that calls for a user response in the midst of the activity, or a window that presents users with vital information when they select a particular item on-screen.

The visual content of the window is provided by a hierarchy of views — objects derived from the base View class. Each view controls a particular rectangular space within the window. Parent views contain and organize the layout of their children. Leaf views (those at the bottom of the hierarchy) draw in the rectangles they control and respond to user actions directed at that space. Views are, therefore, where the activity's interaction with the user takes place.

For example, a view might display a small image and initiate an action when the user taps that image. Android has a number of ready-made views that you can use — including buttons, text fields, scroll bars, menu items, check boxes, and more.

A view hierarchy is placed within an activity's window by the Activity.setContentView() method. The content view is the View object at the root of the hierarchy.

Activity Lifecycle

Activities in the system are managed as an activity stack.
When a new activity is started, it is placed on the top of the stack and becomes the running activity -- the previous activity always remains below it in the stack, and will not come to the foreground again until the new activity exits.

An activity has essentially four states:

If an activity in the foreground of the screen (at the top of the stack), it is active or running.

If an activity has lost focus but is still visible (that is, a new non-full-sized or transparent activity has focus on top of your activity), it is paused.

A paused activity is completely alive (it maintains all state and member information and remains attached to the window manager), but can be killed by the system in extreme low memory situations.

If an activity is completely obscured by another activity, it is stopped.

It still retains all state and member information, however, it is no longer visible to the user so its window is hidden and it will often be killed by the system when memory is needed elsewhere.

If an activity is paused or stopped, the system can drop the activity from memory by either asking it to finish, or simply killing its process. When it is displayed again to the user, it must be completely restarted and restored to its previous state.

There are three key loops you may be interested in monitoring within your activity:

The entire lifetime of an activity happens between the first call to onCreate(Bundle) through to a single final call to onDestroy().

An activity will do all setup of "global" state in onCreate(), and release all remaining resources in onDestroy(). For example, if it has a thread running in the background to download data from the network, it may create that thread in onCreate() and then stop the thread in onDestroy().

The visible lifetime of an activity happens between a call to onStart() until a corresponding call to onStop(). During this time the user can see the activity on-screen, though it may not be in the foreground and interacting with the user. Between these two methods you can maintain resources that are needed to show the activity to the user.

For example, you can register an IntentReceiver in onStart() to monitor for changes that impact your UI, and unregister it in onStop() when the user an no longer see what you are displaying. The onStart() and onStop() methods can be called multiple times, as the activity becomes visible and hidden to the user.

The foreground lifetime of an activity happens between a call to onResume() until a corresponding call to onPause(). During this time the activity is in front of all other activities and interacting with the user.

An activity can frequently go between the resumed and paused states -- for example when the device goes to sleep, when an activity result is delivered, when a new intent is delivered -- so the code in these methods should be fairly lightweight.

The entire lifecycle of an activity is defined by the following Activity methods. All of these are hooks that you can override to do appropriate work when the activity changes state. All activities will implement onCreate(Bundle) to do their initial setup; many will also implement onPause() to commit changes to data and otherwise prepare to stop interacting with the user.

You should always call up to your superclass when implementing these methods.

protected void onCreate(Bundle icicle);

Called when the activity is first created. This is where you should do all of your normal static set up: create views, bind data to lists, etc. This method also provides you with a Bundle containing the activity's previously frozen state, if there was one.

Always followed by ..




protected void onStart();

Called when the activity is becoming visible to the user.

Followed by onResume() if the activity comes to the foreground, or onStop() if it becomes hidden.

protected void onRestart();

Called after your activity has been stopped, prior to it being started again. Always followed by onStart()

protected void onResume();
Called when the activity will start interacting with the user. At this point your activity is at the top of the activity stack, with user input going to it.

Always followed by onPause().

protected void onPause();
Called when the system is about to start resuming a previous activity. This is typically used to commit unsaved changes to persistent data, stop animations and other things that may be consuming CPU, etc. Implementations of this method must be very quick because the next activity will not be resumed until this method returns.

Followed by either onResume() if the activity returns back to the front, or onStop() if it becomes invisible to the user.

protected void onStop();
Called when the activity is no longer visible to the user, because another activity has been resumed and is covering this one. This may happen either because a new activity is being started, an existing one is being brought in front of this one, or this one is being destroyed.

Followed by either onRestart() if this activity is coming back to interact with the user, or onDestroy() if this activity is going away.

protected void onDestroy();
The final call you receive before your activity is destroyed. This can happen either because the activity is finishing (someone called finish() on it, or because the system is temporarily destroying this instance of the activity to save space. You can distinguish between these two scenarios with the isFinishing() method.

A first hand look at building an Android application