ViewerComparator


1   /*******************************************************************************
2    * Copyright (c) 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   ******************************************************************************/
11  
12  package org.eclipse.jface.viewers;
13  
14  import java.util.Arrays  ;
15  import java.util.Comparator  ;
16  
17  import org.eclipse.jface.util.Policy;
18  
19  /**
20   * A viewer comparator is used by a {@link StructuredViewer} to
21   * reorder the elements provided by its content provider.
22   * <p>
23   * The default <code>compare</code> method compares elements using two steps. 
24   * The first step uses the values returned from <code>category</code>. 
25   * By default, all elements are in the same category. 
26   * The second level is based on a case insensitive compare of the strings obtained 
27   * from the content viewer's label provider via <code>ILabelProvider.getText</code>.
28   * </p>
29   * <p>
30   * Subclasses may implement the <code>isSorterProperty</code> method;
31   * they may reimplement the <code>category</code> method to provide 
32   * categorization; and they may override the <code>compare</code> methods
33   * to provide a totally different way of sorting elements.
34   * </p>
35   * @see IStructuredContentProvider
36   * @see StructuredViewer
37   * 
38   * @since 3.2
39   */
40  public class ViewerComparator {
41      /**
42       * The comparator to use to sort a viewer's contents.
43       */
44      private Comparator   comparator;
45  
46      /**
47       * Creates a new {@link ViewerComparator}, which uses the default comparator
48       * to sort strings.
49       *
50       */
51      public ViewerComparator(){
52          this(null);
53      }
54      
55      /**
56       * Creates a new {@link ViewerComparator}, which uses the given comparator
57       * to sort strings.
58       * 
59       * @param comparator
60       */
61      public ViewerComparator(Comparator   comparator){
62          this.comparator = comparator;
63      }
64  
65      /**
66       * Returns the comparator used to sort strings.
67       * 
68       * @return the comparator used to sort strings
69       */
70      protected Comparator   getComparator() {
71          if (comparator == null){
72              comparator = Policy.getComparator();
73          }
74          return comparator;
75      }
76  
77      /**
78       * Returns the category of the given element. The category is a
79       * number used to allocate elements to bins; the bins are arranged
80       * in ascending numeric order. The elements within a bin are arranged
81       * via a second level sort criterion.
82       * <p>
83       * The default implementation of this framework method returns
84       * <code>0</code>. Subclasses may reimplement this method to provide
85       * non-trivial categorization.
86       * </p>
87       *
88       * @param element the element
89       * @return the category
90       */
91      public int category(Object   element) {
92          return 0;
93      }
94  
95      /**
96       * Returns a negative, zero, or positive number depending on whether
97       * the first element is less than, equal to, or greater than
98       * the second element.
99       * <p>
100      * The default implementation of this method is based on
101      * comparing the elements' categories as computed by the <code>category</code>
102      * framework method. Elements within the same category are further 
103      * subjected to a case insensitive compare of their label strings, either
104      * as computed by the content viewer's label provider, or their 
105      * <code>toString</code> values in other cases. Subclasses may override.
106      * </p>
107      * 
108      * @param viewer the viewer
109      * @param e1 the first element
110      * @param e2 the second element
111      * @return a negative number if the first element is less  than the 
112      *  second element; the value <code>0</code> if the first element is
113      *  equal to the second element; and a positive number if the first
114      *  element is greater than the second element
115      */
116     public int compare(Viewer viewer, Object   e1, Object   e2) {
117         int cat1 = category(e1);
118         int cat2 = category(e2);
119 
120         if (cat1 != cat2) {
121             return cat1 - cat2;
122         }
123         
124         String   name1;
125         String   name2;
126 
127         if (viewer == null || !(viewer instanceof ContentViewer)) {
128             name1 = e1.toString();
129             name2 = e2.toString();
130         } else {
131             IBaseLabelProvider prov = ((ContentViewer) viewer)
132                     .getLabelProvider();
133             if (prov instanceof ILabelProvider) {
134                 ILabelProvider lprov = (ILabelProvider) prov;
135                 name1 = lprov.getText(e1);
136                 name2 = lprov.getText(e2);
137             } else {
138                 name1 = e1.toString();
139                 name2 = e2.toString();
140             }
141         }
142         if (name1 == null) {
143             name1 = "";//$NON-NLS-1$
144         }
145         if (name2 == null) {
146             name2 = "";//$NON-NLS-1$
147         }
148 
149         // use the comparator to compare the strings
150         return getComparator().compare(name1, name2);
151     }
152 
153     /**
154      * Returns whether this viewer sorter would be affected 
155      * by a change to the given property of the given element.
156      * <p>
157      * The default implementation of this method returns <code>false</code>.
158      * Subclasses may reimplement.
159      * </p>
160      *
161      * @param element the element
162      * @param property the property
163      * @return <code>true</code> if the sorting would be affected,
164      *    and <code>false</code> if it would be unaffected
165      */
166     public boolean isSorterProperty(Object   element, String   property) {
167         return false;
168     }
169 
170     /**
171      * Sorts the given elements in-place, modifying the given array.
172      * <p>
173      * The default implementation of this method uses the 
174      * java.util.Arrays#sort algorithm on the given array, 
175      * calling <code>compare</code> to compare elements.
176      * </p>
177      * <p>
178      * Subclasses may reimplement this method to provide a more optimized implementation.
179      * </p>
180      *
181      * @param viewer the viewer
182      * @param elements the elements to sort
183      */
184     public void sort(final Viewer viewer, Object  [] elements) {
185         Arrays.sort(elements, new Comparator  () {
186             public int compare(Object   a, Object   b) {
187                 return ViewerComparator.this.compare(viewer, a, b);
188             }
189         });
190     }   
191 }
192
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags