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
|
/*
* Copyright (C) 2010 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 android.app;
import android.content.Context;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
/**
* Represents a contextual mode of the user interface. Contextual modes can be used for
* modal interactions with content and replace parts of the normal UI until finished.
* Examples of good contextual modes include selection modes, search, content editing, etc.
*/
public abstract class ContextualMode {
/**
* Set the title of the contextual mode. This method will have no visible effect if
* a custom view has been set.
*
* @param title Title string to set
*
* @see #setCustomView(View)
*/
public abstract void setTitle(CharSequence title);
/**
* Set the subtitle of the contextual mode. This method will have no visible effect if
* a custom view has been set.
*
* @param subtitle Subtitle string to set
*
* @see #setCustomView(View)
*/
public abstract void setSubtitle(CharSequence subtitle);
/**
* Set a custom view for this contextual mode. The custom view will take the place of
* the title and subtitle. Useful for things like search boxes.
*
* @param view Custom view to use in place of the title/subtitle.
*
* @see #setTitle(CharSequence)
* @see #setSubtitle(CharSequence)
*/
public abstract void setCustomView(View view);
/**
* Invalidate the contextual mode and refresh menu content. The contextual mode's
* {@link ContextualMode.Callback} will have its
* {@link Callback#onPrepareContextualMode(ContextualMode, Menu)} method called.
* If it returns true the menu will be scanned for updated content and any relevant changes
* will be reflected to the user.
*/
public abstract void invalidate();
/**
* Finish and close this context mode. The context mode's {@link ContextualMode.Callback} will
* have its {@link Callback#onDestroyContextualMode(ContextualMode)} method called.
*/
public abstract void finish();
/**
* Returns the menu of actions that this contextual mode presents.
* @return The contextual mode's menu.
*/
public abstract Menu getMenu();
/**
* Returns the current title of this contextual mode.
* @return Title text
*/
public abstract CharSequence getTitle();
/**
* Returns the current subtitle of this contextual mode.
* @return Subtitle text
*/
public abstract CharSequence getSubtitle();
/**
* Returns the current custom view for this contextual mode.
* @return The current custom view
*/
public abstract View getCustomView();
/**
* Callback interface for contextual modes. Supplied to
* {@link Context#startContextualMode(Callback)}, a Callback
* configures and handles events raised by a user's interaction with a context mode.
*
* <p>A context mode's lifecycle is as follows:
* <ul>
* <li>{@link Callback#onCreateContextualMode(ContextualMode, Menu)} once on initial
* creation</li>
* <li>{@link Callback#onPrepareContextualMode(ContextualMode, Menu)} after creation
* and any time the {@link ContextualMode} is invalidated</li>
* <li>{@link Callback#onContextualItemClicked(ContextualMode, MenuItem)} any time a
* contextual action button is clicked</li>
* <li>{@link Callback#onDestroyContextualMode(ContextualMode)} when the context mode
* is closed</li>
* </ul>
*/
public interface Callback {
/**
* Called when a contextual mode is first created. The menu supplied will be used to
* generate action buttons for the contextual mode.
*
* @param mode ContextualMode being created
* @param menu Menu used to populate contextual action buttons
* @return true if the contextual mode should be created, false if entering this
* mode should be aborted.
*/
public boolean onCreateContextualMode(ContextualMode mode, Menu menu);
/**
* Called to refresh a contextual mode's action menu whenever it is invalidated.
*
* @param mode ContextualMode being prepared
* @param menu Menu used to populate contextual action buttons
* @return true if the menu or contextual mode was updated, false otherwise.
*/
public boolean onPrepareContextualMode(ContextualMode mode, Menu menu);
/**
* Called to report a user click on a contextual action button.
*
* @param mode The current ContextualMode
* @param item The item that was clicked
* @return true if this callback handled the event, false if the standard MenuItem
* invocation should continue.
*/
public boolean onContextualItemClicked(ContextualMode mode, MenuItem item);
/**
* Called when a contextual mode is about to be exited and destroyed.
*
* @param mode The current ContextualMode being destroyed
*/
public void onDestroyContextualMode(ContextualMode mode);
}
}
|
