Manages a list of selectable items. More...

#include <juce_SelectedItemSet.h>

Inheritance diagram for SelectedItemSet< SelectableItemType >:

Collaboration diagram for SelectedItemSet< SelectableItemType >:

[legend]

Public Types
typedef Array< SelectableItemType >	ItemArray

typedef SelectableItemType	ItemType

typedef TypeHelpers::ParameterType< SelectableItemType >::type	ParameterType

Public Member Functions
	SelectedItemSet ()
	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...

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster. 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...

SelectableItemType *	begin () const noexcept
	Provides iterator access to the array of items. 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...

void	deselect (ParameterType item)
	Deselects an item. More...

void	deselectAll ()
	Deselects all items. More...

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...

SelectableItemType *	end () const noexcept
	Provides iterator access to the array of items. More...

const ItemArray &	getItemArray () const noexcept
	Provides access to the array of 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...

virtual void	itemDeselected (SelectableItemType)
	Can be overridden to do special handling when an item is deselected. More...

virtual void	itemSelected (SelectableItemType)
	Can be overridden to do special handling when an item is selected. More...

SelectedItemSet &	operator= (const SelectedItemSet &other)
	Creates a copy of another set. More...

void	removeAllChangeListeners ()
	Removes all listeners from the list. More...

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list. More...

void	selectOnly (ParameterType item)
	Clears any other currently selected items, and selects this item. 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...

Private Attributes
ItemArray	selectedItems

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

◆ ItemArray

template<class SelectableItemType >

typedef Array<SelectableItemType> SelectedItemSet< SelectableItemType >::ItemArray

◆ ItemType

template<class SelectableItemType >

typedef SelectableItemType SelectedItemSet< SelectableItemType >::ItemType

◆ ParameterType

template<class SelectableItemType >

typedef TypeHelpers::ParameterType<SelectableItemType>::type SelectedItemSet< SelectableItemType >::ParameterType

Constructor & Destructor Documentation

◆ SelectedItemSet() [1/3]

template<class SelectableItemType >

SelectedItemSet< SelectableItemType >::SelectedItemSet ( )

inline

Creates an empty set.

◆ SelectedItemSet() [2/3]

template<class SelectableItemType >

SelectedItemSet< SelectableItemType >::SelectedItemSet ( const ItemArray & items )

inlineexplicit

Creates a set based on an array of items.

◆ SelectedItemSet() [3/3]

template<class SelectableItemType >

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

inline

Creates a copy of another set.

Member Function Documentation

◆ addChangeListener()

void ChangeBroadcaster::addChangeListener ( ChangeListener * listener )

inherited

Registers a listener to receive change callbacks from this broadcaster.

Trying to add a listener that's already on the list will have no effect.

◆ addToSelection()

template<class SelectableItemType >

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

inline

Selects an item.

If the item is already selected, no change notification will be sent out.

See also: selectOnly, addToSelectionBasedOnModifiers

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::add(), SelectedItemSet< SelectableItemType >::changed(), SelectedItemSet< SelectableItemType >::isSelected(), SelectedItemSet< SelectableItemType >::itemSelected(), and SelectedItemSet< SelectableItemType >::selectedItems.

Referenced by SelectedItemSet< SelectableItemType >::addToSelectionBasedOnModifiers().

◆ addToSelectionBasedOnModifiers()

template<class SelectableItemType >

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

inline

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
	)

inline

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
	)

inline

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

item	the item to select (or deselect)
modifiers	the modifiers from the mouse-up event
wasItemDragged	true if your item was dragged during the mouse click
resultOfMouseDownSelectMethod	this 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().

◆ begin()

template<class SelectableItemType >

SelectableItemType* SelectedItemSet< SelectableItemType >::begin ( ) const

inlinenoexcept

Provides iterator access to the array of items.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::begin(), and SelectedItemSet< SelectableItemType >::selectedItems.

◆ changed() [1/2]

template<class SelectableItemType >

void SelectedItemSet< SelectableItemType >::changed ( )

inline

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

References ChangeBroadcaster::sendChangeMessage().

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

◆ changed() [2/2]

template<class SelectableItemType >

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

inline

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

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

◆ deselect()

template<class SelectableItemType >

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

inline

Deselects an item.

