Package se.conciliate.extensions.ui.widgets

Interface ChooserWidget<T>

All Known Subinterfaces:
MultiChooserWidget<T>
public interface ChooserWidget<T>
A widget for choosing elements of type <T>.
Author:
Per-Erik

  • Method Details

    • findChosenValue

      void findChosenValue(ChooserCallback<T> callback)
      Finds the currently chosen value. If more than one value can be selected, finds the lead selection. This method takes a callback in case the implementer need to load aditional data before it can fully determine what has been choosen. If a filter is currently being applied in the background, the callback should be called with an empty list.
      Parameters:
      callback - The callback used to inform the caller when the selection and all data needed has been loaded.

    • setPreselectedValue

      void setPreselectedValue(T preselected)
      Sets a preselected value. If the filter allows it, and it is possible to select a value without interfering with the users selection, this widget should select the given value. If a filter is applying, the selection should be applied when the filter process is done. Note that the selected value should be treated exactly as if the selection was made by the user. Thus, a call to this method must be followed by a call to findChosenValue to actually choose the value (as opposed to just selecting it). Also note that the behaviour of calling this method in between calls to findChosenValue and its callback is undefined. (After calling findChosenValue, always wait for the callback to be called before calling this method.)

      NOTE: If 'preselected' is not part of what this chooser would be able to choose among, this is a no-op. It is thus not supposed to throw IndexOutOfBoundsException, NullPointerException or similar.

      NOTE: It is up to the implementation whether to use the preselected value after reset() is called.

      NOTE: Implementations may disregard this call completely. Whether a preselction is possible or not is thus implementation specific.
      Parameters:
      preselected - A preselcted value.

    • setCallback

      void setCallback(ChooserCallback<T> callback)
      This is an optional method that may or may not be implemented by the chooser implementation. It is optional in that it either does nothing or it takes this call to mean "when you, the chooser, concider that a valid choice has been made, call this callback". This is usefull if the chooser, for example, displays a list of elements and whant to "return" a value when the user double clicks one of the elements.

      If the implementation uses the callback, it must not be called while findChosenValue is "pending". That is, as soon as findChosenValue is called, the callback sent to that method must be used to communicate back to the client code. To avoid having the callback sent to this method invoked after an invocation on the callback of findChosenValue, it is suggested that any user of a ChooserWidget calls setCallback(null) before any call to findChosenValue or direclty after the callback of findChosenValue has been invoked.
      Parameters:
      callback - A callback that may be used by this chooser to inform the caller that this chooser as found a valid choice. The call may also be ignored by an implementation.

    • setFilter

      void setFilter(ChooserFilter<T> filter)
      Sets a filter on this chooser. The chooser must consult this filter before presenting any value as choosable. Generally, when this method is called, the implementation should apply the filter in the background (this is not mandated, the filter should execute quickly!) and while applying, not letting the user choose anything. If, while applying the filter, a call to findChosenValue is received, it is assumed that the user has not chosen anything and therefore an empty list should be sent to the callback of findChosenValue. Ideally, this also cancels any started background threads that is currently applying the filter.
      To stop the filtering or to cancel the applying of the filter, this method may be called with a parameter of null. As soon as this is registered, succeeding calls to findChosenValue should behave as if a filter was never applyed and the user should once again be able to chose values.

      NOTE: How the filtering is displayed in the chooser component is enterily up to the implementation. It can range from removing elements to dimming them out or simply not make them selectable. The ideal is to remove the elements. What is mandated is that an element for wich filter.accept(elem) returns false, must never be part of the list sent to findChosenValue's callback.

      NOTE: Once a filter is applied, it should continue to hold for any new element that this chooser may discover (if any discovering process is ongoing). NOTE: The results of calling this method after a call to findChosenValue but before a result has been returned to it's callback is undefined. That is, when findChosenValue has been called, always wait for the callback to be invoked before changing the filter. Implementors may thus assume that the filter will not change between a call to findChosenValue and its callback.
      Parameters:
      filter - A chooser filter to be consulted when filtering or null to not filter anything.

    • getChooserComponent

      JComponent getChooserComponent()
      Returns the component used to display this chooser widget.
      Returns:
      the component used to display this chooser widget.

    • reset

      void reset()
      Resets the state of the component. It is up to the implementation to choose what to reset but it is suggested, not mandated, that the call resets the JComponent to a state where it looks as if it was just created. It is also suggested that any selections are cleared.

      NOTE: Resetting the chooser causes any applied filter to be removed. Thus, a reset is also an implicit call to setFilter(null).