/*
* Copyright 2007 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.user.client.DOM;
import com.google.gwt.user.client.Element;
import java.util.Iterator;
/**
* Abstract base class for all panels, which are widgets that can contain other
* widgets.
*/
public abstract class Panel extends Widget implements HasWidgets.ForIsWidget {
/**
* Adds a child widget.
*
* <p>
* <b>How to Override this Method</b>
* </p>
* <p>
* There are several important things that must take place in the correct
* order to properly add or insert a Widget to a Panel. Not all of these steps
* will be relevant to every Panel, but all of the steps must be considered.
* <ol>
* <li><b>Validate:</b> Perform any sanity checks to ensure the Panel can
* accept a new Widget. Examples: checking for a valid index on insertion;
* checking that the Panel is not full if there is a max capacity.</li>
* <li><b>Adjust for Reinsertion:</b> Some Panels need to handle the case
* where the Widget is already a child of this Panel. Example: when performing
* a reinsert, the index might need to be adjusted to account for the Widget's
* removal. See {@link ComplexPanel#adjustIndex(Widget, int)}.</li>
* <li><b>Detach Child:</b> Remove the Widget from its existing parent, if
* any. Most Panels will simply call {@link Widget#removeFromParent()} on the
* Widget.</li>
* <li><b>Logical Attach:</b> Any state variables of the Panel should be
* updated to reflect the addition of the new Widget. Example: the Widget is
* added to the Panel's {@link WidgetCollection} at the appropriate index.</li>
* <li><b>Physical Attach:</b> The Widget's Element must be physically
* attached to the Panel's Element, either directly or indirectly.</li>
* <li><b>Adopt:</b> Call {@link #adopt(Widget)} to finalize the add as the
* very last step.</li>
* </ol>
* </p>
*
* @param child the widget to be added
* @throws UnsupportedOperationException if this method is not supported (most
* often this means that a specific overload must be called)
* @see HasWidgets#add(Widget)
*/
public void add(Widget child) {
throw new UnsupportedOperationException(
"This panel does not support no-arg add()");
}
public void add(IsWidget child) {
this.add(asWidgetOrNull(child));
}
public void clear() {
Iterator<Widget> it = iterator();
while (it.hasNext()) {
it.next();
it.remove();
}
}
/**
* Removes a child widget.
*
* <p>
* <b>How to Override this Method</b>
* </p>
* <p>
* There are several important things that must take place in the correct
* order to properly remove a Widget from a Panel. Not all of these steps will
* be relevant to every Panel, but all of the steps must be considered.
* <ol>
* <li><b>Validate:</b> Make sure this Panel is actually the parent of the
* child Widget; return <code>false</code> if it is not.</li>
* <li><b>Orphan:</b> Call {@link #orphan(Widget)} first while the child
* Widget is still attached.</li>
* <li><b>Physical Detach:</b> Adjust the DOM to account for the removal of
* the child Widget. The Widget's Element must be physically removed from the
* DOM.</li>
* <li><b>Logical Detach:</b> Update the Panel's state variables to reflect
* the removal of the child Widget. Example: the Widget is removed from the
* Panel's {@link WidgetCollection}.</li>
* </ol>
* </p>
*
* @param child the widget to be removed
* @return <code>true</code> if the child was present
*/
public abstract boolean remove(Widget child);
public boolean remove(IsWidget child) {
return remove(asWidgetOrNull(child));
}
/**
* Finalize the attachment of a Widget to this Panel. This method is the
* <b>last</b> step in adding or inserting a Widget into a Panel, and should
* be called after physical attachment in the DOM is complete. This Panel
* becomes the parent of the child Widget, and the child will now fire its
* {@link Widget#onAttach()} event if this Panel is currently attached.
*
* @param child the widget to be adopted
* @see #add(Widget)
*/
protected final void adopt(Widget child) {
assert (child.getParent() == null);
child.setParent(this);
}
/**
* This method was formerly part of the process of adding a Widget to a Panel
* but has been deprecated in favor of {@link #adopt(Widget)}.
*
* @deprecated Use {@link #adopt(Widget)}.
*/
@Deprecated
protected void adopt(Widget w, Element container) {
// Remove the widget from its current parent, if any.
w.removeFromParent();
// Attach it at the DOM and GWT levels.
if (container != null) {
DOM.appendChild(container, w.getElement());
}
w.setParent(this);
}
/**
* This method was formerly part of the process of removing a Widget from a
* Panel but has been deprecated in favor of {@link #orphan(Widget)}.
*
* @deprecated Use {@link #orphan(Widget)}.
*/
@Deprecated
protected void disown(Widget w) {
// Only disown it if it's actually contained in this panel.
if (w.getParent() != this) {
throw new IllegalArgumentException("w is not a child of this panel");
}
// setParent() must be called before removeChild() to ensure that the
// element is still attached when onDetach()/onUnload() are called.
Element elem = w.getElement();
w.setParent(null);
DOM.removeChild(DOM.getParent(elem), elem);
}
@Override
protected void doAttachChildren() {
AttachDetachException.tryCommand(this, AttachDetachException.attachCommand);
}
@Override
protected void doDetachChildren() {
AttachDetachException.tryCommand(this, AttachDetachException.detachCommand);
}
/**
* <p>
* This method must be called as part of the remove method of any Panel. It
* ensures that the Widget's parent is cleared. This method should be called
* after verifying that the child Widget is an existing child of the Panel,
* but before physically removing the child Widget from the DOM. The child
* will now fire its {@link Widget#onDetach()} event if this Panel is
* currently attached.
* </p>
* <p>
* Calls to {@link #orphan(Widget)} should be wrapped in a try/finally block
* to ensure that the widget is physically detached even if orphan throws an
* exception.
* </p>
*
* @param child the widget to be disowned
* @see #add(Widget)
*/
protected final void orphan(Widget child) {
assert (child.getParent() == this);
child.setParent(null);
}
}