001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.swing.tabcontrol;
043:
044: import org.netbeans.swing.tabcontrol.event.ComplexListDataListener;
045:
046: import javax.swing.*;
047: import javax.swing.event.ChangeListener;
048: import java.util.Collections;
049: import java.util.List;
050:
051: /**
052: * A data model representing a set of tabs and their associated data. Allows for
053: * atomic add/remove/modification operations any of which are guaranteed to fire
054: * only one event on completion. Note that for modification operations
055: * (<code>setText()</code>, <code>setIcon</code>, <code>setIconsAndText</code>,
056: * no event will be fired unless data is actually changed - calling these
057: * methods with the same values that the tabs already have will not generate
058: * events. The <code>isWidthChanged</code> method for generated events will
059: * return <code>true</code> for events which can affect the area needed to
060: * display a tab (such as text or icon width changes).
061: * <p>
062: * Note: The standard UI implementations which use this model make no provisions
063: * for thread-safety. All changes fired from a TabDataModel should happen on the
064: * AWT event thread.
065: *
066: * @author Tim Boudreau
067: */
068: public interface TabDataModel {
069: /**
070: * The number of tabs contained in the model.
071: *
072: * @return The number of tabs
073: */
074: public int size();
075:
076: /**
077: * Retrieve data for a given tab
078: *
079: * @param index The index for which to retrieve tab data
080: * @return Data describing the tab
081: */
082: public TabData getTab(int index);
083:
084: /**
085: * Set the tab data for a given tab to the passed value
086: *
087: * @param index The index of the tab to be changed
088: * @param data The new tab data for this index
089: */
090: public void setTab(int index, TabData data);
091:
092: /**
093: * Set the icon for a given tab. Will trigger a list data event, and the
094: * resulting event's widthChanged property will be set appropriately if the
095: * displayed width has changed.
096: *
097: * @param index The index to set the icon for
098: * @param i The icon to use for the tab
099: */
100: public void setIcon(int index, Icon i);
101:
102: /**
103: * Set the text for a given tab. Triggers a list data event.
104: *
105: * @param index The index of the tab
106: * @param txt The replacement text
107: */
108: public void setText(int index, String txt);
109:
110: /**
111: * Atomically set the icons for a set of indices. Fires a single list data
112: * event with the indexes of any tabs in which the data was actually
113: * changed. If the passed data perfectly match the existing data, no event
114: * will be fired.
115: *
116: * @param indices The indices for which the corresponding icons should be
117: * changed
118: * @param icons The replacement icons. This array must be the same length
119: * as the indices parameter
120: */
121: public void setIcon(int[] indices, Icon[] icons);
122:
123: /**
124: * Atomically set the text for a number of tabs. Fires a single list data
125: * event with the indexes of any tabs in which the data was actually
126: * changed. If the passed data perfectly match the existing data, no event
127: * will be fired.1
128: *
129: * @param indices The indices of the tabs to change
130: * @param txt The text values for the tabs
131: */
132: public void setText(int[] indices, String[] txt);
133:
134: /**
135: * Atomically set the icons and text simultaneously for more than one tab.
136: * Fires a single list data event with the indexes of any tabs in which the
137: * data was actually changed. If the passed data perfectly match the
138: * existing data, no event will be fired.1
139: *
140: * @param indices The indices which should have their data changed
141: * @param txt The replacement text values corresponding to the passed
142: * indices
143: * @param icons The replacement icons corresponding to the passed indices
144: */
145: public void setIconsAndText(int[] indices, String[] txt,
146: Icon[] icons);
147:
148: /**
149: * Atomically add a set of tabs at the specified index
150: *
151: * @param start The insert point for new tabs
152: * @param data The tab data to insert
153: */
154: public void addTabs(int start, TabData[] data);
155:
156: /**
157: * Remove the tab at the specified index
158: *
159: * @param index The tab index
160: */
161: public void removeTab(int index);
162:
163: /**
164: * Add the specified tabs at the specified indices
165: *
166: * @param indices The indices at which tabs will be added
167: * @param data The tabs to add, in order corresponding to the indices
168: * parameter
169: */
170: public void addTabs(int[] indices, TabData[] data);
171:
172: /**
173: * Replace the entire set of tabs represented by the model
174: */
175: public void setTabs(TabData[] data);
176:
177: /**
178: * Remove the tabs at the specified indices
179: *
180: * @param indices The indices at which tabs should be removed
181: */
182: public void removeTabs(int[] indices);
183:
184: /**
185: * Remove a range of tabs
186: *
187: * @param start the start index
188: * @param end the end index
189: */
190: public void removeTabs(int start, int end);
191:
192: /**
193: * Add a single tab at the specified location
194: */
195: public void addTab(int index, TabData data);
196:
197: /**
198: * Retrieve all the tab data contained in the model as a List
199: *
200: * @return a List of TabData objects
201: */
202: public java.util.List<TabData> getTabs();
203:
204: /**
205: * Fetch the index of a tab matching the passed TabData object. Note that
206: * the tooltip property of the passed TabData object is not used to test
207: * equality.
208: *
209: * 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>
210: */
211: public int indexOf(TabData td);
212:
213: /**
214: * Add a data listener
215: *
216: * @param listener The listener
217: */
218: public void addComplexListDataListener(
219: ComplexListDataListener listener);
220:
221: /**
222: * Remove a data listener
223: *
224: * @param listener The listener
225: */
226: public void removeComplexListDataListener(
227: ComplexListDataListener listener);
228:
229: //XXX remove this and handel the ComplexNNN events so nothing is repainted
230: //if not displayed on screen!
231: /**
232: * The model will fire a change event whenever a modification occurs that
233: * could require a repaint. <strong>This method is only here for the
234: * prototype - eventually the UI delegate should listen for ComplexDataNN
235: * events and optimize repaints based on the actual areas affected.
236: */
237: public void addChangeListener(ChangeListener listener);
238:
239: /**
240: * The model will fire a change event whenever a modification occurs that
241: * could require a repaint. <strong>This method is only here for the
242: * prototype - eventually the UI delegate should listen for ComplexDataNN
243: * events and optimize repaints based on the actual areas affected.
244: */
245: public void removeChangeListener(ChangeListener listener);
246: }
|