Xamarin Mobile Development for Android Cookbook

Chapter 1. Working with Xamarin.Android

In this chapter, we will cover the following recipes:

Creating Xamarin.Android projects
Creating user interface layouts
Creating an option menu
Supporting previous Android versions
Adding an action bar
Navigating with the action bar
Adding action bar action items
Creating contextual action mode menu
Sharing code with other platforms

Creating Xamarin.Android projects

Before any apps can be created, the development environment has to be set up and the software downloaded and installed.

Getting ready

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

Go to http://xamarin.com/download:
Enter your details for registration.
Click on the Download Xamarin for Windows or Download Xamarin for OS X links, depending on the operating system you are using.
Once the download has completed, launch the installer, following the on-screen instructions. Setup will continue to download and install all the required components:
Once the installer has finished, you should have a working installation of Xamarin Studio, the IDE designed for cross-platform development.

How to do it...

Creating Xamarin.Android projects is very simple!

Open Xamarin Studio.
Select File, then New, and then Solution…:
Select C#, then Android, and then Android Application:
Enter a name for your app, for example XamarinCookbook.
Click on OK.
We now have a fully functional Xamarin.Android app, which can be deployed to a device or an emulator.
In the target device dropdown, select either an emulator or your device (if you have attached an Android device).
Finally, click on Run and the app will install and launch.

How it works...

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.

Tip

Whatever can be done in Java, and much more, can be done in C#.

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.

Tip

Various attributes can be used to provide the same functionality that modifying the AndroidManifest.xml file would bring.

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 user interface layouts

All apps require some form of user interface for the user to input data or view the output of information.

How to do it...

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

If we are using code to create a button on the screen, we would do something similar to this:

protected override void OnCreate(Bundle bundle)
{
  base.OnCreate(bundle);

  LinearLayout layout = new LinearLayout(this);
  layout.Orientation = Orientation.Vertical;

  Button button = new Button(this);
  button.Text = "Hello World!";
  layout.AddView(
    button, 
    ViewGroup.LayoutParams.MatchParent,
    ViewGroup.LayoutParams.WrapContent);

  SetContentView(layout);
}

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

The equivalent interface in XML would be created and stored in the layout sub-folder of the Resources folder and reads as follows:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout 
 xmlns:android="http://schemas.android.com/apk/res/android"
  android:id="@+id/layout"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical">
  <Button
    android:id="@+id/button"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Hello World!" />
</LinearLayout>

Once we have created the interface in XML, we have to indicate to the activity which layout file is to be used. This is done by invoking the SetContentView() method in the OnCreate() method of the activity. For example, say we named our layout file Main.axml:

protected override void OnCreate(Bundle bundle)
{
  base.OnCreate(bundle);

  // note the name "Main"
  SetContentView(Resource.Layout.Main);
}

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

In order to access the control at runtime, we make use of the FindViewById method on the activity or a view (use the View property of a fragment):
```
Button btn = FindViewById<Button>(Resource.Id.buttonId);
```

How it works...

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.

Tip

Fragments can be used in addition to layouts to create advanced interfaces consisting of self-contained, reusable regions.

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.

Tip

A wide view hierarchy is better than a deep view hierarchy.

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.

Tip

The ID need not be unique, but it's best to be completely unique when possible so that the specific view can be found in the hierarchy.

There's more...

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.

Creating an options menu

Android provides the user with the ability to display a special type of menu that contains a set of items that pertains to the entire app, instead of the current activity.

How to do it...

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:

First, we create a new XML file with the name of the menu, for example Options.xml, in the menu folder under the Resources folder.

Then, we create the menu structure in this file, for example, create three menu items: refresh, settings, and about.

<?xml version="1.0" encoding="utf-8" ?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
  <item
    android:id="@+id/action_refresh"
    android:icon="@drawable/ic_action_refresh"
    android:title="@string/action_refresh" />
  <item
    android:id="@+id/action_settings"
    android:title="@string/action_settings" />
  <item
    android:id="@+id/action_about"
    android:title="@string/action_about"/>
</menu>

Once we have the structure, we override the OnCreateOptionsMenu() method and inflate the resource:

public override bool OnCreateOptionsMenu(IMenu menu)
{
  MenuInflater.Inflate(Resource.Menu.Options, menu);
  return true;
}

