1 /***
2 * Ambient - A music player for the Android platform
3 Copyright (C) 2007 Martin Vysny
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18 package sk.baka.ambient.views.gesturelist;
19
20 import java.util.List;
21
22 import sk.baka.ambient.collection.TrackMetadataBean;
23 import sk.baka.ambient.commons.Interval;
24 import android.view.View;
25
26 /***
27 * Listens for events produced by the gesture list view listener.
28 *
29 * @author Martin Vysny
30 */
31 public interface IGestureListViewListener {
32 /***
33 * <p>
34 * Remove these items from the list. The list view sets the highlight
35 * automatically to zero interval.
36 * </p>
37 * <p>
38 * This operation is invoked even when {@link #isReadOnly()} returns
39 * <code>false</code> as some use cases activates a "Go Back" activity
40 * instead of deleting items.
41 * </p>
42 *
43 * @param remove
44 * remove these items. The interval is not <code>null</code>
45 * however it may be empty.
46 */
47 void removeItems(final Interval remove);
48
49 /***
50 * Selection was changed. The new highlight is already being drawn.
51 *
52 * @param highlight
53 * highlighted items
54 */
55 void highlightChanged(final Interval highlight);
56
57 /***
58 * Checks if we can start highlight mode now.
59 *
60 * @return <code>true</code> if highlight mode can be started,
61 * <code>false</code> otherwise.
62 */
63 boolean canHighlight();
64
65 /***
66 * Checks if the list view is currently read-only.
67 *
68 * @return <code>true</code> if the view cannot be modified,
69 * <code>false</code> otherwise.
70 */
71 boolean isReadOnly();
72
73 /***
74 * The drag'n'drop operation is finished. This view has received a list of
75 * tracks.
76 *
77 * @param tracks
78 * the tracks
79 * @param x
80 * the drop point x axis relative to the item upper-left corner.
81 * @param y
82 * the drop point y axis relative to the item upper-left corner.
83 * @param index
84 * the index of the item where the files were dropped.
85 */
86 void dropItems(final List<TrackMetadataBean> tracks, final int x,
87 final int y, final int index);
88
89 /***
90 * The item was activated, either by clicking on it or using a keyboard.
91 *
92 * @param index
93 * the index of the item.
94 * @param model
95 * the model for the item.
96 */
97 void itemActivated(final int index, final Object model);
98
99 /***
100 * <p>
101 * Move selected items up or down. The listener must update the items and
102 * return the new highlight. This operation is always considered as a
103 * short-running and thus always executed directly in handler's event
104 * thread.
105 * </p>
106 * <p>
107 * The list view will be redrawn automatically when the method returns.
108 * </p>
109 * <p>
110 * This operation is invoked only when {@link #isReadOnly()} returns
111 * <code>false</code>.
112 * </p>
113 *
114 * @param highlight
115 * move these items
116 * @param index
117 * drop the items before item with this index.
118 * @return new interval which contains all moved tracks.
119 */
120 Interval moveItems(final Interval highlight, final int index);
121
122 /***
123 * <p>
124 * Move selected items up or down. The listener must update the items and
125 * return the new highlight. This operation is always considered as a
126 * short-running and thus always executed directly in handler's event
127 * thread.
128 * </p>
129 * <p>
130 * The list view will be redrawn automatically when the method returns.
131 * </p>
132 * <p>
133 * This operation is invoked only when {@link #isReadOnly()} returns
134 * <code>false</code>.
135 * </p>
136 *
137 * @param highlight
138 * move these items
139 * @param down
140 * down if <code>true</code> then move the highlighted interval
141 * down, otherwise move it up.
142 * @return new interval which contains all moved tracks.
143 */
144 Interval moveItemsByOne(final Interval highlight, final boolean down);
145
146 /***
147 * Checks if the model currently supports computing tracks. This also
148 * affects the drag'n'drop capability - we cannot drag'n'drop if a track
149 * list cannot be computed.
150 *
151 * @return <code>true</code> if the model can compute tracks,
152 * <code>false</code> otherwise.
153 */
154 boolean canComputeItems();
155
156 /***
157 * <p>
158 * Checks if the {@link #computeTracks(Interval)} method will be a long
159 * operation. If yes, then the operation will be run in new thread. If not,
160 * the operation will be run in handler event thread.
161 * </p>
162 * <p>
163 * This method is only invoked when {@link #canComputeItems()} returns
164 * <code>true</code>.
165 * </p>
166 *
167 * @param interval
168 * the selection
169 * @return <code>true</code> if long operation, <code>false</code>
170 * otherwise.
171 */
172 boolean isComputeTracksLong(final Interval interval);
173
174 /***
175 * <p>
176 * Checks if the {@link #computeTracks(Interval)} method will involve
177 * polling of some data from the Internet.
178 * </p>
179 * <p>
180 * This method is only invoked when {@link #canComputeItems()} returns
181 * <code>true</code>.
182 * </p>
183 *
184 * @param interval
185 * the selection
186 * @return <code>true</code> if some Internet resources will be polled,
187 * <code>false</code> otherwise.
188 */
189 boolean isComputeTracksOnlineOp(final Interval interval);
190
191 /***
192 * <p>
193 * Retrieve a list of tracks from the selection. This operation may not be
194 * invoked from the handler's thread (depending on the result of the
195 * {@link #isComputeTracksLong(Interval)} method). The method implementation
196 * should thus periodically check for the {@link Thread#isInterrupted()
197 * interrupted} flag. When interrupted, it should return an empty list or
198 * <code>null</code> ASAP. It may do so by throwing an exception
199 * </p>
200 * <p>
201 * If the method is invoked in a non-handler thread the callee wraps the
202 * result in a thread-safe list.
203 * </p>
204 * <p>
205 * The method may throw {@link RuntimeException} - it will be caught and
206 * displayed unless the thread is interrupted.
207 * </p>
208 * <p>
209 * This method is only invoked when {@link #canComputeItems()} returns
210 * <code>true</code>.
211 * </p>
212 *
213 * @param highlight
214 * the selection
215 * @return a list of tracks, must not be <code>null</code>.
216 */
217 List<TrackMetadataBean> computeTracks(final Interval highlight);
218
219 /***
220 * <p>
221 * Returns a very short and simple string representation of the selected
222 * contents.
223 * </p>
224 * <p>
225 * This method is only invoked when {@link #canComputeItems()} returns
226 * <code>true</code>.
227 * </p>
228 *
229 * @param highlight
230 * the highlighted items.
231 * @return short description of selected contents. May be <code>null</code>
232 * if no hint should be shown.
233 */
234 String getHint(final Interval highlight);
235
236 /***
237 * An item view is being drawn (or re-drawn) on screen. The implementation
238 * should correctly set the view contents, based on the model object. The
239 * model object is taken from the {@link GesturesListView#getModel()} list.
240 * The only exception is the EOP special item. For more information please
241 * read {@link ModelHolder here}.
242 *
243 * @param listView
244 * the listview containing the view
245 * @param itemView
246 * the view representing a single item
247 * @param index
248 * the index in the {@link GesturesListView#getModel()} list. May
249 * point outside of the model list only when drawing an EOP item.
250 * @param model
251 * The model object, taken from the
252 * {@link GesturesListView#getModel()} list. This value may
253 * optionally be the {@link MutableListAdapter#EOP_MODEL_MARKER}
254 * object - in this case the special EndOfPlaylist item must be
255 * drawn.
256 */
257 void update(final GesturesListView listView, final View itemView,
258 final int index, final Object model);
259
260 /***
261 * Sets the new clipboard.
262 *
263 * @param clipboard
264 * the clipboard to set.
265 */
266 void setClipboard(final TrackListClipboardObject clipboard);
267
268 /***
269 * Retrieves current clipboard value.
270 *
271 * @return current clipboard contents. Do NOT cache this value.
272 */
273 Object getClipboard();
274 }