## com.google.gwt.user.client.ui
Class PopupPanel

    java.lang.Object
      com.google.gwt.user.client.ui.UIObject
          com.google.gwt.user.client.ui.Widget
              com.google.gwt.user.client.ui.Panel
                  com.google.gwt.user.client.ui.SimplePanel
                      com.google.gwt.user.client.ui.PopupPanel

All Implemented Interfaces:
  EventListener, EventPreview, HasAnimation, HasWidgets, SourcesPopupEvents, java.lang.Iterable<Widget>

Direct Known Subclasses:
  DecoratedPopupPanel

    public class PopupPanel

extends SimplePanel
implements SourcesPopupEvents, EventPreview, HasAnimation

A panel that can "pop up" over other widgets. It overlays the browser's client area (and any previously-created popups).

The width and height of the PopupPanel cannot be explicitly set; they are determined by the PopupPanel's widget. Calls to `setWidth(String)` and `setHeight(String)` will call these methods on the PopupPanel's widget.

### Example

>     public class PopupPanelExample implements EntryPoint {

>       private static class MyPopup extends PopupPanel {

>         public MyPopup() {
>           // PopupPanel's constructor takes 'auto-hide' as its boolean parameter.
>           // If this is set, the panel closes itself automatically when the user
>           // clicks outside of it.
>           super(true);

>           // PopupPanel is a SimplePanel, so you have to set it's widget property to
>           // whatever you want its contents to be.
>           setWidget(new Label("Click outside of this popup to close it"));
>         }
>       }

>       public void onModuleLoad() {
>         Button b1 = new Button("Click me to show popup");
>         b1.addClickListener(new ClickListener() {
>           public void onClick(Widget sender) {
>             // Instantiate the popup and show it.
>             new MyPopup().show();
>           }
>         });

>         RootPanel.get().add(b1);

>         Button b2 = new Button("Click me to show popup partway across the screen");

>         b2.addClickListener(new ClickListener() {
>           public void onClick(Widget sender) {
>             // Create the new popup.
>             final MyPopup popup = new MyPopup();
>             // Position the popup 1/3rd of the way down and across the screen, and
>             // show the popup. Since the position calculation is based on the
>             // offsetWidth and offsetHeight of the popup, you have to use the
>             // setPopupPositionAndShow(callback) method. The alternative would
>             // be to call show(), calculate the left and top positions, and
>             // call setPopupPosition(left, top). This would have the ugly side
>             // effect of the popup jumping from its original position to its
>             // new position.
>             popup.setPopupPositionAndShow(new PopupPanel.PositionCallback() {
>               public void setPosition(int offsetWidth, int offsetHeight) {
>                 int left = (Window.getClientWidth() - offsetWidth) / 3;
>                 int top = (Window.getClientHeight() - offsetHeight) / 3;
>                 popup.setPopupPosition(left, top);
>               }
>             });
>           }
>         });

>         RootPanel.get().add(b2);
>       }
>     }

### CSS Style Rules

- .gwt-PopupPanel { the outside of the popup }
- .gwt-PopupPanel .popupContent { the wrapper around the content }

