KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > user > client > ui > TabPanel


1 /*
2  * Copyright 2007 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */

16 package com.google.gwt.user.client.ui;
17
18 import java.util.Iterator JavaDoc;
19
20 /**
21  * A panel that represents a tabbed set of pages, each of which contains another
22  * widget. Its child widgets are shown as the user selects the various tabs
23  * associated with them. The tabs can contain arbitrary HTML.
24  *
25  * <p>
26  * <img class='gallery' SRC='TabPanel.png'/>
27  * </p>
28  *
29  * <p>
30  * Note that this widget is not a panel per se, but rather a
31  * {@link com.google.gwt.user.client.ui.Composite} that aggregates a
32  * {@link com.google.gwt.user.client.ui.TabBar} and a
33  * {@link com.google.gwt.user.client.ui.DeckPanel}. It does, however, implement
34  * {@link com.google.gwt.user.client.ui.HasWidgets}.
35  * </p>
36  *
37  * <h3>CSS Style Rules</h3>
38  * <ul class='css'>
39  * <li>.gwt-TabPanel { the tab panel itself }</li>
40  * <li>.gwt-TabPanelBottom { the bottom section of the tab panel (the deck
41  * containing the widget) }</li>
42  * </ul>
43  *
44  * <p>
45  * <h3>Example</h3> {@example com.google.gwt.examples.TabPanelExample}
46  * </p>
47  */

48 public class TabPanel extends Composite implements TabListener,
49     SourcesTabEvents, HasWidgets, IndexedPanel {
50
51   /**
52    * This extension of DeckPanel overrides the public mutator methods to
53    * prevent external callers from adding to the state of the DeckPanel.
54    * <p>
55    * Removal of Widgets is supported so that WidgetCollection.WidgetIterator
56    * operates as expected.
57    * </p><p>
58    * We ensure that the DeckPanel cannot become of of sync with its
59    * associated TabBar by delegating all mutations to the TabBar to this
60    * implementation of DeckPanel.
61    * </p>
62    */

63   private static class TabbedDeckPanel extends DeckPanel {
64     private UnmodifiableTabBar tabBar;
65     
66     public TabbedDeckPanel(UnmodifiableTabBar tabBar) {
67       this.tabBar = tabBar;
68     }
69     
70     public void clear() {
71       throw new UnsupportedOperationException JavaDoc(
72           "Use TabPanel.clear() to alter the DeckPanel");
73     }
74     
75     public void insert(Widget w, int beforeIndex) {
76       throw new UnsupportedOperationException JavaDoc(
77           "Use TabPanel.insert() to alter the DeckPanel");
78     }
79     
80     public boolean remove(Widget w) {
81       // Removal of items from the TabBar is delegated to the DeckPanel
82
// to ensure consistency
83
int idx = getWidgetIndex(w);
84       if (idx != -1) {
85         tabBar.removeTabProtected(idx);
86         return super.remove(w);
87       }
88
89       return false;
90     }
91     
92     protected void insertProtected(Widget w, String JavaDoc tabText, boolean asHTML,
93         int beforeIndex) {
94     
95       // Check to see if the TabPanel already contains the Widget. If so,
96
// remove it and see if we need to shift the position to the left.
97
int idx = getWidgetIndex(w);
98       if (idx != -1) {
99         remove(w);
100         if (idx < beforeIndex) {
101           beforeIndex--;
102         }
103       }
104       
105       tabBar.insertTabProtected(tabText, asHTML, beforeIndex);
106       super.insert(w, beforeIndex);
107     }
108     
109     protected void insertProtected(Widget w, Widget tabWidget,
110         int beforeIndex) {
111     
112       // Check to see if the TabPanel already contains the Widget. If so,
113
// remove it and see if we need to shift the position to the left.
114
int idx = getWidgetIndex(w);
115       if (idx != -1) {
116         remove(w);
117         if (idx < beforeIndex) {
118           beforeIndex--;
119         }
120       }
121       
122       tabBar.insertTabProtected(tabWidget, beforeIndex);
123       super.insert(w, beforeIndex);
124     }
125   };
126   
127   /**
128    * This extension of TabPanel overrides the public mutator methods to
129    * prevent external callers from modifying the state of the TabBar.
130    */

131   private static class UnmodifiableTabBar extends TabBar {
132     public void insertTab(String JavaDoc text, boolean asHTML, int beforeIndex) {
133       throw new UnsupportedOperationException JavaDoc(
134           "Use TabPanel.insert() to alter the TabBar");
135     }
136     
137     public void insertTab(Widget widget, int beforeIndex) {
138       throw new UnsupportedOperationException JavaDoc(
139           "Use TabPanel.insert() to alter the TabBar");
140     }
141     
142     public void removeTab(int index) {
143       // It's possible for removeTab() to function correctly, but it's
144
// preferable to have only TabbedDeckPanel.remove() be operable,
145
// especially since TabBar does not export an Iterator over its values.
146
throw new UnsupportedOperationException JavaDoc(
147           "Use TabPanel.remove() to alter the TabBar");
148     }
149     
150     protected void insertTabProtected(String JavaDoc text, boolean asHTML,
151         int beforeIndex) {
152       super.insertTab(text, asHTML, beforeIndex);
153     }
154     
155     protected void insertTabProtected(Widget widget, int beforeIndex) {
156       super.insertTab(widget, beforeIndex);
157     }
158     
159     protected void removeTabProtected(int index) {
160       super.removeTab(index);
161     }
162   }
163   
164   private UnmodifiableTabBar tabBar = new UnmodifiableTabBar();
165   private TabbedDeckPanel deck = new TabbedDeckPanel(tabBar);
166   private TabListenerCollection tabListeners;
167
168   /**
169    * Creates an empty tab panel.
170    */

171   public TabPanel() {
172     VerticalPanel panel = new VerticalPanel();
173     panel.add(tabBar);
174     panel.add(deck);
175
176     panel.setCellHeight(deck, "100%");
177     tabBar.setWidth("100%");
178
179     tabBar.addTabListener(this);
180     initWidget(panel);
181     setStyleName("gwt-TabPanel");
182     deck.setStyleName("gwt-TabPanelBottom");
183   }
184
185   public void add(Widget w) {
186     throw new UnsupportedOperationException JavaDoc(
187         "A tabText parameter must be specified with add().");
188   }
189
190   /**
191    * Adds a widget to the tab panel. If the Widget is already attached to
192    * the TabPanel, it will be moved to the right-most index.
193    *
194    * @param w the widget to be added
195    * @param tabText the text to be shown on its tab
196    */

197   public void add(Widget w, String JavaDoc tabText) {
198     insert(w, tabText, getWidgetCount());
199   }
200
201   /**
202    * Adds a widget to the tab panel. If the Widget is already attached to
203    * the TabPanel, it will be moved to the right-most index.
204    *
205    * @param w the widget to be added
206    * @param tabText the text to be shown on its tab
207    * @param asHTML <code>true</code> to treat the specified text as HTML
208    */

209   public void add(Widget w, String JavaDoc tabText, boolean asHTML) {
210     insert(w, tabText, asHTML, getWidgetCount());
211   }
212
213   /**
214    * Adds a widget to the tab panel. If the Widget is already attached to
215    * the TabPanel, it will be moved to the right-most index.
216    *
217    * @param w the widget to be added
218    * @param tabWidget the widget to be shown in the tab
219    */

220   public void add(Widget w, Widget tabWidget) {
221     insert(w, tabWidget, getWidgetCount());
222   }
223
224   public void addTabListener(TabListener listener) {
225     if (tabListeners == null) {
226       tabListeners = new TabListenerCollection();
227     }
228     tabListeners.add(listener);
229   }
230
231   public void clear() {
232     while (getWidgetCount() > 0) {
233       remove(getWidget(0));
234     }
235   }
236
237   /**
238    * Gets the deck panel within this tab panel. Adding or removing Widgets
239    * from the DeckPanel is not supported and will throw
240    * UnsupportedOperationExceptions.
241    *
242    * @return the deck panel
243    */

244   public DeckPanel getDeckPanel() {
245     return deck;
246   }
247
248   /**
249    * Gets the tab bar within this tab panel. Adding or removing tabs from
250    * from the TabBar is not supported and will throw
251    * UnsupportedOperationExceptions.
252    *
253    * @return the tab bar
254    */

255   public TabBar getTabBar() {
256     return tabBar;
257   }
258
259   public Widget getWidget(int index) {
260     return deck.getWidget(index);
261   }
262
263   public int getWidgetCount() {
264     return deck.getWidgetCount();
265   }
266
267   public int getWidgetIndex(Widget widget) {
268     return deck.getWidgetIndex(widget);
269   }
270
271   /**
272    * Inserts a widget into the tab panel. If the Widget is already attached
273    * to the TabPanel, it will be moved to the requested index.
274    *
275    * @param widget the widget to be inserted
276    * @param tabText the text to be shown on its tab
277    * @param asHTML <code>true</code> to treat the specified text as HTML
278    * @param beforeIndex the index before which it will be inserted
279    */

280   public void insert(Widget widget, String JavaDoc tabText, boolean asHTML,
281       int beforeIndex) {
282     // Delegate updates to the TabBar to our DeckPanel implementation
283
deck.insertProtected(widget, tabText, asHTML, beforeIndex);
284   }
285
286   /**
287    * Inserts a widget into the tab panel. If the Widget is already attached
288    * to the TabPanel, it will be moved to the requested index.
289    *
290    * @param widget the widget to be inserted.
291    * @param tabWidget the widget to be shown on its tab.
292    * @param beforeIndex the index before which it will be inserted.
293    */

294   public void insert(Widget widget, Widget tabWidget, int beforeIndex) {
295     // Delegate updates to the TabBar to our DeckPanel implementation
296
deck.insertProtected(widget, tabWidget, beforeIndex);
297   }
298
299   /**
300    * Inserts a widget into the tab panel. If the Widget is already attached
301    * to the TabPanel, it will be moved to the requested index.
302    *
303    * @param widget the widget to be inserted
304    * @param tabText the text to be shown on its tab
305    * @param beforeIndex the index before which it will be inserted
306    */

307   public void insert(Widget widget, String JavaDoc tabText, int beforeIndex) {
308     insert(widget, tabText, false, beforeIndex);
309   }
310
311   public Iterator JavaDoc iterator() {
312     // The Iterator returned by DeckPanel supports removal and will invoke
313
// TabbedDeckPanel.remove(), which is an active function.
314
return deck.iterator();
315   }
316
317   public boolean onBeforeTabSelected(SourcesTabEvents sender, int tabIndex) {
318     if (tabListeners != null) {
319       return tabListeners.fireBeforeTabSelected(this, tabIndex);
320     }
321     return true;
322   }
323
324   public void onTabSelected(SourcesTabEvents sender, int tabIndex) {
325     deck.showWidget(tabIndex);
326     if (tabListeners != null) {
327       tabListeners.fireTabSelected(this, tabIndex);
328     }
329   }
330
331   public boolean remove(int index) {
332     // Delegate updates to the TabBar to our DeckPanel implementation
333
return deck.remove(index);
334   }
335
336   /**
337    * Removes the given widget, and its associated tab.
338    *
339    * @param widget the widget to be removed
340    */

341   public boolean remove(Widget widget) {
342     // Delegate updates to the TabBar to our DeckPanel implementation
343
return deck.remove(widget);
344   }
345
346   public void removeTabListener(TabListener listener) {
347     if (tabListeners != null) {
348       tabListeners.remove(listener);
349     }
350   }
351
352   /**
353    * Programmatically selects the specified tab.
354    *
355    * @param index the index of the tab to be selected
356    */

357   public void selectTab(int index) {
358     tabBar.selectTab(index);
359   }
360 }
361
Popular Tags