Package util

# Class HistoryList<T>

java.lang.Object
util.HistoryList<T>

Type Parameters:
  `T` - the type of items in the list

public class HistoryList<T> extends Object
An object meant to track items with the ability to go back and forth within the list of items.

By default, duplicate entries are not allowed. This allows for a simplified history of unique items. If the client prefers to have an accurate history, then call `setAllowDuplicates(boolean)` in order to keep all history entries.

By default, null values are not allowed. If the client allows null/empty values, then they should call `setAllowNulls(boolean)` with a value of true. This allows the backward navigation to work correctly when the client's active item is cleared. When that item is cleared, then client is expected to call `add(Object)` with value of null. (This is safe to do, regardless of whether null are allowed). When nulls are allowed and a null value is received, then current item is placed onto the history stack as the previous item. This way, when the user presses the back button, the last visible item will be activated.

Note: when nulls are allowed, only a single null value will be stored. Further, if new, non-null items are added, then the null value is dropped.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HistoryList(int size, BiConsumer<T,T> itemSelectedCallback)`
  The sized passed here limits the size of the list, with the oldest items being dropped as the list grows.
  `HistoryList(int size, Consumer<T> itemSelectedCallback)`
  The sized passed here limits the size of the list, with the oldest items being dropped as the list grows.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(T t)`
  Adds an item to this history list.
  `void`
  `clear()`
  Clears all history entries and resets the current item pointer.
  `T`
  `getCurrentHistoryItem()`
  Returns the item currently pointed to within the list of items.
  `List<T>`
  `getNextHistoryItems()`
  Get all items in the history that come after the current history item.
  `List<T>`
  `getPreviousHistoryItems()`
  Get all items in the history that come before the current history item.
  `void`
  `goBack()`
  Moves this history list's current item pointer back one and then calls the user-provided callback to signal the newly selected item.
  `void`
  `goBackTo(T t)`
  Performs a `goBack()` until the given item becomes the current item.
  `void`
  `goForward()`
  Moves this history list's current item pointer forward one and then calls the user-provided callback to signal the newly selected item.
  `void`
  `goForwardTo(T t)`
  Performs a `goForward()` until the given item becomes the current item.
  `boolean`
  `hasNext()`
  Returns true if this history list's current item pointer is not at the end of the list.
  `boolean`
  `hasPrevious()`
  Returns true if this history list's current item pointer is not at the beginning of the list.
  `void`
  `setAllowDuplicates(boolean allowDuplicates)`
  True signals that this list will allow duplicate entries.
  `void`
  `setAllowNulls(boolean allowNulls)`
  True signals that the client allows null items to be used.
  `int`
  `size()`
  Returns the number of items in this history list
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### HistoryList

    public HistoryList(int size, Consumer<T> itemSelectedCallback)
    The sized passed here limits the size of the list, with the oldest items being dropped as the list grows. The given callback will be called when `goBack()` or `goForward()` are called.
    Parameters:
      `size` - the max number of items to keep in the list
      `itemSelectedCallback` - the function to call when the client selects an item by going back or forward

  - ### HistoryList

    public HistoryList(int size, BiConsumer<T,T> itemSelectedCallback)
    The sized passed here limits the size of the list, with the oldest items being dropped as the list grows. The given callback will be called when `goBack()` or `goForward()` are called.
    Parameters:
      `size` - the max number of items to keep in the list
      `itemSelectedCallback` - the function to call when the client selects an item by going back or forward. This callback will be passed the newly selected item as the first argument and the previously selected item as the second argument.

- ## Method Details

  - ### setAllowDuplicates

    public void setAllowDuplicates(boolean allowDuplicates)
    True signals that this list will allow duplicate entries. False signals to not only not allow duplicates, but to also move the position of an item if it is re-added to the list.

    For correct behavior when not allowing duplicates, ensure you have defined an `equals` method to work as you expect. If two different items are considered equal, then this class will only remove the duplicate if the equals method returns true.

    The default is false

    Parameters:
      `allowDuplicates` - true to allow duplicates

  - ### setAllowNulls

    public void setAllowNulls(boolean allowNulls)
    True signals that the client allows null items to be used. When this is true, a null value will be stored in this list only as the last item. See the javadoc for more info.
    Parameters:
      `allowNulls` - true to allow nulls; the default is false

  - ### add

    public void add(T t)
    Adds an item to this history list. `null` values are ignored.

    Calls to this method during selection notification will have no effect. If you need to update the history during a notification, then you must do so at a later time, perhaps by using `SystemUtilities.runSwingLater(Runnable)`.

    Parameters:
      `t` - the item to add.

  - ### hasNext

    public boolean hasNext()
    Returns true if this history list's current item pointer is not at the end of the list.
    Returns:
      true if this history list's current item pointer is not at the end of the list.

  - ### hasPrevious

    public boolean hasPrevious()
    Returns true if this history list's current item pointer is not at the beginning of the list.
    Returns:
      true if this history list's current item pointer is not at the beginning of the list.

  - ### goBack

    public void goBack()
    Moves this history list's current item pointer back one and then calls the user-provided callback to signal the newly selected item.

    No action is taken if the current pointer is already at the beginning of the list.

  - ### goBackTo

    public void goBackTo(T t)
    Performs a `goBack()` until the given item becomes the current item. This is useful if you wish to go backward to a specific item in the list.
    Parameters:
      `t` - the item

  - ### goForward

    public void goForward()
    Moves this history list's current item pointer forward one and then calls the user-provided callback to signal the newly selected item.

    No action is taken if the current pointer is already at the end of the list.

  - ### goForwardTo

    public void goForwardTo(T t)
    Performs a `goForward()` until the given item becomes the current item. This is useful if you wish to go forward to a specific item in the list.
    Parameters:
      `t` - the item

  - ### getCurrentHistoryItem

    public T getCurrentHistoryItem()
    Returns the item currently pointed to within the list of items. When an item is added, this will be that item. Otherwise, it will be the last item navigated.
    Returns:
      the item currently pointed to within the list of items.

  - ### getPreviousHistoryItems

    public List<T> getPreviousHistoryItems()
    Get all items in the history that come before the current history item. They are returned in navigation order, as traversed if `goBack()` is called.
    Returns:
      the items

  - ### getNextHistoryItems

    public List<T> getNextHistoryItems()
    Get all items in the history that come after the current history item. They are returned in navigation order, as traversed if `goForward()` is called.
    Returns:
      the items

  - ### clear

    public void clear()
    Clears all history entries and resets the current item pointer.

  - ### size

    public int size()
    Returns the number of items in this history list
    Returns:
      the number of items in this history list

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`