Package com.google.gwt.user.client.ui

Class PopupPanel

  • All Implemented Interfaces:
    HasAttachHandlers, HasCloseHandlers<PopupPanel>, HasHandlers, EventListener, EventPreview, AcceptsOneWidget, HasAnimation, HasOneWidget, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IsWidget, SourcesPopupEvents, java.lang.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

    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
    .gwt-PopupPanelGlass
    the glass background behind the popup

    • 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

      • 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 java.lang.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 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()
        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)

      • 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

      • 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​(java.lang.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​(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

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

      • 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

      • 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

      • maybeUpdateSize

        void maybeUpdateSize()
        We control size by setting our child widget's size. However, if we don't currently have a child, we record the size the user wanted so that when we do get a child, we can set it correctly. Until size is explicitly cleared, any child put into the popup will be given that size.

      • setAnimation

        void setAnimation​(PopupPanel.ResizeAnimation animation)
        Sets the animation used to animate this popup. Used by gwt-incubator to allow DropDownPanel to override the default popup animation. Not protected because the exact API may change in gwt 1.6.
        Parameters:
        animation - the animation to use for this popup