universum.studios.android.widget.adapter.module

Class SelectionModule

java.lang.Object

universum.studios.android.widget.adapter.module.AdapterModule

universum.studios.android.widget.adapter.module.SelectionModule

public class SelectionModule
extends AdapterModule

An AdapterModule implementation that specifies API to support selection feature for the associated adapter.

This module supports both, SINGLE and MULTIPLE selection modes. The desired selection mode may be changed via setMode(int) and obtained via getMode().

The associated adapter is required to dispatch to this module desired selection changes either via toggleSelection(long) or via setSelected(long, boolean) methods. Initial selection may be specified via setSelection(List). The current selection (selected ids) may be obtained via getSelection() where in SINGLE selection mode the returned array will contain only single item. The code snippet below shows basic usage of this module within an adapter:

 public class SampleAdapter extends BaseAdapter implements ModuleAdapter {

      // Selection module providing selection feature for this adapter.
      private SelectionModule mSelectionModule;

      // ...

      public SampleAdapter(@NonNull Context context) {
          super(context);
          this.mSelectionModule = new SelectionModule();
          this.mSelectionModule.setMode(SelectionModule.MULTIPLE);
          this.mSelectionModule.attachToAdapter(this);
      }

      public void toggleItemSelection(long id) {
          mSelectionModule.toggleSelection(id);
          // no need to call notifyDataSetChanged() if adapter auto notification is enabled
      }

      @NonNull
      public List<Long> getSelection() {
          return mSelectionModule.getSelection();
      }

      @NonNull
      protected void onBindViewHolder(@NonNull Object viewHolder, int position) {
          // Use mSelectionModule.isSelected(getItemId(position)) to check if item is selected or not.
      }

      // ...
 }
 

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SelectionModule.SavedState An AdapterSavedState implementation used to ensure that the state of SelectionModule is properly saved.
static interface	SelectionModule.SelectionMode Defines an annotation for determining set of allowed modes for SelectionModule.

Nested classes/interfaces inherited from class universum.studios.android.widget.adapter.module.AdapterModule

AdapterModule.ModuleAdapter

Field Summary

Fields

Modifier and Type	Field and Description
static int	MULTIPLE Mode that allows multiple items to be selected.
static int	SINGLE Mode that allows only a single item to be selected.

Constructor Summary

Constructors

Constructor and Description
SelectionModule()

Method Summary

Modifier and Type	Method and Description
void	clearSelection() Deselects all currently selected ids and notifies adapter.
protected void	clearSelection(boolean notify) Removes all ids form the set of the currently selected ids.
void	clearSelectionInRange(int startPosition, int count) Deselects all currently selected ids in the [startPosition, startPosition + count) range and notifies adapter.
protected void	deselect(long id) Removes the specified id form the set of the currently selected ids.
int	getMode() Returns the current selection mode of this module.
List<Long>	getSelection() Returns list containing ids that are at this time selected within this module.
int	getSelectionSize() Returns size of the current selection.
boolean	isSelected(long id) Checks whether the specified id is currently selected or not.
boolean	requiresStateSaving() Returns a boolean flag indicating whether this module requires state saving or not.
void	restoreInstanceState(Parcelable savedState) Restores the previous state, saved via AdapterModule.saveInstanceState(), of this adapter module.
Parcelable	saveInstanceState() Saves the current state of this adapter module.
protected void	select(long id) Adds the specified id into the set of the currently selected ids.
void	selectAll() Same as selectRange(int, int) with parameters (0, ModuleAdapter.getItemCount()).
void	selectRange(int startPosition, int count) Selects all ids in the [startPosition, startPosition + count) range and notifies adapter.
void	setMode(int mode) Sets the current selection mode of this module to the specified one.
void	setSelected(long id, boolean selected) Changes selection state of the specified id to the desired one and notifies adapter.
void	setSelection(List<Long> selection) Sets a selection for this module and notifies adapter.
int	toggleSelection(long id) Changes selection state of the specified id to the opposite one (selected -> unselected; unselected -> selected) and notifies adapter.

Methods inherited from class universum.studios.android.widget.adapter.module.AdapterModule

assertAttachedToAdapterOrThrow, attachToAdapter, isAdapterNotificationEnabled, notifyAdapter, onAttachedToAdapter, setAdapterNotificationEnabled

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SINGLE

public static final int SINGLE

Mode that allows only a single item to be selected.

See Also:

getSelection(), Constant Field Values

MULTIPLE

public static final int MULTIPLE

Mode that allows multiple items to be selected.

See Also:

getSelection(), Constant Field Values

Constructor Detail

SelectionModule

public SelectionModule()

Method Detail

setMode

public void setMode(int mode)

Sets the current selection mode of this module to the specified one.

Note, that changing of selection mode also clears the current selection of this module and notifies adapter.

Default value: SINGLE

Parameters:

mode - The desired selection mode. One of SINGLE or MULTIPLE.

See Also:

getMode(), getSelection()

getMode

public int getMode()

Returns the current selection mode of this module.

Returns:

Current selection mode. One of SINGLE or MULTIPLE.

See Also:

setMode(int)

toggleSelection

public int toggleSelection(long id)

Changes selection state of the specified id to the opposite one (selected -> unselected; unselected -> selected) and notifies adapter.

Parameters:

id - The id of an item of which selection state to toggle.

Returns:

Size of the current selection.

See Also:

setSelected(long, boolean), AdapterModule.isAdapterNotificationEnabled()

setSelected

public void setSelected(long id,
                        boolean selected)

Changes selection state of the specified id to the desired one and notifies adapter.

Parameters:

id - The id of an item of which selection state to change.

selected - New selection state. True to be selected, false otherwise,

See Also:

toggleSelection(long), selectRange(int, int), selectAll(), AdapterModule.isAdapterNotificationEnabled()

selectAll

public void selectAll()

Same as selectRange(int, int) with parameters (0, ModuleAdapter.getItemCount()).

Note, that calling of this method for mode other than MULTIPLE will throw an exception.

Throws:

IllegalStateException - If the current mode is not MULTIPLE.

See Also:

setSelected(long, boolean)

selectRange

public void selectRange(int startPosition,
                        int count)

Selects all ids in the [startPosition, startPosition + count) range and notifies adapter.

All previously selected ids will remain selected.

Note, that calling of this method for mode other than MULTIPLE will throw an exception.

Parameters:

startPosition - The position from which to start selection.

count - Count of items to select from the start position.

Throws:

IllegalStateException - If the current mode is not MULTIPLE.

IndexOutOfBoundsException - If startPosition + count > n.

See Also:

selectAll(), setSelected(long, boolean), AdapterModule.isAdapterNotificationEnabled()

setSelection

public void setSelection(@Nullable
                         List<Long> selection)

Sets a selection for this module and notifies adapter. The specified selection will override any current selection of this module.

Parameters:

selection - The desired selection. May be null to clear the current selection.

See Also:

getSelection(), AdapterModule.isAdapterNotificationEnabled()

isSelected

public boolean isSelected(long id)

Checks whether the specified id is currently selected or not.

Parameters:

id - The id of an item of which selection state to check.

Returns:

True if item with the specified id is selected, false otherwise.

See Also:

setSelected(long, boolean), toggleSelection(long)

getSelection

@NonNull
public List<Long> getSelection()

Returns list containing ids that are at this time selected within this module.

In SINGLE selection mode the returned list will contain maximum of 1 selected id, in MULTIPLE selection mode all selected ids will be contained in the returned list.

Returns:

List with selected ids or immutable empty list if there is no selection.

getSelectionSize

public int getSelectionSize()

Returns size of the current selection.

Returns:

Count of the currently selected ids.

See Also:

getSelection()

clearSelection

public void clearSelection()

Deselects all currently selected ids and notifies adapter.

See Also:

clearSelectionInRange(int, int), AdapterModule.isAdapterNotificationEnabled()

clearSelection

protected final void clearSelection(boolean notify)

Removes all ids form the set of the currently selected ids.

Parameters:

notify - True to notify the associated adapter via AdapterModule.notifyAdapter(), false otherwise.

clearSelectionInRange

public void clearSelectionInRange(int startPosition,
                                  int count)

Deselects all currently selected ids in the [startPosition, startPosition + count) range and notifies adapter.

Note, that calling of this method for mode other than MULTIPLE will throw an exception.

Parameters:

startPosition - The position from which to start deselection.

count - Count of items to deselect from the start position.

Throws:

IllegalStateException - If the current mode is not MULTIPLE.

IndexOutOfBoundsException - If startPosition + count > n.

See Also:

clearSelection(), AdapterModule.isAdapterNotificationEnabled()

select

protected final void select(long id)

Adds the specified id into the set of the currently selected ids. If there is already same id presented, addition of the given one will be ignored.

Parameters:

id - The id to add into the selected ones.

See Also:

deselect(long)

deselect

protected final void deselect(long id)

Removes the specified id form the set of the currently selected ids.

Parameters:

id - The id to remove from the selected ones.

See Also:

select(long)

requiresStateSaving

public boolean requiresStateSaving()

Description copied from class: AdapterModule

Returns a boolean flag indicating whether this module requires state saving or not.

This implementation by default returns false.

Overrides:

requiresStateSaving in class AdapterModule

Returns:

True whether this module have some selection to save, false otherwise.

saveInstanceState

@NonNull
 @CallSuper
public Parcelable saveInstanceState()

Description copied from class: AdapterModule

Saves the current state of this adapter module.

If you decide to override this method, do not forget to call super.saveInstanceState() and pass the obtained super state to the corresponding constructor of your saved state implementation to ensure the state of all classes along the chain is properly saved.

Returns:

Saved state of this module or an empty state if this module does not need to save its state.

restoreInstanceState

@CallSuper
public void restoreInstanceState(@NonNull
                                             Parcelable savedState)

Description copied from class: AdapterModule

Restores the previous state, saved via AdapterModule.saveInstanceState(), of this adapter module.

If you decide to override this method, do not forget to call super.restoreInstanceState(Parcelable) and pass there the parent state obtained from your saved state implementation to ensure the state of all classes along the chain is properly restored.

Parameters:

savedState - Should be the same state as obtained via AdapterModule.saveInstanceState() before.