ComboBox Class Reference

Inheritance diagram for ComboBox:

Detailed Description

A component that lets the user choose from a drop-down list of choices.

The combo-box has a list of text strings, each with an associated id number, that will be shown in the drop-down list when the user clicks on the component.

The currently selected choice is displayed in the combo-box, and this can either be read-only text, or editable.

To find out when the user selects a different item or edits the text, you can register a ComboBoxListener to receive callbacks.

See also:: ComboBoxListener

Public Types

enum ColourIds {
backgroundColourId = 0x1000b00, textColourId = 0x1000a00, outlineColourId = 0x1000c00, buttonColourId = 0x1000d00,
arrowColourId = 0x1000e00
}

A set of colour IDs to use to change the colour of various aspects of the combo box. More...

Public Member Functions

ComboBox (const String &componentName)

Creates a combo-box.

~ComboBox ()

Destructor.

void setEditableText (const bool isEditable)

Sets whether the test in the combo-box is editable.

bool isTextEditable () const throw ()

Returns true if the text is directly editable.

void setJustificationType (const Justification &justification) throw ()

Sets the style of justification to be used for positioning the text.

const Justification getJustificationType () const throw ()

Returns the current justification for the text box.

void addItem (const String &newItemText, const int newItemId) throw ()

Adds an item to be shown in the drop-down list.

void addSeparator () throw ()

Adds a separator line to the drop-down list.

void addSectionHeading (const String &headingName) throw ()

Adds a heading to the drop-down list, so that you can group the items into different sections.

void setItemEnabled (const int itemId, const bool isEnabled) throw ()

This allows items in the drop-down list to be selectively disabled.

void changeItemText (const int itemId, const String &newText) throw ()

Changes the text for an existing item.

void clear (const bool dontSendChangeMessage=false)

Removes all the items from the drop-down list.

int getNumItems () const throw ()

Returns the number of items that have been added to the list.

const String getItemText (const int index) const throw ()

Returns the text for one of the items in the list.

int getItemId (const int index) const throw ()

Returns the ID for one of the items in the list.

int getSelectedId () const throw ()

Returns the ID of the item that's currently shown in the box.

void setSelectedId (const int newItemId, const bool dontSendChangeMessage=false) throw ()

Sets one of the items to be the current selection.

int getSelectedItemIndex () const throw ()

Returns the index of the item that's currently shown in the box.

void setSelectedItemIndex (const int newItemIndex, const bool dontSendChangeMessage=false) throw ()

Sets one of the items to be the current selection.

const String getText () const throw ()

Returns the text that is currently shown in the combo-box's text field.

void setText (const String &newText, const bool dontSendChangeMessage=false) throw ()

Sets the contents of the combo-box's text field.

void showEditor ()

Programmatically opens the text editor to allow the user to edit the current item.

void addListener (ComboBoxListener *const listener) throw ()

Registers a listener that will be called when the box's content changes.

void removeListener (ComboBoxListener *const listener) throw ()

Deregisters a previously-registered listener.

void setTextWhenNothingSelected (const String &newMessage) throw ()

Sets a message to display when there is no item currently selected.

const String getTextWhenNothingSelected () const throw ()

Returns the text that is shown when no item is selected.

void setTextWhenNoChoicesAvailable (const String &newMessage) throw ()

Sets the message to show when there are no items in the list, and the user clicks on the drop-down box.

const String getTextWhenNoChoicesAvailable () const throw ()

Returns the text shown when no items have been added to the list.

void setTooltip (const String &newTooltip)

Gives the ComboBox a tooltip.

void labelTextChanged (Label *)

void enablementChanged ()

void colourChanged ()

void focusGained (Component::FocusChangeType cause)

void focusLost (Component::FocusChangeType cause)

void handleAsyncUpdate ()

const String getTooltip ()

void mouseDown (const MouseEvent &)

void mouseDrag (const MouseEvent &)

void mouseUp (const MouseEvent &)

void lookAndFeelChanged ()

void paint (Graphics &)

void resized ()

bool keyStateChanged ()

bool keyPressed (const KeyPress &)

Member Enumeration Documentation

enum ComboBox::ColourIds

