Xamarin Mobile Development for Android Cookbook

Before we start creating any Android apps, we need to get our tools in place using the installer from Xamarin.

Creating Xamarin.Android projects is very simple!

Xamarin.Android allows us to write native Android apps using .NET and C# or F#. Xamarin.Android does not abstract or emulate any Android features. Rather, it is an alternate programming language available for the development of Android apps.

Some of the benefits of using Xamarin.Android are found in the small things. For example, if we are using Android Studio or Eclipse, we will have to make changes in AndroidManifest.xml. If we are using Xamarin.Android, we can do much of this work by using the familiar attributes.

To add the <activity> element into the manifest with Xamarin.Android, we add the [Activity] attribute on an activity as follows:

[Activity(
  Label = "My App", 
  MainLauncher = true, 
  Icon = "@drawable/icon")]
public class MainActivity : Activity
{
}

This will create a section in ApplicationManifest.xml at compile time, as highlighted in the following code:

<activity android:label="My App"
  android:icon="@drawable/icon"
  android:name="mynamespace.MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>

If we want to add permissions to our app, all we need to do is add this:

[assembly: UsesPermission(Manifest.Permission.Camera)]

There are many other attributes that help us build the manifest file, such as the [Service] and [IntentFilter] attributes.

Creating an interface for our apps is very easy. There are two ways to create user interfaces, with code or with XML:

Both XML and code can be used to create equivalent UIs, but using XML, we have additional capabilities:

Regardless of whether the layout was created in code or through XML files, we are able to access the various controls similarly:

Separating the UI from the code allows us to easily make changes for updates as well as to support different screen configurations. The benefit of this is that it allows us to modify the UI without updating the code. And part of this is the fact that the Android system can switch the entire layout at runtime. Different layouts for different screen configurations can be selected simply by changing the suffix of the layout folder name.

For example, if we want our Main layout to have the LinearLayout method to be vertical in portrait orientation and horizontal in landscape orientation, all we have to do is create two layout files with the same name in different folders as follows:

<project-root>/Resources/layout/<layout-file-name>.axml
<project-root>/Resources/layout-land/<layout-file-name>.axml

There are many uses for the suffixes, and there are many different suffixes. Each of the resource subfolders can have suffixes, including values, layout, menu, and drawable. Each of the folders can have combinations of the suffixes for language or culture, screen orientation, screen density, screen size, and platform version. More information can be found online at https://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources.

The Android layout structure usually follows the structure of the type, with the element name matching the type name and property names matching the attribute names. For example, the Button type has a Text property; thus, the XML will have a <Button android:text="..." /> element.

Although we can nest one or more layouts within another layout, we should strive to keep our layout hierarchy as shallow as possible. The layout will be drawn faster if it has fewer nested layouts.

One of the most important attributes in layouts is the id attribute. This attribute is used to uniquely identify a view within a tree. An ID need not be unique throughout the entire tree, but it should be unique within the part of the tree that is being searched.

Layout files are an easy way to create the UI separate from the code, and in the same way, resource files can be used to separate the localizable text from the layout. This is achieved by placing the strings into a resource file and then, referencing each the string from the layout. Say we have a button that has some text:

<Button android:text="Hello World!" />

This value can be extracted and placed into a file under the values folder of the project resources (<project-root>/Resources/values/<file-name>.xml):

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="buttonText">Hello World!</string>
</resources>

The layout file can then be updated to reference the value:

<Button android:text="@string/buttonText" />

Using this pattern, we are able to not only extract strings but any value for any attribute, including layout information. An example would be to extract an element's padding and use a larger padding for larger screens. These types of resources are placed in the values folder with a suffix, such as -large for large screens.

Adding an options menu to our app is very simple, and only two things are required: a menu structure and code to connect the menu with the activity. In order to use a menu layout file, a resource file needs to be added:

Menus, especially the options menu, are both simple and important to Android apps. The Options menu contains items that are relevant to the current activity. They are important, but they are often not commonly used and so don't have a dedicated space in the layout.

An Android screen with an options menu at the bottom

As with traditional layout files, using resource files for menus allows greater flexibility for the many screen configurations as well as for simplifying customizations to menus.

Each menu item contains a unique ID, which allows the system to recognize the item when the user selects it, and a title, which is used to present the item to the user. There are also additional properties, the most commonly used of these being the icon. When using action bars, this icon is used to display an image alongside, or in place of, the title.

The MenuInflater instance creates the menu structure from the resource file and inflates it into the IMenu instance. All the menu items in the resource will be added as children to the menu.

When we handle the menu item selections, the menu item that was selected is passed into the OnOptionsItemSelected() method. If the event was handled, true should be returned; otherwise, the system will keep on processing the event.

We can use any of the properties on the menu item, but one of the more commonly used ones is ItemId, which contains the ID that was used in the resource file. This ID can be used to determine which item was selected.

In order to add the new features of the later versions of Android to the older versions of Android, all we need to do is add a small package:

If we want to add support for the new UI paradigm that uses fragments and action bars, we need to install two of the Android support packages:

There are several support library packages, each adding other types of forward compatibility, but these two are the most commonly used.

As Android is developed, new features are being added and designs change. We want to always provide the latest features to our users, but some users either haven't or can't upgrade to the latest version of Android. By including the Android Support Libraries in our app, we can make use of the new features, but still support the old versions.

Xamarin.Android provides three version numbers to specify what and how types can be used. The target framework version specifies what types are available for consumption as well as what toolset to use during compilation. This should be the latest as we always want to use the latest tools.

However, this will make some types and members available to apps even if they aren't actually available on the Android version that the user is using. For example, it will make the ActionBar type available to apps running on Android version 2.3. If the user were to run the app, it would probably crash.

In these instances, we can set the minimum Android version to be a version that supports these types and members. But, this will then reduce the number of devices that we can install our app on. This is why we use the support libraries; they allow the types to be used on most versions of Android.

The Android support libraries provide us with a type that we know we can use everywhere, and then that base type manages the features to make sure they function as expected. For example, we can use the ActionBar type on most versions of Android because the support library made it available through the AppCompatActivity type.

Because the AppCompatActivity type is an adaptive extension for the traditional Activity type, we have to use a different theme. This theme adjusts so that the new look and feel of the UI gets carried all the way back to the old Android versions.

There are a few differences when using the support library. With native support for the action bar, the AppCompatActivity type has a property named ActionBar; however, in the support library, the property is named SupportActionBar. This is just a property name change, but the functionality is the same.

Sometimes, features have to be added to the existing types that are not in the support libraries. In these cases, static methods are provided. The native support for custom views in menu items includes a method named SetActionView:

menuItem.SetActionView(someView);

This method does not exist on the IMenuItem type for the older versions of Android, so we make use of the static method on the MenuItemCompat type:

MenuItemCompat.SetActionView(menuItem, someView);

Besides using the Android Support Libraries to handle different versions, there is another way to handle different versions at runtime. Android provides us with the version number of the current operating system through the Build.VERSION type.

This type has a property, SdkInt, which we can use to detect the current version. It represents the current API level of the version. Each version of Android has received a series of updates and new features. For example, Android 4 has received numerous updates since its initial release, new features being added each time.

Sometimes the support library cannot cover all the cases, and we will have to write specific code for particular versions:

int apiLevel = (int)Build.VERSION.SdkInt;
if (Build.VERSION.SdkInt >= BuildVersionCodes.IceCreamSandwich) {
  // Android version 4.0 and above
} else {
  // Android versions below version 4.0
}

Although this can be done, it introduces spaghetti code and should be avoided. In addition to different code, the app may behave differently on different versions, even if the support library could have handled it. We will now have to manage these differences ourselves each time a new version of Android is released.

Adding an action bar is very simple and does not need many changes to our app, even if they are to run on the old versions of Android:

To provide an action bar to previous versions of Android, we use the Android Support Libraries:

Certain commands are used very frequently in an app. These commands are often the main set of actions available to the current app screen. Because these commands are so important, they have a dedicated area in the app, often at the top of the screen. In a to-do list app, this might be the action to add a new task. In a shopping app, this might be the option to search for a product.

An Android screen with an action bar at the top

