1page.title=Abstracting the New APIs
2parent.title=Creating Backward-Compatible UIs
3parent.link=index.html
4
5trainingnavtop=true
6next.title=Proxying to the New APIs
7next.link=new-implementation.html
8
9@jd:body
10
11<div id="tb-wrapper">
12<div id="tb">
13
14<h2>This lesson teaches you to:</h2>
15<ul>
16  <li><a href="#prepare-abstraction">Prepare for Abstraction</a></li>
17  <li><a href="#create-abstract-tab">Create an Abstract Tab Interface</a></li>
18  <li><a href="#abstract-actionbar-tab">Abstract ActionBar.Tab</a></li>
19  <li><a href="#abstract-actionbar-methods">Abstract ActionBar Tab Methods</a></li>
20</ul>
21
22<h2>You should also read</h2>
23<ul>
24  <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
25  <li><a href="{@docRoot}guide/topics/ui/actionbar.html#Tabs">Action Bar Tabs</a></li>
26</ul>
27
28<h2>Try it out</h2>
29
30<div class="download-box">
31<a href="http://developer.android.com/shareables/training/TabCompat.zip"
32  class="button">Download the sample app</a>
33<p class="filename">TabCompat.zip</p>
34</div>
35
36</div>
37</div>
38
39<p>Suppose you want to use <a href="{@docRoot}guide/topics/ui/actionbar.html#Tabs">action bar tabs</a> as the primary form of top-level navigation in your application. Unfortunately, the {@link android.app.ActionBar} APIs are only available in Android 3.0 or later (API level 11+). Thus, if you want to distribute your application to devices running earlier versions of the platform, you need to provide an implementation that supports the newer API while providing a fallback mechanism that uses older APIs.</p>
40
41<p>In this class, you build a tabbed user interface (UI) component that uses abstract classes with version-specific implementations to provide backward-compatibility. This lesson describes how to create an abstraction layer for the new tab APIs as the first step toward building the tab component.</p>
42
43<h2 id="prepare-abstraction">Prepare for Abstraction</h2>
44
45<p><a href="http://en.wikipedia.org/wiki/Abstraction_(computer_science)">Abstraction</a> in the Java programming language involves the creation of one or more interfaces or abstract classes to hide implementation details. In the case of newer Android APIs, you can use abstraction to build version-aware components that use the current APIs on newer devices, and fallback to older, more compatible APIs on older devices.</p>
46
47<p>When using this approach, you first determine what newer classes you want to be able to use in a backward compatible way, then create abstract classes, based on the public interfaces of the newer classes. In defining the abstraction interfaces, you should mirror the newer API as much as possible. This maximizes forward-compatibility and makes it easier to drop the abstraction layer in the future when it is no longer necessary.</p>
48
49<p>After creating abstract classes for these new APIs, any number of implementations can be created and chosen at runtime. For the purposes of backward-compatibility, these implementations can vary by required API level. Thus, one implementation may use recently released APIs, while others can use older APIs.</p>
50
51<h2 id="create-abstract-tab">Create an Abstract Tab Interface</h2>
52
53<p>In order to create a backward-compatible version of tabs, you should first determine which features and specific APIs your application requires. In the case of top-level section tabs, suppose you have the following functional requirements:</p>
54
55<ol>
56<li>Tab indicators should show text and an icon.</li>
57<li>Tabs can be associated with a fragment instance.</li>
58<li>The activity should be able to listen for tab changes.</li>
59</ol>
60
61<p>Preparing these requirements in advance allows you to control the scope of your abstraction layer. This means that you can spend less time creating multiple implementations of your abstraction layer and begin using your new backward-compatible implementation sooner.</p>
62
63<p>The key APIs for tabs are in {@link android.app.ActionBar} and {@link android.app.ActionBar.Tab ActionBar.Tab}. These are the APIs to abstract in order to make your tabs version-aware. The requirements for this example project call for compatibility back to Eclair (API level 5) while taking advantage of the new tab features in Honeycomb (API Level 11). A diagram of the class structure to support these two implementations and their abstract base classes (or interfaces) is shown below.</p>
64
65<img src="{@docRoot}images/training/backward-compatible-ui-classes.png"
66  alt="Class diagram of abstract base classes and version-specific implementations." id="figure-classes">
67
68<p class="img-caption"><strong>Figure 1.</strong> Class diagram of abstract base classes and version-specific implementations.</p>
69
70<h2 id="abstract-actionbar-tab">Abstract ActionBar.Tab</h2>
71
72<p>Get started on building your tab abstraction layer by creating an abstract class representing a tab, that mirrors the {@link android.app.ActionBar.Tab ActionBar.Tab} interface:</p>
73
74<pre>
75public abstract class CompatTab {
76    ...
77    public abstract CompatTab setText(int resId);
78    public abstract CompatTab setIcon(int resId);
79    public abstract CompatTab setTabListener(
80            CompatTabListener callback);
81    public abstract CompatTab setFragment(Fragment fragment);
82
83    public abstract CharSequence getText();
84    public abstract Drawable getIcon();
85    public abstract CompatTabListener getCallback();
86    public abstract Fragment getFragment();
87    ...
88}
89</pre>
90
91<p>You can use an abstract class instead of an interface here to simplify the implementation of common features such as association of tab objects with activities (not shown in the code snippet).</p>
92
93<h2 id="abstract-actionbar-methods">Abstract ActionBar Tab Methods</h2>
94
95<p>Next, define an abstract class that allows you to create and add tabs to an activity, like {@link android.app.ActionBar#newTab ActionBar.newTab()} and {@link android.app.ActionBar#addTab ActionBar.addTab()}:</p>
96
97<pre>
98public abstract class TabHelper {
99    ...
100
101    public CompatTab newTab(String tag) {
102        // This method is implemented in a later lesson.
103    }
104
105    public abstract void addTab(CompatTab tab);
106
107    ...
108}
109</pre>
110
111<p>In the next lessons, you create implementations for <code>TabHelper</code> and <code>CompatTab</code> that work across both older and newer platform versions.</p>
112