public class

DragSortListView

extends ListView
java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.widget.AdapterView<T extends android.widget.Adapter>
         ↳ android.widget.AbsListView
           ↳ android.widget.ListView
             ↳ com.mobeta.android.dslv.DragSortListView

Class Overview

ListView subclass that mediates drag and drop resorting of items.

Summary

Nested Classes
interface DragSortListView.DragListener  
interface DragSortListView.DragScrollProfile Interface for controlling scroll speed as a function of touch position and time. 
interface DragSortListView.DragSortListener  
interface DragSortListView.DropListener Your implementation of this has to reorder your ListAdapter! Make sure to call notifyDataSetChanged() or something like it in your implementation. 
interface DragSortListView.FloatViewManager Interface for customization of the floating View appearance and dragging behavior. 
interface DragSortListView.RemoveListener Make sure to call notifyDataSetChanged() or something like it in your implementation. 
Constants
int DRAG_NEG_X Drag flag bit.
int DRAG_NEG_Y Drag flag bit.
int DRAG_POS_X Drag flag bit.
int DRAG_POS_Y Drag flag bit.
[Expand]
Inherited Constants
From class android.widget.ListView
From class android.widget.AbsListView
From class android.widget.AdapterView
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Fields
From class android.view.View
Public Constructors
DragSortListView(Context context, AttributeSet attrs)
Public Methods
void cancelDrag()
Cancel a drag.
float getFloatAlpha()
ListAdapter getInputAdapter()
As opposed to getAdapter(), which returns a heavily wrapped ListAdapter (DragSortListView wraps the input ListAdapter {\emph and} ListView wraps the wrapped one).
boolean isDragEnabled()
void moveCheckState(int from, int to)
Use this to move the check state of an item from one position to another in a drop operation.
void moveItem(int from, int to)
Move an item, bypassing the drag-sort process.
boolean onInterceptTouchEvent(MotionEvent ev)
boolean onTouchEvent(MotionEvent ev)
void removeCheckState(int position)
Use this when an item has been deleted, to move the check state of all following items up one step.
void removeItem(int which)
void removeItem(int which, float velocityX)
Removes an item from the list and animates the removal.
void requestLayout()
void setAdapter(ListAdapter adapter)
For each DragSortListView Listener interface implemented by adapter, this method calls the appropriate set*Listener method with adapter as the argument.
void setDragEnabled(boolean enabled)
Allows for easy toggling between a DragSortListView and a regular old ListView.
void setDragListener(DragSortListView.DragListener l)
void setDragScrollProfile(DragSortListView.DragScrollProfile ssp)
Completely custom scroll speed profile.
void setDragScrollStart(float heightFraction)
Set the width of each drag scroll region by specifying a fraction of the ListView height.
void setDragScrollStarts(float upperFrac, float lowerFrac)
Set the width of each drag scroll region by specifying a fraction of the ListView height.
void setDragSortListener(DragSortListView.DragSortListener l)
void setDropListener(DragSortListView.DropListener l)
This better reorder your ListAdapter! DragSortListView does not do this for you; doesn't make sense to.
void setFloatAlpha(float alpha)
Usually called from a FloatViewManager.
void setFloatViewManager(DragSortListView.FloatViewManager manager)
void setMaxScrollSpeed(float max)
Set maximum drag scroll speed in positions/second.
void setRemoveListener(DragSortListView.RemoveListener l)
Probably a no-brainer, but make sure that your remove listener calls notifyDataSetChanged() or something like it.
boolean startDrag(int position, int dragFlags, int deltaX, int deltaY)
Start a drag of item at position using the registered FloatViewManager.
boolean startDrag(int position, View floatView, int dragFlags, int deltaX, int deltaY)
Start a drag of item at position without using a FloatViewManager.
boolean stopDrag(boolean remove, float velocityX)
boolean stopDrag(boolean remove)
Stop a drag in progress.
boolean stopDragWithVelocity(boolean remove, float velocityX)
Protected Methods
void dispatchDraw(Canvas canvas)
void layoutChildren()
boolean onDragTouchEvent(MotionEvent ev)
void onDraw(Canvas canvas)
void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
void onSizeChanged(int w, int h, int oldw, int oldh)
[Expand]
Inherited Methods
From class android.widget.ListView
From class android.widget.AbsListView
From class android.widget.AdapterView
From class android.view.ViewGroup
From class android.view.View
From class java.lang.Object
From interface android.graphics.drawable.Drawable.Callback
From interface android.text.TextWatcher
From interface android.view.KeyEvent.Callback
From interface android.view.ViewManager
From interface android.view.ViewParent
From interface android.view.ViewTreeObserver.OnGlobalLayoutListener
From interface android.view.ViewTreeObserver.OnTouchModeChangeListener
From interface android.view.accessibility.AccessibilityEventSource
From interface android.widget.Filter.FilterListener

