001: /*******************************************************************************
002: * Copyright (c) 2006 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: ******************************************************************************/package org.eclipse.jface.viewers;
011:
012: import java.util.Arrays;
013: import java.util.Comparator;
014:
015: import org.eclipse.jface.util.Policy;
016:
017: /**
018: * A viewer comparator is used by a {@link StructuredViewer} to
019: * reorder the elements provided by its content provider.
020: * <p>
021: * The default <code>compare</code> method compares elements using two steps.
022: * The first step uses the values returned from <code>category</code>.
023: * By default, all elements are in the same category.
024: * The second level is based on a case insensitive compare of the strings obtained
025: * from the content viewer's label provider via <code>ILabelProvider.getText</code>.
026: * </p>
027: * <p>
028: * Subclasses may implement the <code>isSorterProperty</code> method;
029: * they may reimplement the <code>category</code> method to provide
030: * categorization; and they may override the <code>compare</code> methods
031: * to provide a totally different way of sorting elements.
032: * </p>
033: * @see IStructuredContentProvider
034: * @see StructuredViewer
035: *
036: * @since 3.2
037: */
038: public class ViewerComparator {
039: /**
040: * The comparator to use to sort a viewer's contents.
041: */
042: private Comparator comparator;
043:
044: /**
045: * Creates a new {@link ViewerComparator}, which uses the default comparator
046: * to sort strings.
047: *
048: */
049: public ViewerComparator() {
050: this (null);
051: }
052:
053: /**
054: * Creates a new {@link ViewerComparator}, which uses the given comparator
055: * to sort strings.
056: *
057: * @param comparator
058: */
059: public ViewerComparator(Comparator comparator) {
060: this .comparator = comparator;
061: }
062:
063: /**
064: * Returns the comparator used to sort strings.
065: *
066: * @return the comparator used to sort strings
067: */
068: protected Comparator getComparator() {
069: if (comparator == null) {
070: comparator = Policy.getComparator();
071: }
072: return comparator;
073: }
074:
075: /**
076: * Returns the category of the given element. The category is a
077: * number used to allocate elements to bins; the bins are arranged
078: * in ascending numeric order. The elements within a bin are arranged
079: * via a second level sort criterion.
080: * <p>
081: * The default implementation of this framework method returns
082: * <code>0</code>. Subclasses may reimplement this method to provide
083: * non-trivial categorization.
084: * </p>
085: *
086: * @param element the element
087: * @return the category
088: */
089: public int category(Object element) {
090: return 0;
091: }
092:
093: /**
094: * Returns a negative, zero, or positive number depending on whether
095: * the first element is less than, equal to, or greater than
096: * the second element.
097: * <p>
098: * The default implementation of this method is based on
099: * comparing the elements' categories as computed by the <code>category</code>
100: * framework method. Elements within the same category are further
101: * subjected to a case insensitive compare of their label strings, either
102: * as computed by the content viewer's label provider, or their
103: * <code>toString</code> values in other cases. Subclasses may override.
104: * </p>
105: *
106: * @param viewer the viewer
107: * @param e1 the first element
108: * @param e2 the second element
109: * @return a negative number if the first element is less than the
110: * second element; the value <code>0</code> if the first element is
111: * equal to the second element; and a positive number if the first
112: * element is greater than the second element
113: */
114: public int compare(Viewer viewer, Object e1, Object e2) {
115: int cat1 = category(e1);
116: int cat2 = category(e2);
117:
118: if (cat1 != cat2) {
119: return cat1 - cat2;
120: }
121:
122: String name1;
123: String name2;
124:
125: if (viewer == null || !(viewer instanceof ContentViewer)) {
126: name1 = e1.toString();
127: name2 = e2.toString();
128: } else {
129: IBaseLabelProvider prov = ((ContentViewer) viewer)
130: .getLabelProvider();
131: if (prov instanceof ILabelProvider) {
132: ILabelProvider lprov = (ILabelProvider) prov;
133: name1 = lprov.getText(e1);
134: name2 = lprov.getText(e2);
135: } else {
136: name1 = e1.toString();
137: name2 = e2.toString();
138: }
139: }
140: if (name1 == null) {
141: name1 = "";//$NON-NLS-1$
142: }
143: if (name2 == null) {
144: name2 = "";//$NON-NLS-1$
145: }
146:
147: // use the comparator to compare the strings
148: return getComparator().compare(name1, name2);
149: }
150:
151: /**
152: * Returns whether this viewer sorter would be affected
153: * by a change to the given property of the given element.
154: * <p>
155: * The default implementation of this method returns <code>false</code>.
156: * Subclasses may reimplement.
157: * </p>
158: *
159: * @param element the element
160: * @param property the property
161: * @return <code>true</code> if the sorting would be affected,
162: * and <code>false</code> if it would be unaffected
163: */
164: public boolean isSorterProperty(Object element, String property) {
165: return false;
166: }
167:
168: /**
169: * Sorts the given elements in-place, modifying the given array.
170: * <p>
171: * The default implementation of this method uses the
172: * java.util.Arrays#sort algorithm on the given array,
173: * calling <code>compare</code> to compare elements.
174: * </p>
175: * <p>
176: * Subclasses may reimplement this method to provide a more optimized implementation.
177: * </p>
178: *
179: * @param viewer the viewer
180: * @param elements the elements to sort
181: */
182: public void sort(final Viewer viewer, Object[] elements) {
183: Arrays.sort(elements, new Comparator() {
184: public int compare(Object a, Object b) {
185: return ViewerComparator.this.compare(viewer, a, b);
186: }
187: });
188: }
189: }
|