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:

HasAttachHandlers, HasCloseHandlers<PopupPanel>, HasHandlers, EventListener, EventPreview, AcceptsOneWidget, HasAnimation, HasOneWidget, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IsWidget, SourcesPopupEvents, Iterable<Widget>

Direct Known Subclasses:

DecoratedPopupPanel, LoggingPopup

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.

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

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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

Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasWidgets

HasWidgets.ForIsWidget

Field Summary

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

DEBUG_ID_PREFIX

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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<com.google.gwt.user.client.ui.PopupPanel>) 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.
protected Element	getGlassElement() Get the glass element used by this PopupPanel.
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.
protected Element	getStyleElement() Template method that returns the element to which style names will be applied.
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) Deprecated. Use onPreviewNativeEvent(com.google.gwt.user.client.Event.NativePreviewEvent) instead
boolean	onKeyDownPreview(char key, int modifiers) Deprecated. Use onPreviewNativeEvent(com.google.gwt.user.client.Event.NativePreviewEvent) instead
boolean	onKeyPressPreview(char key, int modifiers) Deprecated. Use onPreviewNativeEvent(com.google.gwt.user.client.Event.NativePreviewEvent) instead
boolean	onKeyUpPreview(char key, int modifiers) Deprecated. Use onPreviewNativeEvent(com.google.gwt.user.client.Event.NativePreviewEvent) instead
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.
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<com.google.gwt.user.client.ui.PopupPanel>) 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.
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, setWidget

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

add, adopt, clear, doAttachChildren, doDetachChildren, orphan, remove

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

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, fireEvent, getHandlerCount, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onBrowserEvent, onDetach, onLoad, removeFromParent, setLayoutData, sinkEvents, unsinkEvents

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, resolvePotentialElement, setElement, setElement, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setVisible, sinkBitlessEvent, toString

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode

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

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

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<com.google.gwt.user.client.ui.PopupPanel>) 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.

getGlassStyleName

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

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 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()

Description copied from interface: HasAnimation

Returns true if animations are enabled, false if not.

Specified by:

isAnimationEnabled in interface HasAnimation

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

isAutoHideOnHistoryEventsEnabled

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

isGlassEnabled

public boolean isGlassEnabled()

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

Returns:

true if enabled

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.

Specified by:

isVisible in interface HasVisibility

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(com.google.gwt.user.client.Event.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(com.google.gwt.user.client.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

onKeyPressPreview

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

Deprecated. Use onPreviewNativeEvent(com.google.gwt.user.client.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

onKeyUpPreview

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

Deprecated. Use onPreviewNativeEvent(com.google.gwt.user.client.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

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<com.google.gwt.user.client.ui.PopupPanel>) 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

setAutoHideOnHistoryEventsEnabled

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

setGlassEnabled

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

setGlassStyleName

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

setHeight

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.

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

Specified by:

setVisible in interface HasVisibility

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.

Specified by:

setWidget in interface HasOneWidget

Overrides:

setWidget in class SimplePanel

Parameters:

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

setWidth

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.

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

getGlassElement

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

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: Widget

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

Overrides:

onUnload in class Widget