JUCE
Public Types | Public Member Functions | List of all members
SelectedItemSet< SelectableItemType > Class Template Reference

Manages a list of selectable items. More...

Inheritance diagram for SelectedItemSet< SelectableItemType >:

Public Types

using ItemType = SelectableItemType
 
using ItemArray = Array< SelectableItemType >
 
using ParameterType = typename TypeHelpers::ParameterType< SelectableItemType >::type
 

Public Member Functions

 SelectedItemSet ()=default
 Creates an empty set. More...
 
 SelectedItemSet (const ItemArray &items)
 Creates a set based on an array of items. More...
 
 SelectedItemSet (const SelectedItemSet &other)
 Creates a copy of another set. More...
 
SelectedItemSetoperator= (const SelectedItemSet &other)
 Creates a copy of another set. More...
 
void selectOnly (ParameterType item)
 Clears any other currently selected items, and selects this item. More...
 
void addToSelection (ParameterType item)
 Selects an item. More...
 
void addToSelectionBasedOnModifiers (ParameterType item, ModifierKeys modifiers)
 Selects or deselects an item. More...
 
bool addToSelectionOnMouseDown (ParameterType item, ModifierKeys modifiers)
 Selects or deselects items that can also be dragged, based on a mouse-down event. More...
 
void addToSelectionOnMouseUp (ParameterType item, ModifierKeys modifiers, const bool wasItemDragged, const bool resultOfMouseDownSelectMethod)
 Selects or deselects items that can also be dragged, based on a mouse-up event. More...
 
void deselect (ParameterType item)
 Deselects an item. More...
 
void deselectAll ()
 Deselects all items. More...
 
int getNumSelected () const noexcept
 Returns the number of currently selected items. More...
 
SelectableItemType getSelectedItem (const int index) const
 Returns one of the currently selected items. More...
 
bool isSelected (ParameterType item) const noexcept
 True if this item is currently selected. More...
 
const ItemArraygetItemArray () const noexcept
 Provides access to the array of items. More...
 
SelectableItemType * begin () noexcept
 Provides iterator access to the array of items. More...
 
const SelectableItemType * begin () const noexcept
 
SelectableItemType * end () noexcept
 Provides iterator access to the array of items. More...
 
const SelectableItemType * end () const noexcept
 Provides iterator access to the array of items. More...
 
virtual void itemSelected (SelectableItemType)
 Can be overridden to do special handling when an item is selected. More...
 
virtual void itemDeselected (SelectableItemType)
 Can be overridden to do special handling when an item is deselected. More...
 
void changed ()
 Used internally, but can be called to force a change message to be sent to the ChangeListeners. More...
 
void changed (const bool synchronous)
 Used internally, but can be called to force a change message to be sent to the ChangeListeners. More...
 
- Public Member Functions inherited from ChangeBroadcaster
 ChangeBroadcaster () noexcept
 Creates an ChangeBroadcaster. More...
 
virtual ~ChangeBroadcaster ()
 Destructor. More...
 
void addChangeListener (ChangeListener *listener)
 Registers a listener to receive change callbacks from this broadcaster. More...
 
void removeChangeListener (ChangeListener *listener)
 Unregisters a listener from the list. More...
 
void removeAllChangeListeners ()
 Removes all listeners from the list. More...
 
void sendChangeMessage ()
 Causes an asynchronous change message to be sent to all the registered listeners. More...
 
void sendSynchronousChangeMessage ()
 Sends a synchronous change message to all the registered listeners. More...
 
void dispatchPendingMessages ()
 If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...
 

Detailed Description

template<class SelectableItemType>
class SelectedItemSet< SelectableItemType >

Manages a list of selectable items.

Use one of these to keep a track of things that the user has highlighted, like icons or things in a list.

The class is templated so that you can use it to hold either a set of pointers to objects, or a set of ID numbers or handles, for cases where each item may not always have a corresponding object.

To be informed when items are selected/deselected, register a ChangeListener with this object.

Member Typedef Documentation

