/*
* Copyright 2008 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.animation.client.Animation;
import com.google.gwt.core.client.GWT;
import com.google.gwt.event.logical.shared.CloseEvent;
import com.google.gwt.event.logical.shared.CloseHandler;
import com.google.gwt.event.logical.shared.HasCloseHandlers;
import com.google.gwt.event.logical.shared.HasOpenHandlers;
import com.google.gwt.event.logical.shared.OpenEvent;
import com.google.gwt.event.logical.shared.OpenHandler;
import com.google.gwt.event.shared.HandlerRegistration;
import com.google.gwt.resources.client.ClientBundle;
import com.google.gwt.resources.client.ImageResource;
import com.google.gwt.resources.client.ImageResource.ImageOptions;
import com.google.gwt.user.client.DOM;
import com.google.gwt.user.client.Element;
import com.google.gwt.user.client.Event;
import java.util.Iterator;
/**
* A widget that consists of a header and a content panel that discloses the
* content when a user clicks on the header.
*
* <h3>CSS Style Rules</h3>
* <dl class="css">
* <dt>.gwt-DisclosurePanel
* <dd>the panel's primary style
* <dt>.gwt-DisclosurePanel-open
* <dd> dependent style set when panel is open
* <dt>.gwt-DisclosurePanel-closed
* <dd> dependent style set when panel is closed
* </dl>
* <p>
* <img class='gallery' src='doc-files/DisclosurePanel.png'/>
* </p>
*
* <p>
* The header and content sections can be easily selected using css with a child
* selector:<br/>
* .gwt-DisclosurePanel-open .header { ... }
* </p>
* <h3>Use in UiBinder Templates</h3>
* <p>
* DisclosurePanel elements in
* {@link com.google.gwt.uibinder.client.UiBinder UiBinder} templates can
* have one widget child and one of two types of header elements. A
* <g:header> element can hold text (not 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 header is not a runtime object,
* and so cannot have a <code>ui:field</code> attribute.)
* <p>
* For example:<pre>
* <g:DisclosurePanel>
* <g:header>Text header</g:header>
* <g:Label>Widget body</g:Label>
* </g:DisclosurePanel>
*
* <g:DisclosurePanel>
* <g:customHeader>
* <g:Label>Widget header</g:Label>
* </g:customHeader>
* <g:Label>Widget body</g:Label>
* </g:DisclosurePanel>
* </pre>
*/
@SuppressWarnings("deprecation")
public final class DisclosurePanel extends Composite implements
FiresDisclosureEvents, HasWidgets.ForIsWidget, HasAnimation,
HasOpenHandlers<DisclosurePanel>, HasCloseHandlers<DisclosurePanel> {
interface DefaultImages extends ClientBundle {
@ImageOptions(flipRtl = true)
ImageResource disclosurePanelClosed();
ImageResource disclosurePanelOpen();
}
private static final DefaultImages DEFAULT_IMAGES = GWT.create(DefaultImages.class);
/**
* Used to wrap widgets in the header to provide click support. Effectively
* wraps the widget in an <code>anchor</code> to get automatic keyboard
* access.
*/
private final class ClickableHeader extends SimplePanel {
private ClickableHeader() {
// Anchor is used to allow keyboard access.
super(DOM.createAnchor());
Element elem = getElement();
DOM.setElementProperty(elem, "href", "javascript:void(0);");
// Avoids layout problems from having blocks in inlines.
DOM.setStyleAttribute(elem, "display", "block");
sinkEvents(Event.ONCLICK);
setStyleName(STYLENAME_HEADER);
}
@Override
public void onBrowserEvent(Event event) {
// no need to call super.
switch (DOM.eventGetType(event)) {
case Event.ONCLICK:
// Prevent link default action.
DOM.eventPreventDefault(event);
setOpen(!isOpen);
}
}
}
/**
* An {@link Animation} used to open the content.
*/
private static class ContentAnimation extends Animation {
/**
* Whether the item is being opened or closed.
*/
private boolean opening;
/**
* The {@link DisclosurePanel} being affected.
*/
private DisclosurePanel curPanel;
/**
* Open or close the content.
*
* @param panel the panel to open or close
* @param animate true to animate, false to open instantly
*/
public void setOpen(DisclosurePanel panel, boolean animate) {
// Immediately complete previous open
cancel();
// Open the new item
if (animate) {
curPanel = panel;
opening = panel.isOpen;
run(ANIMATION_DURATION);
} else {
panel.contentWrapper.setVisible(panel.isOpen);
if (panel.isOpen) {
// Special treatment on the visible case to ensure LazyPanel works
panel.getContent().setVisible(true);
}
}
}
@Override
protected void onComplete() {
if (!opening) {
curPanel.contentWrapper.setVisible(false);
}
DOM.setStyleAttribute(curPanel.contentWrapper.getElement(), "height",
"auto");
curPanel = null;
}
@Override
protected void onStart() {
super.onStart();
if (opening) {
curPanel.contentWrapper.setVisible(true);
// Special treatment on the visible case to ensure LazyPanel works
curPanel.getContent().setVisible(true);
}
}
@Override
protected void onUpdate(double progress) {
int scrollHeight = DOM.getElementPropertyInt(
curPanel.contentWrapper.getElement(), "scrollHeight");
int height = (int) (progress * scrollHeight);
if (!opening) {
height = scrollHeight - height;
}
height = Math.max(height, 1);
DOM.setStyleAttribute(curPanel.contentWrapper.getElement(), "height",
height + "px");
DOM.setStyleAttribute(curPanel.contentWrapper.getElement(), "width",
"auto");
}
}
/**
* The default header widget used within a {@link DisclosurePanel}.
*/
private class DefaultHeader extends Widget implements HasText,
OpenHandler<DisclosurePanel>, CloseHandler<DisclosurePanel> {
/**
* imageTD holds the image for the icon, not null. labelTD holds the text
* for the label.
*/
private final Element labelTD;
private final Image iconImage;
private final Imager imager;
private DefaultHeader(final DisclosurePanelImages images, String text) {
this(new Imager() {
public Image makeImage() {
return images.disclosurePanelClosed().createImage();
}
public void updateImage(boolean open, Image image) {
if (open) {
images.disclosurePanelOpen().applyTo(image);
} else {
images.disclosurePanelClosed().applyTo(image);
}
}
}, text);
}
private DefaultHeader(Imager imager, String text) {
this.imager = imager;
iconImage = imager.makeImage();
// I do not need any Widgets here, just a DOM structure.
Element root = DOM.createTable();
Element tbody = DOM.createTBody();
Element tr = DOM.createTR();
final Element imageTD = DOM.createTD();
labelTD = DOM.createTD();
setElement(root);
DOM.appendChild(root, tbody);
DOM.appendChild(tbody, tr);
DOM.appendChild(tr, imageTD);
DOM.appendChild(tr, labelTD);
// set image TD to be same width as image.
DOM.setElementProperty(imageTD, "align", "center");
DOM.setElementProperty(imageTD, "valign", "middle");
DOM.setStyleAttribute(imageTD, "width", iconImage.getWidth() + "px");
DOM.appendChild(imageTD, iconImage.getElement());
setText(text);
addOpenHandler(this);
addCloseHandler(this);
setStyle();
}
private DefaultHeader(final ImageResource openImage,
final ImageResource closedImage, String text) {
this(new Imager() {
public Image makeImage() {
return new Image(closedImage);
}
public void updateImage(boolean open, Image image) {
if (open) {
image.setResource(openImage);
} else {
image.setResource(closedImage);
}
}
}, text);
}
public final String getText() {
return DOM.getInnerText(labelTD);
}
public final void onClose(CloseEvent<DisclosurePanel> event) {
setStyle();
}
public final void onOpen(OpenEvent<DisclosurePanel> event) {
setStyle();
}
public final void setText(String text) {
DOM.setInnerText(labelTD, text);
}
private void setStyle() {
imager.updateImage(isOpen, iconImage);
}
}
private interface Imager {
Image makeImage();
void updateImage(boolean open, Image image);
}
/**
* The duration of the animation.
*/
private static final int ANIMATION_DURATION = 350;
// Stylename constants.
private static final String STYLENAME_DEFAULT = "gwt-DisclosurePanel";
private static final String STYLENAME_SUFFIX_OPEN = "open";
private static final String STYLENAME_SUFFIX_CLOSED = "closed";
private static final String STYLENAME_HEADER = "header";
private static final String STYLENAME_CONTENT = "content";
/**
* The {@link Animation} used to open and close the content.
*/
private static ContentAnimation contentAnimation;
/**
* top level widget. The first child will be a reference to {@link #header}.
* The second child will be a reference to {@link #contentWrapper}.
*/
private final VerticalPanel mainPanel = new VerticalPanel();
/**
* The wrapper around the content widget.
*/
private final SimplePanel contentWrapper = new SimplePanel();
/**
* holds the header widget.
*/
private final ClickableHeader header = new ClickableHeader();
private boolean isAnimationEnabled = false;
private boolean isOpen = false;
/**
* Creates an empty DisclosurePanel that is initially closed.
*/
public DisclosurePanel() {
initWidget(mainPanel);
mainPanel.add(header);
mainPanel.add(contentWrapper);
DOM.setStyleAttribute(contentWrapper.getElement(), "padding", "0px");
DOM.setStyleAttribute(contentWrapper.getElement(), "overflow", "hidden");
setStyleName(STYLENAME_DEFAULT);
setContentDisplay(false);
}
/**
* Creates a DisclosurePanel with the specified header text, an initial
* open/close state and a bundle of images to be used in the default header
* widget.
*
* @param images a bundle that provides disclosure panel specific images
* @param headerText the text to be displayed in the header
* @param isOpen the initial open/close state of the content panel
*
* @deprecated use
* {@link #DisclosurePanel(ImageResource, ImageResource, String)}
* and {@link #setOpen(boolean)}
*/
@Deprecated
public DisclosurePanel(DisclosurePanelImages images, String headerText,
boolean isOpen) {
this();
setOpen(isOpen);
setHeader(new DefaultHeader(images, headerText));
}
/**
* Creates a DisclosurePanel with the specified header text, an initial
* open/close state and a bundle of images to be used in the default header
* widget.
*
* @param openImage the open state image resource
* @param closedImage the closed state image resource
* @param headerText the text to be displayed in the header
*/
public DisclosurePanel(ImageResource openImage, ImageResource closedImage,
String headerText) {
this();
setHeader(new DefaultHeader(openImage, closedImage, headerText));
}
/**
* Creates a DisclosurePanel that will be initially closed using the specified
* text in the header.
*
* @param headerText the text to be displayed in the header
*/
public DisclosurePanel(String headerText) {
this(DEFAULT_IMAGES.disclosurePanelOpen(),
DEFAULT_IMAGES.disclosurePanelClosed(), headerText);
}
/**
* Creates a DisclosurePanel with the specified header text and an initial
* open/close state.
*
* @param headerText the text to be displayed in the header
* @param isOpen the initial open/close state of the content panel
* @deprecated use {@link #DisclosurePanel(String)} and
* {@link #setOpen(boolean)}
*/
@Deprecated
public DisclosurePanel(String headerText, boolean isOpen) {
this(DEFAULT_IMAGES.disclosurePanelOpen(),
DEFAULT_IMAGES.disclosurePanelClosed(), headerText);
this.setOpen(isOpen);
}
/**
* Creates a DisclosurePanel that will be initially closed using a widget as
* the header.
*
* @param header the widget to be used as a header
* @deprecated use {@link #DisclosurePanel()} and {@link #setHeader(Widget)}
*/
@Deprecated
public DisclosurePanel(Widget header) {
this();
setHeader(header);
}
/**
* Creates a DisclosurePanel using a widget as the header and an initial
* open/close state.
*
* @param header the widget to be used as a header
* @param isOpen the initial open/close state of the content panel
* @deprecated use {@link #DisclosurePanel()}, {@link #setOpen(boolean)} and
* {@link #setHeader(Widget)} instead
*/
@Deprecated
public DisclosurePanel(Widget header, boolean isOpen) {
this();
setHeader(header);
setOpen(isOpen);
}
public void add(Widget w) {
if (this.getContent() == null) {
setContent(w);
} else {
throw new IllegalStateException(
"A DisclosurePanel can only contain two Widgets.");
}
}
/**
* Overloaded version for IsWidget.
*
* @see #add(Widget)
*/
public void add(IsWidget w) {
this.add(asWidgetOrNull(w));
}
public HandlerRegistration addCloseHandler(
CloseHandler<DisclosurePanel> handler) {
return addHandler(handler, CloseEvent.getType());
}
/**
* Attaches an event handler to the panel to receive {@link DisclosureEvent}
* notification.
*
* @param handler the handler to be added (should not be null)
* @deprecated Use {@link DisclosurePanel#addOpenHandler(OpenHandler)} and
* {@link DisclosurePanel#addCloseHandler(CloseHandler)} instead
*/
@Deprecated
public void addEventHandler(final DisclosureHandler handler) {
ListenerWrapper.WrappedOldDisclosureHandler.add(this, handler);
}
public HandlerRegistration addOpenHandler(OpenHandler<DisclosurePanel> handler) {
return addHandler(handler, OpenEvent.getType());
}
public void clear() {
setContent(null);
}
/**
* Gets the widget that was previously set in {@link #setContent(Widget)}.
*
* @return the panel's current content widget
*/
public Widget getContent() {
return contentWrapper.getWidget();
}
/**
* Gets the widget that is currently being used as a header.
*
* @return the widget currently being used as a header
*/
public Widget getHeader() {
return header.getWidget();
}
/**
* Gets a {@link HasText} instance to provide access to the headers's text, if
* the header widget does provide such access.
*
* @return a reference to the header widget if it implements {@link HasText},
* <code>null</code> otherwise
*/
public HasText getHeaderTextAccessor() {
Widget widget = header.getWidget();
return (widget instanceof HasText) ? (HasText) widget : null;
}
public boolean isAnimationEnabled() {
return isAnimationEnabled;
}
/**
* Determines whether the panel is open.
*
* @return <code>true</code> if panel is in open state
*/
public boolean isOpen() {
return isOpen;
}
public Iterator<Widget> iterator() {
return WidgetIterators.createWidgetIterator(this,
new Widget[] {getContent()});
}
public boolean remove(Widget w) {
if (w == getContent()) {
setContent(null);
return true;
}
return false;
}
/**
* Overloaded version for IsWidget.
*
* @see #remove(Widget)
*/
public boolean remove(IsWidget w) {
return this.remove(asWidgetOrNull(w));
}
/**
* Removes an event handler from the panel.
*
* @param handler the handler to be removed
* @deprecated Use the {@link HandlerRegistration#removeHandler} method on the
* object returned by an add*Handler method instead
*/
@Deprecated
public void removeEventHandler(DisclosureHandler handler) {
ListenerWrapper.WrappedOldDisclosureHandler.remove(this, handler);
}
public void setAnimationEnabled(boolean enable) {
isAnimationEnabled = enable;
}
/**
* Sets the content widget which can be opened and closed by this panel. If
* there is a preexisting content widget, it will be detached.
*
* @param content the widget to be used as the content panel
*/
public void setContent(Widget content) {
final Widget currentContent = getContent();
// Remove existing content widget.
if (currentContent != null) {
contentWrapper.setWidget(null);
currentContent.removeStyleName(STYLENAME_CONTENT);
}
// Add new content widget if != null.
if (content != null) {
contentWrapper.setWidget(content);
content.addStyleName(STYLENAME_CONTENT);
setContentDisplay(false);
}
}
/**
* Sets the widget used as the header for the panel.
*
* @param headerWidget the widget to be used as the header
*/
public void setHeader(Widget headerWidget) {
header.setWidget(headerWidget);
}
/**
* Changes the visible state of this <code>DisclosurePanel</code>.
*
* @param isOpen <code>true</code> to open the panel, <code>false</code> to
* close
*/
public void setOpen(boolean isOpen) {
if (this.isOpen != isOpen) {
this.isOpen = isOpen;
setContentDisplay(true);
fireEvent();
}
}
/**
* <b>Affected Elements:</b>
* <ul>
* <li>-header = the clickable header.</li>
* </ul>
*
* @see UIObject#onEnsureDebugId(String)
*/
@Override
protected void onEnsureDebugId(String baseID) {
super.onEnsureDebugId(baseID);
header.ensureDebugId(baseID + "-header");
}
private void fireEvent() {
if (isOpen) {
OpenEvent.fire(this, this);
} else {
CloseEvent.fire(this, this);
}
}
private void setContentDisplay(boolean animate) {
if (isOpen) {
removeStyleDependentName(STYLENAME_SUFFIX_CLOSED);
addStyleDependentName(STYLENAME_SUFFIX_OPEN);
} else {
removeStyleDependentName(STYLENAME_SUFFIX_OPEN);
addStyleDependentName(STYLENAME_SUFFIX_CLOSED);
}
if (getContent() != null) {
if (contentAnimation == null) {
contentAnimation = new ContentAnimation();
}
contentAnimation.setOpen(this, animate && isAnimationEnabled);
}
}
}