If we want to respond to items being selected in that menu, all we need to do is override the OnOptionsItemSelected() method:

public override bool OnOptionsItemSelected(IMenuItem item) {
  if (item.ItemId == Resource.Id.action_refresh) {
    // do something here...
    return true; // we handled the event
  }
  return base.OnOptionsItemSelected(item);
}

How it works...

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.

Tip

Although not required, it is recommended that most menu items include an icon.

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.

Note

The OnCreateOptionsMenu() method should return true if the menu is to be displayed. Returning false will result in the menu not being displayed.

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.

Supporting previous Android versions

As the Android operating system evolves, many new features are added and older devices are often left behind.

How to do it...

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:

An Android app has three platform versions to be set. The first is the API features that are available to code against. We set this to always be the latest in the Target Framework dropdown of the project options.
The next version to set (via Minimum Android version) is the lowest version of the OS that the app can be installed on. When using the support libraries, we can usually target versions down to version 2.3.
Lastly, the Target Android version dropdown specifies how the app should behave when installed on a later version of the OS. Typically, this should always be the latest version so the app will always function as the user expects.

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:

Create or open a project in Xamarin Studio.
1. Right-click on the project folder in the Solution Explorer list.
2. Select Add and then Add Packages….
3. In the Add Packages dialog that is displayed, search for Xamarin.Android.Support.
4. Select both Xamarin Support Library v4 and Xamarin Support Library v7 AppCompat.
5. Click on Add Package.

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

Once the packages are installed, our activities can now inherit from the AppCompatActivity type instead of the usual Activity type:
```
public class MyActivity : AppCompatActivity
{
}
```
Finally, we specify that the activity theme be one of the AppCompat derivatives using the Theme property in the [Activity] attribute:
```
[Activity(..., Theme = "@style/Theme.AppCompat", ...)]
```

How it works...

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.

Note

Types from the Android Support Library are available to almost all versions of Android currently in use.

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.

Tip

Setting the minimum Android version for an app will prevent the app from being installed on devices with earlier versions of the OS.

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.

Note

When using the AppCompatActivity type, the activity theme must be one of the AppCompat theme variations.

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);

There's more...

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

Almost all apps require some form of commanding, usually being frequently used. As a result, these commands should be presented in an easily consumed region of the screen, regardless of differences in screen configuration.

How to do it...

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:

By default, on Android 4.0, apps will have an action bar. To access this, we can use the ActionBar property on the Activity type:
```
ActionBar.Title = "Xamarin Cookbook"; 
```

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

First, we need to install the Xamarin Support Library v7 AppCompat Component or NuGet.
Then, we need to ensure our activities inherit from the AppCompatActivity type instead of the usual Activity type:
```
public class MyActivity : AppCompatActivity
{
}
```
Next, we add the Theme property to the [Activity] attribute:
```
[Activity(..., Theme = "@style/Theme.AppCompat")]
```
Finally, if we need to access the ActionBar instance, it is available via the SupportActionBar property on the activity:
```
SupportActionBar.Title = "Xamarin Cookbook";
```

How it works...

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.

There's more...

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);

Navigating with the action bar

The action bar is used to allow the user to navigate to a parent activity, as well as show the user where they are in the app.

How to do it...

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.

First, we need to ensure that our source activity is accessible using a known name by adding a [Register] attribute:
```
[Register("com.xamarincookbook.MainActivity")]
public class MainActivity : AppCompatActivity
{
}
```

Next, we let the system know which activity we want to navigate up to using a [MetaData] attribute:

[MetaData(
  "android.support.PARENT_ACTIVITY", 
  Value = "com.xamarincookbook.MainActivity")]
public class RecipeDetailsActivity : AppCompatActivity {
}

Then in the child activity, we let the action bar know that we want to allow upward navigation:
```
SupportActionBar.SetDisplayHomeAsUpEnabled(true);
```

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

First, we set the ParentActivity property on the [Activity] attribute:

[Activity (ParentActivity = typeof(MainActivity))]
public class RecipeDetailsActivity : Activity
{
}

Then, we let the child activity's action bar know that we want to allow upward navigation:
```
ActionBar.SetDisplayHomeAsUpEnabled(true);
```

How it works...

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.

Tip

If an activity is the topmost one in an app and it does not have a parent activity, it should not present an up button.

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.

There's more...

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.