Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  HasCloseHandlers<PopupPanel>, HasHandlers, EventListener, EventPreview, HasAnimation, HasWidgets, SourcesPopupEvents, java.lang.Iterable<Widget>

Direct Known Subclasses:
  DecoratedPopupPanel

    public class PopupPanel

extends SimplePanel
implements SourcesPopupEvents, EventPreview, HasAnimation, HasCloseHandlers<PopupPanel>

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

A PopupPanel should not generally be added to other panels; rather, it should be shown and hidden using the `show()` and `hide()` methods.

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.addClickHandler(new ClickHandler() {
>           public void onClick(ClickEvent event) {
>             // 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.addClickHandler(new ClickHandler() {
>           public void onClick(ClickEvent event) {
>             // 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` | `addAutoHidePartner(Element partner)` Mouse events that occur within an autoHide partner will not hide a panel set to autoHide.
`HandlerRegistration` | `addCloseHandler(CloseHandler<PopupPanel> handler)` Adds a `CloseEvent` handler.
`void` | `addPopupListener(PopupListener listener)` Deprecated. Use `addCloseHandler(com.google.gwt.event.logical.shared.CloseHandler)` instead
`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.
`protected Element` | `getStyleElement()` Template method that returns the element to which style names will be applied.
`java.lang.String` | `getTitle()` Gets the title associated with this object.
`void` | `hide()` Hides the popup and detaches it from the page.
`void` | `hide(boolean autoClosed)` Hides the popup and detaches it from the page.
`boolean` | `isAnimationEnabled()`
`boolean` | `isAutoHideEnabled()` Returns `true` if the popup should be automatically hidden when the user clicks outside of it.
`boolean` | `isModal()` Returns `true` if keyboard or mouse events that do not target the PopupPanel or its children should be ignored.
`boolean` | `isPreviewingAllNativeEvents()` Returns `true` if the popup should preview all native events, even if the event has already been consumed by another popup.
`boolean` | `isShowing()` Determines whether or not this popup is showing.
`boolean` | `isVisible()` Determines whether or not this popup is visible.
`boolean` | `onEventPreview(Event event)` Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead
`boolean` | `onKeyDownPreview(char key, int modifiers)` Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead
`boolean` | `onKeyPressPreview(char key, int modifiers)` Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead
`boolean` | `onKeyUpPreview(char key, int modifiers)` Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead
`protected void` | `onPreviewNativeEvent(Event.NativePreviewEvent event)`
`protected void` | `onUnload()` A Panel's onUnload method will be called before its children become detached themselves.
`void` | `removeAutoHidePartner(Element partner)` Remove an autoHide partner.
`void` | `removePopupListener(PopupListener listener)` Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by `addCloseHandler(com.google.gwt.event.logical.shared.CloseHandler)` instead
`void` | `setAnimationEnabled(boolean enable)` Enable or disable animations.
`void` | `setAutoHideEnabled(boolean autoHide)` Enable or disable the autoHide feature.
`void` | `setHeight(java.lang.String height)` Sets the height of the panel's child widget.
`void` | `setModal(boolean modal)` When the popup is modal, keyboard or mouse events that do not target the PopupPanel or its children will be ignored.
`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` | `setPreviewingAllNativeEvents(boolean previewAllNativeEvents)` When enabled, the popup will preview all native events, even if another popup was opened after this one.
`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 and attach it to the page.
`void` | `showRelativeTo(UIObject target)` Normally, the popup is positioned directly below the relative target, with its left edge aligned with the left edge of the target.

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, orphan`

Methods inherited from class com.google.gwt.user.client.ui.Widget
`addDomHandler, addHandler, delegateEvent, fireEvent, getHandlerCount, getParent, isAttached, isOrWasAttached, onAttach, onBrowserEvent, onDetach, removeFromParent, sinkEvents`

Methods inherited from class com.google.gwt.user.client.ui.UIObject
`addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, setElement, setElement, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setVisible, toString, unsinkEvents`

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

Methods inherited from interface com.google.gwt.event.shared.HasHandlers
`fireEvent`

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

### addAutoHidePartner

    public void addAutoHidePartner(Element partner)

  Mouse events that occur within an autoHide partner will not hide a panel set to autoHide.

  Parameters:
    `partner` - the auto hide partner to add

### addCloseHandler

    public HandlerRegistration addCloseHandler(CloseHandler<PopupPanel> handler)

  Description copied from interface: `HasCloseHandlers`
  Adds a `CloseEvent` handler.

  Specified by:
    `addCloseHandler` in interface `HasCloseHandlers<PopupPanel>`
  Parameters:
    `handler` - the handler
  Returns:
    the registration for the event

### addPopupListener

    @Deprecated
    public void addPopupListener(PopupListener listener)

  Deprecated. Use `addCloseHandler(com.google.gwt.event.logical.shared.CloseHandler)` instead

  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 and detaches it from the page. This has no effect if it is not currently showing.

### hide

    public void hide(boolean autoClosed)

  Hides the popup and detaches it from the page. This has no effect if it is not currently showing.

  Parameters:
    `autoClosed` - the value that will be passed to `CloseHandler.onClose(CloseEvent)` when the popup is closed

### isAnimationEnabled

    public boolean isAnimationEnabled()

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

### isAutoHideEnabled

    public boolean isAutoHideEnabled()

  Returns `true` if the popup should be automatically hidden when the user clicks outside of it.

  Returns:
    true if autoHide is enabled, false if disabled

### isModal

    public boolean isModal()

  Returns `true` if keyboard or mouse events that do not target the PopupPanel or its children should be ignored.

  Returns:
    true if popup is modal, false if not

### isPreviewingAllNativeEvents

    public boolean isPreviewingAllNativeEvents()

  Returns `true` if the popup should preview all native events, even if the event has already been consumed by another popup.

  Returns:
    true if previewAllNativeEvents is enabled, false if disabled

### isShowing

    public boolean isShowing()

  Determines whether or not this popup is showing.

  Returns:
    `true` if the popup is showing
  See Also:
    `show()`, `hide()`

### isVisible

    public boolean isVisible()

  Determines whether or not this popup is visible. Note that this just checks the `visibility` style attribute, which is set in the `setVisible(boolean)` method. If you want to know if the popup is attached to the page, use `isShowing()` instead.

  Overrides:
    `isVisible` in class `UIObject`
  Returns:
    `true` if the object is visible
  See Also:
    `setVisible(boolean)`

### onEventPreview

    @Deprecated
    public boolean onEventPreview(Event event)

  Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead

  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

    @Deprecated
    public boolean onKeyDownPreview(char key,
                                               int modifiers)

  Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead

  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 `KeyCodes`.
  Returns:
    `false` to suppress the event

### onKeyPressPreview

    @Deprecated
    public boolean onKeyPressPreview(char key,
                                                int modifiers)

  Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead

  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 `KeyCodes`.
  Returns:
    `false` to suppress the event

### onKeyUpPreview

    @Deprecated
    public boolean onKeyUpPreview(char key,
                                             int modifiers)

  Deprecated. Use `#onPreviewNativeEvent(NativePreviewEvent)` instead

  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 `KeyCodes`.
  Returns:
    `false` to suppress the event

### removeAutoHidePartner

    public void removeAutoHidePartner(Element partner)

  Remove an autoHide partner.

  Parameters:
    `partner` - the auto hide partner to remove

### removePopupListener

    @Deprecated
    public void removePopupListener(PopupListener listener)

  Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by `addCloseHandler(com.google.gwt.event.logical.shared.CloseHandler)` instead

  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

### setAutoHideEnabled

    public void setAutoHideEnabled(boolean autoHide)

  Enable or disable the autoHide feature. When enabled, the popup will be automatically hidden when the user clicks outside of it.

  Parameters:
    `autoHide` - true to enable autoHide, 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")

### setModal

    public void setModal(boolean modal)

  When the popup is modal, keyboard or mouse events that do not target the PopupPanel or its children will be ignored.

  Parameters:
    `modal` - true to make the popup modal

### 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)`

### setPreviewingAllNativeEvents

    public void setPreviewingAllNativeEvents(boolean previewAllNativeEvents)

  When enabled, the popup will preview all native events, even if another popup was opened after this one.

  If autoHide is enabled, enabling this feature will cause the popup to autoHide even if another non-modal popup was shown after it. If this feature is disabled, the popup will only autoHide if it was the last popup opened.

  Parameters:
    `previewAllNativeEvents` - true to enable, false to disable

### 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. This method just sets the `visibility` style attribute. You need to call `show()` to actually attached/detach the `PopupPanel` to the page.

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

### 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 and attach it to the page. It must have a child widget before this method is called.

### showRelativeTo

    public final void showRelativeTo(UIObject target)

  Normally, the popup is positioned directly below the relative target, with its left edge aligned with the left edge of the target. Depending on the width and height of the popup and the distance from the target to the bottom and right edges of the window, the popup may be displayed directly above the target, and/or its right edge may be aligned with the right edge of the target.

  Parameters:
    `target` - the target to show the popup below

### 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

### getStyleElement

    protected Element getStyleElement()

  Description copied from class: `UIObject`
  Template method that returns the element to which style names will be applied. By default it returns the root element, but this method may be overridden to apply styles to a child element.

  Overrides:
    `getStyleElement` in class `UIObject`
  Returns:
    the element to which style names will be applied

### onPreviewNativeEvent

    protected void onPreviewNativeEvent(Event.NativePreviewEvent event)

### onUnload

    protected void onUnload()

  Description copied from class: `Panel`
  A Panel's onUnload method will be called before its children become detached themselves.

  Overrides:
    `onUnload` in class `Panel`
  See Also:
    `Widget.onLoad()`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD