A component that lets the user choose from a drop-down list of choices. More...
Inherits Component, SettableTooltipClient, Label::Listener, Value::Listener, and AsyncUpdater.
Classes | |
| class | Listener |
| A class for receiving events from a ComboBox. More... | |
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=String::empty) | |
| Creates a combo-box. | |
| ~ComboBox () | |
| Destructor. | |
| void | setEditableText (bool isEditable) |
| Sets whether the test in the combo-box is editable. | |
| bool | isTextEditable () const noexcept |
| Returns true if the text is directly editable. | |
| void | setJustificationType (const Justification &justification) |
| Sets the style of justification to be used for positioning the text. | |
| const Justification | getJustificationType () const noexcept |
| Returns the current justification for the text box. | |
| void | addItem (const String &newItemText, int newItemId) |
| Adds an item to be shown in the drop-down list. | |
| void | addSeparator () |
| Adds a separator line to the drop-down list. | |
| void | addSectionHeading (const String &headingName) |
| Adds a heading to the drop-down list, so that you can group the items into different sections. | |
| void | setItemEnabled (int itemId, bool shouldBeEnabled) |
| This allows items in the drop-down list to be selectively disabled. | |
| bool | isItemEnabled (int itemId) const noexcept |
| Returns true if the given item is enabled. | |
| void | changeItemText (int itemId, const String &newText) |
| Changes the text for an existing item. | |
| void | clear (bool dontSendChangeMessage=false) |
| Removes all the items from the drop-down list. | |
| int | getNumItems () const noexcept |
| Returns the number of items that have been added to the list. | |
| String | getItemText (int index) const |
| Returns the text for one of the items in the list. | |
| int | getItemId (int index) const noexcept |
| Returns the ID for one of the items in the list. | |
| int | indexOfItemId (int itemId) const noexcept |
| Returns the index in the list of a particular item ID. | |
| int | getSelectedId () const noexcept |
| Returns the ID of the item that's currently shown in the box. | |
| Value & | getSelectedIdAsValue () |
| Returns a Value object that can be used to get or set the selected item's ID. | |
| void | setSelectedId (int newItemId, bool dontSendChangeMessage=false) |
| Sets one of the items to be the current selection. | |
| int | getSelectedItemIndex () const |
| Returns the index of the item that's currently shown in the box. | |
| void | setSelectedItemIndex (int newItemIndex, bool dontSendChangeMessage=false) |
| Sets one of the items to be the current selection. | |
| String | getText () const |
| Returns the text that is currently shown in the combo-box's text field. | |
| void | setText (const String &newText, bool dontSendChangeMessage=false) |
| 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 | showPopup () |
| Pops up the combo box's list. | |
| void | addListener (Listener *listener) |
| Registers a listener that will be called when the box's content changes. | |
| void | removeListener (Listener *listener) |
| Deregisters a previously-registered listener. | |
| void | setTextWhenNothingSelected (const String &newMessage) |
| Sets a message to display when there is no item currently selected. | |
| String | getTextWhenNothingSelected () const |
| Returns the text that is shown when no item is selected. | |
| void | setTextWhenNoChoicesAvailable (const String &newMessage) |
| Sets the message to show when there are no items in the list, and the user clicks on the drop-down box. | |
| String | getTextWhenNoChoicesAvailable () const |
| 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 *) |
| Called when a Label's text has changed. | |
| void | enablementChanged () |
| Callback to indicate that this component has been enabled or disabled. | |
| void | colourChanged () |
| This method is called when a colour is changed by the setColour() method. | |
| void | focusGained (Component::FocusChangeType cause) |
| Called to indicate that this component has just acquired the keyboard focus. | |
| void | focusLost (Component::FocusChangeType cause) |
| Called to indicate that this component has just lost the keyboard focus. | |
| void | handleAsyncUpdate () |
| Called back to do whatever your class needs to do. | |
| const String | getTooltip () |
| Returns the tooltip assigned to this object. | |
| void | mouseDown (const MouseEvent &) |
| Called when a mouse button is pressed while it's over this component. | |
| void | mouseDrag (const MouseEvent &) |
| Called when the mouse is moved while a button is held down. | |
| void | mouseUp (const MouseEvent &) |
| Called when a mouse button is released. | |
| void | lookAndFeelChanged () |
| Called to let the component react to a change in the look-and-feel setting. | |
| void | paint (Graphics &) |
| Components can override this method to draw their content. | |
| void | resized () |
| Called when this component's size has been changed. | |
| bool | keyStateChanged (bool isKeyDown) |
| Called when a key is pressed or released. | |
| bool | keyPressed (const KeyPress &) |
| Called when a key is pressed. | |
| void | valueChanged (Value &) |
| Called when a Value object is changed. | |
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 ComboBox::Listener to receive callbacks.
| 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
| 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. |
| ComboBox::ComboBox | ( | const String & | componentName = String::empty ) |
[explicit] |
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.
| componentName | the name to set for the component (see Component::setName()) |
| ComboBox::~ComboBox | ( | ) |
Destructor.
| void ComboBox::setEditableText | ( | 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 |
Returns true if the text is directly editable.
| void ComboBox::setJustificationType | ( | const Justification & | justification ) |
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 |
Returns the current justification for the text box.
| void ComboBox::addItem | ( | const String & | newItemText, |
| int | newItemId | ||
| ) |
Adds an item to be shown in the drop-down list.
| 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(). Note that this value can not be 0! |
| void ComboBox::addSeparator | ( | ) |
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 ) |
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.
| void ComboBox::setItemEnabled | ( | int | itemId, |
| bool | shouldBeEnabled | ||
| ) |
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.
| bool ComboBox::isItemEnabled | ( | int | itemId ) | const |
Returns true if the given item is enabled.
| void ComboBox::changeItemText | ( | int | itemId, |
| const String & | newText | ||
| ) |
Changes the text for an existing item.
| void ComboBox::clear | ( | 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.
| int ComboBox::getNumItems | ( | ) | const |
Returns the number of items that have been added to the list.
Note that this doesn't include headers or separators.
| String ComboBox::getItemText | ( | int | index ) | const |
Returns the text for one of the items in the list.
Note that this doesn't include headers or separators.
| index | the item's index from 0 to (getNumItems() - 1) |
| int ComboBox::getItemId | ( | int | index ) | const |
Returns the ID for one of the items in the list.
Note that this doesn't include headers or separators.
| index | the item's index from 0 to (getNumItems() - 1) |
| int ComboBox::indexOfItemId | ( | int | itemId ) | const |
Returns the index in the list of a particular item ID.
If no such ID is found, this will return -1.
| int ComboBox::getSelectedId | ( | ) | const |
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.
| Value& ComboBox::getSelectedIdAsValue | ( | ) |
Returns a Value object that can be used to get or set the selected item's ID.
You can call Value::referTo() on this object to make the combo box control another Value object.
| void ComboBox::setSelectedId | ( | int | newItemId, |
| bool | dontSendChangeMessage = false |
||
| ) |
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.
| newItemId | the new item to select |
| dontSendChangeMessage | if set to true, this method won't trigger a change notification |
| int ComboBox::getSelectedItemIndex | ( | ) | const |
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.
| void ComboBox::setSelectedItemIndex | ( | int | newItemIndex, |
| bool | dontSendChangeMessage = false |
||
| ) |
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.
| newItemIndex | the new item to select |
| dontSendChangeMessage | if set to true, this method won't trigger a change notification |
| String ComboBox::getText | ( | ) | const |
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.
| void ComboBox::setText | ( | const String & | newText, |
| bool | dontSendChangeMessage = false |
||
| ) |
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.
| newText | the text to select |
| dontSendChangeMessage | if set to true, this method won't trigger a change notification |
| 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.
| void ComboBox::showPopup | ( | ) |
Pops up the combo box's list.
| void ComboBox::addListener | ( | Listener * | listener ) |
Registers a listener that will be called when the box's content changes.
| void ComboBox::removeListener | ( | Listener * | listener ) |
Deregisters a previously-registered listener.
| void ComboBox::setTextWhenNothingSelected | ( | const String & | newMessage ) |
Sets a message to display when there is no item currently selected.
| String ComboBox::getTextWhenNothingSelected | ( | ) | const |
Returns the text that is shown when no item is selected.
| void ComboBox::setTextWhenNoChoicesAvailable | ( | const String & | newMessage ) |
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.
| String ComboBox::getTextWhenNoChoicesAvailable | ( | ) | const |
Returns the text shown when no items have been added to the list.
| void ComboBox::setTooltip | ( | const String & | newTooltip ) | [virtual] |
Gives the ComboBox a tooltip.
Reimplemented from SettableTooltipClient.
| void ComboBox::labelTextChanged | ( | Label * | labelThatHasChanged ) | [virtual] |
Called when a Label's text has changed.
Implements Label::Listener.
| void ComboBox::enablementChanged | ( | ) | [virtual] |
Callback to indicate that this component has been enabled or disabled.
This can be triggered by one of the component's parent components being enabled or disabled, as well as changes to the component itself.
The default implementation of this method does nothing; your class may wish to repaint itself or something when this happens.
Reimplemented from Component.
| void ComboBox::colourChanged | ( | ) | [virtual] |
This method is called when a colour is changed by the setColour() method.
Reimplemented from Component.
| void ComboBox::focusGained | ( | Component::FocusChangeType | cause ) | [virtual] |
Called to indicate that this component has just acquired the keyboard focus.
Reimplemented from Component.
| void ComboBox::focusLost | ( | Component::FocusChangeType | cause ) | [virtual] |
Called to indicate that this component has just lost the keyboard focus.
Reimplemented from Component.
| void ComboBox::handleAsyncUpdate | ( | ) | [virtual] |
Called back to do whatever your class needs to do.
This method is called by the message thread at the next convenient time after the triggerAsyncUpdate() method has been called.
Implements AsyncUpdater.
| const String ComboBox::getTooltip | ( | ) | [virtual] |
Returns the tooltip assigned to this object.
Reimplemented from SettableTooltipClient.
| void ComboBox::mouseDown | ( | const MouseEvent & | e ) | [virtual] |
Called when a mouse button is pressed while it's over this component.
The MouseEvent object passed in contains lots of methods for finding out which button was pressed, as well as which modifier keys (e.g. shift, ctrl) were held down at the time.
Once a button is held down, the mouseDrag method will be called when the mouse moves, until the button is released.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void ComboBox::mouseDrag | ( | const MouseEvent & | e ) | [virtual] |
Called when the mouse is moved while a button is held down.
When a mouse button is pressed inside a component, that component receives mouseDrag callbacks each time the mouse moves, even if the mouse strays outside the component's bounds.
If you want to be able to drag things off the edge of a component and have the component scroll when you get to the edges, the beginDragAutoRepeat() method might be useful.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void ComboBox::mouseUp | ( | const MouseEvent & | e ) | [virtual] |
Called when a mouse button is released.
A mouseUp callback is sent to the component in which a button was pressed even if the mouse is actually over a different component when the button is released.
The MouseEvent object passed in contains lots of methods for finding out which buttons were down just before they were released.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void ComboBox::lookAndFeelChanged | ( | ) | [virtual] |
Called to let the component react to a change in the look-and-feel setting.
When the look-and-feel is changed for a component, this will be called in all its child components, recursively.
It can also be triggered manually by the sendLookAndFeelChange() method, in case an application uses a LookAndFeel class that might have changed internally.
Reimplemented from Component.
| void ComboBox::paint | ( | Graphics & | g ) | [virtual] |
Components can override this method to draw their content.
The paint() method gets called when a region of a component needs redrawing, either because the component's repaint() method has been called, or because something has happened on the screen that means a section of a window needs to be redrawn.
Any child components will draw themselves over whatever this method draws. If you need to paint over the top of your child components, you can also implement the paintOverChildren() method to do this.
If you want to cause a component to redraw itself, this is done asynchronously - calling the repaint() method marks a region of the component as "dirty", and the paint() method will automatically be called sometime later, by the message thread, to paint any bits that need refreshing. In Juce (and almost all modern UI frameworks), you never redraw something synchronously.
You should never need to call this method directly - to take a snapshot of the component you could use createComponentSnapshot() or paintEntireComponent().
| g | the graphics context that must be used to do the drawing operations. |
Reimplemented from Component.
| void ComboBox::resized | ( | ) | [virtual] |
Called when this component's size has been changed.
A component can implement this method to do things such as laying out its child components when its width or height changes.
The method is called synchronously as a result of the setBounds or setSize methods, so repeatedly changing a components size will repeatedly call its resized method (unlike things like repainting, where multiple calls to repaint are coalesced together).
If the component is a top-level window on the desktop, its size could also be changed by operating-system factors beyond the application's control.
Reimplemented from Component.
| bool ComboBox::keyStateChanged | ( | bool | isKeyDown ) | [virtual] |
Called when a key is pressed or released.
Whenever a key on the keyboard is pressed or released (including modifier keys like shift and ctrl), this method will be called on the component that currently has the keyboard focus. Remember that a component will only be given the focus if its setWantsKeyboardFocus() method has been used to enable this.
If your implementation returns true, the event will be consumed and not passed on to any other listeners. If it returns false, then any KeyListeners that have been registered with this component will have their keyStateChanged methods called. As soon as one of these returns true, the process will stop, but if they all return false, the event will be passed upwards to this component's parent, and so on.
The default implementation of this method does nothing and returns false.
To find out which keys are up or down at any time, see the KeyPress::isKeyCurrentlyDown() method.
| isKeyDown | true if a key has been pressed; false if it has been released |
Reimplemented from Component.
| bool ComboBox::keyPressed | ( | const KeyPress & | key ) | [virtual] |
Called when a key is pressed.
When a key is pressed, the component that has the keyboard focus will have this method called. Remember that a component will only be given the focus if its setWantsKeyboardFocus() method has been used to enable this.
If your implementation returns true, the event will be consumed and not passed on to any other listeners. If it returns false, the key will be passed to any KeyListeners that have been registered with this component. As soon as one of these returns true, the process will stop, but if they all return false, the event will be passed upwards to this component's parent, and so on.
The default implementation of this method does nothing and returns false.
Reimplemented from Component.
| void ComboBox::valueChanged | ( | Value & | value ) | [virtual] |
Called when a Value object is changed.
Note that the Value object passed as a parameter may not be exactly the same object that you registered the listener with - it might be a copy that refers to the same underlying ValueSource. To find out, you can call Value::refersToSameSourceAs().
Implements Value::Listener.