A set of colour IDs to use to change the colour of various aspects of the combo box.
These constants can be used either via the Component::setColour(), or LookAndFeel::setColour() methods.
To change the colours of the menu that pops up

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

Enumerator:

backgroundColourId The background colour to fill the box with.

textColourId The colour for the text in the box.

outlineColourId The colour for an outline around the box.

buttonColourId The base colour for the button (a LookAndFeel class will probably use variations on this).

arrowColourId The colour for the arrow shape that pops up the menu.

Constructor & Destructor Documentation

ComboBox::ComboBox ( const String & componentName )

Creates a combo-box.
On construction, the text field will be empty, so you should call the setSelectedId() or setText() method to choose the initial value before displaying it.

Parameters:

componentName the name to set for the component (see Component::setName())

ComboBox::~ComboBox ( )

Destructor.

Member Function Documentation

void ComboBox::setEditableText ( const bool isEditable )

Sets whether the test in the combo-box is editable.
The default state for a new ComboBox is non-editable, and can only be changed by choosing from the drop-down list.

bool ComboBox::isTextEditable ( ) const throw ()

Returns true if the text is directly editable.

See also:
setEditableText

void ComboBox::setJustificationType ( const Justification & justification ) throw ()

Sets the style of justification to be used for positioning the text.
The default is Justification::centredLeft. The text is displayed using a Label component inside the ComboBox.

const Justification ComboBox::getJustificationType ( ) const throw ()

Returns the current justification for the text box.

See also:
setJustificationType

void ComboBox::addItem ( const String & newItemText,

const int newItemId

) throw ()

Adds an item to be shown in the drop-down list.

Parameters:

newItemText the text of the item to show in the list

newItemId an associated ID number that can be set or retrieved - see getSelectedId() and setSelectedId()

See also:
setItemEnabled, addSeparator, addSectionHeading, removeItem, getNumItems, getItemText, getItemId

void ComboBox::addSeparator ( ) throw ()

Adds a separator line to the drop-down list.
This is like adding a separator to a popup menu. See PopupMenu::addSeparator().

void ComboBox::addSectionHeading ( const String & headingName ) throw ()

Adds a heading to the drop-down list, so that you can group the items into different sections.
The headings are indented slightly differently to set them apart from the items on the list, and obviously can't be selected. You might want to add separators between your sections too.

See also:
addItem, addSeparator

void ComboBox::setItemEnabled ( const int itemId,

const bool isEnabled

) throw ()

This allows items in the drop-down list to be selectively disabled.
When you add an item, it's enabled by default, but you can call this method to change its status.
If you disable an item which is already selected, this won't change the current selection - it just stops the user choosing that item from the list.

void ComboBox::changeItemText ( const int itemId,

const String & newText

) throw ()

Changes the text for an existing item.

void ComboBox::clear ( const bool dontSendChangeMessage = false )

Removes all the items from the drop-down list.
If this call causes the content to be cleared, then a change-message will be broadcast unless dontSendChangeMessage is true.

See also:
addItem, removeItem, getNumItems

int ComboBox::getNumItems ( ) const throw ()

Returns the number of items that have been added to the list.
Note that this doesn't include headers or separators.

const String ComboBox::getItemText ( const int index ) const throw ()

Returns the text for one of the items in the list.
Note that this doesn't include headers or separators.

Parameters:

index the item's index from 0 to (getNumItems() - 1)

int ComboBox::getItemId ( const int index ) const throw ()

Returns the ID for one of the items in the list.
Note that this doesn't include headers or separators.

Parameters:

index the item's index from 0 to (getNumItems() - 1)

int ComboBox::getSelectedId ( ) const throw ()

Returns the ID of the item that's currently shown in the box.
If no item is selected, or if the text is editable and the user has entered something which isn't one of the items in the list, then this will return 0.

See also:
setSelectedId, getSelectedItemIndex, getText

void ComboBox::setSelectedId ( const int newItemId,

const bool dontSendChangeMessage = false

) throw ()

Sets one of the items to be the current selection.
This will set the ComboBox's text to that of the item that matches this ID.

Parameters:

newItemId the new item to select

dontSendChangeMessage if set to true, this method won't trigger a change notification

See also:
getSelectedId, setSelectedItemIndex, setText

int ComboBox::getSelectedItemIndex ( ) const throw ()

Returns the index of the item that's currently shown in the box.
If no item is selected, or if the text is editable and the user has entered something which isn't one of the items in the list, then this will return -1.

See also:
setSelectedItemIndex, getSelectedId, getText

void ComboBox::setSelectedItemIndex ( const int newItemIndex,

const bool dontSendChangeMessage = false

) throw ()

Sets one of the items to be the current selection.
This will set the ComboBox's text to that of the item at the given index in the list.

Parameters:

newItemIndex the new item to select

dontSendChangeMessage if set to true, this method won't trigger a change notification

See also:
getSelectedItemIndex, setSelectedId, setText

const String ComboBox::getText ( ) const throw ()

Returns the text that is currently shown in the combo-box's text field.
If the ComboBox has editable text, then this text may have been edited by the user; otherwise it will be one of the items from the list, or possibly an empty string if nothing was selected.

See also:
setText, getSelectedId, getSelectedItemIndex

void ComboBox::setText ( const String & newText,

const bool dontSendChangeMessage = false

) throw ()

Sets the contents of the combo-box's text field.
The text passed-in will be set as the current text regardless of whether it is one of the items in the list. If the current text isn't one of the items, then getSelectedId() will return -1, otherwise it wil return the approriate ID.

Parameters:

newText the text to select

dontSendChangeMessage if set to true, this method won't trigger a change notification

See also:
getText

void ComboBox::showEditor ( )

Programmatically opens the text editor to allow the user to edit the current item.
This is the same effect as when the box is clicked-on.
See also:
Label::showEditor();

void ComboBox::addListener ( ComboBoxListener *const listener ) throw ()

Registers a listener that will be called when the box's content changes.

void ComboBox::removeListener ( ComboBoxListener *const listener ) throw ()

Deregisters a previously-registered listener.

void ComboBox::setTextWhenNothingSelected ( const String & newMessage ) throw ()

Sets a message to display when there is no item currently selected.

See also:
getTextWhenNothingSelected

const String ComboBox::getTextWhenNothingSelected ( ) const throw ()

Returns the text that is shown when no item is selected.

See also:
setTextWhenNothingSelected

void ComboBox::setTextWhenNoChoicesAvailable ( const String & newMessage ) throw ()

Sets the message to show when there are no items in the list, and the user clicks on the drop-down box.
By default it just says "no choices", but this lets you change it to something more meaningful.

const String ComboBox::getTextWhenNoChoicesAvailable ( ) const throw ()

Returns the text shown when no items have been added to the list.

See also:
setTextWhenNoChoicesAvailable

void ComboBox::setTooltip ( const String & newTooltip ) [virtual]

Gives the ComboBox a tooltip.

Reimplemented from SettableTooltipClient.

void ComboBox::labelTextChanged ( Label * ) [virtual]

For internal use only.

Implements LabelListener.

void ComboBox::enablementChanged ( ) [virtual]

For internal use only.

Reimplemented from Component.

void ComboBox::colourChanged ( ) [virtual]

For internal use only.

Reimplemented from Component.

void ComboBox::focusGained ( Component::FocusChangeType cause ) [virtual]

For internal use only.

Reimplemented from Component.

void ComboBox::focusLost ( Component::FocusChangeType cause ) [virtual]

For internal use only.

Reimplemented from Component.

void ComboBox::handleAsyncUpdate ( ) [virtual]

For internal use only.

Implements AsyncUpdater.

const String ComboBox::getTooltip ( ) [virtual]

For internal use only.

Reimplemented from SettableTooltipClient.

void ComboBox::mouseDown ( const MouseEvent & ) [virtual]

For internal use only.

Reimplemented from Component.

void ComboBox::mouseDrag ( const MouseEvent & ) [virtual]

For internal use only.

Reimplemented from Component.

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

For internal use only.

Reimplemented from Component.

void ComboBox::lookAndFeelChanged ( ) [virtual]

For internal use only.

Reimplemented from Component.

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

For internal use only.

Reimplemented from Component.

void ComboBox::resized ( ) [virtual]

For internal use only.

Reimplemented from Component.

bool ComboBox::keyStateChanged ( ) [virtual]

For internal use only.

Reimplemented from Component.

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

For internal use only.

Reimplemented from Component.

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

juce_ComboBox.h


Public Types
enum	ColourIds { backgroundColourId = 0x1000b00, textColourId = 0x1000a00, outlineColourId = 0x1000c00, buttonColourId = 0x1000d00, arrowColourId = 0x1000e00 }
	A set of colour IDs to use to change the colour of various aspects of the combo box. More...
Public Member Functions
	ComboBox (const String &componentName)
	Creates a combo-box.
	~ComboBox ()
	Destructor.
void	setEditableText (const bool isEditable)
	Sets whether the test in the combo-box is editable.
bool	isTextEditable () const throw ()
	Returns true if the text is directly editable.
void	setJustificationType (const Justification &justification) throw ()
	Sets the style of justification to be used for positioning the text.
const Justification	getJustificationType () const throw ()
	Returns the current justification for the text box.
void	addItem (const String &newItemText, const int newItemId) throw ()
	Adds an item to be shown in the drop-down list.
void	addSeparator () throw ()
	Adds a separator line to the drop-down list.
void	addSectionHeading (const String &headingName) throw ()
	Adds a heading to the drop-down list, so that you can group the items into different sections.
void	setItemEnabled (const int itemId, const bool isEnabled) throw ()
	This allows items in the drop-down list to be selectively disabled.
void	changeItemText (const int itemId, const String &newText) throw ()
	Changes the text for an existing item.
void	clear (const bool dontSendChangeMessage=false)
	Removes all the items from the drop-down list.
int	getNumItems () const throw ()
	Returns the number of items that have been added to the list.
const String	getItemText (const int index) const throw ()
	Returns the text for one of the items in the list.
int	getItemId (const int index) const throw ()
	Returns the ID for one of the items in the list.
int	getSelectedId () const throw ()
	Returns the ID of the item that's currently shown in the box.
void	setSelectedId (const int newItemId, const bool dontSendChangeMessage=false) throw ()
	Sets one of the items to be the current selection.
int	getSelectedItemIndex () const throw ()
	Returns the index of the item that's currently shown in the box.
void	setSelectedItemIndex (const int newItemIndex, const bool dontSendChangeMessage=false) throw ()
	Sets one of the items to be the current selection.
const String	getText () const throw ()
	Returns the text that is currently shown in the combo-box's text field.
void	setText (const String &newText, const bool dontSendChangeMessage=false) throw ()
	Sets the contents of the combo-box's text field.
void	showEditor ()
	Programmatically opens the text editor to allow the user to edit the current item.
void	addListener (ComboBoxListener *const listener) throw ()
	Registers a listener that will be called when the box's content changes.
void	removeListener (ComboBoxListener *const listener) throw ()
	Deregisters a previously-registered listener.
void	setTextWhenNothingSelected (const String &newMessage) throw ()
	Sets a message to display when there is no item currently selected.
const String	getTextWhenNothingSelected () const throw ()
	Returns the text that is shown when no item is selected.
void	setTextWhenNoChoicesAvailable (const String &newMessage) throw ()
	Sets the message to show when there are no items in the list, and the user clicks on the drop-down box.
const String	getTextWhenNoChoicesAvailable () const throw ()
	Returns the text shown when no items have been added to the list.
void	setTooltip (const String &newTooltip)
	Gives the ComboBox a tooltip.
void	labelTextChanged (Label *)
void	enablementChanged ()
void	colourChanged ()
void	focusGained (Component::FocusChangeType cause)
void	focusLost (Component::FocusChangeType cause)
void	handleAsyncUpdate ()
const String	getTooltip ()
void	mouseDown (const MouseEvent &)
void	mouseDrag (const MouseEvent &)
void	mouseUp (const MouseEvent &)
void	lookAndFeelChanged ()
void	paint (Graphics &)
void	resized ()
bool	keyStateChanged ()
bool	keyPressed (const KeyPress &)