Package icyllis.modernui.widget

Class PopupWindow

java.lang.Object
icyllis.modernui.widget.PopupWindow
public class PopupWindow extends Object

This class represents a popup window that can be used to display an arbitrary view. The popup window is a floating container that appears on top of the current application window.

Animation

Popup window enter and exit transitions may be specified by calling either setEnterTransition(Transition) or setExitTransition(Transition) and passing a Transition.

This is a modified version from Android. Modern UI implementations require the root view must be a WindowGroup for its behavior to intercept input events. We don't need its anchoring feature, because it will calculate all transformation matrices. Firstly, the performance is slightly lower, and we don't want the position of pop-up window to change too frequently.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    PopupWindow.OnDismissListener
    Listener that is called when this popup window is dismissed.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PopupWindow()
    Create a new empty, non focusable popup window of dimension (0,0).
    PopupWindow(int width, int height)
    Create a new empty, non focusable popup window.
    PopupWindow(View contentView)
    Create a new non focusable popup window which can display the contentView.
    PopupWindow(View contentView, int width, int height)
    Create a new non focusable popup window which can display the contentView.
    PopupWindow(View contentView, int width, int height, boolean focusable)
    Create a new popup window which can display the contentView.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dismiss()
    Disposes of the popup window.
    protected View
    getAnchor()
     
    Drawable
    getBackground()
    Return the drawable used as the popup window's background.
    View
    getContentView()
    Return the view used as the content of the popup window.
    protected WindowManager.LayoutParams
    getDecorViewLayoutParams()
     
    float
    getElevation()
     
    Transition
    getEnterTransition()
    Returns the enter transition to be used when the popup window is shown.
    Rect
    getEpicenterBounds()
    Returns bounds which are used as a center of the enter and exit transitions.
    Transition
    getExitTransition()
    Returns the exit transition to be used when the popup window is dismissed.
    int
    getHeight()
    Returns the popup's requested height.
    int
    getMaxAvailableHeight(View anchor)
    Returns the maximum height that is available for the popup to be completely shown.
    int
    getMaxAvailableHeight(View anchor, int yOffset)
    Returns the maximum height that is available for the popup to be completely shown.
    protected final PopupWindow.OnDismissListener
    getOnDismissListener()
     
    boolean
    getOverlapAnchor()
    Returns whether the popup window should overlap its anchor view when displayed as a drop-down.
    protected final Rect
    getTransitionEpicenter()
    Returns the window-relative epicenter bounds to be used by enter and exit transitions.
    int
    getWidth()
    Returns the popup's requested width.
    int
    getWindowLayoutType()
    Returns the layout type for this window.
    protected boolean
    hasContentView()
     
    protected boolean
    hasDecorView()
     
    boolean
    isAboveAnchor()
    Indicates whether the popup is showing above (the y coordinate of the popup's bottom is less than the y coordinate of the anchor) or below the anchor view (the y coordinate of the popup is greater than y coordinate of the anchor's bottom).
    boolean
    isClippedToScreen()
    Indicates whether this popup will be clipped to the screen and not to the containing window
    boolean
    isClippingEnabled()
    Indicates whether clipping of the popup window is enabled.
    boolean
    isFocusable()
    Indicate whether the popup window can grab the focus.
    boolean
    isOutsideTouchable()
    Indicates whether the popup window will be informed of touch events outside of its window.
    boolean
    isShowing()
    Indicate whether this popup window is showing on screen.
    boolean
    isTouchable()
    Indicates whether the popup window receives touch events.
    boolean
    isTouchModal()
    Indicates whether outside touches will be sent to this window or other windows behind it
    void
    setBackgroundDrawable(Drawable background)
    Specifies the background drawable for this popup window.
    void
    setClippingEnabled(boolean enabled)
    Allows the popup window to extend beyond the bounds of the screen.
    void
    setContentView(View contentView)
    Change the popup's content.
    void
    setElevation(float elevation)
    Specifies the elevation for this popup window.
    void
    setEnterTransition(Transition enterTransition)
    Sets the enter transition to be used when the popup window is shown.
    void
    setEpicenterBounds(Rect bounds)
    Sets the bounds used as the epicenter of the enter and exit transitions.
    void
    setExitTransition(Transition exitTransition)
    Sets the exit transition to be used when the popup window is dismissed.
    void
    setFocusable(boolean focusable)
    Changes the focusability of the popup window.
    void
    setHeight(int height)
    Sets the popup's requested height.
    void
    setIsClippedToScreen(boolean enabled)
    Clip this popup window to the screen, but not to the containing window.
    void
    setOnDismissListener(PopupWindow.OnDismissListener onDismissListener)
    Sets the listener to be called when the window is dismissed.
    void
    setOutsideTouchable(boolean touchable)
    Controls whether the pop-up will be informed of touch events outside of its window.
    void
    setOverlapAnchor(boolean overlapAnchor)
    Sets whether the popup window should overlap its anchor view when displayed as a drop-down.
    void
    setTouchable(boolean touchable)
    Changes the touchability of the popup window.
    void
    setTouchInterceptor(View.OnTouchListener l)
    Set a callback for all touch events being dispatched to the popup window.
    void
    setTouchModal(boolean touchModal)
    Set whether this window is touch modal or if outside touches will be sent to other windows behind it.
    void
    setWidth(int width)
    Sets the popup's requested width.
    void
    setWindowLayoutType(int layoutType)
    Set the layout type for this window.
    final void
    showAsDropDown(View anchor)
    Display the content view in a popup window anchored to the bottom-left corner of the anchor view.
    final void
    showAsDropDown(View anchor, int xOff, int yOff)
    Display the content view in a popup window anchored to the bottom-left corner of the anchor view offset by the specified x and y coordinates.
    void
    showAsDropDown(View anchor, int xOff, int yOff, int gravity)
    Displays the content view in a popup window anchored to the corner of another view.
    void
    showAtLocation(View parent, int gravity, int x, int y)
    Display the content view in a popup window at the specified location.
    void
    update()
    Updates the state of the popup window, if it is currently being displayed, from the currently set state.
    void
    update(int width, int height)
    Updates the dimension of the popup window.
    void
    update(int x, int y, int width, int height)
    Updates the position and the dimension of the popup window.
    void
    update(int x, int y, int width, int height, boolean force)
    Updates the position and the dimension of the popup window.
    void
    update(View anchor, int width, int height)
    Updates the position and the dimension of the popup window.
    void
    update(View anchor, int xoff, int yoff, int width, int height)
    Updates the position and the dimension of the popup window.
    protected void
    update(View anchor, ViewGroup.LayoutParams params)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • PopupWindow

      public PopupWindow()

      Create a new empty, non focusable popup window of dimension (0,0).

      The popup does not provide any background. This should be handled by the content view.

    • PopupWindow

      public PopupWindow(View contentView)

      Create a new non focusable popup window which can display the contentView. The dimension of the window are (0,0).

      The popup does not provide any background. This should be handled by the content view.

      Parameters:
      contentView - the popup's content

    • PopupWindow

      public PopupWindow(int width, int height)

      Create a new empty, non focusable popup window. The dimension of the window must be passed to this constructor.

      The popup does not provide any background. This should be handled by the content view.

      Parameters:
      width - the popup's width
      height - the popup's height

    • PopupWindow

      public PopupWindow(View contentView, int width, int height)

      Create a new non focusable popup window which can display the contentView. The dimension of the window must be passed to this constructor.

      The popup does not provide any background. This should be handled by the content view.

      Parameters:
      contentView - the popup's content
      width - the popup's width
      height - the popup's height

    • PopupWindow

      public PopupWindow(View contentView, int width, int height, boolean focusable)

      Create a new popup window which can display the contentView. The dimension of the window must be passed to this constructor.

      The popup does not provide any background. This should be handled by the content view.

      Parameters:
      contentView - the popup's content
      width - the popup's width
      height - the popup's height
      focusable - true if the popup can be focused, false otherwise

  • Method Details

    • setEnterTransition

      public void setEnterTransition(@Nullable Transition enterTransition)
      Sets the enter transition to be used when the popup window is shown.
      Parameters:
      enterTransition - the enter transition, or null to clear
      See Also:

    • getEnterTransition

      @Nullable public Transition getEnterTransition()
      Returns the enter transition to be used when the popup window is shown.
      Returns:
      the enter transition, or null if not set
      See Also:

    • setExitTransition

      public void setExitTransition(@Nullable Transition exitTransition)
      Sets the exit transition to be used when the popup window is dismissed.
      Parameters:
      exitTransition - the exit transition, or null to clear
      See Also:

    • getExitTransition

      @Nullable public Transition getExitTransition()
      Returns the exit transition to be used when the popup window is dismissed.
      Returns:
      the exit transition, or null if not set
      See Also:

    • getEpicenterBounds

      @Nullable public Rect getEpicenterBounds()

      Returns bounds which are used as a center of the enter and exit transitions.

      Transitions use Rect, referred to as the epicenter, to orient the direction of travel. For popup windows, the anchor view bounds are used as the default epicenter.

      See Transition.setEpicenterCallback(Transition.EpicenterCallback) for more information about how transition epicenters work.

      Returns:
      bounds relative to anchor view, or null if not set
      See Also:

    • setEpicenterBounds

      public void setEpicenterBounds(@Nullable Rect bounds)

      Sets the bounds used as the epicenter of the enter and exit transitions.

      Transitions use Rect, referred to as the epicenter, to orient the direction of travel. For popup windows, the anchor view bounds are used as the default epicenter.

      See Transition.setEpicenterCallback(Transition.EpicenterCallback) for more information about how transition epicenters work.

      Parameters:
      bounds - the epicenter bounds relative to the anchor view, or null to use the default epicenter
      See Also:

    • getBackground

      @Nullable public Drawable getBackground()
      Return the drawable used as the popup window's background.
      Returns:
      the background drawable or null if not set
      See Also:

    • setBackgroundDrawable

      public void setBackgroundDrawable(@Nullable Drawable background)
      Specifies the background drawable for this popup window. The background can be set to null.
      Parameters:
      background - the popup's background
      See Also:

    • getElevation

      public float getElevation()
      Returns:
      the elevation for this popup window in pixels
      See Also:

    • setElevation

      public void setElevation(float elevation)
      Specifies the elevation for this popup window.
      Parameters:
      elevation - the popup's elevation in pixels
      See Also:

    • getContentView

      public View getContentView()

      Return the view used as the content of the popup window.

      Returns:
      a View representing the popup's content
      See Also:

    • setContentView

      public void setContentView(View contentView)

      Change the popup's content. The content is represented by an instance of View.

      This method has no effect if called when the popup is showing.

      Parameters:
      contentView - the new content for the popup
      See Also:

    • setTouchInterceptor

      public void setTouchInterceptor(@Nullable View.OnTouchListener l)
      Set a callback for all touch events being dispatched to the popup window.

    • isFocusable

      public boolean isFocusable()

      Indicate whether the popup window can grab the focus.

      Returns:
      true if the popup is focusable, false otherwise
      See Also:

    • setFocusable

      public void setFocusable(boolean focusable)

      Changes the focusability of the popup window. When focusable, the window will grab the focus from the current focused widget if the popup contains a focusable View. By default a popup window is not focusable.

      If the popup is showing, calling this method will take effect only the next time the popup is shown or through a manual call to one of the update() methods.

      Parameters:
      focusable - true if the popup should grab focus, false otherwise.
      See Also:

    • isTouchable

      public boolean isTouchable()

      Indicates whether the popup window receives touch events.

      Returns:
      true if the popup is touchable, false otherwise
      See Also:

    • setTouchable

      public void setTouchable(boolean touchable)

      Changes the touchability of the popup window. When touchable, the window will receive touch events, otherwise touch events will go to the window below it. By default the window is touchable.

      If the popup is showing, calling this method will take effect only the next time the popup is shown or through a manual call to one of the update() methods.

      Parameters:
      touchable - true if the popup should receive touch events, false otherwise
      See Also:

    • isOutsideTouchable

      public boolean isOutsideTouchable()

      Indicates whether the popup window will be informed of touch events outside of its window.

      Returns:
      true if the popup is outside touchable, false otherwise
      See Also:

    • setOutsideTouchable

      public void setOutsideTouchable(boolean touchable)

      Controls whether the pop-up will be informed of touch events outside of its window. This only makes sense for pop-ups that are touchable but not focusable, which means touches outside of the window will be delivered to the window behind. The default is false.

      If the popup is showing, calling this method will take effect only the next time the popup is shown or through a manual call to one of the update() methods.

      Parameters:
      touchable - true if the popup should receive outside touch events, false otherwise
      See Also:

    • isClippingEnabled

      public boolean isClippingEnabled()

      Indicates whether clipping of the popup window is enabled.

      Returns:
      true if the clipping is enabled, false otherwise
      See Also:

    • setClippingEnabled

      public void setClippingEnabled(boolean enabled)

      Allows the popup window to extend beyond the bounds of the screen. By default the window is clipped to the screen boundaries. Setting this to false will allow windows to be accurately positioned.

      If the popup is showing, calling this method will take effect only the next time the popup is shown or through a manual call to one of the update() methods.

      Parameters:
      enabled - false if the window should be allowed to extend outside of the screen
      See Also:

    • isClippedToScreen

      public boolean isClippedToScreen()

      Indicates whether this popup will be clipped to the screen and not to the containing window

      Returns:
      true if popup will be clipped to the screen instead of the window, false otherwise
      See Also:

    • setIsClippedToScreen

      public void setIsClippedToScreen(boolean enabled)

      Clip this popup window to the screen, but not to the containing window.

      If the popup is showing, calling this method will take effect only the next time the popup is shown or through a manual call to one of the update() methods.

      Parameters:
      enabled - true to clip to the screen.
      See Also:

    • setWindowLayoutType

      public void setWindowLayoutType(int layoutType)
      Set the layout type for this window.

      See Window for possible values.

      Parameters:
      layoutType - Layout type for this window.
      See Also:

    • getWindowLayoutType

      public int getWindowLayoutType()
      Returns the layout type for this window.
      See Also:

    • isTouchModal

      public boolean isTouchModal()

      Indicates whether outside touches will be sent to this window or other windows behind it

      Returns:
      true if touches will be sent to this window, false otherwise
      See Also:

    • setTouchModal

      public void setTouchModal(boolean touchModal)

      Set whether this window is touch modal or if outside touches will be sent to other windows behind it.

      If the popup is showing, calling this method will take effect only the next time the popup is shown or through a manual call to one of the update() methods.

      Parameters:
      touchModal - true to send all outside touches to this window, false to other windows behind it
      See Also:

    • getHeight

      public int getHeight()
      Returns the popup's requested height. May be a layout constant such as ViewGroup.LayoutParams.WRAP_CONTENT or ViewGroup.LayoutParams.MATCH_PARENT.

      The actual size of the popup may depend on other factors such as clipping and window layout.

      Returns:
      the popup height in pixels or a layout constant
      See Also:

    • setHeight

      public void setHeight(int height)
      Sets the popup's requested height. May be a layout constant such as ViewGroup.LayoutParams.WRAP_CONTENT or ViewGroup.LayoutParams.MATCH_PARENT.

      The actual size of the popup may depend on other factors such as clipping and window layout.

      If the popup is showing, calling this method will take effect the next time the popup is shown.

      Parameters:
      height - the popup height in pixels or a layout constant
      See Also:

    • getWidth

      public int getWidth()
      Returns the popup's requested width. May be a layout constant such as ViewGroup.LayoutParams.WRAP_CONTENT or ViewGroup.LayoutParams.MATCH_PARENT.

      The actual size of the popup may depend on other factors such as clipping and window layout.

      Returns:
      the popup width in pixels or a layout constant
      See Also:

    • setWidth

      public void setWidth(int width)
      Sets the popup's requested width. May be a layout constant such as ViewGroup.LayoutParams.WRAP_CONTENT or ViewGroup.LayoutParams.MATCH_PARENT.

      The actual size of the popup may depend on other factors such as clipping and window layout.

      If the popup is showing, calling this method will take effect the next time the popup is shown.

      Parameters:
      width - the popup width in pixels or a layout constant
      See Also:

    • setOverlapAnchor

      public void setOverlapAnchor(boolean overlapAnchor)
      Sets whether the popup window should overlap its anchor view when displayed as a drop-down.

      If the popup is showing, calling this method will take effect only the next time the popup is shown.

      Parameters:
      overlapAnchor - Whether the popup should overlap its anchor.
      See Also:

    • getOverlapAnchor

      public boolean getOverlapAnchor()
      Returns whether the popup window should overlap its anchor view when displayed as a drop-down.
      Returns:
      Whether the popup should overlap its anchor.
      See Also:

    • isShowing

      public boolean isShowing()

      Indicate whether this popup window is showing on screen.

      Returns:
      true if the popup is showing, false otherwise

    • showAtLocation

      public void showAtLocation(@Nonnull View parent, int gravity, int x, int y)

      Display the content view in a popup window at the specified location. If the popup window cannot fit on screen, it will be clipped. Specifying a gravity of Gravity.NO_GRAVITY is similar to specifying Gravity.LEFT | Gravity.TOP.

      Parameters:
      parent - a parent view to get the window
      gravity - the gravity which controls the placement of the popup window
      x - the popup's x location offset
      y - the popup's y location offset

    • showAsDropDown

      public final void showAsDropDown(@Nonnull View anchor)
      Display the content view in a popup window anchored to the bottom-left corner of the anchor view. If there is not enough room on screen to show the popup in its entirety, this method tries to find a parent scroll view to scroll. If no parent scroll view can be scrolled, the bottom-left corner of the popup is pinned in the top left corner of the anchor view.
      Parameters:
      anchor - the view on which to pin the popup window
      See Also:

    • showAsDropDown

      public final void showAsDropDown(@Nonnull View anchor, int xOff, int yOff)
      Display the content view in a popup window anchored to the bottom-left corner of the anchor view offset by the specified x and y coordinates. If there is not enough room on screen to show the popup in its entirety, this method tries to find a parent scroll view to scroll. If no parent scroll view can be scrolled, the bottom-left corner of the popup is pinned in the top left corner of the anchor view.

      If the view later scrolls to move anchor to a different location, the popup will be moved correspondingly.

      Parameters:
      anchor - the view on which to pin the popup window
      xOff - A horizontal offset from the anchor in pixels
      yOff - A vertical offset from the anchor in pixels
      See Also:

    • showAsDropDown

      public void showAsDropDown(@Nonnull View anchor, int xOff, int yOff, int gravity)
      Displays the content view in a popup window anchored to the corner of another view. The window is positioned according to the specified gravity and offset by the specified x and y coordinates.

      If there is not enough room on screen to show the popup in its entirety, this method tries to find a parent scroll view to scroll. If no parent view can be scrolled, the specified vertical gravity will be ignored and the popup will anchor itself such that it is visible.

      If the view later scrolls to move anchor to a different location, the popup will be moved correspondingly.

      Parameters:
      anchor - the view on which to pin the popup window
      xOff - A horizontal offset from the anchor in pixels
      yOff - A vertical offset from the anchor in pixels
      gravity - Alignment of the popup relative to the anchor
      See Also:

    • isAboveAnchor

      public boolean isAboveAnchor()
      Indicates whether the popup is showing above (the y coordinate of the popup's bottom is less than the y coordinate of the anchor) or below the anchor view (the y coordinate of the popup is greater than y coordinate of the anchor's bottom).

      The value returned by this method is meaningful only after showAsDropDown(View) or showAsDropDown(View, int, int) was invoked.

      Returns:
      True if this popup is showing above the anchor view, false otherwise.

    • getMaxAvailableHeight

      public int getMaxAvailableHeight(@Nonnull View anchor)
      Returns the maximum height that is available for the popup to be completely shown. It is recommended that this height be the maximum for the popup's height, otherwise it is possible that the popup will be clipped.
      Parameters:
      anchor - The view on which the popup window must be anchored.
      Returns:
      The maximum available height for the popup to be completely shown.

    • getMaxAvailableHeight

      public int getMaxAvailableHeight(@Nonnull View anchor, int yOffset)
      Returns the maximum height that is available for the popup to be completely shown. It is recommended that this height be the maximum for the popup's height, otherwise it is possible that the popup will be clipped.
      Parameters:
      anchor - The view on which the popup window must be anchored.
      yOffset - y offset from the view's bottom edge
      Returns:
      The maximum available height for the popup to be completely shown.

    • dismiss

      public void dismiss()
      Disposes of the popup window. This method can be invoked only after showAsDropDown(View) has been executed. Failing that, calling this method will have no effect.
      See Also:

    • getTransitionEpicenter

      @Nullable protected final Rect getTransitionEpicenter()
      Returns the window-relative epicenter bounds to be used by enter and exit transitions.

      Note: This is distinct from the rect passed to setEpicenterBounds(Rect), which is anchor-relative.

      Returns:
      the window-relative epicenter bounds to be used by enter and exit transitions

    • setOnDismissListener

      public void setOnDismissListener(PopupWindow.OnDismissListener onDismissListener)
      Sets the listener to be called when the window is dismissed.
      Parameters:
      onDismissListener - The listener.

    • getOnDismissListener

      protected final PopupWindow.OnDismissListener getOnDismissListener()

    • update

      public void update()
      Updates the state of the popup window, if it is currently being displayed, from the currently set state.

      This includes:

    • update

      protected void update(View anchor, ViewGroup.LayoutParams params)

    • update

      public void update(int width, int height)
      Updates the dimension of the popup window.

      Calling this function also updates the window with the current popup state as described for update().

      Parameters:
      width - the new width in pixels, must be >= 0 or -1 to ignore
      height - the new height in pixels, must be >= 0 or -1 to ignore

    • update

      public void update(int x, int y, int width, int height)
      Updates the position and the dimension of the popup window.

      Width and height can be set to -1 to update location only. Calling this function also updates the window with the current popup state as described for update().

      Parameters:
      x - the new x location
      y - the new y location
      width - the new width in pixels, must be >= 0 or -1 to ignore
      height - the new height in pixels, must be >= 0 or -1 to ignore

    • update

      public void update(int x, int y, int width, int height, boolean force)
      Updates the position and the dimension of the popup window.

      Width and height can be set to -1 to update location only. Calling this function also updates the window with the current popup state as described for update().

      Parameters:
      x - the new x location
      y - the new y location
      width - the new width in pixels, must be >= 0 or -1 to ignore
      height - the new height in pixels, must be >= 0 or -1 to ignore
      force - true to reposition the window even if the specified position already seems to correspond to the LayoutParams, false to only reposition if needed

    • hasContentView

      protected boolean hasContentView()

    • hasDecorView

      protected boolean hasDecorView()

    • getDecorViewLayoutParams

      protected WindowManager.LayoutParams getDecorViewLayoutParams()

    • update

      public void update(View anchor, int width, int height)
      Updates the position and the dimension of the popup window.

      Calling this function also updates the window with the current popup state as described for update().

      Parameters:
      anchor - the popup's anchor view
      width - the new width in pixels, must be >= 0 or -1 to ignore
      height - the new height in pixels, must be >= 0 or -1 to ignore

    • update

      public void update(View anchor, int xoff, int yoff, int width, int height)
      Updates the position and the dimension of the popup window.

      Width and height can be set to -1 to update location only. Calling this function also updates the window with the current popup state as described for update().

      If the view later scrolls to move anchor to a different location, the popup will be moved correspondingly.

      Parameters:
      anchor - the popup's anchor view
      xoff - x offset from the view's left edge
      yoff - y offset from the view's bottom edge
      width - the new width in pixels, must be >= 0 or -1 to ignore
      height - the new height in pixels, must be >= 0 or -1 to ignore

    • getAnchor

      @Nullable protected View getAnchor()