While adding an action bar on older Android versions, it is important to inherit it from the AppCompatActivity type. This type includes all the logic required for including an action bar in the app. It also provides many different methods and properties for accessing and configuring the action bar. In newer versions of Android, all the features are included in the Activity type.

Although the functionality is the same, we do have to access the various pieces using the support members when using the support libraries. An example would be to use the SupportActionBar property instead of the ActionBar property. If we use the ActionBar property, the app will crash on devices that don't natively support the ActionBar property.

In order to render the action bar, the activity needs to use a theme that contains a style for the action bar or one that inherits from such a theme. For the older versions of Android, we can use the AppCompat themes, such as Theme.AppCompat.

With the release of Android version 5.0, Google introduced a new style of action bar. The new Toolbar type performs the same function as the action bar but can be placed anywhere on the screen. The action bar is always placed at the top of the screen, but toolbar is not restricted to that location and can even be placed inside other layouts.

To make use of the Toolbar type, we can either use the native type, or we can use the type found in the support libraries. Like any Android View, we can add the ToolBar type to the layout:

<android.support.v7.widget.Toolbar
  android:id="@+id/my_toolbar"
  android:layout_width="match_parent"
  android:layout_height="?attr/actionBarSize"
  android:background="?attr/colorPrimary"
  android:elevation="4dp"
  android:theme="@style/ThemeOverlay.AppCompat.ActionBar"
  app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/>

The difference is in how the activity is set up. First, as we are not going to be using the default ActionBar property, we can use the Theme.AppCompat.NoActionBar theme. Then, we have to let the activity know which view is the Toolbar type:

var toolbar = FindViewById<Toolbar>(Resource.Id.toolbar);
SetSupportActionBar(toolbar);

Navigation with the action bar is an upward navigation, rather than a backward navigation. This navigation is very simple to add and involves only two steps. If we support versions of Android versions below 4.1, we will make use of the support library.

If the Android version is 4.1 and above, we use the native types and members:

The action bar can facilitate direct navigation in two ways: navigating up to the parent activity and navigating down to a child activity. Navigating down is often done by adding action items to the action bar.

Action bar automatically navigates up to the parent activity when the user taps the icon, which is different from the traditional back navigation. The up navigation within an app is based on the hierarchical relationships between activities, that is, navigation to the parent activity. The back navigation is navigation back through the history of activities, in reverse chronological order.

Sometimes the back navigation is the same as the up navigation. This happens when the previously viewed screen is also the hierarchical parent of the current screen. However the up navigation will keep the user in the app, but back navigation may return the user to the home screen or another app.

When adding the [MetaData] attribute to the activity, we need to reference the final compiled name of the parent activity. Xamarin.Android mangles the final name of the types to avoid possible conflicts, so we have to let the compiler know exactly what name to use. We do this using a [Register] attribute on the parent activity, and we then use the same value for the value component of the metadata.

The action bar lets the user know where they are in the app by using the action bar's title, which is usually the current activity's label. This can be customized by assigning a new string value to the Title property on the ActionBar instance.

Sometimes the up navigation will take the user to different parent activities, depending on how the user arrived at the current activity. In these cases, we override several members in our activity. If our app is not going to have the activity instantiated on any other apps, we only need to override the SupportParentActivityIntent or ParentActivityIntent properties:

public override Intent SupportParentActivityIntent {
  get {return new Intent(this, typeof(MainActivity));}
}

If our activity is going to be used by other apps, we also need to override the OnCreateNavigateUpTaskStack() or OnCreateSupportNavigateUpTaskStack() method.

By simply using the action bar, all the action items are added to the overflow:

However, we can customize what items are displayed, and how they are displayed:

Action item buttons are just traditional options menu items but are optionally always visible on the action bar.

The underlying logic to handle item selections is the same as that for the traditional options menu. No change is required to existing code inside the OnOptionsItemSelected() method.

The value of the showAsAction attribute can be ifRoom, never, or always. This value can optionally be combined, using a pipe, with withText and/or collapseActionView.

We can provide a context menu for any view, but they are most often used for items in a list, grid, or other view collection. One way to show a contextual menu is to use a floating or pop-up menu, and it is the recommended way for apps supporting versions of Android below version 3.0.

When the user long-taps on a view that has been registered for a context menu, the activity or fragment attempts to display a menu that is created or inflated in the OnCreateContextMenu() method.

After the user selects an item from the contextual menu, the OnContextItemSelected() method on the activity or fragment is invoked. In this method, we initiate the desired operation that was selected. We can identify the selected item using the ItemId property.

Using the IContextMenu instance that is passed into the OnCreateContextMenu() method, we can change or remove the header of the popup menu. The header could be a combination of an icon and/or text or a separate custom view:

menu.SetHeaderTitle("My Context Menu Heading");

There are a few steps to implementing a contextual action bar:

The contextual action mode menu is actually a separate action bar-like UI element that overlays but does not replace the actual action bar.

This menu provides a set of commands that can be displayed based on some context, usually after a selection of an item on the screen. Selections are usually done after a long-tap, similar to traditional context menus; however, instead of a popup, the action bar is transformed. This provides a consistent interface without disrupting the flow of the task.

In order to enter action mode, we invoke the StartSupportActionMode() method. If we are not using the support libraries, we invoke the StartActionMode() method. This will return an ActionMode instance, which can then be used to customize the appearance of the action mode overlay.

When entering action mode, the OnCreateActionMode() method is invoked. Here we create the various action items that will be presented on the actions bar.

The OnPrepareActionMode() method is invoked whenever the action mode changes or is invalidated. This method allows us to optionally modify the UI. We must return true if any changes were made and false if nothing was modified.

When the user selects an action item, the OnActionItemClicked() method will be invoked. The current action mode and the selected item are provided so that we can perform the task.

If we are using lists and supporting Android 3.0 and above, there is an extra feature that we can make use of: multiple selections. There is currently no native support for a similar functionality on older versions of Android; however, there is no reason why we can't use this feature on newer Android versions.

Implementing this requires a few extra steps but is actually an extension of the normal contextual action mode. Instead of implementing the ActionMode.ICallback interface, implement the AbsListView.IMultiChoiceModeListener interface (which actually derives from ActionMode.ICallback). This adds one extra method:

public void OnItemCheckedStateChanged(
  ActionMode mode, int position, long id, bool isChecked) {
  // handle item selections and deselections
}

And finally, we let the list view know about the multiselect availability by passing the instance. This is done instead of registering the context menu for floating menus:

listView.ChoiceMode = ChoiceMode.MultipleModal;
listView.SetMultiChoiceModeListener(this);

First, we are going to create the project structure that we are going to use to create our cross-platform app. In this example, we will only target Xamarin.Android and the Console, but extra platforms can be added.

Now that we have created the main logic of the app, we can look at those native implementations. First, we will create the Console app that will run on almost any desktop operating system, such as Windows, Mac OS, and most of the flavors of Linux:

If we run the desktop project now, the console will start up, download the blog feed, and then display each entry along with a short summary. Last but not least, we want to get that mobile version going. And what better platform to support first than Android?

If we run this Android app now, we shall get that app that downloads the latest Xamarin blog posts and displays them in a neat list.

Portable class libraries is one of the most important aspects of code reuse. Although there are many different ways to reuse code, such as file linking or shared projects, none can match the reliability and ease of simply reusing the compiled assembly. This assembly can be tested and verified and then used and reused without fear of problems arising on different platforms.

Why? It is because each platform in each portable class library profile promises to support all the features, for all platforms, in that profile, and all those features function exactly the same.

Using Xamarin.Android, we now have all the features of the .NET runtime available, the same runtime that runs on almost all devices. Along with that same runtime, we can now build libraries that run on that runtime, and those libraries will run on all platforms that have the same runtime. Those platforms include iOS, Android, Windows Phone, Mac OS, Windows, Linux, and even more, such as PlayStation!

Although we can never achieve 100 percent code reuse, as each platform has differences (especially in the user interface), much of the code lives below the surface and can be reused. And using the commonality of the runtime and languages, we can create abstractions that can work around the platform differences, resulting in even more code reuse.

Although we only covered two platforms in this example, we can already see that it takes more code to work with the data than it does to display it. Adding extra platforms, such as Windows Phone and iOS, will result in this ultra-simple example app being able to support the major mobile operating systems, with the only difference being the UI.