◆ ItemType

template<class SelectableItemType >
using SelectedItemSet< SelectableItemType >::ItemType = SelectableItemType

◆ ItemArray

template<class SelectableItemType >
using SelectedItemSet< SelectableItemType >::ItemArray = Array<SelectableItemType>

◆ ParameterType

template<class SelectableItemType >
using SelectedItemSet< SelectableItemType >::ParameterType = typename TypeHelpers::ParameterType<SelectableItemType>::type

Constructor & Destructor Documentation

◆ SelectedItemSet() [1/3]

template<class SelectableItemType >
SelectedItemSet< SelectableItemType >::SelectedItemSet ( )
default

Creates an empty set.

◆ SelectedItemSet() [2/3]

template<class SelectableItemType >
SelectedItemSet< SelectableItemType >::SelectedItemSet ( const ItemArray items)
explicit

Creates a set based on an array of items.

◆ SelectedItemSet() [3/3]

template<class SelectableItemType >
SelectedItemSet< SelectableItemType >::SelectedItemSet ( const SelectedItemSet< SelectableItemType > &  other)

Creates a copy of another set.

Member Function Documentation

◆ operator=()

template<class SelectableItemType >
SelectedItemSet& SelectedItemSet< SelectableItemType >::operator= ( const SelectedItemSet< SelectableItemType > &  other)

◆ selectOnly()

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::selectOnly ( ParameterType  item)

◆ addToSelection()

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::addToSelection ( ParameterType  item)

◆ addToSelectionBasedOnModifiers()

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::addToSelectionBasedOnModifiers ( ParameterType  item,
ModifierKeys  modifiers 
)

Selects or deselects an item.

This will use the modifier keys to decide whether to deselect other items first.

So if the shift key is held down, the item will be added without deselecting anything (same as calling addToSelection() )

If no modifiers are down, the current selection will be cleared first (same as calling selectOnly() )

If the ctrl (or command on the Mac) key is held down, the item will be toggled - so it'll be added to the set unless it's already there, in which case it'll be deselected.

If the items that you're selecting can also be dragged, you may need to use the addToSelectionOnMouseDown() and addToSelectionOnMouseUp() calls to handle the subtleties of this kind of usage.

See also
selectOnly, addToSelection, addToSelectionOnMouseDown, addToSelectionOnMouseUp

References SelectedItemSet< SelectableItemType >::addToSelection(), SelectedItemSet< SelectableItemType >::deselect(), ModifierKeys::isCommandDown(), SelectedItemSet< SelectableItemType >::isSelected(), ModifierKeys::isShiftDown(), and SelectedItemSet< SelectableItemType >::selectOnly().

Referenced by SelectedItemSet< SelectableItemType >::addToSelectionOnMouseDown(), and SelectedItemSet< SelectableItemType >::addToSelectionOnMouseUp().

◆ addToSelectionOnMouseDown()

template<class SelectableItemType >
bool SelectedItemSet< SelectableItemType >::addToSelectionOnMouseDown ( ParameterType  item,
ModifierKeys  modifiers 
)

Selects or deselects items that can also be dragged, based on a mouse-down event.

If you call addToSelectionOnMouseDown() at the start of your mouseDown event, and then call addToSelectionOnMouseUp() at the end of your mouseUp event, this makes it easy to handle multiple-selection of sets of objects that can also be dragged.

For example, if you have several items already selected, and you click on one of them (without dragging), then you'd expect this to deselect the other, and just select the item you clicked on. But if you had clicked on this item and dragged it, you'd have expected them all to stay selected.

When you call this method, you'll need to store the boolean result, because the addToSelectionOnMouseUp() method will need to be know this value.

See also
addToSelectionOnMouseUp, addToSelectionBasedOnModifiers

References SelectedItemSet< SelectableItemType >::addToSelectionBasedOnModifiers(), ModifierKeys::isPopupMenu(), and SelectedItemSet< SelectableItemType >::isSelected().

