Monthly Archives: May 2014

GitHub Card Android App

In this post we will be proceeding with the app development for our GitHub Card App. Here we are targeting android audience. This is the wire frame we designed for our card App.

App Wireframe

App Wireframe

Since this is a wireframe, we don’t have to match it exactly but we will try to keep the layout as close to this as possible. It would be tricky to get the number of total commits so we will be ignoring this for now.

GitHub API

GitHub provides users’ and repositories’ data through REST based HTTP services. It is currently version V3 of the API. The details about the api can be found here [https://developer.github.com/v3/]. We can test our requests using Curl as follows:

Curl_GitHubApi

Creating GitHub Contributions Android Project

Let’s use Android Studio for our development. You can download the tool here. We are naming the project as GitHubCard.Android. The project is being targeted for API 19 (KitKat).

GitHubCardAndroidApp

Here we are using a clipart as an icon for the app. Let’s pick a simple clipart from the gallery.

GitHubCard_icon

Since we selected the option “Create Activity” in the first page of the wizard, we are asked about the type of the activity. Let us select a empty activity.

EmptyActivityGitHubAndroidApp

Now we need to specify the details about the activity. It includes activity and layout name for the activity.

GitHubCardActivityCreate

And that completes the wizard, we have our project created in the workspace. It appears as follows:

ProjectFolderGitHubAndroidApp

There are two folders which are of special concern. They are src and build folders. Here src folder contains project’s code including layouts. The type “R” is of special importance in an Android project. We can find it in build folder.

ProjectGitHubCardApp

Android Permissions

In order to access GitHub user profile and repository data, we need to have access to internet. This would require our app to require permissions to access the network. We need to declare this in AndroidManifest.xml of the app.

What is Activity in an Anrdoid App

Activities define the interface display for an android app. Its layout and behavior are defined separately. We can define a layout for an activity or an app widget. If you are coming for a XAML background like me, you must be used to define the application view in XML. The mapping of an activity layout to an activity is defined in activity definition using tools:context. Here tools is the namespace, “http://schemas.android.com/tools”. In the java code we can define the content-view for the activity of interest. Here we have the onCreate() definition of our card activity.

onCreateSetContentView

So anything we want to show on the UI, we create an activity for that. As we just discussed, an activity is bound to a view defined in XML so technically, we can bind more than one view to an activity but this is generally not recommended. There are a number of overloads of setContentView method.

setContentViewOverloads

An activity has a single thread i.e. UI thread. The activity currently being displayed is referred as Active. Creating multiple activities doesn’t create new threads as only a single activity is active at a given time.

Activity Designer
An Activity can be mapped to one or more layouts. These layouts are defined res/layout folder for an android project. We generally specify the layout of an activity using setContentView method in onCreate method.

This is like Microsoft’s XAML technologies where views are defined in XAML, which is based on XML. The behavior is defined outside the layout definition in view models. Android layout is also defined in XML. For convenience, we can use the Activity Designer, which makes it easier to generate this XML.

activity_designer

Double clicking a widget enables us to change the orientation and Id of the selected widget.

DoubleClickComponent

This is the layout definition for our GitHubCardActivity. It is a simple layout with a few TextView(s) (for name and other info) , ImageView (for profile picture) and ListView (for showing the list of user’s repositories).

You can notice the strings being referenced as strings/id. This is a reference to strings.xml containing the definitions of these strings. We can find the file in res/values folder.

Downloading Profile and Repositories Info

Downloading the profile and repositories info for the user is the most important part of the development for this app. Let’s first create an interface type to hold information for user’s profile data. We are naming the type as GitHubProfileDetails.

And here is the interface type to download profile and repositories data. Since we would be accessing the network, we might need to handle IOException cases. All the data is returned in JSON format by default. We might run into issues while formatting the JSON data causing JSONException. The calling code must handle these two exceptions.

Here is the implementation for GitHubProfileDetails. Here we are using the URL from the profile data returned to download user’s profile pic. Just make sure that this is being constructed on a non-UI thread as we cannot access network on UI thread in android.

And here is the implementation for GitHubProfileDetailsDownloader interface. Since we can use different approaches to download this data. We are deliberately keeping this type agnostic to the particular approach used. The profile’s data is downloaded as JSON. Here we are parsing JSON and creating a GitHubProfile instance. Similarly we are getting the repositories’ data and returning it to the calling code.

GitHub Repositories List
In order to show the list of user’s repositories we are using ListView. This is used to display a list of scrollable items. This is how we are defining it in activity_git_hub_card.xml.

Please notice the id here. We will be using the same id in activity definition to access the element to bind it to user’s repositories data using R type.

In android, we use Adapters to bind data to ListView. It also provides sorting and filtering capabilities. Let’s look at the inheritance tree of ListView type. All elements which inherit from AdapterView can use adapters. From the definition, we notice that it supports ListAdapter, which is an interface type. Based on Liskov’s substitution principle, it must also support all implementations of the interface.

ListViewInheritence

Here is the code, we are using to create an ArrayAdpater from the data returned by GitHub API. Since we are just interested in the name of repositories, we are just passing them to this method. After creating an ArrayAdpater for the data, we are just setting the ListView’s adapter.

Just note that we have added this method in GitHubCardActivity. We also need to make sure that the method is being called on UI thread, which is obvious here since we are calling it from onPostExecute of AsyncTask.

Loading Image from GitHub Profile

ImageView doesn’t allow directly setting a web Uri to load image. We need to explicitly load image and assign it to the imageView source. We should remember that we are required to download this in a non-UI thread to avoid the InvocationException. Here we are using URL to create an HttpConnection with the image source. We are then getting the InputStream from the connection. BitmapFactory allows us to create an Bitmap from an InputStream.

Since URL’s constructor can throw a MalformedURLException and HttpConnection.getInputStream() can throw an IOException, we need to catch them.

After downloading image and other profile data, we need to show them on UI. In this method we are providing the data using GitHubProfileDetails type. Since we need to show name, blog, date of creation and number of followers’ data in a certain format, we are using String.format for this purpose. ImageView cannot use a web URI, so we have downloaded the whole bitmap, now we just need to set the bitmap as the profile picture.

AsyncTasks for Profile and Repositories’ data

Since we need to download data on a non-UI thread (because of android’s restriction of network access on a non-UI thread) and populate UI elements on a UI thread (android’s restriction for accessing the UI elements only in UI thread), AsyncTask is ideal for this purpose. We can download the profile data first, get URL for repositories and then download the repositories’ data. But since the URL for repositories’ data is also standard one, I think it should be fine if just directly use it and download this in parallel to the profile data.

Below we have introduced two AsyncTask (s) to download user’s profile and repositories details. If you are coming from a Microsoft’s background, AsyncTask (s) are very similar to BackgroundWorker. They allow some processing to be done on a background thread. During the processing, we can report progress of the operation which can be used to update UI. After completion of task, it executes onPostExecute() method.

Unlike Microsoft’s BackgroundWorker, it doesn’t provide any event for progress publishing and task completion but it provides other overridable methods for this purpose. This makes it difficult to pass the data to the UI Activity which can be fulfilled by providing callbacks. Here we are providing two child types for AsyncTask. We are expecting the GitHubCardActivity to be passed as constructor’s arguments. We are using the provided instance to use callbacks once the required data is available. In the callbacks (discussed above), we are updating the UI.

Running App

Now let us run this app. We can use a virtual device for running this. Here we are using Galaxy. This is the output of the app.

AndroidApp

Download Code

You can download the app from GitHub.

AndroidApp_GitHubDownload

A Simple Android App for learning

In my talk about options for development for google glass, I briefly discussed about Android studio to be an option. In this post, we will not be discussing about glassware development though. We will be focusing on creating a simple android app. Since this would be our first one, we would like to keep the discussion as simple and straight as possible.

The App should just have a button and a number. Clicking the number each time should increment the number on the screen.

Let’s open our Android Studio and create a new project. Let’s name this project as IncrementerApp. Let’s keep the default options selected here. If you have a .net development background, like me, this first screen does confuse us. There are so many platform versions asked. In our .net experience, we just have one version to care about. That is the version we develop against, and that is the version we expect our customer to be running our application against. But don’t be confused, just get in the water, it will be just fine.

IncrementerApp

Now let’s move to the next stage of the project creation wizard. Here we are adding a blank activity. We don’t want any additional features added to the activity here.

ActivityDefinition

Hitting the Finish button would create the activity with default definition. Now for our activity, we should specially be careful about two files. They are IncrememntActivity.java and activity_increment.xml files. It has picked up the name for xml file from the casing of the name of the activity. Here you should know that all the activities should have these two files. The java file defines the behavior of the activity, while the xml one defines the activity layout. Since each activity is something that we want to show to the screen, it must have a layout, generally only one.

ProjectWindow

Let’s add a Framelayout the activity layout. We add a TextView and a button to the layout as follows:

layout_app

You might have noticed the button’s content as Increment. Now Android is very good at providing a framework for resources from the ground-up. There are already existing resource files for different purposes. Here we have introduced the “Increment” text in strings resource file. It should be available for selection as follows:

increment_button

Here the resource file has already been updated as follows:

stringsxml

You can directly go to the definition of these resource definitions by CTRL + MOUSE OVER over the resource usage. It transforms into a hyperlink then which can be used to traverse to the definition site. You can also notice that we have updated the text of TextView as 0.

controlMouseOver_001

The similar is not true for the Ids. We define Ids here in the layout definitions with + sign. They are then compiled into a new class type R, which can be used from rest of the application. They are added to a final class in R called id. You might need to rebuild the project if you have just updated an id. So

IncrementTextViewInR

Now add the following code to IncrementActivity java class. This would define an event handler our Increment button. It accesses the TextView using the id discussed above using findViewById method. The method is defined in the parent class of the Activity. Since it returns a View type, we need to typecast the result to TextView. After getting the contents of the text view, we are just parsing it to an integer, incrementing it and assigning it back to the same TextView.

Now we need to hook-up this handler to our button. We can simply achieve this using the property definition window of the button. It lists the assignable methods defined in the activity associated with this layout definition. Let’s select buttonOnClick here.

2014-05-11_1735

Mapping Between Activity and Layout

Before running the project, let’s just take a moment to discuss a few things. First of all, we have just discussed that behaviors and layout of an activity is defined in its corresponding java and xml files. Now how they are mapped to each other. Actually, it is a two-way mapping. In the java file, we generally add the layout mapping in the onCreate() method. In the xml layout definition we set the context of the layout to be the specific activity.

TwoWayMapping

Android View & Layout Components

All the UI components in Android are derived from View type. Here we have used a TextView and Button. Both of them are derived from View type. In addition to these we have used FrameworkLayout. Layouts are also specialized views. All layouts are derived from ViewGroup which inherits from View. These view groups are containers for other view objects.

ViewGroupLayout

Running Project

An android app can be run on a real or a virtual device. Here virtual devices are emulators available to test an app. As we run the project, the following dialog is available for selecting the device we want to test it on. It includes all the devices connected to the system used for development which have debugging enabled. We can also launch emulators for testing on virtual devices. Since I have previously added a virtual device for Galaxy Nexus, this is available in the list for selection.

RunningProject_ChooseDevice

We can manage the list of virtual devices (emulators) from AVD (Android Virtual Devices) manager.

AVD_Manager

As we start debugging the project, the IDE provides us a list of running devices. We can select either of them to run our app. We can also start a new device for this purpose.

RunningApp

Code Inspections

Android Studio is amazing in helping us determine the code issues. In the code editor it shows help based on the code inspection settings. We can update the inspection settings from Code Inspection window.

CodeInspections

Debugging Apps

It must be remembered that breakpoints are hit only in the case when we debug the app. If we just run it, no breakpoints are hit. So make sure that we select a debug option from the menu drop down.

DebugAppsBreakPoints

Although this is not recommended but we can always set an application to be debug-able in the android manifest.

android_debugable

You can see that the code inspection has highlighted this. Actually this flag is automatically set when an application is debugged from the editor. Setting this here explicitly also sets it in the apk generated for the app, which is not recommended.

Let’s Debug Incrementer App

Now let’s run the project. It installs and debugs application on that device. This is remote debugging on that device provided by ADB. We can discuss it later. All the messages are added to the console so that you might have an idea what’s going on here.

DebugConsoleMessage

As the application is running and the button is being clicked, you can set breakpoint in the onClick handler for the button. It provides a comprehensive view of the current application state. We can also step through the code here.

Breakpoints

You can notice that as we are hitting the button, it is incrementing the number in the view, which is as per our original requirement.

RunApp

Download Code

You can download the app’s code from Github:

IncrementerAndroidApp