Nested Class Summary
`static interface` `PopupPanel.PositionCallback` A callback that is used to set the position of a `PopupPanel` right before it is shown.

Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject
`UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

Field Summary

Fields inherited from class com.google.gwt.user.client.ui.UIObject
`DEBUG_ID_PREFIX`

Constructor Summary
`PopupPanel()` Creates an empty popup panel.
`PopupPanel(boolean autoHide)` Creates an empty popup panel, specifying its "auto-hide" property.
`PopupPanel(boolean autoHide, boolean modal)` Creates an empty popup panel, specifying its "auto-hide" and "modal" properties.

Method Summary
`void` `addPopupListener(PopupListener listener)` Adds a listener interface to receive popup events.
`void` `center()` Centers the popup in the browser window and shows it.
`protected Element` `getContainerElement()` Override this method to specify that an element other than the root element be the container for the panel's child widget.
`int` `getOffsetHeight()` Gets the panel's offset height in pixels.
`int` `getOffsetWidth()` Gets the panel's offset width in pixels.
`int` `getPopupLeft()` Gets the popup's left position relative to the browser's client area.
`int` `getPopupTop()` Gets the popup's top position relative to the browser's client area.
`java.lang.String` `getTitle()` Gets the title associated with this object.
`void` `hide()` Hides the popup.
`boolean` `isAnimationEnabled()`
`protected void` `onDetach()` This method is called when a widget is detached from the browser's document.
`boolean` `onEventPreview(Event event)` Called when a browser event occurs and this event preview is on top of the preview stack.
`boolean` `onKeyDownPreview(char key, int modifiers)` Popups get an opportunity to preview keyboard events before they are passed to a widget contained by the Popup.
`boolean` `onKeyPressPreview(char key, int modifiers)` Popups get an opportunity to preview keyboard events before they are passed to a widget contained by the Popup.
`boolean` `onKeyUpPreview(char key, int modifiers)` Popups get an opportunity to preview keyboard events before they are passed to a widget contained by the Popup.
`void` `removePopupListener(PopupListener listener)` Removes a previously added popup listener.
`void` `setAnimationEnabled(boolean enable)` Enable or disable animations.
`void` `setHeight(java.lang.String height)` Sets the height of the panel's child widget.
`void` `setPopupPosition(int left, int top)` Sets the popup's position relative to the browser's client area.
`void` `setPopupPositionAndShow(PopupPanel.PositionCallback callback)` Sets the popup's position using a `PopupPanel.PositionCallback`, and shows the popup.
`void` `setTitle(java.lang.String title)` Sets the title associated with this object.
`void` `setVisible(boolean visible)` Sets whether this object is visible.
`void` `setWidget(Widget w)` Sets this panel's widget.
`void` `setWidth(java.lang.String width)` Sets the width of the panel's child widget.
`void` `show()` Shows the popup.

Methods inherited from class com.google.gwt.user.client.ui.SimplePanel
`add, getWidget, iterator, remove`

Methods inherited from class com.google.gwt.user.client.ui.Panel
`adopt, adopt, clear, disown, doAttachChildren, doDetachChildren, onLoad, onUnload, orphan`

Methods inherited from class com.google.gwt.user.client.ui.Widget
`getParent, isAttached, onAttach, onBrowserEvent, removeFromParent`

Methods inherited from class com.google.gwt.user.client.ui.UIObject

`addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, setElement, setElement, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setVisible, sinkEvents, toString, unsinkEvents`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### PopupPanel

    public PopupPanel()

  Creates an empty popup panel. A child widget must be added to it before it is shown.

### PopupPanel

    public PopupPanel(boolean autoHide)

  Creates an empty popup panel, specifying its "auto-hide" property.

  Parameters:
    `autoHide` - `true` if the popup should be automatically hidden when the user clicks outside of it

### PopupPanel

    public PopupPanel(boolean autoHide,
                      boolean modal)

  Creates an empty popup panel, specifying its "auto-hide" and "modal" properties.

  Parameters:
    `autoHide` - `true` if the popup should be automatically hidden when the user clicks outside of it
    `modal` - `true` if keyboard or mouse events that do not target the PopupPanel or its children should be ignored

Method Detail

### addPopupListener

    public void addPopupListener(PopupListener listener)

  Description copied from interface: `SourcesPopupEvents`
  Adds a listener interface to receive popup events.

  Specified by:
    `addPopupListener` in interface `SourcesPopupEvents`
  Parameters:
    `listener` - the listener interface to add.

### center

    public void center()

  Centers the popup in the browser window and shows it. If the popup was already showing, then the popup is centered.

### getOffsetHeight

    public int getOffsetHeight()

  Gets the panel's offset height in pixels. Calls to `setHeight(String)` before the panel's child widget is set will not influence the offset height.

  Overrides:
    `getOffsetHeight` in class `UIObject`
  Returns:
    the object's offset height

### getOffsetWidth

    public int getOffsetWidth()

  Gets the panel's offset width in pixels. Calls to `setWidth(String)` before the panel's child widget is set will not influence the offset width.

  Overrides:
    `getOffsetWidth` in class `UIObject`
  Returns:
    the object's offset width

### getPopupLeft

    public int getPopupLeft()

  Gets the popup's left position relative to the browser's client area.

  Returns:
    the popup's left position

### getPopupTop

    public int getPopupTop()

  Gets the popup's top position relative to the browser's client area.

  Returns:
    the popup's top position

### getTitle

    public java.lang.String getTitle()

  Description copied from class: `UIObject`
  Gets the title associated with this object. The title is the 'tool-tip' displayed to users when they hover over the object.

  Overrides:
    `getTitle` in class `UIObject`
  Returns:
    the object's title

### hide

    public void hide()

  Hides the popup. This has no effect if it is not currently visible.

### isAnimationEnabled

    public boolean isAnimationEnabled()

  Specified by:
    `isAnimationEnabled` in interface `HasAnimation`
  Returns:
    true if animations are enabled, false if not

### onEventPreview

    public boolean onEventPreview(Event event)

  Description copied from interface: `EventPreview`
  Called when a browser event occurs and this event preview is on top of the preview stack.

  Specified by:
    `onEventPreview` in interface `EventPreview`
  Parameters:
    `event` - the browser event
  Returns:
    `false` to cancel the event
  See Also:
    `DOM.addEventPreview(EventPreview)`

### onKeyDownPreview

    public boolean onKeyDownPreview(char key,
                                    int modifiers)

  Popups get an opportunity to preview keyboard events before they are passed to a widget contained by the Popup.

  Parameters:
    `key` - the key code of the depressed key
    `modifiers` - keyboard modifiers, as specified in `KeyboardListener`.
  Returns:
    `false` to suppress the event

### onKeyPressPreview

    public boolean onKeyPressPreview(char key,
                                     int modifiers)

  Popups get an opportunity to preview keyboard events before they are passed to a widget contained by the Popup.

  Parameters:
    `key` - the unicode character pressed
    `modifiers` - keyboard modifiers, as specified in `KeyboardListener`.
  Returns:
    `false` to suppress the event

### onKeyUpPreview

    public boolean onKeyUpPreview(char key,
                                  int modifiers)

  Popups get an opportunity to preview keyboard events before they are passed to a widget contained by the Popup.

  Parameters:
    `key` - the key code of the released key
    `modifiers` - keyboard modifiers, as specified in `KeyboardListener`.
  Returns:
    `false` to suppress the event

### removePopupListener

    public void removePopupListener(PopupListener listener)

  Description copied from interface: `SourcesPopupEvents`
  Removes a previously added popup listener.

  Specified by:
    `removePopupListener` in interface `SourcesPopupEvents`
  Parameters:
    `listener` - the listener interface to remove.

### setAnimationEnabled

    public void setAnimationEnabled(boolean enable)

  Description copied from interface: `HasAnimation`
  Enable or disable animations.

  Specified by:
    `setAnimationEnabled` in interface `HasAnimation`
  Parameters:
    `enable` - true to enable, false to disable

### setHeight

    public void setHeight(java.lang.String height)

  Sets the height of the panel's child widget. If the panel's child widget has not been set, the height passed in will be cached and used to set the height immediately after the child widget is set.

  Note that subclasses may have a different behavior. A subclass may decide not to change the height of the child widget. It may instead decide to change the height of an internal panel widget, which contains the child widget.

  Overrides:
    `setHeight` in class `UIObject`
  Parameters:
    `height` - the object's new height, in CSS units (e.g. "10px", "1em")

### setPopupPosition

    public void setPopupPosition(int left,
                                 int top)

  Sets the popup's position relative to the browser's client area. The popup's position may be set before calling `show()`.

  Parameters:
    `left` - the left position, in pixels
    `top` - the top position, in pixels

### setPopupPositionAndShow

    public void setPopupPositionAndShow(PopupPanel.PositionCallback callback)

  Sets the popup's position using a `PopupPanel.PositionCallback`, and shows the popup. The callback allows positioning to be performed based on the offsetWidth and offsetHeight of the popup, which are normally not available until the popup is showing. By positioning the popup before it is shown, the the popup will not jump from its original position to the new position.

  Parameters:
    `callback` - the callback to set the position of the popup
  See Also:
    `PopupPanel.PositionCallback.setPosition(int offsetWidth, int offsetHeight)`

### setTitle

    public void setTitle(java.lang.String title)

  Description copied from class: `UIObject`
  Sets the title associated with this object. The title is the 'tool-tip' displayed to users when they hover over the object.

  Overrides:
    `setTitle` in class `UIObject`
  Parameters:
    `title` - the object's new title

### setVisible

    public void setVisible(boolean visible)

  Sets whether this object is visible.

  Overrides:
    `setVisible` in class `UIObject`
  Parameters:
    `visible` - `true` to show the object, `false` to hide it

### setWidget

    public void setWidget(Widget w)

  Description copied from class: `SimplePanel`
  Sets this panel's widget. Any existing child widget will be removed.

  Overrides:
    `setWidget` in class `SimplePanel`
  Parameters:
    `w` - the panel's new widget, or `null` to clear the panel

### setWidth

    public void setWidth(java.lang.String width)

  Sets the width of the panel's child widget. If the panel's child widget has not been set, the width passed in will be cached and used to set the width immediately after the child widget is set.

  Note that subclasses may have a different behavior. A subclass may decide not to change the width of the child widget. It may instead decide to change the width of an internal panel widget, which contains the child widget.

  Overrides:
    `setWidth` in class `UIObject`
  Parameters:
    `width` - the object's new width, in CSS units (e.g. "10px", "1em")

### show

    public void show()

  Shows the popup. It must have a child widget before this method is called.

### getContainerElement

    protected Element getContainerElement()

  Description copied from class: `SimplePanel`
  Override this method to specify that an element other than the root element be the container for the panel's child widget. This can be useful when you want to create a simple panel that decorates its contents. Note that this method continues to return the `Element` class defined in the `User` module to maintain backwards compatibility.

  Overrides:
    `getContainerElement` in class `SimplePanel`
  Returns:
    the element to be used as the panel's container

### onDetach

    protected void onDetach()

  This method is called when a widget is detached from the browser's document. To receive notification before the PopupPanel is removed from the document, override the `Widget.onUnload()` method instead.

  Overrides:
    `onDetach` in class `Widget`