ListPopupWindow

open class ListPopupWindow : ShowableListMenu
kotlin.Any
   ↳ androidx.appcompat.widget.ListPopupWindow

Static library support version of the framework's android.widget.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.

Summary

Constants

static Int

Mode for setInputMethodMode(int): the requirements for the input method should be based on the focusability of the popup.

static Int

Mode for setInputMethodMode(int): this popup always needs to work with an input method, regardless of whether it is focusable.

static Int

Mode for setInputMethodMode(int): this popup never needs to work with an input method, regardless of whether it is focusable.

static Int

Alias for ViewGroup.LayoutParams#MATCH_PARENT.

static Int

The provided prompt view should appear above list content.

static Int

The provided prompt view should appear below list content.

static Int

Alias for ViewGroup.LayoutParams#WRAP_CONTENT.

Public constructors

<init>(@NonNull context: Context)

Create a new, empty popup window capable of displaying items from a ListAdapter.

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?)

Create a new, empty popup window capable of displaying items from a ListAdapter.

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, @AttrRes defStyleAttr: Int)

Create a new, empty popup window capable of displaying items from a ListAdapter.

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, @AttrRes defStyleAttr: Int, @StyleRes defStyleRes: Int)

Create a new, empty popup window capable of displaying items from a ListAdapter.

Public methods

open Unit

Clear any current list selection.

open OnTouchListener!

Returns an OnTouchListener that can be added to the source view to implement drag-to-open behavior.

open Unit

Dismiss the popup window.

open View?

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

open Int

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

open Drawable?

open Rect?

Return custom anchor-relative bounds of the popup's transition epicenter

open Int

open Int

open Int

Return the current value in setInputMethodMode(int).

open ListView?

open Int

open Any?

open Long

open Int

open View?

open Int

Returns the current value in setSoftInputMode(int).

open Int

open Int

open Boolean

open Boolean

Returns whether the popup window will be modal when shown.

open Boolean

open Boolean
onKeyDown(keyCode: Int, @NonNull event: KeyEvent)

Filter key down events.

open Boolean
onKeyPreIme(keyCode: Int, @NonNull event: KeyEvent)

Filter pre-IME key events.

open Boolean
onKeyUp(keyCode: Int, @NonNull event: KeyEvent)

Filter key up events.

open Boolean
performItemClick(position: Int)

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

open Unit

Post a show() call to the UI thread.

open Unit
setAdapter(@Nullable adapter: ListAdapter?)

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

open Unit
setAnchorView(@Nullable anchor: View?)

Sets the popup's anchor view.

open Unit
setAnimationStyle(@StyleRes animationStyle: Int)

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

open Unit

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

open Unit

Sets the width of the popup window by the size of its content.

open Unit

Set the gravity of the dropdown list.

open Unit
setEpicenterBounds(@Nullable bounds: Rect?)

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

open Unit
setHeight(height: Int)

Sets the height of the popup window in pixels.

open Unit

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

open Unit

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

open Unit

Sets a drawable to use as the list item selector.

open Unit
setModal(modal: Boolean)

Set whether this window should be modal when shown.

open Unit

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

open Unit
setOnItemClickListener(@Nullable clickListener: OnItemClickListener?)

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

open Unit
setOnItemSelectedListener(@Nullable selectedListener: OnItemSelectedListener?)

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

open Unit

Set where the optional prompt view should appear.

open Unit
setPromptView(@Nullable prompt: View?)

Set a view to act as a user prompt for this popup window.

open Unit
setSelection(position: Int)

Set the selected position of the list.

open Unit

Sets the operating mode for the soft input area.

open Unit

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

open Unit
setWidth(width: Int)

Sets the width of the popup window in pixels.

open Unit
setWindowLayoutType(layoutType: Int)

Set the layout type for this popup window.

open Unit

Show the popup list.

Constants

INPUT_METHOD_FROM_FOCUSABLE

static val INPUT_METHOD_FROM_FOCUSABLE: Int

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.

Value: PopupWindow.INPUT_METHOD_FROM_FOCUSABLE

INPUT_METHOD_NEEDED

static val INPUT_METHOD_NEEDED: Int

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.

Value: PopupWindow.INPUT_METHOD_NEEDED

INPUT_METHOD_NOT_NEEDED

static val INPUT_METHOD_NOT_NEEDED: Int

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.

Value: PopupWindow.INPUT_METHOD_NOT_NEEDED

MATCH_PARENT

static val MATCH_PARENT: Int

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.

Value: ViewGroup.LayoutParams.MATCH_PARENT

POSITION_PROMPT_ABOVE

static val POSITION_PROMPT_ABOVE: Int

The provided prompt view should appear above list content.

Value: 0

POSITION_PROMPT_BELOW

static val POSITION_PROMPT_BELOW: Int

The provided prompt view should appear below list content.

Value: 1

WRAP_CONTENT

static val WRAP_CONTENT: Int

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

Value: ViewGroup.LayoutParams.WRAP_CONTENT

Public constructors

<init>

ListPopupWindow(@NonNull 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.

<init>

ListPopupWindow(@NonNull context: Context, @Nullable attrs: AttributeSet?)

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 Context: Attributes from inflating parent views used to style the popup.

<init>

ListPopupWindow(@NonNull context: Context, @Nullable attrs: AttributeSet?, @AttrRes defStyleAttr: Int)

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 Context: Attributes from inflating parent views used to style the popup.
defStyleAttr Context: Default style attribute to use for popup content.

<init>

ListPopupWindow(@NonNull context: Context, @Nullable attrs: AttributeSet?, @AttrRes defStyleAttr: Int, @StyleRes defStyleRes: Int)

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 Context: Attributes from inflating parent views used to style the popup.
defStyleAttr Context: Style attribute to read for default styling of popup content.
defStyleRes Context: Style resource ID to use for default styling of popup content.

Public methods

clearListSelection

open fun clearListSelection(): Unit

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

createDragToOpenListener

open fun createDragToOpenListener(src: View!): OnTouchListener!

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.

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
Return
OnTouchListener!: a touch listener that controls drag-to-open behavior

dismiss

open fun dismiss(): Unit

Dismiss the popup window.

getAnchorView

@Nullable open fun getAnchorView(): View?

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

Return
View?: The popup's anchor view

getAnimationStyle

@StyleRes open fun getAnimationStyle(): Int

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

Return
Int: Animation style that will be used.

getBackground

@Nullable open fun getBackground(): Drawable?
Return
Drawable?: The background drawable for the popup window.

getEpicenterBounds

@Nullable open fun getEpicenterBounds(): Rect?

Return custom anchor-relative bounds of the popup's transition epicenter

Return
Rect?: anchor-relative bounds, or @null if not set

getHeight

open fun getHeight(): Int
Return
Int: The height of the popup window in pixels.

getHorizontalOffset

open fun getHorizontalOffset(): Int
Return
Int: The horizontal offset of the popup from its anchor in pixels.

getInputMethodMode

open fun getInputMethodMode(): Int

Return the current value in setInputMethodMode(int).

getListView

@Nullable open fun getListView(): ListView?
Return
ListView?: The ListView displayed within the popup window. Only valid when isShowing() == true.

getPromptPosition

open fun getPromptPosition(): Int
Return
Int: Where the optional prompt view should appear.

getSelectedItem

@Nullable open fun getSelectedItem(): Any?
Return
Any?: The currently selected item or null if the popup is not showing.

getSelectedItemId

open fun getSelectedItemId(): Long
Return
Long: The ID of the currently selected item or ListView#INVALID_ROW_ID if isShowing() == false.

getSelectedItemPosition

open fun getSelectedItemPosition(): Int
Return
Int: The position of the currently selected item or ListView#INVALID_POSITION if isShowing() == false.

getSelectedView

@Nullable open fun getSelectedView(): View?
Return
View?: The View for the currently selected item or null if isShowing() == false.

getSoftInputMode

open fun getSoftInputMode(): Int

Returns the current value in setSoftInputMode(int).

getVerticalOffset

open fun getVerticalOffset(): Int
Return
Int: The vertical offset of the popup from its anchor in pixels.

getWidth

open fun getWidth(): Int
Return
Int: The width of the popup window in pixels.

isInputMethodNotNeeded

open fun isInputMethodNotNeeded(): Boolean
Return
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

open fun isModal(): Boolean

Returns whether the popup window will be modal when shown.

Return
Boolean: true if the popup window will be modal, false otherwise.

isShowing

open fun isShowing(): Boolean
Return
Boolean: true if the popup is currently showing, false otherwise.

onKeyDown

open fun onKeyDown(keyCode: Int, @NonNull event: KeyEvent): Boolean

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 Int: event param passed to the host view's onKeyDown
Return
Boolean: true if the event was handled, false if it was ignored.

onKeyPreIme

open fun onKeyPreIme(keyCode: Int, @NonNull event: KeyEvent): Boolean

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 Int: event param passed to the host view's onKeyPreIme
Return
Boolean: true if the event was handled, false if it was ignored.

onKeyUp

open fun onKeyUp(keyCode: Int, @NonNull event: KeyEvent): Boolean

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 Int: event param passed to the host view's onKeyUp
Return
Boolean: true if the event was handled, false if it was ignored.

performItemClick

open fun performItemClick(position: Int): Boolean

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

Parameters
position Int: Adapter position for performing the click
Return
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

open fun postShow(): Unit

Post a show() call to the UI thread.

setAdapter

open fun setAdapter(@Nullable adapter: ListAdapter?): Unit

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

open fun setAnchorView(@Nullable anchor: View?): Unit

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

open fun setAnimationStyle(@StyleRes animationStyle: Int): Unit

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

Parameters
animationStyle Int: Animation style to use.

setBackgroundDrawable

open fun setBackgroundDrawable(@Nullable d: Drawable?): Unit

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

Parameters
d Drawable?: A drawable to set as the background.

setContentWidth

open fun setContentWidth(width: Int): Unit

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

open fun setDropDownGravity(gravity: Int): Unit

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

open fun setEpicenterBounds(@Nullable bounds: Rect?): Unit

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

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

setHeight

open fun setHeight(height: Int): Unit

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.
Exceptions
IllegalArgumentException if height is set to negative value

setHorizontalOffset

open fun setHorizontalOffset(offset: Int): Unit

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

open fun setInputMethodMode(mode: Int): Unit

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.

setListSelector

open fun setListSelector(selector: Drawable!): Unit

Sets a drawable to use as the list item selector.

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

setModal

open fun setModal(modal: Boolean): Unit

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

open fun setOnDismissListener(@Nullable listener: OnDismissListener?): Unit

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

Parameters
listener OnDismissListener?: Listener that will be notified when the popup is dismissed.

setOnItemClickListener

open fun setOnItemClickListener(@Nullable clickListener: OnItemClickListener?): Unit

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

Parameters
clickListener OnItemClickListener?: Listener to register

setOnItemSelectedListener

open fun setOnItemSelectedListener(@Nullable selectedListener: OnItemSelectedListener?): Unit

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

Parameters
selectedListener OnItemSelectedListener?: Listener to register.

setPromptPosition

open fun setPromptPosition(position: Int): Unit

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

open fun setPromptView(@Nullable prompt: View?): Unit

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

open fun setSelection(position: Int): Unit

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

Parameters
position Int: List position to set as selected.

setSoftInputMode

open fun setSoftInputMode(mode: Int): Unit

Sets the operating mode for the soft input area.

Parameters
mode Int: The desired mode, see android.view.WindowManager.LayoutParams#softInputMode for the full list

setVerticalOffset

open fun setVerticalOffset(offset: Int): Unit

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

open fun setWidth(width: Int): Unit

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

open fun setWindowLayoutType(layoutType: Int): Unit

Set the layout type for this popup window.

See WindowManager.LayoutParams#type for possible values.

Parameters
layoutType Int: Layout type for this window.

show

open fun show(): Unit

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