TabDataModel


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.swing.tabcontrol;
21  
22  import org.netbeans.swing.tabcontrol.event.ComplexListDataListener;
23  
24  import javax.swing.*;
25  import javax.swing.event.ChangeListener  ;
26  import java.util.Collections  ;
27  import java.util.List  ;
28  
29  /**
30   * A data model representing a set of tabs and their associated data. Allows for
31   * atomic add/remove/modification operations any of which are guaranteed to fire
32   * only one event on completion.  Note that for modification operations
33   * (<code>setText()</code>, <code>setIcon</code>, <code>setIconsAndText</code>,
34   * no event will be fired unless data is actually changed - calling these
35   * methods with the same values that the tabs already have will not generate
36   * events. The <code>isWidthChanged</code> method for generated events will
37   * return <code>true</code> for events which can affect the area needed to
38   * display a tab (such as text or icon width changes).
39   * <p>
40   * Note:  The standard UI implementations which use this model make no provisions
41   * for thread-safety.  All changes fired from a TabDataModel should happen on the
42   * AWT event thread. 
43   *
44   * @author Tim Boudreau
45   */
46  public interface TabDataModel {
47      /**
48       * The number of tabs contained in the model.
49       *
50       * @return The number of tabs
51       */
52      public int size();
53  
54      /**
55       * Retrieve data for a given tab
56       *
57       * @param index The index for which to retrieve tab data
58       * @return Data describing the tab
59       */
60      public TabData getTab(int index);
61  
62      /**
63       * Set the tab data for a given tab to the passed value
64       *
65       * @param index The index of the tab to be changed
66       * @param data  The new tab data for this index
67       */
68      public void setTab(int index, TabData data);
69  
70      /**
71       * Set the icon for a given tab.  Will trigger a list data event, and the
72       * resulting event's widthChanged property will be set appropriately if the
73       * displayed width has changed.
74       *
75       * @param index The index to set the icon for
76       * @param i     The icon to use for the tab
77       */
78      public void setIcon(int index, Icon i);
79  
80      /**
81       * Set the text for a given tab.  Triggers a list data event.
82       *
83       * @param index The index of the tab
84       * @param txt   The replacement text
85       */
86      public void setText(int index, String   txt);
87  
88      /**
89       * Atomically set the icons for a set of indices.  Fires a single list data
90       * event with the indexes of any tabs in which the data was actually
91       * changed.  If the passed data perfectly match the existing data, no event
92       * will be fired.
93       *
94       * @param indices The indices for which the corresponding icons should be
95       *                changed
96       * @param icons   The replacement icons.  This array must be the same length
97       *                as the indices parameter
98       */
99      public void setIcon(int[] indices, Icon[] icons);
100 
101     /**
102      * Atomically set the text for a number of tabs.  Fires a single list data
103      * event with the indexes of any tabs in which the data was actually
104      * changed.  If the passed data perfectly match the existing data, no event
105      * will be fired.1
106      *
107      * @param indices The indices of the tabs to change
108      * @param txt     The text values for the tabs
109      */
110     public void setText(int[] indices, String  [] txt);
111 
112     /**
113      * Atomically set the icons and text simultaneously for more than one tab.
114      * Fires a single list data event with the indexes of any tabs in which the
115      * data was actually changed.  If the passed data perfectly match the
116      * existing data, no event will be fired.1
117      *
118      * @param indices The indices which should have their data changed
119      * @param txt     The replacement text values corresponding to the passed
120      *                indices
121      * @param icons   The replacement icons corresponding to the passed indices
122      */
123     public void setIconsAndText(int[] indices, String  [] txt, Icon[] icons);
124 
125     /**
126      * Atomically add a set of tabs at the specified index
127      *
128      * @param start The insert point for new tabs
129      * @param data  The tab data to insert
130      */
131     public void addTabs(int start, TabData[] data);
132 
133     /**
134      * Remove the tab at the specified index
135      *
136      * @param index The tab index
137      */
138     public void removeTab(int index);
139 
140     /**
141      * Add the specified tabs at the specified indices
142      *
143      * @param indices The indices at which tabs will be added
144      * @param data    The tabs to add, in order corresponding to the indices
145      *                parameter
146      */
147     public void addTabs(int[] indices, TabData[] data);
148 
149     /**
150      * Replace the entire set of tabs represented by the model
151      */
152     public void setTabs(TabData[] data);
153 
154     /**
155      * Remove the tabs at the specified indices
156      *
157      * @param indices The indices at which tabs should be removed
158      */
159     public void removeTabs(int[] indices);
160 
161     /**
162      * Remove a range of tabs
163      *
164      * @param start the start index
165      * @param end   the end index
166      */
167     public void removeTabs(int start, int end);
168 
169     /**
170      * Add a single tab at the specified location
171      */
172     public void addTab(int index, TabData data);
173 
174     /**
175      * Retrieve all the tab data contained in the model as a List
176      *
177      * @return a List of TabData objects
178      */
179     public java.util.List  <TabData> getTabs();
180 
181     /**
182      * Fetch the index of a tab matching the passed TabData object.  Note that
183      * the tooltip property of the passed TabData object is not used to test
184      * equality.
185      *
186      * See also <a HREF="@org-netbeans-core-windows@/org/netbeans/core/windows/ui/TabData.html#equals()">org.netbeans.core.windows.ui.TabData.equals()</a><BR>
187      */
188     public int indexOf(TabData td);
189 
190     /**
191      * Add a data listener
192      *
193      * @param listener The listener
194      */
195     public void addComplexListDataListener(ComplexListDataListener listener);
196 
197     /**
198      * Remove a data listener
199      *
200      * @param listener The listener
201      */
202     public void removeComplexListDataListener(ComplexListDataListener listener);
203     
204     
205     //XXX remove this and handel the ComplexNNN events so nothing is repainted
206     //if not displayed on screen!
207     /**
208      * The model will fire a change event whenever a modification occurs that
209      * could require a repaint. <strong>This method is only here for the
210      * prototype - eventually the UI delegate should listen for ComplexDataNN
211      * events and optimize repaints based on the actual areas affected.
212      */
213     public void addChangeListener(ChangeListener   listener);
214 
215     /**
216      * The model will fire a change event whenever a modification occurs that
217      * could require a repaint. <strong>This method is only here for the
218      * prototype - eventually the UI delegate should listen for ComplexDataNN
219      * events and optimize repaints based on the actual areas affected.
220      */
221     public void removeChangeListener(ChangeListener   listener);
222 }
223
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags