Java tutorial
/* * Copyright 2009 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.user.client.ui; import com.google.gwt.dom.client.Style.Unit; import com.google.gwt.event.dom.client.ClickEvent; import com.google.gwt.event.dom.client.ClickHandler; import com.google.gwt.event.dom.client.HasClickHandlers; import com.google.gwt.event.dom.client.MouseOutEvent; import com.google.gwt.event.dom.client.MouseOutHandler; import com.google.gwt.event.dom.client.MouseOverEvent; import com.google.gwt.event.dom.client.MouseOverHandler; import com.google.gwt.event.logical.shared.BeforeSelectionEvent; import com.google.gwt.event.logical.shared.BeforeSelectionHandler; import com.google.gwt.event.logical.shared.HasBeforeSelectionHandlers; import com.google.gwt.event.logical.shared.HasSelectionHandlers; import com.google.gwt.event.logical.shared.SelectionEvent; import com.google.gwt.event.logical.shared.SelectionHandler; import com.google.gwt.event.shared.HandlerRegistration; import com.google.gwt.layout.client.Layout.AnimationCallback; import com.google.gwt.safehtml.shared.SafeHtml; import java.util.ArrayList; import java.util.Iterator; import java.util.NoSuchElementException; /** * A panel that stacks its children vertically, displaying only one at a time, * with a header for each child which the user can click to display. * * <p> * This widget will <em>only</em> work in standards mode, which requires that * the HTML page in which it is run have an explicit <!DOCTYPE> * declaration. * </p> * * <h3>CSS Style Rules</h3> * <dl> * <dt>.gwt-StackLayoutPanel <dd> the panel itself * <dt>.gwt-StackLayoutPanel .gwt-StackLayoutPanelHeader <dd> applied to each * header widget * <dt>.gwt-StackLayoutPanel .gwt-StackLayoutPanelHeader-hovering <dd> applied to each * header widget on mouse hover * <dt>.gwt-StackLayoutPanel .gwt-StackLayoutPanelContent <dd> applied to each * child widget * </dl> * * <p> * <h3>Example</h3> * {@example com.google.gwt.examples.StackLayoutPanelExample} * </p> * * <h3>Use in UiBinder Templates</h3> * <p> * A StackLayoutPanel element in a * {@link com.google.gwt.uibinder.client.UiBinder UiBinder} template may have a * <code>unit</code> attribute with a * {@link com.google.gwt.dom.client.Style.Unit Style.Unit} value (it defaults to * PX). * <p> * The children of a StackLayoutPanel element are laid out in <g:stack> * elements. Each stack can have one widget child and one of two types of header * elements. A <g:header> element can hold html, or a <g:customHeader> * element can hold a widget. (Note that the tags of the header elements are not * capitalized. This is meant to signal that the head is not a runtime object, * and so cannot have a <code>ui:field</code> attribute.) * <p> * For example: * * <pre> * <g:StackLayoutPanel unit='PX'> * <g:stack> * <g:header size='3'><b>HTML</b> header</g:header> * <g:Label>able</g:Label> * </g:stack> * <g:stack> * <g:customHeader size='3'> * <g:Label>Custom header</g:Label> * </g:customHeader> * <g:Label>baker</g:Label> * </g:stack> * </g:StackLayoutPanel> * </pre> */ public class StackLayoutPanel extends ResizeComposite implements HasWidgets, ProvidesResize, IndexedPanel.ForIsWidget, AnimatedLayout, HasBeforeSelectionHandlers<Integer>, HasSelectionHandlers<Integer> { private class Header extends Composite implements HasClickHandlers { public Header(Widget child) { initWidget(child); } public HandlerRegistration addClickHandler(ClickHandler handler) { return this.addDomHandler(handler, ClickEvent.getType()); } public HandlerRegistration addMouseOutHandler(MouseOutHandler handler) { return this.addDomHandler(handler, MouseOutEvent.getType()); } public HandlerRegistration addMouseOverHandler(MouseOverHandler handler) { return this.addDomHandler(handler, MouseOverEvent.getType()); } } private static class LayoutData { public double headerSize; public Header header; public Widget widget; public LayoutData(Widget widget, Header header, double headerSize) { this.widget = widget; this.header = header; this.headerSize = headerSize; } } private static final String WIDGET_STYLE = "gwt-StackLayoutPanel"; private static final String CONTENT_STYLE = "gwt-StackLayoutPanelContent"; private static final String HEADER_STYLE = "gwt-StackLayoutPanelHeader"; private static final String HEADER_STYLE_HOVERING = "gwt-StackLayoutPanelHeader-hovering"; private static final int ANIMATION_TIME = 250; private int animationDuration = ANIMATION_TIME; private LayoutPanel layoutPanel; private final Unit unit; private final ArrayList<LayoutData> layoutData = new ArrayList<LayoutData>(); private int selectedIndex = -1; /** * Creates an empty stack panel. * * @param unit the unit to be used for layout */ public StackLayoutPanel(Unit unit) { this.unit = unit; initWidget(layoutPanel = new LayoutPanel()); setStyleName(WIDGET_STYLE); } public void add(Widget w) { assert false : "Single-argument add() is not supported for this widget"; } /** * Adds a child widget to this stack, along with a widget representing the * stack header. * * @param widget the child widget to be added * @param header the html to be shown on its header * @param headerSize the size of the header widget */ public void add(final Widget widget, SafeHtml header, double headerSize) { add(widget, header.asString(), true, headerSize); } /** * Adds a child widget to this stack, along with a widget representing the * stack header. * * @param widget the child widget to be added * @param header the text to be shown on its header * @param asHtml <code>true</code> to treat the specified text as HTML * @param headerSize the size of the header widget */ public void add(final Widget widget, String header, boolean asHtml, double headerSize) { insert(widget, header, asHtml, headerSize, getWidgetCount()); } /** * Overloaded version for IsWidget. * * @see #add(Widget,String,boolean,double) */ public void add(final IsWidget widget, String header, boolean asHtml, double headerSize) { this.add(widget.asWidget(), header, asHtml, headerSize); } /** * Adds a child widget to this stack, along with a widget representing the * stack header. * * @param widget the child widget to be added * @param header the text to be shown on its header * @param headerSize the size of the header widget */ public void add(final Widget widget, String header, double headerSize) { insert(widget, header, headerSize, getWidgetCount()); } /** * Adds a child widget to this stack, along with a widget representing the * stack header. * * @param widget the child widget to be added * @param header the header widget * @param headerSize the size of the header widget */ public void add(final Widget widget, Widget header, double headerSize) { insert(widget, header, headerSize, getWidgetCount()); } /** * Overloaded version for IsWidget. * * @see #add(Widget,Widget,double) */ public void add(final IsWidget widget, IsWidget header, double headerSize) { this.add(widget.asWidget(), header.asWidget(), headerSize); } public HandlerRegistration addBeforeSelectionHandler(BeforeSelectionHandler<Integer> handler) { return addHandler(handler, BeforeSelectionEvent.getType()); } public HandlerRegistration addSelectionHandler(SelectionHandler<Integer> handler) { return addHandler(handler, SelectionEvent.getType()); } public void animate(int duration) { animate(duration, null); } public void animate(int duration, AnimationCallback callback) { // Don't try to animate zero widgets. if (layoutData.size() == 0) { if (callback != null) { callback.onAnimationComplete(); } return; } double top = 0, bottom = 0; int i = 0; for (; i < layoutData.size(); ++i) { LayoutData data = layoutData.get(i); layoutPanel.setWidgetTopHeight(data.header, top, unit, data.headerSize, unit); top += data.headerSize; layoutPanel.setWidgetTopHeight(data.widget, top, unit, 0, unit); if (i == selectedIndex) { break; } } for (int j = layoutData.size() - 1; j > i; --j) { LayoutData data = layoutData.get(j); layoutPanel.setWidgetBottomHeight(data.header, bottom, unit, data.headerSize, unit); layoutPanel.setWidgetBottomHeight(data.widget, bottom, unit, 0, unit); bottom += data.headerSize; } LayoutData data = layoutData.get(selectedIndex); layoutPanel.setWidgetTopBottom(data.widget, top, unit, bottom, unit); layoutPanel.animate(duration, callback); } public void clear() { layoutPanel.clear(); layoutData.clear(); selectedIndex = -1; } public void forceLayout() { layoutPanel.forceLayout(); } /** * Get the duration of the animated transition between children. * * @return the duration in milliseconds */ public int getAnimationDuration() { return animationDuration; } /** * Gets the widget in the stack header at the given index. * * @param index the index of the stack header to be retrieved * @return the header widget */ public Widget getHeaderWidget(int index) { checkIndex(index); return layoutData.get(index).header.getWidget(); } /** * Gets the widget in the stack header associated with the given child widget. * * @param child the child whose stack header is to be retrieved * @return the header widget */ public Widget getHeaderWidget(Widget child) { checkChild(child); return getHeaderWidget(getWidgetIndex(child)); } /** * Gets the currently-selected index. * * @return the selected index, or <code>-1</code> if none is selected */ public int getVisibleIndex() { return selectedIndex; } /** * Gets the currently-selected widget. * * @return the selected widget, or <code>null</code> if none exist */ public Widget getVisibleWidget() { if (selectedIndex == -1) { return null; } return getWidget(selectedIndex); } public Widget getWidget(int index) { return layoutPanel.getWidget(index * 2 + 1); } public int getWidgetCount() { return layoutPanel.getWidgetCount() / 2; } public int getWidgetIndex(IsWidget child) { return getWidgetIndex(asWidgetOrNull(child)); } public int getWidgetIndex(Widget child) { int index = layoutPanel.getWidgetIndex(child); if (index == -1) { return index; } return (index - 1) / 2; } /** * Inserts a widget into the panel. If the Widget is already attached, it will * be moved to the requested index. * * @param child the widget to be added * @param html the safe html to be shown on its header * @param headerSize the size of the header widget * @param beforeIndex the index before which it will be inserted */ public void insert(Widget child, SafeHtml html, double headerSize, int beforeIndex) { insert(child, html.asString(), true, headerSize, beforeIndex); } /** * Inserts a widget into the panel. If the Widget is already attached, it will * be moved to the requested index. * * @param child the widget to be added * @param text the text to be shown on its header * @param asHtml <code>true</code> to treat the specified text as HTML * @param headerSize the size of the header widget * @param beforeIndex the index before which it will be inserted */ public void insert(Widget child, String text, boolean asHtml, double headerSize, int beforeIndex) { HTML contents = new HTML(); if (asHtml) { contents.setHTML(text); } else { contents.setText(text); } insert(child, contents, headerSize, beforeIndex); } /** * Inserts a widget into the panel. If the Widget is already attached, it will * be moved to the requested index. * * @param child the widget to be added * @param text the text to be shown on its header * @param headerSize the size of the header widget * @param beforeIndex the index before which it will be inserted */ public void insert(Widget child, String text, double headerSize, int beforeIndex) { insert(child, text, false, headerSize, beforeIndex); } /** * Inserts a widget into the panel. If the Widget is already attached, it will * be moved to the requested index. * * @param child the widget to be added * @param header the widget to be placed in the associated header * @param headerSize the size of the header widget * @param beforeIndex the index before which it will be inserted */ public void insert(Widget child, Widget header, double headerSize, int beforeIndex) { insert(child, new Header(header), headerSize, beforeIndex); } public Iterator<Widget> iterator() { return new Iterator<Widget>() { int i = 0, last = -1; public boolean hasNext() { return i < layoutData.size(); } public Widget next() { if (!hasNext()) { throw new NoSuchElementException(); } return layoutData.get(last = i++).widget; } public void remove() { if (last < 0) { throw new IllegalStateException(); } StackLayoutPanel.this.remove(layoutData.get(last).widget); i = last; last = -1; } }; } @Override public void onResize() { layoutPanel.onResize(); } public boolean remove(int index) { return remove(getWidget(index)); } public boolean remove(Widget child) { if (child.getParent() != layoutPanel) { return false; } // Find the layoutData associated with this widget and remove it. for (int i = 0; i < layoutData.size(); ++i) { LayoutData data = layoutData.get(i); if (data.widget == child) { layoutPanel.remove(data.header); layoutPanel.remove(data.widget); data.header.removeStyleName(HEADER_STYLE); data.widget.removeStyleName(CONTENT_STYLE); layoutData.remove(i); if (selectedIndex == i) { selectedIndex = -1; if (layoutData.size() > 0) { showWidget(layoutData.get(0).widget); } } else { if (i <= selectedIndex) { selectedIndex--; } animate(animationDuration); } return true; } } return false; } /** * Set the duration of the animated transition between children. * * @param duration the duration in milliseconds. */ public void setAnimationDuration(int duration) { this.animationDuration = duration; } /** * Sets a stack header's HTML contents. * * Use care when setting an object's HTML; it is an easy way to expose * script-based security problems. Consider using * {@link #setHeaderHTML(int, SafeHtml)} or * {@link #setHeaderText(int, String)} whenever possible. * * @param index the index of the header whose HTML is to be set * @param html the header's new HTML contents */ public void setHeaderHTML(int index, String html) { checkIndex(index); LayoutData data = layoutData.get(index); Widget headerWidget = data.header.getWidget(); assert headerWidget instanceof HasHTML : "Header widget does not implement HasHTML"; ((HasHTML) headerWidget).setHTML(html); } /** * Sets a stack header's HTML contents. * * @param index the index of the header whose HTML is to be set * @param html the header's new HTML contents */ public void setHeaderHTML(int index, SafeHtml html) { setHeaderHTML(index, html.asString()); } /** * Sets a stack header's text contents. * * @param index the index of the header whose text is to be set * @param text the object's new text */ public void setHeaderText(int index, String text) { checkIndex(index); LayoutData data = layoutData.get(index); Widget headerWidget = data.header.getWidget(); assert headerWidget instanceof HasText : "Header widget does not implement HasText"; ((HasText) headerWidget).setText(text); } /** * Shows the widget at the specified index and fires events. * * @param index the index of the child widget to be shown. */ public void showWidget(int index) { showWidget(index, true); } /** * Shows the widget at the specified index. * * @param index the index of the child widget to be shown. * @param fireEvents true to fire events, false not to */ public void showWidget(int index, boolean fireEvents) { checkIndex(index); showWidget(index, animationDuration, fireEvents); } /** * Shows the specified widget and fires events. * * @param child the child widget to be shown. */ public void showWidget(Widget child) { showWidget(getWidgetIndex(child)); } /** * Shows the specified widget. * * @param child the child widget to be shown. * @param fireEvents true to fire events, false not to */ public void showWidget(Widget child, boolean fireEvents) { showWidget(getWidgetIndex(child), animationDuration, fireEvents); } @Override protected void onLoad() { // When the widget becomes attached, update its layout. animate(0); } private void checkChild(Widget child) { assert layoutPanel.getChildren().contains(child); } private void checkIndex(int index) { assert (index >= 0) && (index < getWidgetCount()) : "Index out of bounds"; } private void insert(final Widget child, final Header header, double headerSize, int beforeIndex) { assert (beforeIndex >= 0) && (beforeIndex <= getWidgetCount()) : "beforeIndex out of bounds"; // Check to see if the StackPanel already contains the Widget. If so, // remove it and see if we need to shift the position to the left. int idx = getWidgetIndex(child); if (idx != -1) { remove(child); if (idx < beforeIndex) { beforeIndex--; } } int widgetIndex = beforeIndex * 2; layoutPanel.insert(child, widgetIndex); layoutPanel.insert(header, widgetIndex); layoutPanel.setWidgetLeftRight(header, 0, Unit.PX, 0, Unit.PX); layoutPanel.setWidgetLeftRight(child, 0, Unit.PX, 0, Unit.PX); LayoutData data = new LayoutData(child, header, headerSize); layoutData.add(beforeIndex, data); header.addStyleName(HEADER_STYLE); child.addStyleName(CONTENT_STYLE); header.addClickHandler(new ClickHandler() { public void onClick(ClickEvent event) { showWidget(child); } }); header.addMouseOutHandler(new MouseOutHandler() { public void onMouseOut(MouseOutEvent event) { header.removeStyleName(HEADER_STYLE_HOVERING); } }); header.addMouseOverHandler(new MouseOverHandler() { public void onMouseOver(MouseOverEvent event) { header.addStyleName(HEADER_STYLE_HOVERING); } }); if (selectedIndex == -1) { // If there's no visible widget, display the first one. The layout will // be updated onLoad(). showWidget(0); } else if (beforeIndex <= selectedIndex) { // If we inserted an item before the selected index, increment it. selectedIndex++; } // If the widget is already attached, we must call animate() to update the // layout (if it's not yet attached, then onLoad() will do this). if (isAttached()) { animate(animationDuration); } } private void showWidget(int index, final int duration, boolean fireEvents) { checkIndex(index); if (index == selectedIndex) { return; } // Fire the before selection event, giving the recipients a chance to // cancel the selection. if (fireEvents) { BeforeSelectionEvent<Integer> event = BeforeSelectionEvent.fire(this, index); if ((event != null) && event.isCanceled()) { return; } } selectedIndex = index; if (isAttached()) { animate(duration); } // Fire the selection event. if (fireEvents) { SelectionEvent.fire(this, index); } } }