Custom UI for Android

The Android Style and Theme system can be daunting to approach; this document is meant to be a introduction to the theme system, and is intended to help you define custom themes for use with the Social Login Android SDK.

The Android Style and Theme system is a complex and powerful system used to skin the appearance of Android applications. It defines the attributes for each view, while the Android XML Layout system defines where each view appears on a give page. There is some overlap between the Android Style and Theme and the Android Layout system, but this is the general division.

It is easiest to start by extending an existing theme that is close to your desired appearance and tweaking individual attributes. Commonly used themes include the Holo theme, introduced with Honeycomb, and the original Android theme, both of which come in light and dark variants.

Creating a Custom Android Theme

To implement a custom theme create or edit MyAndroidApp/res/values/themes.xml and add the following (replacing MyCustomTheme with the correct class name):


    ...

        #ffff0000

    ...

In your AndroidManifest.xml apply the theme to the activities you want to style. (Replace com.myapp.MyActivity with the appropriate value.):


Your new theme will be applied to your activity, and text is now bright red.

Red Text

Figure 1: Red Text

Choosing a Theme to Extend

Android themes are rich mediums, and possess many attributes that affect the style of the user interface. You must define many of these attributes for proper operation. Because there are so many attributes, and many attributes must be defined prior to use, it is best to extend an existing theme.

The parent attribute of the <style> element controls which theme your custom theme will extend. There are four base Android themes and two Janrain themes that are excellent candidates for extension:

We also bundled two Janrain Themes with the Android library, which adapt between Theme and Theme.Holo depending on the running version of Android:

Note: The Holo theme is not available on Android versions 2.3 and below. If you wish to customize the Holo theme and simultaneously support these lesser versions of Android, you will need to use the theme selector technique to use the appropriate theme on each version of the platform.

Therefore, if you would like to use the Theme.Holo theme where available, and fall back to Theme elsewhere, then you should extend Theme.Janrain.

Colors

You can define colors for drawable resources and apply colors to theme attributes.

Defining Color Drawable Resources

If you wish to present the user interface themed with your application’s color, first define your color as an Android resource. To define a custom color, create or edit MyAndroidApp/res/values/colors.xml and add the following:


   ...
   #ff1a557c
   ...

Note: If your custom color has a dark value then you may wish to extend your custom version of Theme instead of Theme.Light.

Applying Colors to Theme Attributes

You can apply your color to some theme attributes, such as the window background and the primary text color, by adding elements to your custom theme. These attributes are defined in your styles.xml file. For example, to apply the custom color to the window background, add the following two elements to your custom theme, defined in MyAndroidApp/res/values/styles.xml file:


   ...

      @color/my_custom_color
      @color/my_custom_color

   ...

The first <item> controls the background Drawable of the window (a color is a type of Drawable.) The second sets the cache color hint, used by the provider list screen in the library, and other instances of ListView. The windowBackground attribute also accepts Android Drawable values. Drawables include XML defined gradients, XML defined colors, and images. If you use a non-solid-color Drawable for a background you must set android:colorBackgroundCacheHint to #00000000.

Applying Custom Themes to the Android User Interface

Finally, to apply your custom theme with your custom background color to the library user interface, edit your AndroidManifest.xml and change the android:theme attribute of the activity definition with the android:name="com.janrain.android.engage.ui.JRFragmentHostActivity$Fullscreen" attribute (replacing MyCustomTheme as necessary):


For proper operation of the library on Android tablets you will also need to provide a dialog variant of your theme. The dialog variant should extend an existing dialog theme. For example (replace MyCustomThemeDialogVariant with the correct style name):


    ...

        <item name="android:windowBackground"<@color/my_custom_color
        ?android:windowBackground

    ...

You should apply the dialog variant to the activity element of your Android manifest with the android:name="com.janrain.android.engage.ui.JRFragmentHostActivity" attribute (again, replacing MyCustomThemeDialogVariant):


Using a Custom Nine-Patch With Buttons

A nine-patch drawable is a special kind of image which can be scaled in width and height while maintaining its visual integrity. Nine-patches are the most common way to specify the appearance of Android buttons, though you can use any drawable type.

Notice the one pixel black lines around the edge in Figure 3. They control the scaling of the image.

1. Save this bitmap as MyApplication/res/drawable/my_nine_patch.9.png. (Replace MyApplication and my_nine_patch.9.png with the real names of the directory and png.)

2. Define a new style (you can define the new style in the same file that you defined your custom theme from Creating a Custom Android Theme above):


   ...

           @drawable/my_nine_patch

   ...

3. Apply the new button style to the buttonStyle attribute of your custom theme. See Figure 4, for reference.


   ...

           ...
           @style/MyCustomButton

   ...

Now the buttons in the activities your theme is applied to have custom images. However, you may notice that they don’t change appearance when selected. Read Selector Drawables below for an introduction to using multiple drawables to define one drawable that changes based on state.

Other Kinds of Drawables

Drawables are the Android resources used to define the pixels drawn to the screen. (The Android layout resources define what drawables are drawn where.) There are many different kinds of drawable resources.

Selector Drawables

A selector is a drawable which changes based on state. Here is an example selector which switches between the example.9.png nine-patch described above when unselected and your custom color defined above in Defining Color Drawable Resources when selected. For example, create MyApplication/res/drawable/my_custom_selector.xml and add the following (replacing MyApplication and my_custom_selector as necessary):


Now you can use this selector as the drawable applied to the buttonStyle attribute in your custom theme and the buttons will change appearance based on their state:


   ...
           @drawable/my_custom_selector

   ...

If solid flood fill is not the right appearance for selected buttons in your application, you could copy your custom nine-patch and apply a visual affordance for the unpressed state and use the altered nine-patch for the pressed state, or the other way around.

Gradient Drawables

Gradients are a great way to polish the appearance of an application and they are easy to define and use in an Android theme. For example, create MyApplication/res/drawable/my_gradient.xml and add the following (replace MyApplication and my_gradient.xml as appropriate):


Then, apply the gradient to the windowBackground attribute of your custom theme. (See Figure 5 for the result.)


   ...

           ...
           @drawable/my_gradient
           #00000000

   ...

Theme Attributes

Themes offer a wide variety of attributes with which you can control the appearance of an Android activities user interface. For more information see the Android Styles and Themes guide, the Android theme.xml source, and the Android attrs.xml source. Here is a short list of commonly used and otherwise useful Theme attributes you may wish to specify:

(From the Android platform data/res/valus/attrs.xml)

Android Tablet Support

JUMP for Android supports tablet screens either seamlessly, or with embeddable fragments.

Seamless Support

To take advantage of seamless support, continue to call JREngage#showAuthenticationDialog() or JREngage#showSocialPublishingDialogWithActivity(JRActivityObject). These library dialogs display modally.

Embedded Fragment Support

You can also embed the sharing dialog in your UI as an Android Fragment.

Note: Embedded support requires a host activity sub-classed from android.support.v4.app.FragmentActivity. The android.app.FragmentActivity is incompatible for embedded support.