public class

PopupPanel

extends SimplePanel
implements HasCloseHandlers<T> EventPreview HasAnimation SourcesPopupEvents
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
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

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.

The PopupPanel can be optionally displayed with a "glass" element behind it, which is commonly used to gray out the widgets behind it. It can be enabled using setGlassEnabled(boolean). It has a default style name of "gwt-PopupPanelGlass", which can be changed using setGlassStyleName(String).

Example

{@example com.google.gwt.examples.PopupPanelExample}

CSS Style Rules

.gwt-PopupPanel
the outside of the popup
.gwt-PopupPanel .popupContent
the wrapper around the content
.gwt-PopupPanelGlass
the glass background behind the popup

Summary

Nested Classes
interface PopupPanel.PositionCallback A callback that is used to set the position of a PopupPanel right before it is shown. 
[Expand]
Inherited Constants
From class com.google.gwt.user.client.ui.UIObject
Public Constructors
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.
Public Methods
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)
void addPopupListener(PopupListener listener)
This method is deprecated. Use addCloseHandler(CloseHandler) instead
void center()
Centers the popup in the browser window and shows it.
String getGlassStyleName()
Gets the style name to be used on the glass element.
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.
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()
Returns true if animations are enabled, false if not.
boolean isAutoHideEnabled()
Returns true if the popup should be automatically hidden when the user clicks outside of it.
boolean isAutoHideOnHistoryEventsEnabled()
Returns true if the popup should be automatically hidden when the history token changes, such as when the user presses the browser's back button.
boolean isGlassEnabled()
Returns true if a glass element will be displayed under the PopupPanel.
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)
This method is deprecated. Use onPreviewNativeEvent(Event.NativePreviewEvent) instead
boolean onKeyDownPreview(char key, int modifiers)
This method is deprecated. Use onPreviewNativeEvent(Event.NativePreviewEvent) instead
boolean onKeyPressPreview(char key, int modifiers)
This method is deprecated. Use onPreviewNativeEvent(Event.NativePreviewEvent) instead
boolean onKeyUpPreview(char key, int modifiers)
This method is deprecated. Use onPreviewNativeEvent(Event.NativePreviewEvent) instead
void removeAutoHidePartner(Element partner)
Remove an autoHide partner.
void removePopupListener(PopupListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by addCloseHandler(CloseHandler) instead
void setAnimationEnabled(boolean enable)
Enable or disable animations.
void setAutoHideEnabled(boolean autoHide)
Enable or disable the autoHide feature.
void setAutoHideOnHistoryEventsEnabled(boolean enabled)
Enable or disable autoHide on history change events.
void setGlassEnabled(boolean enabled)
When enabled, the background will be blocked with a semi-transparent pane the next time it is shown.
void setGlassStyleName(String glassStyleName)
Sets the style name to be used on the glass element.
void setHeight(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(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(String width)
Sets the width of the panel's child widget.
void show()
Shows the popup and attach it to the page.
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.
Protected Methods
Element getContainerElement()
Override this method to specify that an element other than the root element be the container for the panel's child widget.
Element getGlassElement()
Get the glass element used by this PopupPanel.
Element getStyleElement()
Template method that returns the element to which style names will be applied.
void onPreviewNativeEvent(Event.NativePreviewEvent event)
void onUnload()
This method is called immediately before a widget will be detached from the browser's document.
[Expand]
Inherited Methods
From class com.google.gwt.user.client.ui.SimplePanel
From class com.google.gwt.user.client.ui.Panel
From class com.google.gwt.user.client.ui.Widget
From class com.google.gwt.user.client.ui.UIObject
From class java.lang.Object
From interface com.google.gwt.event.logical.shared.HasAttachHandlers
From interface com.google.gwt.event.logical.shared.HasCloseHandlers
From interface com.google.gwt.event.shared.HasHandlers
From interface com.google.gwt.user.client.EventListener
From interface com.google.gwt.user.client.EventPreview
From interface com.google.gwt.user.client.ui.AcceptsOneWidget
From interface com.google.gwt.user.client.ui.HasAnimation
From interface com.google.gwt.user.client.ui.HasOneWidget
From interface com.google.gwt.user.client.ui.HasWidgets
From interface com.google.gwt.user.client.ui.HasWidgets.ForIsWidget
From interface com.google.gwt.user.client.ui.IsWidget
From interface com.google.gwt.user.client.ui.SourcesPopupEvents
From interface java.lang.Iterable

Public Constructors

public PopupPanel ()

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

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 or the history token changes.

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 or the history token changes.
modal true if keyboard or mouse events that do not target the PopupPanel or its children should be ignored

Public Methods

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

public HandlerRegistration addCloseHandler (CloseHandler<PopupPanel> handler)

public void addPopupListener (PopupListener listener)

This method is deprecated.
Use addCloseHandler(CloseHandler) instead

Adds a listener interface to receive popup events.

Parameters
listener the listener interface to add.

public void center ()

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

public String getGlassStyleName ()

Gets the style name to be used on the glass element. By default, this is "gwt-PopupPanelGlass".

Returns
  • the glass element's style name

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.

Returns
  • the object's offset height

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.

Returns
  • the object's offset width

public int getPopupLeft ()

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

Returns
  • the popup's left position

public int getPopupTop ()

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

Returns
  • the popup's top position

public String getTitle ()

Gets the title associated with this object. The title is the 'tool-tip' displayed to users when they hover over the object.

Returns
  • the object's title

public void hide ()

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

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 onClose(CloseEvent) when the popup is closed

public boolean isAnimationEnabled ()

Returns true if animations are enabled, false if not.

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

public boolean isAutoHideOnHistoryEventsEnabled ()

Returns true if the popup should be automatically hidden when the history token changes, such as when the user presses the browser's back button.

Returns
  • true if enabled, false if disabled

public boolean isGlassEnabled ()

Returns true if a glass element will be displayed under the PopupPanel.

Returns
  • true if enabled

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

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

public boolean isShowing ()

Determines whether or not this popup is showing.

Returns
  • true if the popup is showing
See Also

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.

Returns
  • true if the object is visible

public boolean onEventPreview (Event event)

This method is deprecated.
Use onPreviewNativeEvent(Event.NativePreviewEvent) instead

Called when a browser event occurs and this event preview is on top of the preview stack.

Parameters
event the browser event
Returns
  • false to cancel the event

public boolean onKeyDownPreview (char key, int modifiers)

This method is deprecated.
Use onPreviewNativeEvent(Event.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

public boolean onKeyPressPreview (char key, int modifiers)

This method is deprecated.
Use onPreviewNativeEvent(Event.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

public boolean onKeyUpPreview (char key, int modifiers)

This method is deprecated.
Use onPreviewNativeEvent(Event.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

public void removeAutoHidePartner (Element partner)

Remove an autoHide partner.

Parameters
partner the auto hide partner to remove

public void removePopupListener (PopupListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by addCloseHandler(CloseHandler) instead

Removes a previously added popup listener.

Parameters
listener the listener interface to remove.

public void setAnimationEnabled (boolean enable)

Enable or disable animations.

Parameters
enable true to enable, false to disable

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

public void setAutoHideOnHistoryEventsEnabled (boolean enabled)

Enable or disable autoHide on history change events. When enabled, the popup will be automatically hidden when the history token changes, such as when the user presses the browser's back button. Disabled by default.

Parameters
enabled true to enable, false to disable

public void setGlassEnabled (boolean enabled)

When enabled, the background will be blocked with a semi-transparent pane the next time it is shown. If the PopupPanel is already visible, the glass will not be displayed until it is hidden and shown again.

Parameters
enabled true to enable, false to disable

public void setGlassStyleName (String glassStyleName)

Sets the style name to be used on the glass element. By default, this is "gwt-PopupPanelGlass".

Parameters
glassStyleName the glass element's style name

public void setHeight (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.

Parameters
height the object's new height, in CSS units (e.g. "10px", "1em")

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

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

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

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

public void setTitle (String title)

Sets the title associated with this object. The title is the 'tool-tip' displayed to users when they hover over the object.

Parameters
title the object's new title

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.

Parameters
visible true to show the object, false to hide it
See Also

public void setWidget (Widget w)

Sets this panel's widget. Any existing child widget will be removed.

Parameters
w the panel's new widget, or null to clear the panel

public void setWidth (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.

Parameters
width the object's new width, in CSS units (e.g. "10px", "1em")

public void show ()

Shows the popup and attach it to the page. It must have a child widget before this method is called.

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

Protected Methods

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

Returns
  • the element to be used as the panel's container

protected Element getGlassElement ()

Get the glass element used by this PopupPanel. The element is not created until it is enabled via setGlassEnabled(boolean).

Returns
  • the glass element, or null if not created

protected Element getStyleElement ()

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.

Returns
  • the element to which style names will be applied

protected void onPreviewNativeEvent (Event.NativePreviewEvent event)

protected void onUnload ()

This method is called immediately before a widget will be detached from the browser's document.