Added in API level 11

Summary: XML Attrs | Constants | Ctors | Methods | Inherited Methods

ListPopupWindow

---

Kotlin |Java

public class ListPopupWindow
extends Object

java.lang.Object
↳	android.widget.ListPopupWindow

---

A ListPopupWindow anchors itself to a host view and displays a list of choices.

ListPopupWindow contains a number of tricky behaviors surrounding positioning, scrolling parents to fit the dropdown, interacting sanely with the IME if present, and others.

See also:

• AutoCompleteTextView
• Spinner

Summary

XML attributes
android:dropDownHorizontalOffset	Amount of pixels by which the drop down should be offset horizontally.
android:dropDownVerticalOffset	Amount of pixels by which the drop down should be offset vertically.

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.
int	MATCH_PARENT Alias for ViewGroup.LayoutParams#MATCH_PARENT.
int	POSITION_PROMPT_ABOVE The provided prompt view should appear above list content.
int	POSITION_PROMPT_BELOW The provided prompt view should appear below list content.
int	WRAP_CONTENT Alias for ViewGroup.LayoutParams#WRAP_CONTENT.

Public constructors
ListPopupWindow(Context context) Create a new, empty popup window capable of displaying items from a ListAdapter.
ListPopupWindow(Context context, AttributeSet attrs) Create a new, empty popup window capable of displaying items from a ListAdapter.
ListPopupWindow(Context context, AttributeSet attrs, int defStyleAttr) Create a new, empty popup window capable of displaying items from a ListAdapter.
ListPopupWindow(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes) Create a new, empty popup window capable of displaying items from a ListAdapter.

Public methods
void	clearListSelection() Clear any current list selection.
View.OnTouchListener	createDragToOpenListener(View src) Returns an OnTouchListener that can be added to the source view to implement drag-to-open behavior.
void	dismiss() Dismiss the popup window.
View	getAnchorView() Returns the view that will be used to anchor this popup.
int	getAnimationStyle() Returns the animation style that will be used when the popup window is shown or dismissed.
Drawable	getBackground()
Rect	getEpicenterBounds() Returns bounds which are used as a popup's epicenter of the enter and exit transitions.
int	getHeight()
int	getHorizontalOffset()
int	getInputMethodMode() Return the current value in setInputMethodMode(int).
ListView	getListView()
int	getPromptPosition()
Object	getSelectedItem()
long	getSelectedItemId()
int	getSelectedItemPosition()
View	getSelectedView()
int	getSoftInputMode() Returns the current value in setSoftInputMode(int).
int	getVerticalOffset()
int	getWidth()
boolean	isInputMethodNotNeeded()
boolean	isModal() Returns whether the popup window will be modal when shown.
boolean	isShowing()
boolean	onKeyDown(int keyCode, KeyEvent event) Filter key down events.
boolean	onKeyPreIme(int keyCode, KeyEvent event) Filter pre-IME key events.
boolean	onKeyUp(int keyCode, KeyEvent event) Filter key up events.
boolean	performItemClick(int position) Perform an item click operation on the specified list adapter position.
void	postShow() Post a show() call to the UI thread.
void	setAdapter(ListAdapter adapter) Sets the adapter that provides the data and the views to represent the data in this popup window.
void	setAnchorView(View anchor) Sets the popup's anchor view.
void	setAnimationStyle(int animationStyle) Set an animation style to use when the popup window is shown or dismissed.
void	setBackgroundDrawable(Drawable d) Sets a drawable to be the background for the popup window.
void	setContentWidth(int width) Sets the width of the popup window by the size of its content.
void	setDropDownGravity(int gravity) Set the gravity of the dropdown list.
void	setEpicenterBounds(Rect bounds) Specifies the anchor-relative bounds of the popup's transition epicenter.
void	setHeight(int height) Sets the height of the popup window in pixels.
void	setHorizontalOffset(int offset) Set the horizontal offset of this popup from its anchor view in pixels.
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	setListSelector(Drawable selector) Sets a drawable to use as the list item selector.
void	setModal(boolean modal) Set whether this window should be modal when shown.
void	setOnDismissListener(PopupWindow.OnDismissListener listener) Set a listener to receive a callback when the popup is dismissed.
void	setOnItemClickListener(AdapterView.OnItemClickListener clickListener) Sets a listener to receive events when a list item is clicked.
void	setOnItemSelectedListener(AdapterView.OnItemSelectedListener selectedListener) Sets a listener to receive events when a list item is selected.
void	setPromptPosition(int position) Set where the optional prompt view should appear.
void	setPromptView(View prompt) Set a view to act as a user prompt for this popup window.
void	setSelection(int position) Set the selected position of the list.
void	setSoftInputMode(int mode) Sets the operating mode for the soft input area.
void	setVerticalOffset(int offset) Set the vertical offset of this popup from its anchor view in pixels.
void	setWidth(int width) Sets the width of the popup window in pixels.
void	setWindowLayoutType(int layoutType) Set the layout type for this popup window.
void	show() Show the popup list.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

XML attributes

android:dropDownHorizontalOffset

Amount of pixels by which the drop down should be offset horizontally.

May 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), and mm (millimeters).

Related methods:

• setHorizontalOffset(int)

android:dropDownVerticalOffset

Amount of pixels by which the drop down should be offset vertically.

May 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), and mm (millimeters).

Related methods:

• setVerticalOffset(int)

Constants

INPUT_METHOD_FROM_FOCUSABLE

Added in API level 11

public static final int INPUT_METHOD_FROM_FOCUSABLE

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)

INPUT_METHOD_NEEDED

Added in API level 11

public static final int INPUT_METHOD_NEEDED

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)

INPUT_METHOD_NOT_NEEDED

Added in API level 11

public static final 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. 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)

MATCH_PARENT

Added in API level 11

public static final int MATCH_PARENT

Alias for ViewGroup.LayoutParams#MATCH_PARENT. If used to specify a popup width, the popup will match the width of the anchor view. If used to specify a popup height, the popup will fill available space.

Constant Value: -1 (0xffffffff)

POSITION_PROMPT_ABOVE

Added in API level 11

public static final int POSITION_PROMPT_ABOVE

The provided prompt view should appear above list content.

See also:

• setPromptPosition(int)
• getPromptPosition()
• setPromptView(View)

Constant Value: 0 (0x00000000)

POSITION_PROMPT_BELOW

Added in API level 11

public static final int POSITION_PROMPT_BELOW

The provided prompt view should appear below list content.

See also:

• setPromptPosition(int)
• getPromptPosition()
• setPromptView(View)

Constant Value: 1 (0x00000001)

WRAP_CONTENT

Added in API level 11

public static final int WRAP_CONTENT

Alias for ViewGroup.LayoutParams#WRAP_CONTENT. If used to specify a popup width, the popup will use the width of its content.

Constant Value: -2 (0xfffffffe)

Public constructors

ListPopupWindow

Added in API level 11

public ListPopupWindow (Context context)

Create a new, empty popup window capable of displaying items from a ListAdapter. Backgrounds should be set using setBackgroundDrawable(android.graphics.drawable.Drawable).

Parameters
context	Context: Context used for contained views. This value cannot be null.

ListPopupWindow

Added in API level 11

public ListPopupWindow (Context context, 
                AttributeSet attrs)

Create a new, empty popup window capable of displaying items from a ListAdapter. Backgrounds should be set using setBackgroundDrawable(android.graphics.drawable.Drawable).

Parameters
context	Context: Context used for contained views. This value cannot be null.
attrs	AttributeSet: Attributes from inflating parent views used to style the popup. This value may be null.

ListPopupWindow

Added in API level 11

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

Create a new, empty popup window capable of displaying items from a ListAdapter. Backgrounds should be set using setBackgroundDrawable(android.graphics.drawable.Drawable).

Parameters
context	Context: Context used for contained views. This value cannot be null.
attrs	AttributeSet: Attributes from inflating parent views used to style the popup. This value may be null.
defStyleAttr	int: Default style attribute to use for popup content.

ListPopupWindow

Added in API level 11

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

Create a new, empty popup window capable of displaying items from a ListAdapter. Backgrounds should be set using setBackgroundDrawable(android.graphics.drawable.Drawable).

Parameters
context	Context: Context used for contained views. This value cannot be null.
attrs	AttributeSet: Attributes from inflating parent views used to style the popup. This value may be null.
defStyleAttr	int: Style attribute to read for default styling of popup content.
defStyleRes	int: Style resource ID to use for default styling of popup content.

Public methods

clearListSelection

Added in API level 11

public void clearListSelection ()

Clear any current list selection. Only valid when isShowing() == true.

createDragToOpenListener

Added in API level 19

public View.OnTouchListener createDragToOpenListener (View src)

Returns an OnTouchListener that can be added to the source view to implement drag-to-open behavior. Generally, the source view should be the same view that was passed to setAnchorView(View).

When the listener is set on a view, touching that view and dragging outside of its bounds will open the popup window. Lifting will select the currently touched list item.

Example usage:

 ListPopupWindow myPopup = new ListPopupWindow(context);
 myPopup.setAnchor(myAnchor);
 OnTouchListener dragListener = myPopup.createDragToOpenListener(myAnchor);
 myAnchor.setOnTouchListener(dragListener);
 

Parameters
src	View: the view on which the resulting listener will be set

Returns
View.OnTouchListener	a touch listener that controls drag-to-open behavior

dismiss

Added in API level 11

public void dismiss ()

Dismiss the popup window.

getAnchorView

Added in API level 11

public View getAnchorView ()

Returns the view that will be used to anchor this popup.

Returns
View	The popup's anchor view This value may be null.

getAnimationStyle

Added in API level 11

public int getAnimationStyle ()

Returns the animation style that will be used when the popup window is shown or dismissed.

Returns
int	Animation style that will be used.

getBackground

Added in API level 11

public Drawable getBackground ()

Returns
Drawable	The background drawable for the popup window. This value may be null.

getEpicenterBounds

Added in API level 29

public Rect getEpicenterBounds ()

Returns bounds which are used as a popup's epicenter of the enter and exit transitions.

Returns
Rect	bounds relative to anchor view, or null if not set

See also:

• setEpicenterBounds(Rect)

getHeight

Added in API level 11

public int getHeight ()

Returns
int	The height of the popup window in pixels.

getHorizontalOffset

Added in API level 11

public int getHorizontalOffset ()

Related XML Attributes:

• android:dropDownHorizontalOffset

Returns
int	The horizontal offset of the popup from its anchor in pixels.

getInputMethodMode

Added in API level 11

public int getInputMethodMode ()

Return the current value in setInputMethodMode(int).

Returns
int

See also:

• setInputMethodMode(int)

getListView

Added in API level 11

public ListView getListView ()

Returns
ListView	The ListView displayed within the popup window. Only valid when isShowing() == true. This value may be null.

getPromptPosition

Added in API level 11

public int getPromptPosition ()

Returns
int	Where the optional prompt view should appear.

See also:

• POSITION_PROMPT_ABOVE
• POSITION_PROMPT_BELOW

getSelectedItem

Added in API level 11

public Object getSelectedItem ()

Returns
Object	The currently selected item or null if the popup is not showing.

getSelectedItemId

Added in API level 11

public long getSelectedItemId ()

Returns
long	The ID of the currently selected item or ListView#INVALID_ROW_ID if isShowing() == false.

See also:

• AdapterView.getSelectedItemId()

getSelectedItemPosition

Added in API level 11

public int getSelectedItemPosition ()

Returns
int	The position of the currently selected item or ListView#INVALID_POSITION if isShowing() == false.

See also:

• AdapterView.getSelectedItemPosition()

getSelectedView

Added in API level 11

public View getSelectedView ()

Returns
View	The View for the currently selected item or null if isShowing() == false.

See also:

• AbsListView.getSelectedView()

getSoftInputMode

Added in API level 11

public int getSoftInputMode ()

Returns the current value in setSoftInputMode(int).

Returns
int

See also:

• setSoftInputMode(int)
• WindowManager.LayoutParams.softInputMode

getVerticalOffset

Added in API level 11

public int getVerticalOffset ()

Related XML Attributes:

• android:dropDownVerticalOffset

Returns
int	The vertical offset of the popup from its anchor in pixels.

getWidth

Added in API level 11

public int getWidth ()

Returns
int	The width of the popup window in pixels.

isInputMethodNotNeeded

Added in API level 11

public boolean isInputMethodNotNeeded ()

Returns
boolean	true if this popup is configured to assume the user does not need to interact with the IME while it is showing, false otherwise.

isModal

Added in API level 11

public boolean isModal ()

Returns whether the popup window will be modal when shown.

Returns
boolean	true if the popup window will be modal, false otherwise.

isShowing

Added in API level 11

public boolean isShowing ()

Returns
boolean	true if the popup is currently showing, false otherwise.

onKeyDown

Added in API level 11

public boolean onKeyDown (int keyCode, 
                KeyEvent event)

Filter key down events. By forwarding key down events to this function, views using non-modal ListPopupWindow can have it handle key selection of items.

Parameters
keyCode	int: keyCode param passed to the host view's onKeyDown
event	KeyEvent: event param passed to the host view's onKeyDown This value cannot be null.

Returns
boolean	true if the event was handled, false if it was ignored.

See also:

• setModal(boolean)
• onKeyUp(int, KeyEvent)

onKeyPreIme

Added in API level 11

public boolean onKeyPreIme (int keyCode, 
                KeyEvent event)

Filter pre-IME key events. By forwarding View#onKeyPreIme(int, KeyEvent) events to this function, views using ListPopupWindow can have it dismiss the popup when the back key is pressed.

Parameters
keyCode	int: keyCode param passed to the host view's onKeyPreIme
event	KeyEvent: event param passed to the host view's onKeyPreIme This value cannot be null.

Returns
boolean	true if the event was handled, false if it was ignored.

See also:

• setModal(boolean)

onKeyUp

Added in API level 11

public boolean onKeyUp (int keyCode, 
                KeyEvent event)

Filter key up events. By forwarding key up events to this function, views using non-modal ListPopupWindow can have it handle key selection of items.

Parameters
keyCode	int: keyCode param passed to the host view's onKeyUp
event	KeyEvent: event param passed to the host view's onKeyUp This value cannot be null.

Returns
boolean	true if the event was handled, false if it was ignored.

See also:

• setModal(boolean)
• onKeyDown(int, KeyEvent)

performItemClick

Added in API level 11

public boolean performItemClick (int position)

Perform an item click operation on the specified list adapter position.

Parameters
position	int: Adapter position for performing the click

Returns
boolean	true if the click action could be performed, false if not. (e.g. if the popup was not showing, this method would return false.)

postShow

Added in API level 11

public void postShow ()

Post a show() call to the UI thread.

setAdapter

Added in API level 11

public void setAdapter (ListAdapter adapter)

Sets the adapter that provides the data and the views to represent the data in this popup window.

Parameters
adapter	ListAdapter: The adapter to use to create this window's content. This value may be null.

setAnchorView

Added in API level 11

public void setAnchorView (View anchor)

Sets the popup's anchor view. This popup will always be positioned relative to the anchor view when shown.

Parameters
anchor	View: The view to use as an anchor. This value may be null.

setAnimationStyle

Added in API level 11

public void setAnimationStyle (int animationStyle)

Set an animation style to use when the popup window is shown or dismissed.

Parameters
animationStyle	int: Animation style to use.

setBackgroundDrawable

Added in API level 11

public void setBackgroundDrawable (Drawable d)

Sets a drawable to be the background for the popup window.

Parameters
d	Drawable: A drawable to set as the background. This value may be null.

setContentWidth

Added in API level 11

public void setContentWidth (int width)

Sets the width of the popup window by the size of its content. The final width may be larger to accommodate styled window dressing.

Parameters
width	int: Desired width of content in pixels.

setDropDownGravity

Added in API level 19

public void setDropDownGravity (int gravity)

Set the gravity of the dropdown list. This is commonly used to set gravity to START or END for alignment with the anchor.

Parameters
gravity	int: Gravity value to use

setEpicenterBounds

Added in API level 29

public void setEpicenterBounds (Rect bounds)

Specifies the anchor-relative bounds of the popup's transition epicenter.

Parameters
bounds	Rect: anchor-relative bounds, or null to use default epicenter

See also:

• getEpicenterBounds()

setHeight

Added in API level 11

public void setHeight (int height)

Sets the height of the popup window in pixels. Can also be MATCH_PARENT.

Parameters
height	int: Height of the popup window must be a positive value, MATCH_PARENT, or WRAP_CONTENT.

Throws
IllegalArgumentException	if height is set to negative value

setHorizontalOffset

Added in API level 11

public void setHorizontalOffset (int offset)

Set the horizontal offset of this popup from its anchor view in pixels.

Related XML Attributes:

• android:dropDownHorizontalOffset

Parameters
offset	int: The horizontal offset of the popup from its anchor.

setInputMethodMode

Added in API level 11

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

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 the show() method.

Parameters
mode	int

See also:

• getInputMethodMode()
• show()

setListSelector

Added in API level 11

public void setListSelector (Drawable selector)

Sets a drawable to use as the list item selector.

Parameters
selector	Drawable: List selector drawable to use in the popup.

setModal

Added in API level 11

public void setModal (boolean modal)

Set whether this window should be modal when shown.

If a popup window is modal, it will receive all touch and key input. If the user touches outside the popup window's content area the popup window will be dismissed.

Parameters
modal	boolean: true if the popup window should be modal, false otherwise.

setOnDismissListener

Added in API level 11

public void setOnDismissListener (PopupWindow.OnDismissListener listener)

Set a listener to receive a callback when the popup is dismissed.

Parameters
listener	PopupWindow.OnDismissListener: Listener that will be notified when the popup is dismissed. This value may be null.

setOnItemClickListener

Added in API level 11

public void setOnItemClickListener (AdapterView.OnItemClickListener clickListener)

Sets a listener to receive events when a list item is clicked.

Parameters
clickListener	AdapterView.OnItemClickListener: Listener to register This value may be null.

See also:

• AdapterView.setOnItemClickListener(android.widget.AdapterView.OnItemClickListener)

setOnItemSelectedListener

Added in API level 11

public void setOnItemSelectedListener (AdapterView.OnItemSelectedListener selectedListener)

Sets a listener to receive events when a list item is selected.

Parameters
selectedListener	AdapterView.OnItemSelectedListener: Listener to register. This value may be null.

See also:

• AdapterView.setOnItemSelectedListener(OnItemSelectedListener)

setPromptPosition

Added in API level 11

public void setPromptPosition (int position)

Set where the optional prompt view should appear. The default is POSITION_PROMPT_ABOVE.

Parameters
position	int: A position constant declaring where the prompt should be displayed.

See also:

• POSITION_PROMPT_ABOVE
• POSITION_PROMPT_BELOW

setPromptView

Added in API level 11

public void setPromptView (View prompt)

Set a view to act as a user prompt for this popup window. Where the prompt view will appear is controlled by setPromptPosition(int).

Parameters
prompt	View: View to use as an informational prompt. This value may be null.

setSelection

Added in API level 11

public void setSelection (int position)

Set the selected position of the list. Only valid when isShowing() == true.

Parameters
position	int: List position to set as selected.

setSoftInputMode

Added in API level 11

public void setSoftInputMode (int mode)

Sets the operating mode for the soft input area.

Parameters
mode	int: The desired mode, see WindowManager.LayoutParams.softInputMode for the full list

See also:

• WindowManager.LayoutParams.softInputMode
• getSoftInputMode()

setVerticalOffset

Added in API level 11

public void setVerticalOffset (int offset)

Set the vertical offset of this popup from its anchor view in pixels.

Related XML Attributes:

• android:dropDownVerticalOffset

Parameters
offset	int: The vertical offset of the popup from its anchor.

setWidth

Added in API level 11

public void setWidth (int width)

Sets the width of the popup window in pixels. Can also be MATCH_PARENT or WRAP_CONTENT.

Parameters
width	int: Width of the popup window.

setWindowLayoutType

Added in API level 23

public void setWindowLayoutType (int layoutType)

Set the layout type for this popup window.

See WindowManager.LayoutParams#type for possible values.

Parameters
layoutType	int: Layout type for this window.

See also:

• WindowManager.LayoutParams.type

show

Added in API level 11

public void show ()

Show the popup list. If the list is already showing, this method will recalculate the popup's size and position.