References SelectedItemSet< SelectableItemType >::changed(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::indexOf(), SelectedItemSet< SelectableItemType >::itemDeselected(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::removeAndReturn(), and SelectedItemSet< SelectableItemType >::selectedItems.

Referenced by SelectedItemSet< SelectableItemType >::addToSelectionBasedOnModifiers(), and SelectedItemSet< SelectableItemType >::selectOnly().

◆ deselectAll()

template<class SelectableItemType >

void SelectedItemSet< SelectableItemType >::deselectAll ( )

inline

Deselects all items.

References SelectedItemSet< SelectableItemType >::changed(), SelectedItemSet< SelectableItemType >::itemDeselected(), juce::jmin(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::removeAndReturn(), SelectedItemSet< SelectableItemType >::selectedItems, and Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::size().

Referenced by SelectedItemSet< SelectableItemType >::selectOnly().

◆ dispatchPendingMessages()

void ChangeBroadcaster::dispatchPendingMessages ( )

inherited

If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

For thread-safety reasons, you must only call this method on the main message thread.

◆ end()

template<class SelectableItemType >

SelectableItemType* SelectedItemSet< SelectableItemType >::end ( ) const

inlinenoexcept

Provides iterator access to the array of items.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::end(), and SelectedItemSet< SelectableItemType >::selectedItems.

◆ getItemArray()

template<class SelectableItemType >

const ItemArray& SelectedItemSet< SelectableItemType >::getItemArray ( ) const

inlinenoexcept

Provides access to the array of items.

References SelectedItemSet< SelectableItemType >::selectedItems.

◆ getNumSelected()

template<class SelectableItemType >

int SelectedItemSet< SelectableItemType >::getNumSelected ( ) const

inlinenoexcept

Returns the number of currently selected items.

See also: getSelectedItem

References SelectedItemSet< SelectableItemType >::selectedItems, and Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::size().

◆ getSelectedItem()

template<class SelectableItemType >

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

inline

Returns one of the currently selected items.

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

See also: getNumSelected

References SelectedItemSet< SelectableItemType >::selectedItems.

◆ isSelected()

template<class SelectableItemType >

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

inlinenoexcept

True if this item is currently selected.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::contains(), and SelectedItemSet< SelectableItemType >::selectedItems.

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

◆ itemDeselected()

template<class SelectableItemType >

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

inlinevirtual

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=().

◆ itemSelected()

template<class SelectableItemType >

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

inlinevirtual

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().

◆ operator=()

template<class SelectableItemType >

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

inline

Creates a copy of another set.

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::add(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::begin(), SelectedItemSet< SelectableItemType >::changed(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::end(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::getReference(), SelectedItemSet< SelectableItemType >::isSelected(), SelectedItemSet< SelectableItemType >::itemDeselected(), SelectedItemSet< SelectableItemType >::itemSelected(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::removeAndReturn(), SelectedItemSet< SelectableItemType >::selectedItems, and Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::size().

◆ removeAllChangeListeners()

void ChangeBroadcaster::removeAllChangeListeners ( )

inherited

Removes all listeners from the list.

◆ removeChangeListener()

void ChangeBroadcaster::removeChangeListener ( ChangeListener * listener )

inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ selectOnly()

template<class SelectableItemType >

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

inline

Clears any other currently selected items, and selects this item.

If this item is already the only thing selected, no change notification will be sent out.

See also: addToSelection, addToSelectionBasedOnModifiers

References Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::add(), SelectedItemSet< SelectableItemType >::changed(), SelectedItemSet< SelectableItemType >::deselect(), SelectedItemSet< SelectableItemType >::deselectAll(), Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::getUnchecked(), SelectedItemSet< SelectableItemType >::isSelected(), SelectedItemSet< SelectableItemType >::itemSelected(), juce::jmin(), SelectedItemSet< SelectableItemType >::selectedItems, and Array< ElementType, TypeOfCriticalSectionToUse, minimumAllocatedSize >::size().

Referenced by SelectedItemSet< SelectableItemType >::addToSelectionBasedOnModifiers().

◆ sendChangeMessage()

void ChangeBroadcaster::sendChangeMessage ( )

inherited

Causes an asynchronous change message to be sent to all the registered listeners.

The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().

Referenced by SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void ChangeBroadcaster::sendSynchronousChangeMessage ( )

inherited

Sends a synchronous change message to all the registered listeners.

This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.

See also: dispatchPendingMessages

Referenced by SelectedItemSet< SelectableItemType >::changed().

Member Data Documentation

◆ selectedItems

template<class SelectableItemType >

ItemArray SelectedItemSet< SelectableItemType >::selectedItems

private

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

juce_SelectedItemSet.h

Public Types

Public Member Functions

Private Attributes

Detailed Description

template<class SelectableItemType> class SelectedItemSet< SelectableItemType >

Member Typedef Documentation

◆ ItemArray

◆ ItemType

◆ ParameterType

Constructor & Destructor Documentation

◆ SelectedItemSet() [1/3]

◆ SelectedItemSet() [2/3]

◆ SelectedItemSet() [3/3]

Member Function Documentation

◆ addChangeListener()

◆ addToSelection()

◆ addToSelectionBasedOnModifiers()

◆ addToSelectionOnMouseDown()

◆ addToSelectionOnMouseUp()

◆ begin()

◆ changed() [1/2]

◆ changed() [2/2]

◆ deselect()

◆ deselectAll()

◆ dispatchPendingMessages()

◆ end()

◆ getItemArray()

◆ getNumSelected()

◆ getSelectedItem()

◆ isSelected()

◆ itemDeselected()

◆ itemSelected()

◆ operator=()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ selectOnly()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

Member Data Documentation

◆ selectedItems

template<class SelectableItemType>
class SelectedItemSet< SelectableItemType >