Merge branch 'subtree'
[nikiroo-utils.git] / src / be / nikiroo / utils / ui / ListModel.java
CommitLineData
a917f100
NR
1package be.nikiroo.utils.ui;
2
3import java.awt.Component;
4import java.awt.Point;
8a4297ea 5import java.awt.Window;
a917f100
NR
6import java.awt.event.MouseAdapter;
7import java.awt.event.MouseEvent;
8import java.util.ArrayList;
9import java.util.Collection;
10import java.util.List;
11
12import javax.swing.JList;
13import javax.swing.JPopupMenu;
14import javax.swing.ListCellRenderer;
8a4297ea 15import javax.swing.SwingWorker;
a917f100 16
587139b9
NR
17import be.nikiroo.utils.ui.compat.DefaultListModel6;
18import be.nikiroo.utils.ui.compat.JList6;
19import be.nikiroo.utils.ui.compat.ListCellRenderer6;
a917f100
NR
20
21/**
22 * A {@link javax.swing.ListModel} that can maintain 2 lists; one with the
23 * actual data (the elements), and a second one with the items that are
24 * currently displayed (the items).
25 * <p>
26 * It also offers filter options, supports hovered changes and some more utility
27 * functions.
28 *
29 * @author niki
30 *
31 * @param <T>
32 * the type of elements and items (the same type)
33 */
34public class ListModel<T> extends DefaultListModel6<T> {
35 private static final long serialVersionUID = 1L;
36
e134fbb2
NR
37 /** How long to wait before displaying a tooltip, in milliseconds. */
38 private static final int DELAY_TOOLTIP_MS = 1000;
39
a917f100
NR
40 /**
41 * A filter interface, to check for a condition (note that a Predicate class
42 * already exists in Java 1.8+, and is compatible with this one if you
43 * change the signatures -- but I support java 1.6+).
44 *
45 * @author niki
46 *
47 * @param <T>
48 * the type of elements and items (the same type)
49 */
50 public interface Predicate<T> {
51 /**
52 * Check if an item or an element pass a filter.
53 *
54 * @param item
55 * the item to test
56 *
57 * @return TRUE if the test passed, FALSE if not
58 */
59 public boolean test(T item);
60 }
61
62 /**
63 * A simple interface your elements must implement if you want to use
64 * {@link ListModel#generateRenderer(ListModel)}.
65 *
66 * @author niki
67 */
68 public interface Hoverable {
69 /**
70 * The element is currently selected.
71 *
72 * @param selected
73 * TRUE for selected, FALSE for unselected
74 */
75 public void setSelected(boolean selected);
76
77 /**
78 * The element is currently under the mouse cursor.
79 *
80 * @param hovered
81 * TRUE if it is, FALSE if not
82 */
83 public void setHovered(boolean hovered);
84 }
85
8a4297ea
NR
86 /**
87 * An interface required to support tooltips on this {@link ListModel}.
88 *
89 * @author niki
90 *
91 * @param <T>
92 * the type of elements and items (the same type)
93 */
94 public interface TooltipCreator<T> {
95 /**
96 * Generate a tooltip {@link Window} for this element.
97 * <p>
98 * Note that the tooltip can be of two modes: undecorated or standalone.
99 * An undecorated tooltip will be taken care of by this
100 * {@link ListModel}, but a standalone one is supposed to be its own
101 * Dialog or Frame (it won't be automatically closed).
102 *
103 * @param t
104 * the element to generate a tooltip for
105 * @param undecorated
106 * TRUE for undecorated tooltip, FALSE for standalone
107 * tooltips
108 *
109 * @return the generated tooltip or NULL for none
110 */
111 public Window generateTooltip(T t, boolean undecorated);
112 }
113
a917f100
NR
114 private int hoveredIndex;
115 private List<T> items = new ArrayList<T>();
f2573c37 116 private boolean keepSelection = true;
a917f100 117
22f107ad
NR
118 private DelayWorker tooltipWatcher;
119 private JPopupMenu popup;
8a4297ea
NR
120 private TooltipCreator<T> tooltipCreator;
121 private Window tooltip;
122
b489d804
NR
123 @SuppressWarnings("rawtypes") // JList<?> not compatible Java 1.6
124 private JList list;
125
a917f100
NR
126 /**
127 * Create a new {@link ListModel}.
128 *
129 * @param list
b489d804 130 * the {@link JList6} we will handle the data of (cannot be NULL)
a917f100 131 */
b489d804
NR
132 @SuppressWarnings("rawtypes") // JList<?> not compatible Java 1.6
133 public ListModel(JList6<T> list) {
134 this((JList) list);
a917f100
NR
135 }
136
a917f100
NR
137 /**
138 * Create a new {@link ListModel}.
b489d804
NR
139 * <p>
140 * Note that you must take care of passing a {@link JList} that only handles
141 * elements of the type of this {@link ListModel} -- you can also use
142 * {@link ListModel#ListModel(JList6)} instead.
a917f100
NR
143 *
144 * @param list
b489d804
NR
145 * the {@link JList} we will handle the data of (cannot be NULL,
146 * must only contain elements of the type of this
147 * {@link ListModel})
a917f100 148 */
b489d804 149 @SuppressWarnings({ "unchecked", "rawtypes" }) // JList<?> not in Java 1.6
22f107ad 150 public ListModel(final JList list) {
a917f100 151 this.list = list;
8a4297ea 152
a917f100
NR
153 list.setModel(this);
154
22f107ad
NR
155 // We always have it ready
156 tooltipWatcher = new DelayWorker(DELAY_TOOLTIP_MS);
157 tooltipWatcher.start();
8a4297ea 158
a917f100
NR
159 list.addMouseMotionListener(new MouseAdapter() {
160 @Override
8a4297ea 161 public void mouseMoved(final MouseEvent me) {
22f107ad
NR
162 if (ListModel.this.popup != null
163 && ListModel.this.popup.isShowing())
a917f100
NR
164 return;
165
166 Point p = new Point(me.getX(), me.getY());
8a4297ea 167 final int index = list.locationToIndex(p);
a917f100
NR
168 if (index != hoveredIndex) {
169 int oldIndex = hoveredIndex;
170 hoveredIndex = index;
171 fireElementChanged(oldIndex);
172 fireElementChanged(index);
ae474ca4 173
22f107ad 174 if (ListModel.this.tooltipCreator != null) {
143d16e3 175 showTooltip(null);
8a4297ea 176
8a4297ea
NR
177 tooltipWatcher.delay("tooltip",
178 new SwingWorker<Void, Void>() {
179 @Override
180 protected Void doInBackground()
181 throws Exception {
182 return null;
183 }
184
185 @Override
186 protected void done() {
143d16e3 187 showTooltip(null);
a1d54d11 188
8a4297ea
NR
189 if (index < 0
190 || index != hoveredIndex) {
191 return;
192 }
193
22f107ad
NR
194 if (ListModel.this.popup != null
195 && ListModel.this.popup
196 .isShowing()) {
ae474ca4
NR
197 return;
198 }
199
143d16e3 200 showTooltip(newTooltip(index, me));
8a4297ea
NR
201 }
202 });
203 }
a917f100
NR
204 }
205 }
206 });
207
208 list.addMouseListener(new MouseAdapter() {
209 @Override
210 public void mousePressed(MouseEvent e) {
211 check(e);
212 }
213
214 @Override
215 public void mouseReleased(MouseEvent e) {
216 check(e);
217 }
218
219 @Override
220 public void mouseExited(MouseEvent e) {
22f107ad
NR
221 if (ListModel.this.popup != null
222 && ListModel.this.popup.isShowing())
a917f100
NR
223 return;
224
225 if (hoveredIndex > -1) {
226 int oldIndex = hoveredIndex;
227 hoveredIndex = -1;
228 fireElementChanged(oldIndex);
229 }
230 }
231
232 private void check(MouseEvent e) {
22f107ad 233 if (ListModel.this.popup == null) {
a917f100
NR
234 return;
235 }
236
237 if (e.isPopupTrigger()) {
238 if (list.getSelectedIndices().length <= 1) {
239 list.setSelectedIndex(
240 list.locationToIndex(e.getPoint()));
241 }
242
143d16e3 243 showTooltip(null);
22f107ad 244 ListModel.this.popup.show(list, e.getX(), e.getY());
a917f100
NR
245 }
246 }
8a4297ea 247
a917f100
NR
248 });
249 }
250
f2573c37
NR
251 /**
252 * (Try and) keep the elements that were selected when filtering.
253 * <p>
254 * This will use toString on the elements to identify them, and can be a bit
255 * resource intensive.
256 *
257 * @return TRUE if we do
258 */
259 public boolean isKeepSelection() {
260 return keepSelection;
261 }
262
263 /**
264 * (Try and) keep the elements that were selected when filtering.
265 * <p>
266 * This will use toString on the elements to identify them, and can be a bit
267 * resource intensive.
268 *
269 * @param keepSelection
270 * TRUE to try and keep them selected
271 */
272 public void setKeepSelection(boolean keepSelection) {
273 this.keepSelection = keepSelection;
274 }
275
22f107ad
NR
276 /**
277 * The popup to use and keep track of (can be NULL).
278 *
279 * @return the current popup
280 */
281 public JPopupMenu getPopup() {
282 return popup;
283 }
284
285 /**
286 * The popup to use and keep track of (can be NULL).
287 *
288 * @param popup
289 * the new popup
290 */
291 public void setPopup(JPopupMenu popup) {
292 this.popup = popup;
293 }
294
295 /**
296 * You can use a {@link TooltipCreator} if you want the list to display
297 * tooltips on mouse hover (can be NULL).
298 *
299 * @return the current {@link TooltipCreator}
300 */
301 public TooltipCreator<T> getTooltipCreator() {
302 return tooltipCreator;
303 }
304
305 /**
306 * You can use a {@link TooltipCreator} if you want the list to display
307 * tooltips on mouse hover (can be NULL).
308 *
309 * @param tooltipCreator
310 * the new {@link TooltipCreator}
311 */
312 public void setTooltipCreator(TooltipCreator<T> tooltipCreator) {
313 this.tooltipCreator = tooltipCreator;
314 }
315
a917f100
NR
316 /**
317 * Check if this element is currently under the mouse.
318 *
319 * @param element
320 * the element to check
321 *
322 * @return TRUE if it is
323 */
324 public boolean isHovered(T element) {
325 return indexOf(element) == hoveredIndex;
326 }
327
328 /**
329 * Check if this element is currently under the mouse.
330 *
331 * @param index
332 * the index of the element to check
333 *
334 * @return TRUE if it is
335 */
336 public boolean isHovered(int index) {
337 return index == hoveredIndex;
338 }
339
340 /**
341 * Add an item to the model.
342 *
343 * @param item
344 * the new item to add
345 */
346 public void addItem(T item) {
347 items.add(item);
348 }
349
350 /**
351 * Add items to the model.
352 *
353 * @param items
354 * the new items to add
355 */
356 public void addAllItems(Collection<T> items) {
357 this.items.addAll(items);
358 }
359
360 /**
361 * Removes the first occurrence of the specified element from this list, if
362 * it is present (optional operation).
363 *
364 * @param item
365 * the item to remove if possible (can be NULL)
366 *
367 * @return TRUE if one element was removed, FALSE if not found
368 */
369 public boolean removeItem(T item) {
370 return items.remove(item);
371 }
372
373 /**
374 * Remove the items that pass the given filter (or all items if the filter
375 * is NULL).
376 *
377 * @param filter
378 * the filter (if the filter returns TRUE, the item will be
379 * removed)
380 *
381 * @return TRUE if at least one item was removed
382 */
383 public boolean removeItemIf(Predicate<T> filter) {
384 boolean changed = false;
385 if (filter == null) {
386 changed = !items.isEmpty();
387 clearItems();
388 } else {
389 for (int i = 0; i < items.size(); i++) {
390 if (filter.test(items.get(i))) {
391 items.remove(i--);
392 changed = true;
393 }
394 }
395 }
396
397 return changed;
398 }
399
400 /**
401 * Removes all the items from this model.
402 */
403 public void clearItems() {
404 items.clear();
405 }
406
407 /**
408 * Filter the current elements.
409 * <p>
410 * This method will clear all the elements then look into all the items:
411 * those that pass the given filter will be copied as elements.
412 *
413 * @param filter
414 * the filter to select which elements to keep; an item that pass
415 * the filter will be copied as an element (can be NULL, in that
416 * case all items will be copied as elements)
417 */
b489d804 418 @SuppressWarnings("unchecked") // JList<?> not compatible Java 1.6
a917f100 419 public void filter(Predicate<T> filter) {
f2573c37
NR
420 ListSnapshot snapshot = null;
421
422 if (keepSelection)
423 snapshot = new ListSnapshot(list);
424
a917f100
NR
425 clear();
426 for (T item : items) {
427 if (filter == null || filter.test(item)) {
428 addElement(item);
429 }
430 }
431
f2573c37
NR
432 if (keepSelection)
433 snapshot.apply();
434
a917f100
NR
435 list.repaint();
436 }
437
438 /**
439 * Return the currently selected elements.
440 *
441 * @return the selected elements
442 */
443 public List<T> getSelectedElements() {
444 List<T> selected = new ArrayList<T>();
445 for (int index : list.getSelectedIndices()) {
446 selected.add(get(index));
447 }
448
449 return selected;
450 }
451
452 /**
453 * Return the selected element if <b>one</b> and <b>only one</b> element is
454 * selected. I.E., if zero, two or more elements are selected, NULL will be
455 * returned.
456 *
457 * @return the element if it is the only selected element, NULL otherwise
458 */
459 public T getUniqueSelectedElement() {
460 List<T> selected = getSelectedElements();
461 if (selected.size() == 1) {
462 return selected.get(0);
463 }
464
465 return null;
466 }
467
468 /**
469 * Notify that this element has been changed.
470 *
471 * @param index
472 * the index of the element
473 */
474 public void fireElementChanged(int index) {
475 if (index >= 0) {
476 fireContentsChanged(this, index, index);
477 }
478 }
479
480 /**
481 * Notify that this element has been changed.
482 *
483 * @param element
484 * the element
485 */
486 public void fireElementChanged(T element) {
487 int index = indexOf(element);
488 if (index >= 0) {
489 fireContentsChanged(this, index, index);
490 }
491 }
492
b489d804 493 @SuppressWarnings("unchecked") // JList<?> not compatible Java 1.6
a917f100
NR
494 @Override
495 public T get(int index) {
496 return (T) super.get(index);
497 }
498
8a4297ea
NR
499 private Window newTooltip(final int index, final MouseEvent me) {
500 final T value = ListModel.this.get(index);
8a4297ea 501 final Window newTooltip = tooltipCreator.generateTooltip(value, true);
8a4297ea
NR
502 if (newTooltip != null) {
503 newTooltip.addMouseListener(new MouseAdapter() {
504 @Override
505 public void mouseClicked(MouseEvent e) {
8a4297ea
NR
506 Window promotedTooltip = tooltipCreator
507 .generateTooltip(value, false);
a1d54d11
NR
508 if (promotedTooltip != null) {
509 promotedTooltip.setLocation(me.getXOnScreen(),
510 me.getYOnScreen());
511 promotedTooltip.setVisible(true);
512 }
143d16e3 513
8a4297ea 514 newTooltip.setVisible(false);
8a4297ea
NR
515 }
516 });
8a4297ea 517
a1d54d11 518 newTooltip.setLocation(me.getXOnScreen(), me.getYOnScreen());
143d16e3 519 showTooltip(newTooltip);
8a4297ea
NR
520 }
521
522 return newTooltip;
523 }
524
143d16e3 525 private void showTooltip(Window tooltip) {
22f107ad 526 synchronized (tooltipWatcher) {
143d16e3
NR
527 if (this.tooltip != null) {
528 this.tooltip.setVisible(false);
529 this.tooltip.dispose();
530 }
531
532 this.tooltip = tooltip;
533
534 if (tooltip != null) {
535 tooltip.setVisible(true);
536 }
537 }
538 }
539
a917f100
NR
540 /**
541 * Generate a {@link ListCellRenderer} that supports {@link Hoverable}
542 * elements.
543 *
544 * @param <T>
545 * the type of elements and items (the same type), which should
546 * implement {@link Hoverable} (it will not cause issues if not,
547 * but then, it will be a default renderer)
548 * @param model
549 * the model to use
550 *
551 * @return a suitable, {@link Hoverable} compatible renderer
552 */
553 static public <T extends Component> ListCellRenderer6<T> generateRenderer(
554 final ListModel<T> model) {
555 return new ListCellRenderer6<T>() {
556 @Override
557 public Component getListCellRendererComponent(JList6<T> list,
558 T item, int index, boolean isSelected,
559 boolean cellHasFocus) {
560 if (item instanceof Hoverable) {
561 Hoverable hoverable = (Hoverable) item;
562 hoverable.setSelected(isSelected);
563 hoverable.setHovered(model.isHovered(index));
564 }
565
566 return item;
567 }
568 };
569 }
570}