blob: ae7cb1fe0335eb69341a18a53537cc3454ae961b (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.actionbarsherlock.view;
import android.content.Context;
import android.view.View;
/**
* This class is a mediator for accomplishing a given task, for example sharing a file.
* It is responsible for creating a view that performs an action that accomplishes the task.
* This class also implements other functions such a performing a default action.
* <p>
* An ActionProvider can be optionally specified for a {@link MenuItem} and in such a
* case it will be responsible for creating the action view that appears in the
* {@link android.app.ActionBar} as a substitute for the menu item when the item is
* displayed as an action item. Also the provider is responsible for performing a
* default action if a menu item placed on the overflow menu of the ActionBar is
* selected and none of the menu item callbacks has handled the selection. For this
* case the provider can also optionally provide a sub-menu for accomplishing the
* task at hand.
* </p>
* <p>
* There are two ways for using an action provider for creating and handling of action views:
* <ul>
* <li>
* Setting the action provider on a {@link MenuItem} directly by calling
* {@link MenuItem#setActionProvider(ActionProvider)}.
* </li>
* <li>
* Declaring the action provider in the menu XML resource. For example:
* <pre>
* <code>
* <item android:id="@+id/my_menu_item"
* android:title="Title"
* android:icon="@drawable/my_menu_item_icon"
* android:showAsAction="ifRoom"
* android:actionProviderClass="foo.bar.SomeActionProvider" />
* </code>
* </pre>
* </li>
* </ul>
* </p>
*
* @see MenuItem#setActionProvider(ActionProvider)
* @see MenuItem#getActionProvider()
*/
public abstract class ActionProvider {
private SubUiVisibilityListener mSubUiVisibilityListener;
/**
* Creates a new instance.
*
* @param context Context for accessing resources.
*/
public ActionProvider(Context context) {
}
/**
* Factory method for creating new action views.
*
* @return A new action view.
*/
public abstract View onCreateActionView();
/**
* Performs an optional default action.
* <p>
* For the case of an action provider placed in a menu item not shown as an action this
* method is invoked if previous callbacks for processing menu selection has handled
* the event.
* </p>
* <p>
* A menu item selection is processed in the following order:
* <ul>
* <li>
* Receiving a call to {@link MenuItem.OnMenuItemClickListener#onMenuItemClick
* MenuItem.OnMenuItemClickListener.onMenuItemClick}.
* </li>
* <li>
* Receiving a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem)
* Activity.onOptionsItemSelected(MenuItem)}
* </li>
* <li>
* Receiving a call to {@link android.app.Fragment#onOptionsItemSelected(MenuItem)
* Fragment.onOptionsItemSelected(MenuItem)}
* </li>
* <li>
* Launching the {@link android.content.Intent} set via
* {@link MenuItem#setIntent(android.content.Intent) MenuItem.setIntent(android.content.Intent)}
* </li>
* <li>
* Invoking this method.
* </li>
* </ul>
* </p>
* <p>
* The default implementation does not perform any action and returns false.
* </p>
*/
public boolean onPerformDefaultAction() {
return false;
}
/**
* Determines if this ActionProvider has a submenu associated with it.
*
* <p>Associated submenus will be shown when an action view is not. This
* provider instance will receive a call to {@link #onPrepareSubMenu(SubMenu)}
* after the call to {@link #onPerformDefaultAction()} and before a submenu is
* displayed to the user.
*
* @return true if the item backed by this provider should have an associated submenu
*/
public boolean hasSubMenu() {
return false;
}
/**
* Called to prepare an associated submenu for the menu item backed by this ActionProvider.
*
* <p>if {@link #hasSubMenu()} returns true, this method will be called when the
* menu item is selected to prepare the submenu for presentation to the user. Apps
* may use this to create or alter submenu content right before display.
*
* @param subMenu Submenu that will be displayed
*/
public void onPrepareSubMenu(SubMenu subMenu) {
}
/**
* Notify the system that the visibility of an action view's sub-UI such as
* an anchored popup has changed. This will affect how other system
* visibility notifications occur.
*
* @hide Pending future API approval
*/
public void subUiVisibilityChanged(boolean isVisible) {
if (mSubUiVisibilityListener != null) {
mSubUiVisibilityListener.onSubUiVisibilityChanged(isVisible);
}
}
/**
* @hide Internal use only
*/
public void setSubUiVisibilityListener(SubUiVisibilityListener listener) {
mSubUiVisibilityListener = listener;
}
/**
* @hide Internal use only
*/
public interface SubUiVisibilityListener {
public void onSubUiVisibilityChanged(boolean isVisible);
}
}
|
