1page.title=Action Views and Action Providers
2page.tags="action view", "action provider"
3helpoutsWidget=true
4trainingnavtop=true
5
6@jd:body
7
8<div id="tb-wrapper">
9  <div id="tb">
10
11    <h2>This lesson teaches you to</h2>
12
13    <ol>
14      <li><a href="#action-view">Add an Action View</a></li>
15      <li><a href="#action-provider">Add an Action Provider</a></li>
16    </ol>
17
18<!--
19    <h2>Useful Resources</h2>
20    <ul>
21      <li></li>
22    </ul>
23-->
24
25  </div>
26</div>
27
28<p>
29  The <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
30  appcompat</a> support library {@link android.support.v7.widget.Toolbar} provides several
31  different ways for users to interact with your app. Previous lessons
32  described how to define an <em>action</em>, which can be either a button or a
33  menu item. This lesson describes how to add two versatile components:
34</p>
35
36<ul>
37  <li>An <em>action view</em> is an action that provides rich functionality
38  within the app bar. For example, a search action view allows the user to type
39  their search text in the app bar, without having to change activities or
40  fragments.
41  </li>
42
43  <li>An <em>action provider</em> is an action with its own customized layout.
44  The action initially appears as a button or menu item, but when the user clicks the
45  action, the action provider controls the action's behavior in any way you
46  want to define. For example, the action provider might respond to a click by
47  displaying a menu.
48  </li>
49</ul>
50
51<p>
52  The Android support libraries provide several specialized action view and
53  action provider widgets. For example, the {@link
54  android.support.v7.widget.SearchView} widget implements an action view for
55  entering search queries, and the {@link
56  android.support.v7.widget.ShareActionProvider} widget implements an action
57  provider for
58  sharing information with other apps. You can also define your own action
59  views and action providers.
60</p>
61
62<h2 id="action-view">
63  Add an Action View
64</h2>
65
66<p>
67  To add an action view, create an <a href=
68  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
69  element in the toolbar's menu resource, as <a href="actions.html">Add Action
70  Buttons</a> describes. Add one of the following two
71  attributes to the <a href=
72  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
73  element:
74</p>
75
76<ul>
77  <li>
78    <code>actionViewClass</code>: The class of a widget that implements the
79    action.
80  </li>
81
82  <li>
83    <code>actionLayout</code>: A layout resource describing the action's
84    components.
85  </li>
86</ul>
87
88<p>
89  Set the <code>showAsAction</code> attribute to either
90  <code>"ifRoom|collapseActionView"</code> or
91  <code>"never|collapseActionView"</code>. The <code>collapseActionView</code>
92  flag indicates how to display the widget when the user is not interacting with
93  it: If the widget is on the app bar, the app should display the widget as an
94  icon. If the widget is in the overflow menu, the app should display the widget
95  as a menu item. When the user interacts with the action view, it
96  expands to fill the app bar.
97</p>
98
99<p>
100  For example, the following code adds a {@link
101  android.support.v7.widget.SearchView} widget to the app bar:
102</p>
103
104<pre>
105&lt;item android:id="&#64;+id/action_search"
106     android:title="&#64;string/action_search"
107     android:icon="&#64;drawable/ic_search"
108     <strong>app:showAsAction="ifRoom|collapseActionView"</strong>
109     <strong>app:actionViewClass="android.support.v7.widget.SearchView" /&gt;</strong>
110</pre>
111
112<p>
113  If the user is not interacting with the widget, the app displays the widget
114  as the icon specified by <code>android:icon</code>. (If there is not enough
115  room in the app bar, the app adds the action to the overflow menu.) When the
116  user taps the icon or menu item, the widget expands to fill the toolbar,
117  allowing the user to interact with it.
118</p>
119
120<img src="{@docRoot}images/training/appbar/action_view_2x.png"
121    srcset="{@docRoot}images/training/appbar/action_view.png 1x,
122        {@docRoot}images/training/appbar/action_view_2x.png 2x"
123    alt="" width="400" id="figure-action-view">
124<p class="img-caption">
125  <strong>Figure 1.</strong> When the user clicks an action view's icon, the
126  view's UI fills the toolbar.
127</p>
128
129<p>
130  If you need to configure the action, do so in your activity's {@link
131  android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You
132  can get the action view's object reference by calling the static {@link
133  android.support.v4.view.MenuItemCompat#getActionView getActionView()} method.
134  For example, the following code gets the object reference for the {@link
135  android.support.v7.widget.SearchView} widget defined in the previous code
136  example:
137</p>
138
139<pre>
140&#64;Override
141public boolean onCreateOptionsMenu(Menu menu) {
142    getMenuInflater().inflate(R.menu.main_activity_actions, menu);
143
144    <strong>MenuItem searchItem = menu.findItem(R.id.action_search);</strong>
145    <strong>SearchView searchView =
146            (SearchView) MenuItemCompat.getActionView(searchItem);</strong>
147
148    // Configure the search info and add any event listeners...
149
150    return super.onCreateOptionsMenu(menu);
151}
152</pre>
153<h3 id="view-expansion">Responding to action view expansion</h3>
154
155<p>
156  If the action's <a href=
157  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
158  element has a <code>collapseActionView</code> flag, the app displays the action
159  view as an icon until the user interacts with the action view.
160  When the user clicks on the icon, the built-in handler for {@link
161  android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} expands
162  the action view. If your activity subclass overrides the {@link
163  android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method,
164  your override method must call {@link android.app.Activity#onOptionsItemSelected
165  super.onOptionsItemSelected()} so the superclass can expand the action view.
166</p>
167
168<p>
169  If you want to do something when the action is expanded or collapsed, you can
170  define a class that implements
171  {@link android.view.MenuItem.OnActionExpandListener}, and pass a member of
172  that class to
173  {@link android.view.MenuItem#setOnActionExpandListener
174  setOnActionExpandListener()}. For example, you might want to update the
175  activity based on whether an action view is expanded or collapsed. The
176  following snippet shows how to define and pass a listener:
177</p>
178<pre>
179&#64;Override
180public boolean onCreateOptionsMenu(Menu menu) {
181    getMenuInflater().inflate(R.menu.options, menu);
182    // ...
183
184    // Define the listener
185    OnActionExpandListener expandListener = new OnActionExpandListener() {
186        &#64;Override
187        public boolean onMenuItemActionCollapse(MenuItem item) {
188            // Do something when action item collapses
189            return true;  // Return true to collapse action view
190        }
191
192        &#64;Override
193        public boolean onMenuItemActionExpand(MenuItem item) {
194            // Do something when expanded
195            return true;  // Return true to expand action view
196        }
197    };
198
199    // Get the MenuItem for the action item
200    MenuItem actionMenuItem = menu.findItem(R.id.myActionItem);
201
202    // Assign the listener to that action item
203    MenuItemCompat.setOnActionExpandListener(actionMenuItem, expandListener);
204
205    // Any other things you have to do when creating the options menu…
206
207    return true;
208}
209</pre>
210
211<h2 id="action-provider">
212  Add an Action Provider
213</h2>
214
215<p>
216  To declare an action provider, create an <a href=
217  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
218  element in the toolbar's menu resource, as described in <a href=
219  "actions.html">Add Action Buttons</a>. Add an
220  <code>actionProviderClass</code> attribute, and set it to the fully qualified
221  class name for the action provider class.
222</p>
223
224<p>
225  For example, the following code declares a {@link
226  android.support.v7.widget.ShareActionProvider}, which is a widget defined in
227  the support library that allows your app to share data with other apps:
228</p>
229
230<pre>
231&lt;item android:id="&#64;+id/action_share"
232    android:title="&#64;string/share"
233    app:showAsAction="ifRoom"
234    app:actionProviderClass="android.support.v7.widget.ShareActionProvider"/&gt;
235</pre>
236
237<p>
238  In this case, it is not necessary to declare an icon for the widget, since {@link
239  android.support.v7.widget.ShareActionProvider} provides its own graphics. If
240  you are using a custom action, declare an icon.
241</p>
242
243<p>
244  For information about creating a custom action provider, see the {@link
245  android.support.v4.view.ActionProvider} reference. For information about
246  configuring a {@link android.support.v7.widget.ShareActionProvider}, see the
247  reference for that class.
248</p>
249