Home | History | Annotate | Download | only in backward-compatible-ui 
      1 page.title=Proxying to the New APIs
      2 parent.title=Creating Backward-Compatible UIs
      3 parent.link=index.html
      4 
      5 trainingnavtop=true
      6 previous.title=Abstracting the New APIs
      7 previous.link=abstracting.html
      8 next.title=Creating an Implementation with Older APIs
      9 next.link=older-implementation.html
     10 
     11 @jd:body
     12 
     13 <div id="tb-wrapper">
     14 <div id="tb">
     15 
     16 <h2>This lesson teaches you to:</h2>
     17 <ol>
     18   <li><a href="#new-tabs">Implement Tabs Using New APIs</a></li>
     19   <li><a href="#compattabhoneycomb">Implement CompatTabHoneycomb</a></li>
     20   <li><a href="#tabhelperhoneycomb">Implement TabHelperHoneycomb</a></li>
     21 </ol>
     22 
     23 <h2>You should also read</h2>
     24 <ul>
     25   <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
     26   <li><a href="{@docRoot}guide/topics/ui/actionbar.html#Tabs">Action Bar Tabs</a></li>
     27 </ul>
     28 
     29 <h2>Try it out</h2>
     30 
     31 <div class="download-box">
     32 <a href="http://developer.android.com/shareables/training/TabCompat.zip"
     33   class="button">Download the sample app</a>
     34 <p class="filename">TabCompat.zip</p>
     35 </div>
     36 
     37 </div>
     38 </div>
     39 
     40 <p>This lesson shows you how to subclass the <code>CompatTab</code> and <code>TabHelper</code> abstract classes and use new APIs. Your application can use this implementation on devices running a platform version that supports them.</p>
     41 
     42 <h2 id="new-tabs">Implement Tabs Using New APIs</h2>
     43 
     44 <p>The concrete classes for <code>CompatTab</code> and <code>TabHelper</code> that use newer APIs are a <em>proxy</em> implementation. Since the abstract classes defined in the previous lesson mirror the new APIs (class structure, method signatures, etc.), the concrete classes that use these newer APIs simply proxy method calls and their results.</p>
     45 
     46 <p>You can directly use newer APIs in these concrete classes&mdash;and not crash on earlier devices&mdash;because of lazy class loading. Classes are loaded and initialized on first access&mdash;instantiating the class or accessing one of its static fields or methods for the first time. Thus, as long as you don't instantiate the Honeycomb-specific implementations on pre-Honeycomb devices, the Dalvik VM won't throw any {@link java.lang.VerifyError} exceptions.</p>
     47 
     48 <p>A good naming convention for this implementation is to append the API level or platform version code name corresponding to the APIs required by the concrete classes. For example, the native tab implementation can be provided by <code>CompatTabHoneycomb</code> and <code>TabHelperHoneycomb</code> classes, since they rely on APIs available in Android 3.0 (API level 11) or later.</p>
     49 
     50 <img src="{@docRoot}images/training/backward-compatible-ui-classes-honeycomb.png"
     51   alt="Class diagram for the Honeycomb implementation of tabs." id="figure-classes">
     52 
     53 <p class="img-caption"><strong>Figure 1.</strong> Class diagram for the Honeycomb implementation of tabs.</p>
     54 
     55 <h2 id="compattabhoneycomb">Implement CompatTabHoneycomb</h2>
     56 
     57 <p><code>CompatTabHoneycomb</code> is the implementation of the <code>CompatTab</code> abstract class that <code>TabHelperHoneycomb</code> uses to reference individual tabs. <code>CompatTabHoneycomb</code> simply proxies all method calls to its contained {@link android.app.ActionBar.Tab} object.</p>
     58 
     59 <p>Begin implementing <code>CompatTabHoneycomb</code> using the new {@link android.app.ActionBar.Tab ActionBar.Tab} APIs:</p>
     60 
     61 <pre>
     62 public class CompatTabHoneycomb extends CompatTab {
     63     // The native tab object that this CompatTab acts as a proxy for.
     64     ActionBar.Tab mTab;
     65     ...
     66 
     67     protected CompatTabHoneycomb(FragmentActivity activity, String tag) {
     68         ...
     69         // Proxy to new ActionBar.newTab API
     70         mTab = activity.getActionBar().newTab();
     71     }
     72 
     73     public CompatTab setText(int resId) {
     74         // Proxy to new ActionBar.Tab.setText API
     75         mTab.setText(resId);
     76         return this;
     77     }
     78 
     79     ...
     80     // Do the same for other properties (icon, callback, etc.)
     81 }
     82 </pre>
     83 
     84 <h2 id="tabhelperhoneycomb">Implement TabHelperHoneycomb</h2>
     85 
     86 <p><code>TabHelperHoneycomb</code> is the implementation of the <code>TabHelper</code> abstract class that proxies method calls to an actual {@link android.app.ActionBar}, obtained from its contained {@link android.app.Activity}.</p>
     87 
     88 <p>Implement <code>TabHelperHoneycomb</code>, proxying method calls to the {@link android.app.ActionBar} API:</p>
     89 
     90 <pre>
     91 public class TabHelperHoneycomb extends TabHelper {
     92     ActionBar mActionBar;
     93     ...
     94 
     95     protected void setUp() {
     96         if (mActionBar == null) {
     97             mActionBar = mActivity.getActionBar();
     98             mActionBar.setNavigationMode(
     99                     ActionBar.NAVIGATION_MODE_TABS);
    100         }
    101     }
    102 
    103     public void addTab(CompatTab tab) {
    104         ...
    105         // Tab is a CompatTabHoneycomb instance, so its
    106         // native tab object is an ActionBar.Tab.
    107         mActionBar.addTab((ActionBar.Tab) tab.getTab());
    108     }
    109 
    110     // The other important method, newTab() is part of
    111     // the base implementation.
    112 }
    113 </pre>