Merge "docs: New action views/action providers doc" into mnc-preview-docs

docs/html/training/appbar/action-views.jd

@@ -0,0 +1,248 @@
+page.title=Action Views and Action Providers
+page.tags="action view", "action provider"
+helpoutsWidget=true
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+    <h2>This lesson teaches you to</h2>
+
+    <ol>
+      <li><a href="#action-view">Add an Action View</a></li>
+      <li><a href="#action-provider">Add an Action Provider</a></li>
+    </ol>
+
+<!--
+    <h2>Useful Resources</h2>
+    <ul>
+      <li></li>
+    </ul>
+-->
+
+  </div>
+</div>
+
+<p>
+  The <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
+  appcompat</a> support library {@link android.support.v7.widget.Toolbar} provides several
+  different ways for users to interact with your app. Previous lessons
+  described how to define an <em>action</em>, which can be either a button or a
+  menu item. This lesson describes how to add two versatile components:
+</p>
+
+<ul>
+  <li>An <em>action view</em> is an action that provides rich functionality
+  within the app bar. For example, a search action view allows the user to type
+  their search text in the app bar, without having to change activities or
+  fragments.
+  </li>
+
+  <li>An <em>action provider</em> is an action with its own customized layout.
+  The action initially appears as a button or menu item, but when the user clicks the
+  action, the action provider controls the action's behavior in any way you
+  want to define. For example, the action provider might respond to a click by
+  displaying a menu.
+  </li>
+</ul>
+
+<p>
+  The Android support libraries provide several specialized action view and
+  action provider widgets. For example, the {@link
+  android.support.v7.widget.SearchView} widget implements an action view for
+  entering search queries, and the {@link
+  android.support.v7.widget.ShareActionProvider} widget implements an action
+  provider for
+  sharing information with other apps. You can also define your own action
+  views and action providers.
+</p>
+
+<h2 id="action-view">
+  Add an Action View
+</h2>
+
+<p>
+  To add an action view, create an <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
+  element in the toolbar's menu resource, as <a href="actions.html">Add Action
+  Buttons</a> describes. Add one of the following two
+  attributes to the <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
+  element:
+</p>
+
+<ul>
+  <li>
+    <code>actionViewClass</code>: The class of a widget that implements the
+    action.
+  </li>
+
+  <li>
+    <code>actionLayout</code>: A layout resource describing the action's
+    components.
+  </li>
+</ul>
+
+<p>
+  Set the <code>showAsAction</code> attribute to either
+  <code>"ifRoom|collapseActionView"</code> or
+  <code>"never|collapseActionView"</code>. The <code>collapseActionView</code>
+  flag indicates how to display the widget when the user is not interacting with
+  it: If the widget is on the app bar, the app should display the widget as an
+  icon. If the widget is in the overflow menu, the app should display the widget
+  as a menu item. When the user interacts with the action view, it
+  expands to fill the app bar.
+</p>
+
+<p>
+  For example, the following code adds a {@link
+  android.support.v7.widget.SearchView} widget to the app bar:
+</p>
+
+<pre>
+&lt;item android:id="&#64;+id/action_search"
+     android:title="&#64;string/action_search"
+     android:icon="&#64;drawable/ic_search"
+     <strong>app:showAsAction="ifRoom|collapseActionView"</strong>
+     <strong>app:actionViewClass="android.support.v7.widget.SearchView" /&gt;</strong>
+</pre>
+
+<p>
+  If the user is not interacting with the widget, the app displays the widget
+  as the icon specified by <code>android:icon</code>. (If there is not enough
+  room in the app bar, the app adds the action to the overflow menu.) When the
+  user taps the icon or menu item, the widget expands to fill the toolbar,
+  allowing the user to interact with it.
+</p>
+
+<img src="{@docRoot}images/training/appbar/action_view_2x.png"
+    srcset="{@docRoot}images/training/appbar/action_view.png 1x,
+        {@docRoot}images/training/appbar/action_view_2x.png 2x"
+    alt="" width="400" id="figure-action-view">
+<p class="img-caption">
+  <strong>Figure 1.</strong> When the user clicks an action view's icon, the
+  view's UI fills the toolbar.
+</p>
+
+<p>
+  If you need to configure the action, do so in your activity's {@link
+  android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You
+  can get the action view's object reference by calling the static {@link
+  android.support.v4.view.MenuItemCompat#getActionView getActionView()} method.
+  For example, the following code gets the object reference for the {@link
+  android.support.v7.widget.SearchView} widget defined in the previous code
+  example:
+</p>
+
+<pre>
+&#64;Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    getMenuInflater().inflate(R.menu.main_activity_actions, menu);
+
+    <strong>MenuItem searchItem = menu.findItem(R.id.action_search);</strong>
+    <strong>SearchView searchView =
+            (SearchView) MenuItemCompat.getActionView(searchItem);</strong>
+
+    // Configure the search info and add any event listeners...
+
+    return super.onCreateOptionsMenu(menu);
+}
+</pre>
+<h3 id="view-expansion">Responding to action view expansion</h3>
+
+<p>
+  If the action's <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
+  element has a <code>collapseActionView</code> flag, the app displays the action
+  view as an icon until the user interacts with the action view.
+  When the user clicks on the icon, the built-in handler for {@link
+  android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} expands
+  the action view. If your activity subclass overrides the {@link
+  android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method,
+  your override method must call {@link android.app.Activity#onOptionsItemSelected
+  super.onOptionsItemSelected()} so the superclass can expand the action view.
+</p>
+
+<p>
+  If you want to do something when the action is expanded or collapsed, you can
+  define a class that implements
+  {@link android.view.MenuItem.OnActionExpandListener}, and pass a member of
+  that class to
+  {@link android.view.MenuItem#setOnActionExpandListener
+  setOnActionExpandListener()}. For example, you might want to update the
+  activity based on whether an action view is expanded or collapsed. The
+  following snippet shows how to define and pass a listener:
+</p>
+<pre>
+&#64;Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    getMenuInflater().inflate(R.menu.options, menu);
+    // ...
+
+    // Define the listener
+    OnActionExpandListener expandListener = new OnActionExpandListener() {
+        &#64;Override
+        public boolean onMenuItemActionCollapse(MenuItem item) {
+            // Do something when action item collapses
+            return true;  // Return true to collapse action view
+        }
+
+        &#64;Override
+        public boolean onMenuItemActionExpand(MenuItem item) {
+            // Do something when expanded
+            return true;  // Return true to expand action view
+        }
+    };
+
+    // Get the MenuItem for the action item
+    MenuItem actionMenuItem = menu.findItem(R.id.myActionItem);
+
+    // Assign the listener to that action item
+    MenuItemCompat.setOnActionExpandListener(actionMenuItem, expandListener);
+
+    // Any other things you have to do when creating the options menu…
+
+    return true;
+}
+</pre>
+
+<h2 id="action-provider">
+  Add an Action Provider
+</h2>
+
+<p>
+  To declare an action provider, create an <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
+  element in the toolbar's menu resource, as described in <a href=
+  "actions.html">Add Action Buttons</a>. Add an
+  <code>actionProviderClass</code> attribute, and set it to the fully qualified
+  class name for the action provider class.
+</p>
+
+<p>
+  For example, the following code declares a {@link
+  android.support.v7.widget.ShareActionProvider}, which is a widget defined in
+  the support library that allows your app to share data with other apps:
+</p>
+
+<pre>
+&lt;item android:id="&#64;+id/action_share"
+    android:title="&#64;string/share"
+    app:showAsAction="ifRoom"
+    app:actionProviderClass="android.support.v7.widget.ShareActionProvider"/&gt;
+</pre>
+
+<p>
+  In this case, it is not necessary to declare an icon for the widget, since {@link
+  android.support.v7.widget.ShareActionProvider} provides its own graphics. If
+  you are using a custom action, declare an icon.
+</p>
+
+<p>
+  For information about creating a custom action provider, see the {@link
+  android.support.v4.view.ActionProvider} reference. For information about
+  configuring a {@link android.support.v7.widget.ShareActionProvider}, see the
+  reference for that class.
+</p>

docs/html/training/appbar/index.jd

@@ -95,4 +95,13 @@ startpage=true
     Learn how to add an <em>Up</em> button to your app bar, so users
     can navigate back to the app's home screen.
   </dd>
+
+  <dt>
+    <b><a href="action-views.html">Action Views and Action Providers</a></b>
+  </dt>
+
+  <dd>
+    Learn how to use these widgets to provide advanced functionality in your
+    app bar.
+  </dd>
 </dl>

docs/html/training/training_toc.cs

@@ -1412,6 +1412,9 @@ results."
           <li><a href="<?cs var:toroot ?>training/appbar/up-action.html"
             >Adding an Up Action</a>
           </li>
+          <li><a href="<?cs var:toroot ?>training/appbar/action-views.html"
+            >Action Views and Action Providers</a>
+          </li>
         </ul>
       </li>