A list of items that can be scrolled vertically. More...

Inherits Component, and SettableTooltipClient.

Inherited by FileListComponent, and TableListBox.

Classes
struct	Ids
Public Types
enum	ColourIds { backgroundColourId = 0x1002800, outlineColourId = 0x1002810, textColourId = 0x1002820 }
	A set of colour IDs to use to change the colour of various aspects of the label. More...
Public Member Functions
	ListBox (const String &componentName=String::empty, ListBoxModel *model=nullptr)
	Creates a ListBox.
	~ListBox ()
	Destructor.
void	setModel (ListBoxModel *newModel)
	Changes the current data model to display.
ListBoxModel *	getModel () const noexcept
	Returns the current list model.
void	updateContent ()
	Causes the list to refresh its content.
void	setMultipleSelectionEnabled (bool shouldBeEnabled)
	Turns on multiple-selection of rows.
void	setMouseMoveSelectsRows (bool shouldSelect)
	Makes the list react to mouse moves by selecting the row that the mouse if over.
void	selectRow (int rowNumber, bool dontScrollToShowThisRow=false, bool deselectOthersFirst=true)
	Selects a row.
void	selectRangeOfRows (int firstRow, int lastRow)
	Selects a set of rows.
void	deselectRow (int rowNumber)
	Deselects a row.
void	deselectAllRows ()
	Deselects any currently selected rows.
void	flipRowSelection (int rowNumber)
	Selects or deselects a row.
SparseSet< int >	getSelectedRows () const
	Returns a sparse set indicating the rows that are currently selected.
void	setSelectedRows (const SparseSet< int > &setOfRowsToBeSelected, bool sendNotificationEventToModel=true)
	Sets the rows that should be selected, based on an explicit set of ranges.
bool	isRowSelected (int rowNumber) const
	Checks whether a row is selected.
int	getNumSelectedRows () const
	Returns the number of rows that are currently selected.
int	getSelectedRow (int index=0) const
	Returns the row number of a selected row.
int	getLastRowSelected () const
	Returns the last row that the user selected.
void	selectRowsBasedOnModifierKeys (int rowThatWasClickedOn, const ModifierKeys &modifiers, bool isMouseUpEvent)
	Multiply-selects rows based on the modifier keys.
void	setVerticalPosition (double newProportion)
	Scrolls the list to a particular position.
double	getVerticalPosition () const
	Returns the current vertical position as a proportion of the total.
void	scrollToEnsureRowIsOnscreen (int row)
	Scrolls if necessary to make sure that a particular row is visible.
ScrollBar *	getVerticalScrollBar () const noexcept
	Returns a pointer to the vertical scrollbar.
ScrollBar *	getHorizontalScrollBar () const noexcept
	Returns a pointer to the horizontal scrollbar.
int	getRowContainingPosition (int x, int y) const noexcept
	Finds the row index that contains a given x,y position.
int	getInsertionIndexForPosition (int x, int y) const noexcept
	Finds a row index that would be the most suitable place to insert a new item for a given position.
Rectangle< int >	getRowPosition (int rowNumber, bool relativeToComponentTopLeft) const noexcept
	Returns the position of one of the rows, relative to the top-left of the listbox.
Component *	getComponentForRowNumber (int rowNumber) const noexcept
	Finds the row component for a given row in the list.
int	getRowNumberOfComponent (Component *rowComponent) const noexcept
	Returns the row number that the given component represents.
int	getVisibleRowWidth () const noexcept
	Returns the width of a row (which may be less than the width of this component if there's a scrollbar).
void	setRowHeight (int newHeight)
	Sets the height of each row in the list.
int	getRowHeight () const noexcept
	Returns the height of a row in the list.
int	getNumRowsOnScreen () const noexcept
	Returns the number of rows actually visible.
void	setOutlineThickness (int outlineThickness)
	Sets the thickness of a border that will be drawn around the box.
int	getOutlineThickness () const noexcept
	Returns the thickness of outline that will be drawn around the listbox.
void	setHeaderComponent (Component *newHeaderComponent)
	Sets a component that the list should use as a header.
void	setMinimumContentWidth (int newMinimumWidth)
	Changes the width of the rows in the list.
int	getVisibleContentWidth () const noexcept
	Returns the space currently available for the row items, taking into account borders, scrollbars, etc.
void	repaintRow (int rowNumber) noexcept
	Repaints one of the rows.
virtual Image	createSnapshotOfSelectedRows (int &x, int &y)
	This fairly obscure method creates an image that just shows the currently selected row components.
Viewport *	getViewport () const noexcept
	Returns the viewport that this ListBox uses.
void	refreshFromValueTree (const ValueTree &, ComponentBuilder &)
bool	keyPressed (const KeyPress &)
bool	keyStateChanged (bool isKeyDown)
void	paint (Graphics &)
void	paintOverChildren (Graphics &)
void	resized ()
void	visibilityChanged ()
void	mouseWheelMove (const MouseEvent &, float wheelIncrementX, float wheelIncrementY)
void	mouseMove (const MouseEvent &)
void	mouseExit (const MouseEvent &)
void	mouseUp (const MouseEvent &)
void	colourChanged ()
void	startDragAndDrop (const MouseEvent &, const var &dragDescription, bool allowDraggingToOtherWindows)

Detailed Description

A list of items that can be scrolled vertically.

To create a list, you'll need to create a subclass of ListBoxModel. This can either paint each row of the list and respond to events via callbacks, or for more specialised tasks, it can supply a custom component to fill each row.

See also:: ComboBox, TableListBox

Member Enumeration Documentation

enum ListBox::ColourIds

A set of colour IDs to use to change the colour of various aspects of the label.

These constants can be used either via the Component::setColour(), or LookAndFeel::setColour() methods.

See also:: Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour

Enumerator:

backgroundColourId

The background colour to fill the list with.

Make this transparent if you don't want the background to be filled.

outlineColourId

An optional colour to use to draw a border around the list.

Make this transparent to not have an outline.

textColourId

The preferred colour to use for drawing text in the listbox.

Constructor & Destructor Documentation

ListBox::ListBox	(	const String &	componentName = `String::empty`,
		ListBoxModel *	model = `nullptr`
	)

Creates a ListBox.

The model pointer passed-in can be null, in which case you can set it later with setModel().

ListBox::~ListBox ( )

Destructor.

Member Function Documentation

void ListBox::setModel ( ListBoxModel * newModel )

Changes the current data model to display.

ListBoxModel* ListBox::getModel ( ) const

Returns the current list model.

Reimplemented in TableListBox.

void ListBox::updateContent ( )

Causes the list to refresh its content.

Call this when the number of rows in the list changes, or if you want it to call refreshComponentForRow() on all the row components.

This must only be called from the main message thread.

void ListBox::setMultipleSelectionEnabled ( bool shouldBeEnabled )

Turns on multiple-selection of rows.

By default this is disabled.

When your row component gets clicked you'll need to call the selectRowsBasedOnModifierKeys() method to tell the list that it's been clicked and to get it to do the appropriate selection based on whether the ctrl/shift keys are held down.

void ListBox::setMouseMoveSelectsRows ( bool shouldSelect )

Makes the list react to mouse moves by selecting the row that the mouse if over.

This function is here primarily for the ComboBox class to use, but might be useful for some other purpose too.

void ListBox::selectRow	(	int	rowNumber,
		bool	dontScrollToShowThisRow = `false`,
		bool	deselectOthersFirst = `true`
	)

Selects a row.

If the row is already selected, this won't do anything.

Parameters:

rowNumber	the row to select
dontScrollToShowThisRow	if true, the list's position won't change; if false and the selected row is off-screen, it'll scroll to make sure that row is on-screen
deselectOthersFirst	if true and there are multiple selections, these will first be deselected before this item is selected

See also:: isRowSelected, selectRowsBasedOnModifierKeys, flipRowSelection, deselectRow, deselectAllRows, selectRangeOfRows

void ListBox::selectRangeOfRows	(	int	firstRow,
		int	lastRow
	)

Selects a set of rows.

This will add these rows to the current selection, so you might need to clear the current selection first with deselectAllRows()

Parameters:

firstRow	the first row to select (inclusive)
lastRow	the last row to select (inclusive)

void ListBox::deselectRow ( int rowNumber )

Deselects a row.

If it's not currently selected, this will do nothing.

See also:: selectRow, deselectAllRows

void ListBox::deselectAllRows ( )

Deselects any currently selected rows.

See also:: deselectRow

void ListBox::flipRowSelection ( int rowNumber )

Selects or deselects a row.

If the row's currently selected, this deselects it, and vice-versa.

SparseSet<int> ListBox::getSelectedRows ( ) const

Returns a sparse set indicating the rows that are currently selected.

See also:: setSelectedRows

void ListBox::setSelectedRows	(	const SparseSet< int > &	setOfRowsToBeSelected,
		bool	sendNotificationEventToModel = `true`
	)

Sets the rows that should be selected, based on an explicit set of ranges.

If sendNotificationEventToModel is true, the ListBoxModel::selectedRowsChanged() method will be called. If it's false, no notification will be sent to the model.

See also:: getSelectedRows

bool ListBox::isRowSelected ( int rowNumber ) const

Checks whether a row is selected.

int ListBox::getNumSelectedRows ( ) const

Returns the number of rows that are currently selected.

See also:: getSelectedRow, isRowSelected, getLastRowSelected

int ListBox::getSelectedRow ( int index = 0 ) const

Returns the row number of a selected row.

This will return the row number of the Nth selected row. The row numbers returned will be sorted in order from low to high.

Parameters:

index the index of the selected row to return, (from 0 to getNumSelectedRows() - 1)

Returns:: the row number, or -1 if the index was out of range or if there aren't any rows selected

See also:: getNumSelectedRows, isRowSelected, getLastRowSelected

int ListBox::getLastRowSelected ( ) const

Returns the last row that the user selected.

This isn't the same as the highest row number that is currently selected - if the user had multiply-selected rows 10, 5 and then 6 in that order, this would return 6.

If nothing is selected, it will return -1.

void ListBox::selectRowsBasedOnModifierKeys	(	int	rowThatWasClickedOn,
		const ModifierKeys &	modifiers,
		bool	isMouseUpEvent
	)

Multiply-selects rows based on the modifier keys.

If no modifier keys are down, this will select the given row and deselect any others.

If the ctrl (or command on the Mac) key is down, it'll flip the state of the selected row.

If the shift key is down, it'll select up to the given row from the last row selected.

See also:: selectRow

void ListBox::setVerticalPosition ( double newProportion )

Scrolls the list to a particular position.

The proportion is between 0 and 1.0, so 0 scrolls to the top of the list, 1.0 scrolls to the bottom.

If the total number of rows all fit onto the screen at once, then this method won't do anything.

See also:: getVerticalPosition

double ListBox::getVerticalPosition ( ) const

Returns the current vertical position as a proportion of the total.

This can be used in conjunction with setVerticalPosition() to save and restore the list's position. It returns a value in the range 0 to 1.

See also:: setVerticalPosition

void ListBox::scrollToEnsureRowIsOnscreen ( int row )

Scrolls if necessary to make sure that a particular row is visible.

ScrollBar* ListBox::getVerticalScrollBar ( ) const

Returns a pointer to the vertical scrollbar.

ScrollBar* ListBox::getHorizontalScrollBar ( ) const

Returns a pointer to the horizontal scrollbar.

int ListBox::getRowContainingPosition	(	int	x,
		int	y
	)		const

Finds the row index that contains a given x,y position.

The position is relative to the ListBox's top-left. If no row exists at this position, the method will return -1.

See also:: getComponentForRowNumber

int ListBox::getInsertionIndexForPosition	(	int	x,
		int	y
	)		const

Finds a row index that would be the most suitable place to insert a new item for a given position.

This is useful when the user is e.g. dragging and dropping onto the listbox, because it lets you easily choose the best position to insert the item that they drop, based on where they drop it.

If the position is out of range, this will return -1. If the position is beyond the end of the list, it will return getNumRows() to indicate the end of the list.

See also:: getComponentForRowNumber

Rectangle<int> ListBox::getRowPosition	(	int	rowNumber,
		bool	relativeToComponentTopLeft
	)		const

Returns the position of one of the rows, relative to the top-left of the listbox.

This may be off-screen, and the range of the row number that is passed-in is not checked to see if it's a valid row.

Component* ListBox::getComponentForRowNumber ( int rowNumber ) const

Finds the row component for a given row in the list.

The component returned will have been created using createRowComponent().

If the component for this row is off-screen or if the row is out-of-range, this will return 0.

See also:: getRowContainingPosition

int ListBox::getRowNumberOfComponent ( Component * rowComponent ) const

Returns the row number that the given component represents.

If the component isn't one of the list's rows, this will return -1.

int ListBox::getVisibleRowWidth ( ) const

Returns the width of a row (which may be less than the width of this component if there's a scrollbar).

void ListBox::setRowHeight ( int newHeight )

Sets the height of each row in the list.

The default height is 22 pixels.

See also:: getRowHeight

int ListBox::getRowHeight ( ) const

Returns the height of a row in the list.

See also:: setRowHeight

int ListBox::getNumRowsOnScreen ( ) const

Returns the number of rows actually visible.

This is the number of whole rows which will fit on-screen, so the value might be more than the actual number of rows in the list.

void ListBox::setOutlineThickness ( int outlineThickness )

Sets the thickness of a border that will be drawn around the box.

To set the colour of the outline, use

 setColour (ListBox::outlineColourId, colourXYZ);

See also:: outlineColourId

int ListBox::getOutlineThickness ( ) const

Returns the thickness of outline that will be drawn around the listbox.

See also:: setOutlineColour

void ListBox::setHeaderComponent ( Component * newHeaderComponent )

Sets a component that the list should use as a header.

This will position the given component at the top of the list, maintaining the height of the component passed-in, but rescaling it horizontally to match the width of the items in the listbox.

The component will be deleted when setHeaderComponent() is called with a different component, or when the listbox is deleted.

void ListBox::setMinimumContentWidth ( int newMinimumWidth )

Changes the width of the rows in the list.

This can be used to make the list's row components wider than the list itself - the width of the rows will be either the width of the list or this value, whichever is greater, and if the rows become wider than the list, a horizontal scrollbar will appear.

The default value for this is 0, which means that the rows will always be the same width as the list.

int ListBox::getVisibleContentWidth ( ) const

Returns the space currently available for the row items, taking into account borders, scrollbars, etc.

void ListBox::repaintRow ( int rowNumber )

Repaints one of the rows.

This does not invoke updateContent(), it just invokes a straightforward repaint for the area covered by this row.

virtual Image ListBox::createSnapshotOfSelectedRows	(	int &	x,
		int &	y
	)		`[virtual]`

This fairly obscure method creates an image that just shows the currently selected row components.

It's a handy method for doing drag-and-drop, as it can be passed to the DragAndDropContainer for use as the drag image.

Note that it will make the row components temporarily invisible, so if you're using custom components this could affect them if they're sensitive to that sort of thing.

See also:: Component::createComponentSnapshot

Viewport* ListBox::getViewport ( ) const

Returns the viewport that this ListBox uses.

You may need to use this to change parameters such as whether scrollbars are shown, etc.

void ListBox::refreshFromValueTree	(	const ValueTree &	,
		ComponentBuilder &
	)

bool ListBox::keyPressed ( const KeyPress & ) [virtual]

Reimplemented from Component.

bool ListBox::keyStateChanged ( bool isKeyDown ) [virtual]

Reimplemented from Component.

void ListBox::paint ( Graphics & ) [virtual]

Reimplemented from Component.

void ListBox::paintOverChildren ( Graphics & ) [virtual]

Reimplemented from Component.

void ListBox::resized ( ) [virtual]

Reimplemented from Component.

Reimplemented in TableListBox.

void ListBox::visibilityChanged ( ) [virtual]

Reimplemented from Component.

void ListBox::mouseWheelMove	(	const MouseEvent &	,
		float	wheelIncrementX,
		float	wheelIncrementY
	)		`[virtual]`

Reimplemented from Component.

void ListBox::mouseMove ( const MouseEvent & ) [virtual]

Reimplemented from Component.

void ListBox::mouseExit ( const MouseEvent & ) [virtual]

Reimplemented from Component.

void ListBox::mouseUp ( const MouseEvent & ) [virtual]

Reimplemented from Component.

void ListBox::colourChanged ( ) [virtual]

Reimplemented from Component.

void ListBox::startDragAndDrop	(	const MouseEvent &	,
		const var &	dragDescription,
		bool	allowDraggingToOtherWindows
	)

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

juce_ListBox.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation