A component that displays a text string, and can optionally become a text editor when clicked. More...
Inherits Component, SettableTooltipClient, TextEditor::Listener, ComponentListener, and Value::Listener.
Classes | |
| class | Listener |
| A class for receiving events from a Label. More... | |
Public Types | |
| enum | ColourIds { backgroundColourId = 0x1000280, textColourId = 0x1000281, outlineColourId = 0x1000282 } |
A set of colour IDs to use to change the colour of various aspects of the label. More... | |
Public Member Functions | |
| Label (const String &componentName=String::empty, const String &labelText=String::empty) | |
| Creates a Label. | |
| ~Label () | |
| Destructor. | |
| void | setText (const String &newText, bool broadcastChangeMessage) |
| Changes the label text. | |
| String | getText (bool returnActiveEditorContents=false) const |
| Returns the label's current text. | |
| Value & | getTextValue () |
| Returns the text content as a Value object. | |
| void | setFont (const Font &newFont) |
| Changes the font to use to draw the text. | |
| const Font & | getFont () const noexcept |
| Returns the font currently being used. | |
| void | setJustificationType (const Justification &justification) |
| Sets the style of justification to be used for positioning the text. | |
| const Justification | getJustificationType () const noexcept |
| Returns the type of justification, as set in setJustificationType(). | |
| void | setBorderSize (int horizontalBorder, int verticalBorder) |
| Changes the gap that is left between the edge of the component and the text. | |
| int | getHorizontalBorderSize () const noexcept |
| Returns the size of the horizontal gap being left around the text. | |
| int | getVerticalBorderSize () const noexcept |
| Returns the size of the vertical gap being left around the text. | |
| void | attachToComponent (Component *owner, bool onLeft) |
| Makes this label "stick to" another component. | |
| Component * | getAttachedComponent () const |
| If this label has been attached to another component using attachToComponent, this returns the other component. | |
| bool | isAttachedOnLeft () const noexcept |
| If the label is attached to the left of another component, this returns true. | |
| void | setMinimumHorizontalScale (float newScale) |
| Specifies the minimum amount that the font can be squashed horizantally before it starts using ellipsis. | |
| float | getMinimumHorizontalScale () const noexcept |
| void | addListener (Listener *listener) |
| Registers a listener that will be called when the label's text changes. | |
| void | removeListener (Listener *listener) |
| Deregisters a previously-registered listener. | |
| void | setEditable (bool editOnSingleClick, bool editOnDoubleClick=false, bool lossOfFocusDiscardsChanges=false) |
| Makes the label turn into a TextEditor when clicked. | |
| bool | isEditableOnSingleClick () const noexcept |
| Returns true if this option was set using setEditable(). | |
| bool | isEditableOnDoubleClick () const noexcept |
| Returns true if this option was set using setEditable(). | |
| bool | doesLossOfFocusDiscardChanges () const noexcept |
| Returns true if this option has been set in a call to setEditable(). | |
| bool | isEditable () const noexcept |
| Returns true if the user can edit this label's text. | |
| void | showEditor () |
| Makes the editor appear as if the label had been clicked by the user. | |
| void | hideEditor (bool discardCurrentEditorContents) |
| Hides the editor if it was being shown. | |
| bool | isBeingEdited () const noexcept |
| Returns true if the editor is currently focused and active. | |
Protected Member Functions | |
| virtual TextEditor * | createEditorComponent () |
| Creates the TextEditor component that will be used when the user has clicked on the label. | |
| virtual void | textWasEdited () |
| Called after the user changes the text. | |
| virtual void | textWasChanged () |
| Called when the text has been altered. | |
| virtual void | editorShown (TextEditor *editorComponent) |
| Called when the text editor has just appeared, due to a user click or other focus change. | |
| virtual void | editorAboutToBeHidden (TextEditor *editorComponent) |
| Called when the text editor is going to be deleted, after editing has finished. | |
| void | paint (Graphics &g) |
| Components can override this method to draw their content. | |
| void | resized () |
| Called when this component's size has been changed. | |
| void | mouseUp (const MouseEvent &e) |
| Called when a mouse button is released. | |
| void | mouseDoubleClick (const MouseEvent &e) |
| Called when a mouse button has been double-clicked in this component. | |
| void | componentMovedOrResized (Component &component, bool wasMoved, bool wasResized) |
| Called when the component's position or size changes. | |
| void | componentParentHierarchyChanged (Component &component) |
| Called to indicate that the component's parents have changed. | |
| void | componentVisibilityChanged (Component &component) |
| Called when the component is made visible or invisible. | |
| void | inputAttemptWhenModal () |
| Called when the user tries to click on a component that is blocked by another modal component. | |
| void | focusGained (FocusChangeType) |
| Called to indicate that this component has just acquired the keyboard focus. | |
| void | enablementChanged () |
| Callback to indicate that this component has been enabled or disabled. | |
| KeyboardFocusTraverser * | createFocusTraverser () |
| Creates a KeyboardFocusTraverser object to use to determine the logic by which focus should be passed from this component. | |
| void | textEditorTextChanged (TextEditor &editor) |
| Called when the user changes the text in some way. | |
| void | textEditorReturnKeyPressed (TextEditor &editor) |
| Called when the user presses the return key. | |
| void | textEditorEscapeKeyPressed (TextEditor &editor) |
| Called when the user presses the escape key. | |
| void | textEditorFocusLost (TextEditor &editor) |
| Called when the text editor loses focus. | |
| void | colourChanged () |
| This method is called when a colour is changed by the setColour() method. | |
| void | valueChanged (Value &) |
| Called when a Value object is changed. | |
A component that displays a text string, and can optionally become a text editor when clicked.
| enum Label::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.
Note that you can also use the constants from TextEditor::ColourIds to change the colour of the text editor that is opened when a label is editable.
| Label::Label | ( | const String & | componentName = String::empty, |
| const String & | labelText = String::empty |
||
| ) |
Creates a Label.
| componentName | the name to give the component |
| labelText | the text to show in the label |
| Label::~Label | ( | ) |
Destructor.
| void Label::setText | ( | const String & | newText, |
| bool | broadcastChangeMessage | ||
| ) |
Changes the label text.
If broadcastChangeMessage is true and the new text is different to the current text, then the class will broadcast a change message to any Label::Listener objects that are registered.
| String Label::getText | ( | bool | returnActiveEditorContents = false ) |
const |
Returns the label's current text.
| returnActiveEditorContents | if this is true and the label is currently being edited, then this method will return the text as it's being shown in the editor. If false, then the value returned here won't be updated until the user has finished typing and pressed the return key. |
| Value& Label::getTextValue | ( | ) |
Returns the text content as a Value object.
You can call Value::referTo() on this object to make the label read and control a Value object that you supply.
| void Label::setFont | ( | const Font & | newFont ) |
Changes the font to use to draw the text.
| void Label::setJustificationType | ( | const Justification & | justification ) |
Sets the style of justification to be used for positioning the text.
(The default is Justification::centredLeft)
| const Justification Label::getJustificationType | ( | ) | const |
Returns the type of justification, as set in setJustificationType().
| void Label::setBorderSize | ( | int | horizontalBorder, |
| int | verticalBorder | ||
| ) |
Changes the gap that is left between the edge of the component and the text.
By default there's a small gap left at the sides of the component to allow for the drawing of the border, but you can change this if necessary.
| int Label::getHorizontalBorderSize | ( | ) | const |
Returns the size of the horizontal gap being left around the text.
| int Label::getVerticalBorderSize | ( | ) | const |
Returns the size of the vertical gap being left around the text.
| void Label::attachToComponent | ( | Component * | owner, |
| bool | onLeft | ||
| ) |
Makes this label "stick to" another component.
This will cause the label to follow another component around, staying either to its left or above it.
| owner | the component to follow |
| onLeft | if true, the label will stay on the left of its component; if false, it will stay above it. |
| Component* Label::getAttachedComponent | ( | ) | const |
If this label has been attached to another component using attachToComponent, this returns the other component.
Returns 0 if the label is not attached.
| bool Label::isAttachedOnLeft | ( | ) | const |
If the label is attached to the left of another component, this returns true.
Returns false if the label is above the other component. This is only relevent if attachToComponent() has been called.
| void Label::setMinimumHorizontalScale | ( | float | newScale ) |
Specifies the minimum amount that the font can be squashed horizantally before it starts using ellipsis.
| float Label::getMinimumHorizontalScale | ( | ) | const |
| void Label::addListener | ( | Listener * | listener ) |
Registers a listener that will be called when the label's text changes.
| void Label::removeListener | ( | Listener * | listener ) |
Deregisters a previously-registered listener.
| void Label::setEditable | ( | bool | editOnSingleClick, |
| bool | editOnDoubleClick = false, |
||
| bool | lossOfFocusDiscardsChanges = false |
||
| ) |
Makes the label turn into a TextEditor when clicked.
By default this is turned off.
If turned on, then single- or double-clicking will turn the label into an editor. If the user then changes the text, then the ChangeBroadcaster base class will be used to send change messages to any listeners that have registered.
If the user changes the text, the textWasEdited() method will be called afterwards, and subclasses can override this if they need to do anything special.
| editOnSingleClick | if true, just clicking once on the label will start editing the text |
| editOnDoubleClick | if true, a double-click is needed to start editing |
| lossOfFocusDiscardsChanges | if true, clicking somewhere else while the text is being edited will discard any changes; if false, then this will commit the changes. |
| bool Label::isEditableOnSingleClick | ( | ) | const |
Returns true if this option was set using setEditable().
| bool Label::isEditableOnDoubleClick | ( | ) | const |
Returns true if this option was set using setEditable().
| bool Label::doesLossOfFocusDiscardChanges | ( | ) | const |
Returns true if this option has been set in a call to setEditable().
| bool Label::isEditable | ( | ) | const |
Returns true if the user can edit this label's text.
| void Label::showEditor | ( | ) |
Makes the editor appear as if the label had been clicked by the user.
| void Label::hideEditor | ( | bool | discardCurrentEditorContents ) |
Hides the editor if it was being shown.
| discardCurrentEditorContents | if true, the label's text will be reset to whatever it was before the editor was shown; if false, the current contents of the editor will be used to set the label's text before it is hidden. |
| bool Label::isBeingEdited | ( | ) | const |
Returns true if the editor is currently focused and active.
| virtual TextEditor* Label::createEditorComponent | ( | ) | [protected, virtual] |
Creates the TextEditor component that will be used when the user has clicked on the label.
Subclasses can override this if they need to customise this component in some way.
| virtual void Label::textWasEdited | ( | ) | [protected, virtual] |
Called after the user changes the text.
| virtual void Label::textWasChanged | ( | ) | [protected, virtual] |
Called when the text has been altered.
| virtual void Label::editorShown | ( | TextEditor * | editorComponent ) | [protected, virtual] |
Called when the text editor has just appeared, due to a user click or other focus change.
| virtual void Label::editorAboutToBeHidden | ( | TextEditor * | editorComponent ) | [protected, virtual] |
Called when the text editor is going to be deleted, after editing has finished.
| void Label::paint | ( | Graphics & | g ) | [protected, 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 Label::resized | ( | ) | [protected, 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.
| void Label::mouseUp | ( | const MouseEvent & | e ) | [protected, 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 Label::mouseDoubleClick | ( | const MouseEvent & | e ) | [protected, virtual] |
Called when a mouse button has been double-clicked in 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.
For altering the time limit used to detect double-clicks, see MouseEvent::setDoubleClickTimeout.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void Label::componentMovedOrResized | ( | Component & | component, |
| bool | wasMoved, | ||
| bool | wasResized | ||
| ) | [protected, virtual] |
Called when the component's position or size changes.
| component | the component that was moved or resized |
| wasMoved | true if the component's top-left corner has just moved |
| wasResized | true if the component's width or height has just changed |
Reimplemented from ComponentListener.
| void Label::componentParentHierarchyChanged | ( | Component & | component ) | [protected, virtual] |
Called to indicate that the component's parents have changed.
When a component is added or removed from its parent, all of its children will produce this notification (recursively - so all children of its children will also be called as well).
| component | the component that this listener is registered with |
Reimplemented from ComponentListener.
| void Label::componentVisibilityChanged | ( | Component & | component ) | [protected, virtual] |
Called when the component is made visible or invisible.
| component | the component that changed |
Reimplemented from ComponentListener.
| void Label::inputAttemptWhenModal | ( | ) | [protected, virtual] |
Called when the user tries to click on a component that is blocked by another modal component.
When a component is modal and the user clicks on one of the other components, the modal component will receive this callback.
The default implementation of this method will play a beep, and bring the currently modal component to the front, but it can be overridden to do other tasks.
Reimplemented from Component.
| void Label::focusGained | ( | FocusChangeType | cause ) | [protected, virtual] |
Called to indicate that this component has just acquired the keyboard focus.
Reimplemented from Component.
| void Label::enablementChanged | ( | ) | [protected, 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.
| KeyboardFocusTraverser* Label::createFocusTraverser | ( | ) | [protected, virtual] |
Creates a KeyboardFocusTraverser object to use to determine the logic by which focus should be passed from this component.
The default implementation of this method will return a default KeyboardFocusTraverser if this component is a focus container (as determined by the setFocusContainer() method). If the component isn't a focus container, then it will recursively ask its parents for a KeyboardFocusTraverser.
If you overrride this to return a custom KeyboardFocusTraverser, then this component and all its sub-components will use the new object to make their focusing decisions.
The method should return a new object, which the caller is required to delete when no longer needed.
Reimplemented from Component.
| void Label::textEditorTextChanged | ( | TextEditor & | editor ) | [protected, virtual] |
Called when the user changes the text in some way.
Reimplemented from TextEditor::Listener.
| void Label::textEditorReturnKeyPressed | ( | TextEditor & | editor ) | [protected, virtual] |
Called when the user presses the return key.
Reimplemented from TextEditor::Listener.
| void Label::textEditorEscapeKeyPressed | ( | TextEditor & | editor ) | [protected, virtual] |
Called when the user presses the escape key.
Reimplemented from TextEditor::Listener.
| void Label::textEditorFocusLost | ( | TextEditor & | editor ) | [protected, virtual] |
Called when the text editor loses focus.
Reimplemented from TextEditor::Listener.
| void Label::colourChanged | ( | ) | [protected, virtual] |
This method is called when a colour is changed by the setColour() method.
Reimplemented from Component.
| void Label::valueChanged | ( | Value & | value ) | [protected, 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.
