Android APIs
public class

PopupWindow

extends Object
java.lang.Object
   ↳ android.widget.PopupWindow

Class Overview

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

Summary

Nested Classes
interface PopupWindow.OnDismissListener Listener that is called when this popup window is dismissed. 
XML Attributes
Attribute Name Related Method Description
android:popupBackground setBackgroundDrawable(Drawable) The background to use for the popup window. 
android:popupElevation setElevation(float) Window elevation to use for the popup window. 
Constants
int INPUT_METHOD_FROM_FOCUSABLE Mode for setInputMethodMode(int): the requirements for the input method should be based on the focusability of the popup.
int INPUT_METHOD_NEEDED Mode for setInputMethodMode(int): this popup always needs to work with an input method, regardless of whether it is focusable.
int INPUT_METHOD_NOT_NEEDED Mode for setInputMethodMode(int): this popup never needs to work with an input method, regardless of whether it is focusable.
Public Constructors
PopupWindow(Context context)

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

PopupWindow(Context context, AttributeSet attrs)

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

PopupWindow(Context context, AttributeSet attrs, int defStyleAttr)

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

PopupWindow(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

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

PopupWindow()

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

PopupWindow(View contentView)

Create a new non focusable popup window which can display the contentView.

PopupWindow(int width, int height)

Create a new empty, non focusable popup window.

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.

Public Methods
void dismiss()
Disposes of the popup window.
int getAnimationStyle()

Return the animation style to use the popup appears and disappears

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.

float getElevation()
int getHeight()
Returns the popup's height MeasureSpec.
int getInputMethodMode()
Return the current value in setInputMethodMode(int).
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.
boolean getOverlapAnchor()
Returns whether the popup window should overlap its anchor view when displayed as a drop-down.
int getSoftInputMode()
Returns the current value in setSoftInputMode(int).
int getWidth()
Returns the popup's width MeasureSpec.
int getWindowLayoutType()
Returns the layout type for this window.
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 isAttachedInDecor()

Indicates whether the popup window will be attached in the decor frame of its parent 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 isSplitTouchEnabled()

Indicates whether the popup window supports splitting touches.

boolean isTouchable()

Indicates whether the popup window receives touch events.

void setAnimationStyle(int animationStyle)

Change the animation style resource for this popup.

void setAttachedInDecor(boolean enabled)

This will attach the popup window to the decor frame of the parent window to avoid overlaping with screen decorations like the navigation bar.

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)
void setExitTransition(Transition exitTransition)
void setFocusable(boolean focusable)

Changes the focusability of the popup window.

void setHeight(int height)
Sets the popup's height MeasureSpec.
void setIgnoreCheekPress()
Set the flag on popup to ignore cheek press events; by default this flag is set to false which means the popup will not ignore cheek press dispatch events.
void setInputMethodMode(int mode)
Control how the popup operates with an input method: one of INPUT_METHOD_FROM_FOCUSABLE, INPUT_METHOD_NEEDED, or INPUT_METHOD_NOT_NEEDED.
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 setSoftInputMode(int mode)
Sets the operating mode for the soft input area.
void setSplitTouchEnabled(boolean enabled)

Allows the popup window to split touches across other windows that also support split touch.

void setTouchInterceptor(View.OnTouchListener l)
Set a callback for all touch events being dispatched to the popup window.
void setTouchable(boolean touchable)

Changes the touchability of the popup window.

void setWidth(int width)
Sets the popup's width MeasureSpec.
void setWindowLayoutMode(int widthSpec, int heightSpec)
This method was deprecated in API level 23. Use setWidth(int) and setHeight(int).
void setWindowLayoutType(int layoutType)
Set the layout type for this window.
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 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)
Display the content view in a popup window anchored to the bottom-left corner of the anchor 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(View anchor, int width, int height)
Updates the position and 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(View anchor, int xoff, int yoff, int width, int height)
Updates the position and the dimension of the popup window.
void update()
Updates the state of the popup window, if it is currently being displayed, from the currently set state.
void update(int x, int y, int width, int height, boolean force)
Updates the position and the dimension of the popup window.
void update(int width, int height)
Updates the dimension of the popup window.
[Expand]
Inherited Methods
From class java.lang.Object

XML Attributes

android:popupBackground

The background to use for the popup window.

May be a reference to another resource, in the form "@[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name".

May be a color value, in the form of "#rgb", "#argb", "#rrggbb", or "#aarrggbb".

This corresponds to the global attribute resource symbol popupBackground.

android:popupElevation

Window elevation to use for the popup window.

Must be a dimension value, which is a floating point number appended with a unit such as "14.5sp". Available units are: px (pixels), dp (density-independent pixels), sp (scaled pixels based on preferred font size), in (inches), mm (millimeters).

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol popupElevation.

Related Methods

Constants

public static final int INPUT_METHOD_FROM_FOCUSABLE

Added in API level 3

Mode for setInputMethodMode(int): the requirements for the input method should be based on the focusability of the popup. That is if it is focusable than it needs to work with the input method, else it doesn't.

Constant Value: 0 (0x00000000)

public static final int INPUT_METHOD_NEEDED

Added in API level 3

Mode for setInputMethodMode(int): this popup always needs to work with an input method, regardless of whether it is focusable. This means that it will always be displayed so that the user can also operate the input method while it is shown.

Constant Value: 1 (0x00000001)

public static final int INPUT_METHOD_NOT_NEEDED

Added in API level 3

Mode for setInputMethodMode(int): this popup never needs to work with an input method, regardless of whether it is focusable. This means that it will always be displayed to use as much space on the screen as needed, regardless of whether this covers the input method.

Constant Value: 2 (0x00000002)

Public Constructors

public PopupWindow (Context context)

Added in API level 1

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

The popup does provide a background.

public PopupWindow (Context context, AttributeSet attrs)

Added in API level 1

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

The popup does provide a background.

public PopupWindow (Context context, AttributeSet attrs, int defStyleAttr)

Added in API level 1

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

The popup does provide a background.

public PopupWindow (Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Added in API level 11

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

The popup does not provide a background.

public PopupWindow ()

Added in API level 1

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.

public PopupWindow (View contentView)

Added in API level 1

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

public PopupWindow (int width, int height)

Added in API level 1

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

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

Added in API level 1

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

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

Added in API level 1

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

Public Methods

public void dismiss ()

Added in API level 1

Disposes of the popup window. This method can be invoked only after showAsDropDown(android.view.View) has been executed. Failing that, calling this method will have no effect.

public int getAnimationStyle ()

Added in API level 1

Return the animation style to use the popup appears and disappears

Returns
  • the animation style to use the popup appears and disappears

public Drawable getBackground ()

Added in API level 1

Return the drawable used as the popup window's background.

Related XML Attributes
Returns
  • the background drawable or null if not set

public View getContentView ()

Added in API level 1

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

Returns
  • a View representing the popup's content

public float getElevation ()

Added in API level 21

Related XML Attributes
Returns
  • the elevation for this popup window in pixels

public int getHeight ()

Added in API level 1

Returns the popup's height MeasureSpec.

Returns
  • the height MeasureSpec of the popup
See Also

public int getInputMethodMode ()

Added in API level 3

Return the current value in setInputMethodMode(int).

public int getMaxAvailableHeight (View anchor)

Added in API level 1

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.

public int getMaxAvailableHeight (View anchor, int yOffset)

Added in API level 3

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.

public boolean getOverlapAnchor ()

Added in API level 23

Returns whether the popup window should overlap its anchor view when displayed as a drop-down.

Returns
  • Whether the popup should overlap its anchor.

public int getSoftInputMode ()

Added in API level 4

Returns the current value in setSoftInputMode(int).

public int getWidth ()

Added in API level 1

Returns the popup's width MeasureSpec.

Returns
  • the width MeasureSpec of the popup
See Also

public int getWindowLayoutType ()

Added in API level 23

Returns the layout type for this window.

public boolean isAboveAnchor ()

Added in API level 3

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(android.view.View) or showAsDropDown(android.view.View, int, int) was invoked.

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

public boolean isAttachedInDecor ()

Added in API level 22

Indicates whether the popup window will be attached in the decor frame of its parent window.

Returns
  • true if the window will be attached to the decor frame of its parent window.

public boolean isClippingEnabled ()

Added in API level 3

Indicates whether clipping of the popup window is enabled.

Returns
  • true if the clipping is enabled, false otherwise

public boolean isFocusable ()

Added in API level 1

Indicate whether the popup window can grab the focus.

Returns
  • true if the popup is focusable, false otherwise

public boolean isOutsideTouchable ()

Added in API level 3

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

public boolean isShowing ()

Added in API level 1

Indicate whether this popup window is showing on screen.

Returns
  • true if the popup is showing, false otherwise

public boolean isSplitTouchEnabled ()

Added in API level 11

Indicates whether the popup window supports splitting touches.

Returns
  • true if the touch splitting is enabled, false otherwise

public boolean isTouchable ()

Added in API level 3

Indicates whether the popup window receives touch events.

Returns
  • true if the popup is touchable, false otherwise

public void setAnimationStyle (int animationStyle)

Added in API level 1

Change the animation style resource for this popup.

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
animationStyle animation style to use when the popup appears and disappears. Set to -1 for the default animation, 0 for no animation, or a resource identifier for an explicit animation.
See Also

public void setAttachedInDecor (boolean enabled)

Added in API level 22

This will attach the popup window to the decor frame of the parent window to avoid overlaping with screen decorations like the navigation bar. Overrides the default behavior of the flag FLAG_LAYOUT_ATTACHED_IN_DECOR.

By default the flag is set on SDK version LOLLIPOP_MR1 or greater and cleared on lesser SDK versions.

Parameters
enabled true if the popup should be attached to the decor frame of its parent window.

public void setBackgroundDrawable (Drawable background)

Added in API level 1

Specifies the background drawable for this popup window. The background can be set to null.

Related XML Attributes
Parameters
background the popup's background
See Also

public void setClippingEnabled (boolean enabled)

Added in API level 3

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

public void setContentView (View contentView)

Added in API level 1

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

public void setElevation (float elevation)

Added in API level 21

Specifies the elevation for this popup window.

Related XML Attributes
Parameters
elevation the popup's elevation in pixels
See Also

public void setEnterTransition (Transition enterTransition)

Added in API level 23

public void setExitTransition (Transition exitTransition)

Added in API level 23

public void setFocusable (boolean focusable)

Added in API level 1

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.

public void setHeight (int height)

Added in API level 1

Sets the popup's height MeasureSpec.

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

Parameters
height the height MeasureSpec of the popup

public void setIgnoreCheekPress ()

Added in API level 1

Set the flag on popup to ignore cheek press events; by default this flag is set to false which means the popup will not ignore cheek press dispatch events.

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.

See Also

public void setInputMethodMode (int mode)

Added in API level 3

Control how the popup operates with an input method: one of INPUT_METHOD_FROM_FOCUSABLE, INPUT_METHOD_NEEDED, or INPUT_METHOD_NOT_NEEDED.

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.

public void setOnDismissListener (PopupWindow.OnDismissListener onDismissListener)

Added in API level 1

Sets the listener to be called when the window is dismissed.

Parameters
onDismissListener The listener.

public void setOutsideTouchable (boolean touchable)

Added in API level 3

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

public void setOverlapAnchor (boolean overlapAnchor)

Added in API level 23

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.

public void setSoftInputMode (int mode)

Added in API level 4

Sets the operating mode for the soft input area.

Parameters
mode The desired mode, see softInputMode for the full list

public void setSplitTouchEnabled (boolean enabled)

Added in API level 11

Allows the popup window to split touches across other windows that also support split touch. When this flag is false, the first pointer that goes down determines the window to which all subsequent touches go until all pointers go up. When this flag is true, each pointer (not necessarily the first) that goes down determines the window to which all subsequent touches of that pointer will go until that pointer goes up thereby enabling touches with multiple pointers to be split across multiple windows.

Parameters
enabled true if the split touches should be enabled, false otherwise

public void setTouchInterceptor (View.OnTouchListener l)

Added in API level 3

Set a callback for all touch events being dispatched to the popup window.

public void setTouchable (boolean touchable)

Added in API level 3

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

public void setWidth (int width)

Added in API level 1

Sets the popup's width MeasureSpec.

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

Parameters
width the width MeasureSpec of the popup

public void setWindowLayoutMode (int widthSpec, int heightSpec)

Added in API level 3

This method was deprecated in API level 23.
Use setWidth(int) and setHeight(int).

Change the width and height measure specs that are given to the window manager by the popup. By default these are 0, meaning that the current width or height is requested as an explicit size from the window manager. You can supply WRAP_CONTENT or MATCH_PARENT to have that measure spec supplied instead, replacing the absolute width and height that has been set in the popup.

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

Parameters
widthSpec an explicit width measure spec mode, either WRAP_CONTENT, MATCH_PARENT, or 0 to use the absolute width.
heightSpec an explicit height measure spec mode, either WRAP_CONTENT, MATCH_PARENT, or 0 to use the absolute height.

public void setWindowLayoutType (int layoutType)

Added in API level 23

Set the layout type for this window.

See type for possible values.

Parameters
layoutType Layout type for this window.
See Also

public void showAsDropDown (View anchor, int xoff, int yoff, int gravity)

Added in API level 19

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

public void showAsDropDown (View anchor, int xoff, int yoff)

Added in API level 1

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

public void showAsDropDown (View anchor)

Added in API level 1

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 at the top left corner of the anchor view.

Parameters
anchor the view on which to pin the popup window
See Also

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

Added in API level 1

Display the content view in a popup window at the specified location. If the popup window cannot fit on screen, it will be clipped. See WindowManager.LayoutParams for more information on how gravity and the x and y parameters are related. Specifying a gravity of NO_GRAVITY is similar to specifying Gravity.LEFT | Gravity.TOP.

Parameters
parent a parent view to get the getWindowToken() token from
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

public void update (View anchor, int width, int height)

Added in API level 1

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, must be >= 0 or -1 to ignore
height the new height, must be >= 0 or -1 to ignore

public void update (int x, int y, int width, int height)

Added in API level 1

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, must be >= 0 or -1 to ignore
height the new height, must be >= 0 or -1 to ignore

public void update (View anchor, int xoff, int yoff, int width, int height)

Added in API level 1

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, must be >= 0 or -1 to ignore
height the new height, must be >= 0 or -1 to ignore

public void update ()

Added in API level 3

Updates the state of the popup window, if it is currently being displayed, from the currently set state.

This includes:

public void update (int x, int y, int width, int height, boolean force)

Added in API level 3

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, must be >= 0 or -1 to ignore
height the new height, 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

public void update (int width, int height)

Added in API level 4

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, must be >= 0 or -1 to ignore
height the new height, must be >= 0 or -1 to ignore