Constants

public static final int DRAG_NEG_X

Drag flag bit. Floating View can move in the negative x direction.

Constant Value: 2 (0x00000002)

public static final int DRAG_NEG_Y

Drag flag bit. Floating View can move in the negative y direction. This is subtle. What this actually means is that the floating View can be dragged above its starting position. Remove in favor of lower-bounding item position?

Constant Value: 8 (0x00000008)

public static final int DRAG_POS_X

Drag flag bit. Floating View can move in the positive x direction.

Constant Value: 1 (0x00000001)

public static final int DRAG_POS_Y

Drag flag bit. Floating View can move in the positive y direction. This is subtle. What this actually means is that, if enabled, the floating View can be dragged below its starting position. Remove in favor of upper-bounding item position?

Constant Value: 4 (0x00000004)

Public Constructors

public DragSortListView (Context context, AttributeSet attrs)

Public Methods

public void cancelDrag ()

Cancel a drag. Calls #stopDrag(boolean, boolean) with true as the first argument.

public float getFloatAlpha ()

public ListAdapter getInputAdapter ()

As opposed to getAdapter(), which returns a heavily wrapped ListAdapter (DragSortListView wraps the input ListAdapter {\emph and} ListView wraps the wrapped one).

Returns
  • The ListAdapter set as the argument of setAdapter()

public boolean isDragEnabled ()

public void moveCheckState (int from, int to)

Use this to move the check state of an item from one position to another in a drop operation. If you have a choiceMode which is not none, this method must be called when the order of items changes in an underlying adapter which does not have stable IDs (see hasStableIds()). This is because without IDs, the ListView has no way of knowing which items have moved where, and cannot update the check state accordingly.

A word of warning about a "feature" in Android that you may run into when dealing with movable list items: for an adapter that does have stable IDs, ListView will attempt to locate each item based on its ID and move the check state from the item's old position to the new position — which is all fine and good (and removes the need for calling this function), except for the half-baked approach. Apparently to save time in the naive algorithm used, ListView will only search for an ID in the close neighborhood of the old position. If the user moves an item too far (specifically, more than 20 rows away), ListView will give up and just force the item to be unchecked. So if there is a reasonable chance that the user will move items more than 20 rows away from the original position, you may wish to use an adapter with unstable IDs and call this method manually instead.

public void moveItem (int from, int to)

Move an item, bypassing the drag-sort process. Simply calls through to drop(int, int).

Parameters
from Position to move (NOTE: headers/footers ignored! this is a position in your input ListAdapter).
to Target position (NOTE: headers/footers ignored! this is a position in your input ListAdapter).

public boolean onInterceptTouchEvent (MotionEvent ev)

public boolean onTouchEvent (MotionEvent ev)

public void removeCheckState (int position)

Use this when an item has been deleted, to move the check state of all following items up one step. If you have a choiceMode which is not none, this method must be called when the order of items changes in an underlying adapter which does not have stable IDs (see hasStableIds()). This is because without IDs, the ListView has no way of knowing which items have moved where, and cannot update the check state accordingly. See also further comments on moveCheckState(int, int).

public void removeItem (int which)

public void removeItem (int which, float velocityX)

Removes an item from the list and animates the removal.

Parameters
which Position to remove (NOTE: headers/footers ignored! this is a position in your input ListAdapter).

public void requestLayout ()

public void setAdapter (ListAdapter adapter)

For each DragSortListView Listener interface implemented by adapter, this method calls the appropriate set*Listener method with adapter as the argument.

Parameters
adapter The ListAdapter providing data to back DragSortListView.

public void setDragEnabled (boolean enabled)

Allows for easy toggling between a DragSortListView and a regular old ListView. If enabled, items are draggable, where the drag init mode determines how items are lifted (see setDragInitMode(int)). If disabled, items cannot be dragged.

