Java > Open Source Codes > org > objectstyle > cayenne > modeler > util > MultiColumnBrowser


1 /* ====================================================================
2  *
3  * The ObjectStyle Group Software License, version 1.1
4  * ObjectStyle Group - http://objectstyle.org/
5  *
6  * Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
7  * of the software. All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  *
16  * 2. Redistributions in binary form must reproduce the above copyright
17  * notice, this list of conditions and the following disclaimer in
18  * the documentation and/or other materials provided with the
19  * distribution.
20  *
21  * 3. The end-user documentation included with the redistribution, if any,
22  * must include the following acknowlegement:
23  * "This product includes software developed by independent contributors
24  * and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
25  * Alternately, this acknowlegement may appear in the software itself,
26  * if and wherever such third-party acknowlegements normally appear.
27  *
28  * 4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
29  * or promote products derived from this software without prior written
30  * permission. For written permission, email
31  * "andrus at objectstyle dot org".
32  *
33  * 5. Products derived from this software may not be called "ObjectStyle"
34  * or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
35  * names without prior written permission.
36  *
37  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40  * DISCLAIMED. IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
41  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48  * SUCH DAMAGE.
49  * ====================================================================
50  *
51  * This software consists of voluntary contributions made by many
52  * individuals and hosted on ObjectStyle Group web site. For more
53  * information on the ObjectStyle Group, please see
54  * <http://objectstyle.org/>.
55  */
56 package org.objectstyle.cayenne.modeler.util;
57
58 import java.awt.BorderLayout ;
59 import java.awt.Component ;
60 import java.awt.Dimension ;
61 import java.awt.GridLayout ;
62 import java.awt.Rectangle ;
63 import java.io.Serializable ;
64 import java.util.ArrayList ;
65 import java.util.Collections ;
66 import java.util.Iterator ;
67 import java.util.List ;
68
69 import javax.swing.AbstractListModel ;
70 import javax.swing.DefaultListCellRenderer ;
71 import javax.swing.ImageIcon ;
72 import javax.swing.JLabel ;
73 import javax.swing.JList ;
74 import javax.swing.JPanel ;
75 import javax.swing.JScrollPane ;
76 import javax.swing.JViewport ;
77 import javax.swing.ListCellRenderer ;
78 import javax.swing.ListSelectionModel ;
79 import javax.swing.border.Border ;
80 import javax.swing.event.ListSelectionEvent ;
81 import javax.swing.event.ListSelectionListener ;
82 import javax.swing.event.TreeSelectionEvent ;
83 import javax.swing.event.TreeSelectionListener ;
84 import javax.swing.tree.TreeModel ;
85 import javax.swing.tree.TreePath ;
86
87
88 /**
89  * A simple non-editable tree browser with multiple columns
90  * for display and navigation of a tree structure. This type of
91  * browser is ideal for showing deeply (or infinitely) nested
92  * trees/graphs. The most famous example of its use is Mac OS X
93  * Finder column view.
94  *
95  * <p>
96  * MultiColumnBrowser starts at the root of the tree
97  * and automatically expands to the right as navigation goes deeper.
98  * MultiColumnBrowser uses the same TreeModel as a regular JTree
99  * for its navigation model.
100  * </p>
101  *
102  * <p>
103  * Users are notified of selection changes via a TreeSelectionEvents.
104  * </p>
105  *
106  * @since 1.1
107  * @author Andrei Adamchik
108  */
109 public class MultiColumnBrowser extends JPanel {
110
111     private static final ImageIcon rightArrow =
112         ModelerUtil.buildIcon("scroll_right.gif");
113
114     public static final int DEFAULT_MIN_COLUMNS_COUNT = 3;
115
116     protected int minColumns;
117     protected ListCellRenderer renderer;
118     protected TreeModel model;
119     protected Object [] selectionPath;
120     protected Dimension preferredColumnSize;
121
122     private List columns;
123     private ListSelectionListener browserSelector;
124     private List treeSelectionListeners;
125
126     public MultiColumnBrowser() {
127         this(DEFAULT_MIN_COLUMNS_COUNT);
128     }
129
130     public MultiColumnBrowser(int minColumns) {
131         if (minColumns < DEFAULT_MIN_COLUMNS_COUNT) {
132             throw new IllegalArgumentException (
133                 "Expected "
134                     + DEFAULT_MIN_COLUMNS_COUNT
135                     + " or more columns, got: "
136                     + minColumns);
137         }
138
139         this.minColumns = minColumns;
140         this.browserSelector = new PanelController();
141         this.treeSelectionListeners = Collections.synchronizedList(new ArrayList ());
142         initView();
143     }
144
145     public void addTreeSelectionListener(TreeSelectionListener listener) {
146         synchronized (treeSelectionListeners) {
147             if (listener != null && !treeSelectionListeners.contains(listener)) {
148                 treeSelectionListeners.add(listener);
149             }
150         }
151     }
152
153     public void removeTreeSelectionListener(TreeSelectionListener listener) {
154         synchronized (treeSelectionListeners) {
155             treeSelectionListeners.remove(listener);
156         }
157     }
158
159     /**
160      * Notifies listeners of a tree selection change.
161      */
162     protected void fireTreeSelectionEvent(Object [] selectionPath) {
163         TreeSelectionEvent e =
164             new TreeSelectionEvent (this, new TreePath (selectionPath), false, null, null);
165         synchronized (treeSelectionListeners) {
166             Iterator it = treeSelectionListeners.iterator();
167             while (it.hasNext()) {
168                 TreeSelectionListener listener = (TreeSelectionListener ) it.next();
169                 listener.valueChanged(e);
170             }
171         }
172     }
173
174     /**
175      * Returns current selection path or null if no selection is made.
176      */
177     public TreePath getSelectionPath() {
178         return new TreePath (selectionPath);
179     }
180
181     /**
182      * Returns the minumum number of displayed columns.
183      */
184     public int getMinColumns() {
185         return minColumns;
186     }
187
188     /**
189      * Sets the minumum number of displayed columns.
190      */
191     public void setMinColumns(int minColumns) {
192         this.minColumns = minColumns;
193     }
194
195     /**
196      * Returns prefrred size of a single browser column.
197      */
198     public Dimension getPreferredColumnSize() {
199         return preferredColumnSize;
200     }
201
202     public void setPreferredColumnSize(Dimension preferredColumnSize) {
203         this.preferredColumnSize = preferredColumnSize;
204         refreshPreferredSize();
205     }
206
207     /**
208      * Resets currently used renderer to default one that will
209      * use the "name" property of objects and display a small
210      * arrow to the right of all non-leaf nodes.
211      */
212     public void setDefaultRenderer() {
213         if (!(renderer instanceof MultiColumnBrowserRenderer)) {
214             setRenderer(new MultiColumnBrowserRenderer());
215         }
216     }
217
218     /**
219      * Returns ListCellRenderer for individual elements of each column.
220      */
221     public ListCellRenderer getRenderer() {
222         return renderer;
223     }
224
225     /**
226      * Initializes the renderer of column cells.
227      */
228     public synchronized void setRenderer(ListCellRenderer renderer) {
229         if (this.renderer != renderer) {
230             this.renderer = renderer;
231
232             // update existing browser
233 if (columns != null && columns.size() > 0) {
234                 Iterator it = columns.iterator();
235                 while (it.hasNext()) {
236                     JList column = (JList ) it.next();
237                     column.setCellRenderer(renderer);
238                 }
239             }
240         }
241     }
242
243     /**
244      * Initializes browser model.
245      */
246     public synchronized void setModel(TreeModel model) {
247         if (model == null) {
248             throw new NullPointerException ("Null tree model.");
249         }
250
251         if (this.model != model) {
252             this.model = model;
253
254             // display first column
255 updateFromModel(model.getRoot(), -1);
256         }
257     }
258
259     /**
260      * Returns browser model.
261      */
262     public TreeModel getModel() {
263         return model;
264     }
265
266     /**
267      * Returns a current number of columns.
268      */
269     public int getColumnsCount() {
270         return columns.size();
271     }
272
273     // ====================================================
274 // Internal private methods
275 // ====================================================
276
277     private void initView() {
278         columns = Collections.synchronizedList(new ArrayList (minColumns));
279         adjustViewColumns(minColumns);
280     }
281
282     /**
283      * Expands or contracts the view by <code>delta</code> columns.
284      * Never contracts the view below <code>minColumns</code>.
285      */
286     private void adjustViewColumns(int delta) {
287         if (delta == 0) {
288             return;
289         }
290
291         setLayout(new GridLayout (1, columns.size() + delta, 3, 3));
292         if (delta > 0) {
293             for (int i = 0; i < delta; i++) {
294                 appendColumn();
295             }
296         }
297         else {
298             for (int i = -delta; i > 0 && columns.size() > minColumns; i--) {
299                 removeLastColumn();
300             }
301         }
302
303         refreshPreferredSize();
304         revalidate();
305     }
306
307     private BrowserPanel appendColumn() {
308         BrowserPanel panel = new BrowserPanel();
309         panel.addListSelectionListener(browserSelector);
310         panel.setCellRenderer(renderer);
311
312         columns.add(panel);
313         JScrollPane scroller =
314             new JScrollPane (
315                 panel,
316                 JScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED,
317                 JScrollPane.HORIZONTAL_SCROLLBAR_NEVER);
318
319         // note - it is important to set prefrred size on scroller,
320 // not on the component itself... otherwise resizing
321 // will be very ugly...
322 if (preferredColumnSize != null) {
323             scroller.setPreferredSize(preferredColumnSize);
324         }
325         add(scroller);
326         return panel;
327     }
328
329     private BrowserPanel removeLastColumn() {
330         if (columns.size() == 0) {
331             return null;
332         }
333
334         int index = columns.size() - 1;
335
336         BrowserPanel panel = (BrowserPanel) columns.remove(index);
337         panel.removeListSelectionListener(browserSelector);
338
339         // remove ansestor of the column (JScrollPane)
340 remove(index);
341         return panel;
342     }
343
344     /**
345      * Refreshes preferred size of the browser to
346      * reflect current number of columns.
347      */
348     private void refreshPreferredSize() {
349         if (preferredColumnSize != null) {
350             int w = getColumnsCount() * (preferredColumnSize.width + 3) + 3;
351             int h = preferredColumnSize.height + 6;
352             setPreferredSize(new Dimension (w, h));
353         }
354     }
355
356     /**
357      * Makes numbered column visible if the browser parent allows scrolling.
358      */
359     private void scrollToColumn(int column) {
360         if (getParent() instanceof JViewport ) {
361
362             JViewport viewport = (JViewport ) getParent();
363
364             // find a rectangle in the middle of the browser
365 // and scroll it...
366 double x = getWidth() * column / ((double) getMinColumns());
367             double y = getHeight() / 2;
368
369             if (preferredColumnSize != null) {
370                 x -= preferredColumnSize.width / 2;
371                 if (x < 0) {
372                     x = 0;
373                 }
374             }
375
376             Rectangle rectangle = new Rectangle ((int) x, (int) y, 1, 1);
377
378             // Scroll the area into view.
379 viewport.scrollRectToVisible(rectangle);
380         }
381     }
382
383     /**
384      * Rebuilds view for the new object selection.
385      */
386     private synchronized void updateFromModel(Object selectedNode, int panelIndex) {
387         if(selectionPath == null) {
388             selectionPath = new Object [0];
389         }
390         
391         // clean up extra columns
392 int lastIndex = selectionPath.length;
393
394         // check array range to handle race conditions
395 for (int i = panelIndex + 1;
396             i <= lastIndex && i >= 0 && i < columns.size();
397             i++) {
398             BrowserPanel column = (BrowserPanel) columns.get(i);
399             column.getSelectionModel().clearSelection();
400             column.setRootNode(null);
401         }
402
403         // build path to selected node
404 this.selectionPath = rebuildPath(selectionPath, selectedNode, panelIndex);
405
406         // a selectedNode is contained in "panelIndex" column,
407 // but its children are in the next column.
408 panelIndex++;
409
410         // expand/contract columns as needed
411 adjustViewColumns(panelIndex + 1 - columns.size());
412
413         // selectedNode becomes the root of columns[panelIndex]
414 if (!model.isLeaf(selectedNode)) {
415             BrowserPanel lastPanel = (BrowserPanel) columns.get(panelIndex);
416             lastPanel.setRootNode(selectedNode);
417             scrollToColumn(panelIndex);
418         }
419
420         fireTreeSelectionEvent(selectionPath);
421     }
422
423     /**
424      * Builds a TreePath to the new node, that is known to be a peer or a child
425      * of one of the path components. As the method walks the current path backwards,
426      * it cleans columns that are not common with the new path.
427      */
428     private Object [] rebuildPath(Object [] path, Object node, int panelIndex) {
429         Object [] newPath = new Object [panelIndex + 2];
430         System.arraycopy(path, 0, newPath, 0, panelIndex + 1);
431         newPath[panelIndex + 1] = node;
432         return newPath;
433     }
434
435     // ====================================================
436 // Helper classes
437 // ====================================================
438
439     // ====================================================
440 // Represents a browser column list model. This is an
441 // adapter on top of the TreeModel node, showing the branch
442 // containing node children
443 // ====================================================
444 final class ColumnListModel extends AbstractListModel {
445         Object treeNode;
446         int children;
447
448         void setTreeNode(Object treeNode) {
449             int oldChildren = children;
450             this.treeNode = treeNode;
451             this.children = (treeNode != null) ? model.getChildCount(treeNode) : 0;
452
453             // must fire an event to refresh the view
454 super.fireContentsChanged(
455                 MultiColumnBrowser.this,
456                 0,
457                 Math.max(oldChildren, children));
458         }
459
460         public Object getElementAt(int index) {
461             return model.getChild(treeNode, index);
462         }
463
464         public int getSize() {
465             return children;
466         }
467     }
468
469     // ====================================================
470 // Represents a single browser column
471 // ====================================================
472 final class BrowserPanel extends JList {
473         BrowserPanel() {
474             BrowserPanel.this.setModel(new ColumnListModel());
475             BrowserPanel.this.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
476         }
477
478         void setRootNode(Object node) {
479             ((ColumnListModel) BrowserPanel.this.getModel()).setTreeNode(node);
480         }
481
482         Object getTreeNode() {
483             return ((ColumnListModel) BrowserPanel.this.getModel()).treeNode;
484         }
485     }
486
487     // ====================================================
488 // Processes selection events in each column
489 // ====================================================
490 final class PanelController implements ListSelectionListener {
491         public void valueChanged(ListSelectionEvent e) {
492
493             // ignore "adjusting"
494 if (!e.getValueIsAdjusting()) {
495                 BrowserPanel panel = (BrowserPanel) e.getSource();
496                 Object selectedNode = panel.getSelectedValue();
497
498                 // ignore unselected
499 if (selectedNode != null) {
500                     updateFromModel(selectedNode, columns.indexOf(panel));
501                 }
502             }
503         }
504     }
505
506     // ====================================================
507 // Default renderer that shows non-leaf nodes with a
508 // small right arrow. Unfortunately we can't subclass
509 // DefaultListCellRenerer since it extends JLabel that
510 // does not allow the layout that we need.
511 // ====================================================
512 final class MultiColumnBrowserRenderer implements ListCellRenderer , Serializable {
513
514         ListCellRenderer leafRenderer;
515         JPanel nonLeafPanel;
516         ListCellRenderer nonLeafTextRenderer;
517
518         MultiColumnBrowserRenderer() {
519
520             leafRenderer = CellRenderers.listRenderer();
521
522             nonLeafTextRenderer = new DefaultListCellRenderer () {
523                 public Border getBorder() {
524                     return null;
525                 }
526             };
527
528             nonLeafPanel = new JPanel ();
529             nonLeafPanel.setLayout(new BorderLayout ());
530             nonLeafPanel.add(new JLabel (rightArrow), BorderLayout.EAST);
531             nonLeafPanel.add((Component ) nonLeafTextRenderer, BorderLayout.WEST);
532         }
533
534         public Component getListCellRendererComponent(
535             JList list,
536             Object value,
537             int index,
538             boolean isSelected,
539             boolean cellHasFocus) {
540
541             if (getModel().isLeaf(value)) {
542                 return leafRenderer.getListCellRendererComponent(
543                     list,
544                     value,
545                     index,
546                     isSelected,
547                     cellHasFocus);
548             }
549
550             Object renderedValue = ModelerUtil.getObjectName(value);
551             if (renderedValue == null) {
552                 // render NULL as empty string
553 renderedValue = " ";
554             }
555
556             Component text =
557                 nonLeafTextRenderer.getListCellRendererComponent(
558                     list,
559                     renderedValue,
560                     index,
561                     isSelected,
562                     cellHasFocus);
563
564             nonLeafPanel.setComponentOrientation(text.getComponentOrientation());
565             nonLeafPanel.setBackground(text.getBackground());
566             nonLeafPanel.setForeground(text.getForeground());
567             nonLeafPanel.setEnabled(text.isEnabled());
568             return nonLeafPanel;
569         }
570     }
571
572 }
573

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags