Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.
added in version 1.0.0
belongs to Maven artifact androidx.appcompat:appcompat:1.0.0-rc01

ListPopupWindow

public class ListPopupWindow
extends Object

java.lang.Object
   ↳ androidx.appcompat.widget.ListPopupWindow


Static library support version of the framework's ListPopupWindow. Used to write apps that run on platforms prior to Android L. When running on Android L or above, this implementation is still used; it does not try to switch to the framework's implementation. See the framework SDK documentation for a class overview.

See also:

Summary

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

Constants

INPUT_METHOD_FROM_FOCUSABLE

added in version 1.0.0
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 version 1.0.0
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 version 1.0.0
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 version 1.0.0
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 version 1.0.0
public static final int POSITION_PROMPT_ABOVE

The provided prompt view should appear above list content.

Constant Value: 0 (0x00000000)

POSITION_PROMPT_BELOW

added in version 1.0.0
public static final int POSITION_PROMPT_BELOW

The provided prompt view should appear below list content.

Constant Value: 1 (0x00000001)

WRAP_CONTENT

added in version 1.0.0
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 version 1.0.0
public ListPopupWindow (Context context)

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

Parameters
context Context: Context used for contained views.

ListPopupWindow

added in version 1.0.0
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(Drawable).

Parameters
context Context: Context used for contained views.

attrs AttributeSet: Attributes from inflating parent views used to style the popup.

ListPopupWindow

added in version 1.0.0
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(Drawable).

Parameters
context Context: Context used for contained views.

attrs AttributeSet: Attributes from inflating parent views used to style the popup.

defStyleAttr int: Default style attribute to use for popup content.

ListPopupWindow

added in version 1.0.0
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(Drawable).

Parameters
context Context: Context used for contained views.

attrs AttributeSet: Attributes from inflating parent views used to style the popup.

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 version 1.0.0
public void clearListSelection ()

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

createDragToOpenListener

added in version 1.0.0
public View.OnTouchListener createDragToOpenListener (View src)

Returns an View.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 version 1.0.0
public void dismiss ()

Dismiss the popup window.

getAnchorView

added in version 1.0.0
public View getAnchorView ()

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

Returns
View The popup's anchor view

getAnimationStyle

added in version 1.0.0
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 version 1.0.0
public Drawable getBackground ()

Returns
Drawable The background drawable for the popup window.

getHeight

added in version 1.0.0
public int getHeight ()

Returns
int The height of the popup window in pixels.

getHorizontalOffset

added in version 1.0.0
public int getHorizontalOffset ()

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

getInputMethodMode

added in version 1.0.0
public int getInputMethodMode ()

Return the current value in setInputMethodMode(int).

Returns
int

getListView

added in version 1.0.0
public ListView getListView ()

Returns
ListView The ListView displayed within the popup window. Only valid when isShowing() == true.

getPromptPosition

added in version 1.0.0
public int getPromptPosition ()

Returns
int Where the optional prompt view should appear.

getSelectedItem

added in version 1.0.0
public Object getSelectedItem ()

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

getSelectedItemId

added in version 1.0.0
public long getSelectedItemId ()

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

getSelectedItemPosition

added in version 1.0.0
public int getSelectedItemPosition ()

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

getSelectedView

added in version 1.0.0
public View getSelectedView ()

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

getSoftInputMode

added in version 1.0.0
public int getSoftInputMode ()

Returns the current value in setSoftInputMode(int).

Returns
int

getVerticalOffset

added in version 1.0.0
public int getVerticalOffset ()

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

getWidth

added in version 1.0.0
public int getWidth ()

Returns
int The width of the popup window in pixels.

isInputMethodNotNeeded

added in version 1.0.0
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 version 1.0.0
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 version 1.0.0
public boolean isShowing ()

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

onKeyDown

added in version 1.0.0
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

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

onKeyPreIme

added in version 1.0.0
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

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

See also:

onKeyUp

added in version 1.0.0
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

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

performItemClick

added in version 1.0.0
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 version 1.0.0
public void postShow ()

Post a show() call to the UI thread.

setAdapter

added in version 1.0.0
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.

setAnchorView

added in version 1.0.0
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.

setAnimationStyle

added in version 1.0.0
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 version 1.0.0
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.

setContentWidth

added in version 1.0.0
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 version 1.0.0
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

setHeight

added in version 1.0.0
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 version 1.0.0
public void setHorizontalOffset (int offset)

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

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

setInputMethodMode

added in version 1.0.0
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

setListSelector

added in version 1.0.0
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 version 1.0.0
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 version 1.0.0
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.

setOnItemClickListener

added in version 1.0.0
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

setOnItemSelectedListener

added in version 1.0.0
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.

setPromptPosition

added in version 1.0.0
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.

setPromptView

added in version 1.0.0
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.

setSelection

added in version 1.0.0
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 version 1.0.0
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

setVerticalOffset

added in version 1.0.0
public void setVerticalOffset (int offset)

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

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

setWidth

added in version 1.0.0
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 version 1.0.0
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.

show

added in version 1.0.0
public void show ()

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