Parameters
enabled Set true to enable list item dragging

public void setDragListener (DragSortListView.DragListener l)

public void setDragScrollProfile (DragSortListView.DragScrollProfile ssp)

Completely custom scroll speed profile. Default increases linearly with position and is constant in time. Create your own by implementing DragSortListView.DragScrollProfile.

public void setDragScrollStart (float heightFraction)

Set the width of each drag scroll region by specifying a fraction of the ListView height.

Parameters
heightFraction Fraction of ListView height. Capped at 0.5f.

public void setDragScrollStarts (float upperFrac, float lowerFrac)

Set the width of each drag scroll region by specifying a fraction of the ListView height.

Parameters
upperFrac Fraction of ListView height for up-scroll bound. Capped at 0.5f.
lowerFrac Fraction of ListView height for down-scroll bound. Capped at 0.5f.

public void setDragSortListener (DragSortListView.DragSortListener l)

public void setDropListener (DragSortListView.DropListener l)

This better reorder your ListAdapter! DragSortListView does not do this for you; doesn't make sense to. Make sure notifyDataSetChanged() or something like it is called in your implementation. Furthermore, if you have a choiceMode other than none and the ListAdapter does not return true for hasStableIds(), you will need to call moveCheckState(int, int) to move the check boxes along with the list items.

public void setFloatAlpha (float alpha)

Usually called from a FloatViewManager. The float alpha will be reset to the xml-defined value every time a drag is stopped.

public void setFloatViewManager (DragSortListView.FloatViewManager manager)

public void setMaxScrollSpeed (float max)

Set maximum drag scroll speed in positions/second. Only applies if using default ScrollSpeedProfile.

Parameters
max Maximum scroll speed.

public void setRemoveListener (DragSortListView.RemoveListener l)

Probably a no-brainer, but make sure that your remove listener calls notifyDataSetChanged() or something like it. When an item removal occurs, DragSortListView relies on a redraw of all the items to recover invisible views and such. Strictly speaking, if you remove something, your dataset has changed...

public boolean startDrag (int position, int dragFlags, int deltaX, int deltaY)

Start a drag of item at position using the registered FloatViewManager. Calls through to startDrag(int, View, int, int, int) after obtaining the floating View from the FloatViewManager.

Parameters
position Item to drag.
dragFlags Flags that restrict some movements of the floating View. For example, set dragFlags |= ~DRAG_NEG_X to allow dragging the floating View in all directions except off the screen to the left.
deltaX Offset in x of the touch coordinate from the left edge of the floating View (i.e. touch-x minus float View left).
deltaY Offset in y of the touch coordinate from the top edge of the floating View (i.e. touch-y minus float View top).
Returns
  • True if the drag was started, false otherwise. This startDrag will fail if we are not currently in a touch event, there is no registered FloatViewManager, or the FloatViewManager returns a null View.

public boolean startDrag (int position, View floatView, int dragFlags, int deltaX, int deltaY)

Start a drag of item at position without using a FloatViewManager.

Parameters
position Item to drag.
floatView Floating View.
dragFlags Flags that restrict some movements of the floating View. For example, set dragFlags |= ~DRAG_NEG_X to allow dragging the floating View in all directions except off the screen to the left.
deltaX Offset in x of the touch coordinate from the left edge of the floating View (i.e. touch-x minus float View left).
deltaY Offset in y of the touch coordinate from the top edge of the floating View (i.e. touch-y minus float View top).
Returns
  • True if the drag was started, false otherwise. This startDrag will fail if we are not currently in a touch event, floatView is null, or there is a drag in progress.

public boolean stopDrag (boolean remove, float velocityX)

public boolean stopDrag (boolean remove)

Stop a drag in progress. Pass true if you would like to remove the dragged item from the list.

Parameters
remove Remove the dragged item from the list. Calls a registered RemoveListener, if one exists. Otherwise, calls the DropListener, if one exists.
Returns
  • True if the stop was successful. False if there is no floating View.

public boolean stopDragWithVelocity (boolean remove, float velocityX)

Protected Methods

protected void dispatchDraw (Canvas canvas)

protected void layoutChildren ()

protected boolean onDragTouchEvent (MotionEvent ev)

protected void onDraw (Canvas canvas)

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

protected void onSizeChanged (int w, int h, int oldw, int oldh)