◆ addToSelectionOnMouseUp()

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::addToSelectionOnMouseUp ( ParameterType  item,
ModifierKeys  modifiers,
const bool  wasItemDragged,
const bool  resultOfMouseDownSelectMethod 
)

Selects or deselects items that can also be dragged, based on a mouse-up event.

Call this during a mouseUp callback, when you have previously called the addToSelectionOnMouseDown() method during your mouseDown event.

See addToSelectionOnMouseDown() for more info

Parameters
itemthe item to select (or deselect)
modifiersthe modifiers from the mouse-up event
wasItemDraggedtrue if your item was dragged during the mouse click
resultOfMouseDownSelectMethodthis is the boolean return value that came back from the addToSelectionOnMouseDown() call that you should have made during the matching mouseDown event

References SelectedItemSet< SelectableItemType >::addToSelectionBasedOnModifiers().

◆ deselect()

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::deselect ( ParameterType  item)

◆ deselectAll()

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::deselectAll ( )

◆ getNumSelected()

template<class SelectableItemType >
int SelectedItemSet< SelectableItemType >::getNumSelected ( ) const
noexcept

Returns the number of currently selected items.

See also
getSelectedItem

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::size().

◆ getSelectedItem()

template<class SelectableItemType >
SelectableItemType SelectedItemSet< SelectableItemType >::getSelectedItem ( const int  index) const

Returns one of the currently selected items.

If the index is out-of-range, this returns a default-constructed SelectableItemType.

See also
getNumSelected

◆ isSelected()

template<class SelectableItemType >
bool SelectedItemSet< SelectableItemType >::isSelected ( ParameterType  item) const
noexcept

◆ getItemArray()

template<class SelectableItemType >
const ItemArray& SelectedItemSet< SelectableItemType >::getItemArray ( ) const
noexcept

Provides access to the array of items.

◆ begin() [1/2]

template<class SelectableItemType >
SelectableItemType* SelectedItemSet< SelectableItemType >::begin ( )
noexcept

Provides iterator access to the array of items.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::begin().

◆ begin() [2/2]

template<class SelectableItemType >
const SelectableItemType* SelectedItemSet< SelectableItemType >::begin ( ) const
noexcept

◆ end() [1/2]

template<class SelectableItemType >
SelectableItemType* SelectedItemSet< SelectableItemType >::end ( )
noexcept

Provides iterator access to the array of items.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::end().

◆ end() [2/2]

template<class SelectableItemType >
const SelectableItemType* SelectedItemSet< SelectableItemType >::end ( ) const
noexcept

Provides iterator access to the array of items.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::end().

◆ itemSelected()

template<class SelectableItemType >
virtual void SelectedItemSet< SelectableItemType >::itemSelected ( SelectableItemType  )
virtual

Can be overridden to do special handling when an item is selected.

For example, if the item is an object, you might want to call it and tell it that it's being selected.

Referenced by SelectedItemSet< SelectableItemType >::addToSelection(), SelectedItemSet< SelectableItemType >::operator=(), and SelectedItemSet< SelectableItemType >::selectOnly().

◆ itemDeselected()

template<class SelectableItemType >
virtual void SelectedItemSet< SelectableItemType >::itemDeselected ( SelectableItemType  )
virtual

Can be overridden to do special handling when an item is deselected.

For example, if the item is an object, you might want to call it and tell it that it's being deselected.

Referenced by SelectedItemSet< SelectableItemType >::deselect(), SelectedItemSet< SelectableItemType >::deselectAll(), and SelectedItemSet< SelectableItemType >::operator=().

◆ changed() [1/2]

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::changed ( )

◆ changed() [2/2]

template<class SelectableItemType >
void SelectedItemSet< SelectableItemType >::changed ( const bool  synchronous)

Used internally, but can be called to force a change message to be sent to the ChangeListeners.

References JUCE_LEAK_DETECTOR, ChangeBroadcaster::sendChangeMessage(), and ChangeBroadcaster::sendSynchronousChangeMessage().


The documentation for this class was generated from the following file: