ListPopupWindow

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

See also
ListPopupWindow

Summary

Constants

const Int

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

const Int

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

const Int

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

const Int

Alias for MATCH_PARENT.

const Int

The provided prompt view should appear above list content.

const Int

The provided prompt view should appear below list content.

const Int

Alias for WRAP_CONTENT.

Public constructors

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

ListPopupWindow(context: Context, attrs: AttributeSet?)

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

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

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

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

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

Public functions

Unit

Clear any current list selection.

View.OnTouchListener!

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

Unit

Dismiss the popup window.

View?

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

@StyleRes Int

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

Drawable?
Rect?

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

Int
Int
Int

Return the current value in setInputMethodMode.

ListView?
Int
Any?
Long
Int
View?
Int

Returns the current value in setSoftInputMode.

Int
Int
Boolean
Boolean

Returns whether the popup window will be modal when shown.

Boolean
Boolean
onKeyDown(keyCode: Int, event: KeyEvent)

Filter key down events.

Boolean
onKeyPreIme(keyCode: Int, event: KeyEvent)

Filter pre-IME key events.

Boolean
onKeyUp(keyCode: Int, event: KeyEvent)

Filter key up events.

Boolean
performItemClick(position: Int)

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

Unit

Post a show call to the UI thread.

Unit

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

Unit
setAnchorView(anchor: View?)

Sets the popup's anchor view.

Unit
setAnimationStyle(animationStyle: @StyleRes Int)

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

Unit

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

Unit

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

Unit

Set the gravity of the dropdown list.

Unit

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

Unit
setHeight(height: Int)

Sets the height of the popup window in pixels.

Unit

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

Unit

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

Unit

Sets a drawable to use as the list item selector.

Unit
setModal(modal: Boolean)

Set whether this window should be modal when shown.

Unit

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

Unit

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

Unit

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

Unit

Set where the optional prompt view should appear.

Unit
setPromptView(prompt: View?)

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

Unit
setSelection(position: Int)

Set the selected position of the list.

Unit

Sets the operating mode for the soft input area.

Unit

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

Unit
setWidth(width: Int)

Sets the width of the popup window in pixels.

Unit
setWindowLayoutType(layoutType: Int)

Set the layout type for this popup window.

Unit

Show the popup list.

Constants

INPUT_METHOD_FROM_FOCUSABLE

Added in 1.1.0
const val INPUT_METHOD_FROM_FOCUSABLE = 0: Int

Mode for setInputMethodMode: 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.

INPUT_METHOD_NEEDED

Added in 1.1.0
const val INPUT_METHOD_NEEDED = 1: Int

Mode for setInputMethodMode: 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.

INPUT_METHOD_NOT_NEEDED

Added in 1.1.0
const val INPUT_METHOD_NOT_NEEDED = 2: Int

Mode for setInputMethodMode: 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.

MATCH_PARENT

Added in 1.1.0
const val MATCH_PARENT = -1: Int

Alias for 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.

POSITION_PROMPT_ABOVE

Added in 1.1.0
const val POSITION_PROMPT_ABOVE = 0: Int

The provided prompt view should appear above list content.

POSITION_PROMPT_BELOW

Added in 1.1.0
const val POSITION_PROMPT_BELOW = 1: Int

The provided prompt view should appear below list content.

WRAP_CONTENT

Added in 1.1.0
const val WRAP_CONTENT = -2: Int

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

Public constructors

ListPopupWindow

Added in 1.1.0
ListPopupWindow(context: Context)

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

Parameters
context: Context

Context used for contained views.

ListPopupWindow

Added in 1.1.0
ListPopupWindow(context: Context, attrs: AttributeSet?)

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

Parameters
context: Context

Context used for contained views.

attrs: AttributeSet?

Attributes from inflating parent views used to style the popup.

ListPopupWindow

Added in 1.1.0
ListPopupWindow(
    context: Context,
    attrs: AttributeSet?,
    defStyleAttr: @AttrRes Int
)

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

Parameters
context: Context

Context used for contained views.

attrs: AttributeSet?

Attributes from inflating parent views used to style the popup.

defStyleAttr: @AttrRes Int

Default style attribute to use for popup content.

ListPopupWindow

Added in 1.1.0
ListPopupWindow(
    context: Context,
    attrs: AttributeSet?,
    defStyleAttr: @AttrRes Int,
    defStyleRes: @StyleRes Int
)

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

Parameters
context: Context

Context used for contained views.

attrs: AttributeSet?

Attributes from inflating parent views used to style the popup.

defStyleAttr: @AttrRes Int

Style attribute to read for default styling of popup content.

defStyleRes: @StyleRes Int

Style resource ID to use for default styling of popup content.

Public functions

clearListSelection

Added in 1.1.0
fun clearListSelection(): Unit

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

createDragToOpenListener

Added in 1.1.0
fun createDragToOpenListener(src: View!): 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

Returns
View.OnTouchListener!

a touch listener that controls drag-to-open behavior

dismiss

Added in 1.1.0
fun dismiss(): Unit

Dismiss the popup window.

getAnchorView

Added in 1.1.0
fun getAnchorView(): View?

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

Returns
View?

The popup's anchor view

getAnimationStyle

Added in 1.1.0
fun getAnimationStyle(): @StyleRes Int

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

Returns
@StyleRes Int

Animation style that will be used.

getBackground

Added in 1.1.0
fun getBackground(): Drawable?
Returns
Drawable?

The background drawable for the popup window.

getEpicenterBounds

Added in 1.1.0
fun getEpicenterBounds(): Rect?

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

Returns
Rect?

anchor-relative bounds, or @null if not set

getHeight

Added in 1.1.0
fun getHeight(): Int
Returns
Int

The height of the popup window in pixels.

getHorizontalOffset

Added in 1.1.0
fun getHorizontalOffset(): Int
Returns
Int

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

getInputMethodMode

Added in 1.1.0
fun getInputMethodMode(): Int

Return the current value in setInputMethodMode.

getListView

Added in 1.1.0
fun getListView(): ListView?
Returns
ListView?

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

getPromptPosition

Added in 1.1.0
fun getPromptPosition(): Int
Returns
Int

Where the optional prompt view should appear.

getSelectedItem

Added in 1.1.0
fun getSelectedItem(): Any?
Returns
Any?

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

getSelectedItemId

Added in 1.1.0
fun getSelectedItemId(): Long
Returns
Long

The ID of the currently selected item or INVALID_ROW_ID if isShowing == false.

getSelectedItemPosition

Added in 1.1.0
fun getSelectedItemPosition(): Int
Returns
Int

The position of the currently selected item or INVALID_POSITION if isShowing == false.

getSelectedView

Added in 1.1.0
fun getSelectedView(): View?
Returns
View?

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

See also
getSelectedView

getSoftInputMode

Added in 1.1.0
fun getSoftInputMode(): Int

Returns the current value in setSoftInputMode.

getVerticalOffset

Added in 1.1.0
fun getVerticalOffset(): Int
Returns
Int

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

getWidth

Added in 1.1.0
fun getWidth(): Int
Returns
Int

The width of the popup window in pixels.

isInputMethodNotNeeded

Added in 1.1.0
fun isInputMethodNotNeeded(): Boolean
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 1.1.0
fun isModal(): Boolean

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 1.1.0
fun isShowing(): Boolean
Returns
Boolean

true if the popup is currently showing, false otherwise.

onKeyDown

Added in 1.1.0
fun onKeyDown(keyCode: Int, 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: KeyEvent

event param passed to the host view's onKeyDown

Returns
Boolean

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

See also
setModal
onKeyUp

onKeyPreIme

Added in 1.1.0
fun onKeyPreIme(keyCode: Int, event: KeyEvent): Boolean

Filter pre-IME key events. By forwarding onKeyPreIme 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
setModal

onKeyUp

Added in 1.1.0
fun onKeyUp(keyCode: Int, 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: KeyEvent

event param passed to the host view's onKeyUp

Returns
Boolean

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

See also
setModal
onKeyDown

performItemClick

Added in 1.1.0
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

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 1.1.0
fun postShow(): Unit

Post a show call to the UI thread.

setAdapter

Added in 1.1.0
fun setAdapter(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

Added in 1.1.0
fun setAnchorView(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

Added in 1.1.0
fun setAnimationStyle(animationStyle: @StyleRes Int): Unit

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

Parameters
animationStyle: @StyleRes Int

Animation style to use.

setBackgroundDrawable

Added in 1.1.0
fun setBackgroundDrawable(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

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
fun setEpicenterBounds(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

Added in 1.1.0
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.

Throws
java.lang.IllegalArgumentException

if height is set to negative value

setHorizontalOffset

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
fun setOnDismissListener(listener: PopupWindow.OnDismissListener?): Unit

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 1.1.0
fun setOnItemClickListener(clickListener: AdapterView.OnItemClickListener?): Unit

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

Parameters
clickListener: AdapterView.OnItemClickListener?

Listener to register

setOnItemSelectedListener

Added in 1.1.0
fun setOnItemSelectedListener(
    selectedListener: AdapterView.OnItemSelectedListener?
): Unit

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

Parameters
selectedListener: AdapterView.OnItemSelectedListener?

Listener to register.

setPromptPosition

Added in 1.1.0
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

Added in 1.1.0
fun setPromptView(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.

Parameters
prompt: View?

View to use as an informational prompt.

setSelection

Added in 1.1.0
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

Added in 1.1.0
fun setSoftInputMode(mode: Int): Unit

Sets the operating mode for the soft input area.

Parameters
mode: Int

The desired mode, see softInputMode for the full list

setVerticalOffset

Added in 1.1.0
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

Added in 1.1.0
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

Added in 1.1.0
fun setWindowLayoutType(layoutType: Int): Unit

Set the layout type for this popup window.

See type for possible values.

Parameters
layoutType: Int

Layout type for this window.

See also
type

show

Added in 1.1.0
fun show(): Unit

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