001: /*******************************************************************************
002: * Copyright (c) 2004, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: * Chris Longfield <clongfield@internap.com> - Fix for Bug 70856
011: * Tom Schindl - fix for bug 157309
012: * Brad Reynolds - bug 141435
013: *******************************************************************************/package org.eclipse.jface.viewers;
014:
015: import java.util.ArrayList;
016: import java.util.List;
017:
018: import org.eclipse.core.runtime.Assert;
019: import org.eclipse.swt.widgets.Control;
020: import org.eclipse.swt.widgets.Widget;
021:
022: /**
023: * Abstract base class for viewers that contain lists of items (such as a combo or list).
024: * Most of the viewer implementation is in this base class, except for the minimal code that
025: * actually communicates with the underlying widget.
026: *
027: * @see org.eclipse.jface.viewers.ListViewer
028: * @see org.eclipse.jface.viewers.ComboViewer
029: *
030: * @since 3.0
031: */
032: public abstract class AbstractListViewer extends StructuredViewer {
033:
034: /**
035: * A list of viewer elements (element type: <code>Object</code>).
036: */
037: private java.util.List listMap = new ArrayList();
038:
039: /**
040: * Adds the given string to the underlying widget at the given index
041: *
042: * @param string the string to add
043: * @param index position to insert the string into
044: */
045: protected abstract void listAdd(String string, int index);
046:
047: /**
048: * Sets the text of the item at the given index in the underlying widget.
049: *
050: * @param index index to modify
051: * @param string new text
052: */
053: protected abstract void listSetItem(int index, String string);
054:
055: /**
056: * Returns the zero-relative indices of the items which are currently
057: * selected in the underlying widget. The array is empty if no items are selected.
058: * <p>
059: * Note: This is not the actual structure used by the receiver
060: * to maintain its selection, so modifying the array will
061: * not affect the receiver.
062: * </p>
063: * @return the array of indices of the selected items
064: */
065: protected abstract int[] listGetSelectionIndices();
066:
067: /**
068: * Returns the number of items contained in the underlying widget.
069: *
070: * @return the number of items
071: */
072: protected abstract int listGetItemCount();
073:
074: /**
075: * Sets the underlying widget's items to be the given array of items.
076: *
077: * @param labels the array of label text
078: */
079: protected abstract void listSetItems(String[] labels);
080:
081: /**
082: * Removes all of the items from the underlying widget.
083: */
084: protected abstract void listRemoveAll();
085:
086: /**
087: * Removes the item from the underlying widget at the given
088: * zero-relative index.
089: *
090: * @param index the index for the item
091: */
092: protected abstract void listRemove(int index);
093:
094: /**
095: * Selects the items at the given zero-relative indices in the underlying widget.
096: * The current selection is cleared before the new items are selected.
097: * <p>
098: * Indices that are out of range and duplicate indices are ignored.
099: * If the receiver is single-select and multiple indices are specified,
100: * then all indices are ignored.
101: *
102: * @param ixs the indices of the items to select
103: */
104: protected abstract void listSetSelection(int[] ixs);
105:
106: /**
107: * Shows the selection. If the selection is already showing in the receiver,
108: * this method simply returns. Otherwise, the items are scrolled until
109: * the selection is visible.
110: */
111: protected abstract void listShowSelection();
112:
113: /**
114: * Deselects all selected items in the underlying widget.
115: */
116: protected abstract void listDeselectAll();
117:
118: /**
119: * Adds the given elements to this list viewer.
120: * If this viewer does not have a sorter, the elements are added at the end
121: * in the order given; otherwise the elements are inserted at appropriate positions.
122: * <p>
123: * This method should be called (by the content provider) when elements
124: * have been added to the model, in order to cause the viewer to accurately
125: * reflect the model. This method only affects the viewer, not the model.
126: * </p>
127: *
128: * @param elements the elements to add
129: */
130: public void add(Object[] elements) {
131: assertElementsNotNull(elements);
132: Object[] filtered = filter(elements);
133: ILabelProvider labelProvider = (ILabelProvider) getLabelProvider();
134: for (int i = 0; i < filtered.length; i++) {
135: Object element = filtered[i];
136: int ix = indexForElement(element);
137: insertItem(labelProvider, element, ix);
138: }
139: }
140:
141: private void insertItem(ILabelProvider labelProvider,
142: Object element, int index) {
143: listAdd(getLabelProviderText(labelProvider, element), index);
144: listMap.add(index, element);
145: mapElement(element, getControl()); // must map it, since findItem only looks in map, if enabled
146: }
147:
148: /**
149: * Inserts the given element into this list viewer at the given position.
150: * If this viewer has a sorter, the position is ignored and the element is
151: * inserted at the correct position in the sort order.
152: * <p>
153: * This method should be called (by the content provider) when elements have
154: * been added to the model, in order to cause the viewer to accurately
155: * reflect the model. This method only affects the viewer, not the model.
156: * </p>
157: *
158: * @param element
159: * the element
160: * @param position
161: * a 0-based position relative to the model, or -1 to indicate
162: * the last position
163: * @since 3.3
164: */
165: public void insert(Object element, int position) {
166: if (getComparator() != null || hasFilters()) {
167: add(element);
168: return;
169: }
170:
171: insertItem((ILabelProvider) getLabelProvider(), element,
172: position);
173: }
174:
175: /**
176: * Return the text for the element from the labelProvider.
177: * If it is null then return the empty String.
178: * @param labelProvider ILabelProvider
179: * @param element
180: * @return String. Return the emptyString if the labelProvider
181: * returns null for the text.
182: *
183: * @since 3.1
184: */
185: private String getLabelProviderText(ILabelProvider labelProvider,
186: Object element) {
187: String text = labelProvider.getText(element);
188: if (text == null) {
189: return "";//$NON-NLS-1$
190: }
191: return text;
192: }
193:
194: /**
195: * Adds the given element to this list viewer.
196: * If this viewer does not have a sorter, the element is added at the end;
197: * otherwise the element is inserted at the appropriate position.
198: * <p>
199: * This method should be called (by the content provider) when a single element
200: * has been added to the model, in order to cause the viewer to accurately
201: * reflect the model. This method only affects the viewer, not the model.
202: * Note that there is another method for efficiently processing the simultaneous
203: * addition of multiple elements.
204: * </p>
205: *
206: * @param element the element
207: */
208: public void add(Object element) {
209: add(new Object[] { element });
210: }
211:
212: /* (non-Javadoc)
213: * Method declared on StructuredViewer.
214: * Since SWT.List doesn't use items we always return the List itself.
215: */
216: protected Widget doFindInputItem(Object element) {
217: if (element != null && equals(element, getRoot())) {
218: return getControl();
219: }
220: return null;
221: }
222:
223: /* (non-Javadoc)
224: * Method declared on StructuredViewer.
225: * Since SWT.List doesn't use items we always return the List itself.
226: */
227: protected Widget doFindItem(Object element) {
228: if (element != null) {
229: if (listMapContains(element)) {
230: return getControl();
231: }
232: }
233: return null;
234: }
235:
236: /* (non-Javadoc)
237: * Method declared on StructuredViewer.
238: */
239: protected void doUpdateItem(Widget data, Object element,
240: boolean fullMap) {
241: if (element != null) {
242: int ix = getElementIndex(element);
243: if (ix >= 0) {
244: ILabelProvider labelProvider = (ILabelProvider) getLabelProvider();
245: listSetItem(ix, getLabelProviderText(labelProvider,
246: element));
247: }
248: }
249: }
250:
251: /**
252: * Returns the element with the given index from this list viewer.
253: * Returns <code>null</code> if the index is out of range.
254: *
255: * @param index the zero-based index
256: * @return the element at the given index, or <code>null</code> if the
257: * index is out of range
258: */
259: public Object getElementAt(int index) {
260: if (index >= 0 && index < listMap.size()) {
261: return listMap.get(index);
262: }
263: return null;
264: }
265:
266: /**
267: * The list viewer implementation of this <code>Viewer</code> framework
268: * method returns the label provider, which in the case of list
269: * viewers will be an instance of <code>ILabelProvider</code>.
270: */
271: public IBaseLabelProvider getLabelProvider() {
272: return super .getLabelProvider();
273: }
274:
275: /* (non-Javadoc)
276: * Method declared on Viewer.
277: */
278: /* (non-Javadoc)
279: * Method declared on StructuredViewer.
280: */
281: protected List getSelectionFromWidget() {
282: int[] ixs = listGetSelectionIndices();
283: ArrayList list = new ArrayList(ixs.length);
284: for (int i = 0; i < ixs.length; i++) {
285: Object e = getElementAt(ixs[i]);
286: if (e != null) {
287: list.add(e);
288: }
289: }
290: return list;
291: }
292:
293: /**
294: * @param element the element to insert
295: * @return the index where the item should be inserted.
296: */
297: protected int indexForElement(Object element) {
298: ViewerComparator comparator = getComparator();
299: if (comparator == null) {
300: return listGetItemCount();
301: }
302: int count = listGetItemCount();
303: int min = 0, max = count - 1;
304: while (min <= max) {
305: int mid = (min + max) / 2;
306: Object data = listMap.get(mid);
307: int compare = comparator.compare(this , data, element);
308: if (compare == 0) {
309: // find first item > element
310: while (compare == 0) {
311: ++mid;
312: if (mid >= count) {
313: break;
314: }
315: data = listMap.get(mid);
316: compare = comparator.compare(this , data, element);
317: }
318: return mid;
319: }
320: if (compare < 0) {
321: min = mid + 1;
322: } else {
323: max = mid - 1;
324: }
325: }
326: return min;
327: }
328:
329: /* (non-Javadoc)
330: * Method declared on Viewer.
331: */
332: protected void inputChanged(Object input, Object oldInput) {
333: listMap.clear();
334: Object[] children = getSortedChildren(getRoot());
335: int size = children.length;
336:
337: listRemoveAll();
338: String[] labels = new String[size];
339: for (int i = 0; i < size; i++) {
340: Object el = children[i];
341: labels[i] = getLabelProviderText(
342: (ILabelProvider) getLabelProvider(), el);
343: listMap.add(el);
344: mapElement(el, getControl()); // must map it, since findItem only looks in map, if enabled
345: }
346: listSetItems(labels);
347: }
348:
349: /* (non-Javadoc)
350: * Method declared on StructuredViewer.
351: */
352: protected void internalRefresh(Object element) {
353: Control list = getControl();
354: if (element == null || equals(element, getRoot())) {
355: // the parent
356: if (listMap != null) {
357: listMap.clear();
358: }
359: unmapAllElements();
360: List selection = getSelectionFromWidget();
361:
362: int topIndex = -1;
363: if (selection == null || selection.isEmpty()) {
364: topIndex = listGetTopIndex();
365: }
366:
367: Object[] children = null;
368: list.setRedraw(false);
369: try {
370: listRemoveAll();
371:
372: children = getSortedChildren(getRoot());
373: String[] items = new String[children.length];
374:
375: ILabelProvider labelProvider = (ILabelProvider) getLabelProvider();
376:
377: for (int i = 0; i < items.length; i++) {
378: Object el = children[i];
379: items[i] = getLabelProviderText(labelProvider, el);
380: listMap.add(el);
381: mapElement(el, list); // must map it, since findItem only looks in map, if enabled
382: }
383:
384: listSetItems(items);
385: } finally {
386: list.setRedraw(true);
387: }
388:
389: if (topIndex == -1) {
390: setSelectionToWidget(selection, false);
391: } else {
392: listSetTopIndex(Math.min(topIndex, children.length));
393: }
394: } else {
395: doUpdateItem(list, element, true);
396: }
397: }
398:
399: /**
400: * Returns the index of the item currently at the top of the viewable area.
401: * <p>
402: * Default implementation returns -1.
403: * </p>
404: * @return index, -1 for none
405: * @since 3.3
406: */
407: protected int listGetTopIndex() {
408: return -1;
409: }
410:
411: /**
412: * Sets the index of the item to be at the top of the viewable area.
413: * <p>
414: * Default implementation does nothing.
415: * </p>
416: * @param index the given index. -1 for none. index will always refer to a valid index.
417: * @since 3.3
418: */
419: protected void listSetTopIndex(int index) {
420: }
421:
422: /**
423: * Removes the given elements from this list viewer.
424: *
425: * @param elements the elements to remove
426: */
427: private void internalRemove(final Object[] elements) {
428: Object input = getInput();
429: for (int i = 0; i < elements.length; ++i) {
430: if (equals(elements[i], input)) {
431: setInput(null);
432: return;
433: }
434: int ix = getElementIndex(elements[i]);
435: if (ix >= 0) {
436: listRemove(ix);
437: listMap.remove(ix);
438: unmapElement(elements[i], getControl());
439: }
440: }
441: }
442:
443: /**
444: * Removes the given elements from this list viewer.
445: * The selection is updated if required.
446: * <p>
447: * This method should be called (by the content provider) when elements
448: * have been removed from the model, in order to cause the viewer to accurately
449: * reflect the model. This method only affects the viewer, not the model.
450: * </p>
451: *
452: * @param elements the elements to remove
453: */
454: public void remove(final Object[] elements) {
455: assertElementsNotNull(elements);
456: if (elements.length == 0) {
457: return;
458: }
459: preservingSelection(new Runnable() {
460: public void run() {
461: internalRemove(elements);
462: }
463: });
464: }
465:
466: /**
467: * Removes the given element from this list viewer.
468: * The selection is updated if necessary.
469: * <p>
470: * This method should be called (by the content provider) when a single element
471: * has been removed from the model, in order to cause the viewer to accurately
472: * reflect the model. This method only affects the viewer, not the model.
473: * Note that there is another method for efficiently processing the simultaneous
474: * removal of multiple elements.
475: * </p>
476: *
477: * @param element the element
478: */
479: public void remove(Object element) {
480: remove(new Object[] { element });
481: }
482:
483: /**
484: * The list viewer implementation of this <code>Viewer</code> framework
485: * method ensures that the given label provider is an instance of
486: * <code>ILabelProvider</code>.
487: *
488: * <b>The optional interfaces {@link IColorProvider} and
489: * {@link IFontProvider} have no effect for this type of viewer</b>
490: */
491: public void setLabelProvider(IBaseLabelProvider labelProvider) {
492: Assert.isTrue(labelProvider instanceof ILabelProvider);
493: super .setLabelProvider(labelProvider);
494: }
495:
496: /* (non-Javadoc)
497: * Method declared on StructuredViewer.
498: */
499: protected void setSelectionToWidget(List in, boolean reveal) {
500: if (in == null || in.size() == 0) { // clear selection
501: listDeselectAll();
502: } else {
503: int n = in.size();
504: int[] ixs = new int[n];
505: int count = 0;
506: for (int i = 0; i < n; ++i) {
507: Object el = in.get(i);
508: int ix = getElementIndex(el);
509: if (ix >= 0) {
510: ixs[count++] = ix;
511: }
512: }
513: if (count < n) {
514: System
515: .arraycopy(ixs, 0, ixs = new int[count], 0,
516: count);
517: }
518: listSetSelection(ixs);
519: if (reveal) {
520: listShowSelection();
521: }
522: }
523: }
524:
525: /**
526: * Returns the index of the given element in listMap, or -1 if the element cannot be found.
527: * As of 3.3, uses the element comparer if available.
528: *
529: * @param element
530: * @return the index
531: */
532: int getElementIndex(Object element) {
533: IElementComparer comparer = getComparer();
534: if (comparer == null) {
535: return listMap.indexOf(element);
536: }
537: int size = listMap.size();
538: for (int i = 0; i < size; i++) {
539: if (comparer.equals(element, listMap.get(i)))
540: return i;
541: }
542: return -1;
543: }
544:
545: /**
546: * @param element
547: * @return true if listMap contains the given element
548: *
549: * @since 3.3
550: */
551: private boolean listMapContains(Object element) {
552: return getElementIndex(element) != -1;
553: }
554:
555: }
|