JUCE
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines
Classes | Public Types | Public Member Functions | Protected Member Functions
TextEditor Class Reference

A component containing text that can be edited. More...

Inherits Component, TextInputTarget, and SettableTooltipClient.

List of all members.

Classes

struct  Ids
class  Listener
 Receives callbacks from a TextEditor component when it changes. More...

Public Types

enum  ColourIds {
  backgroundColourId = 0x1000200, textColourId = 0x1000201, highlightColourId = 0x1000202, highlightedTextColourId = 0x1000203,
  outlineColourId = 0x1000205, focusedOutlineColourId = 0x1000206, shadowColourId = 0x1000207
}
 A set of colour IDs to use to change the colour of various aspects of the editor. More...

Public Member Functions

 TextEditor (const String &componentName=String::empty, juce_wchar passwordCharacter=0)
 Creates a new, empty text editor.
virtual ~TextEditor ()
 Destructor.
void setMultiLine (bool shouldBeMultiLine, bool shouldWordWrap=true)
 Puts the editor into either multi- or single-line mode.
bool isMultiLine () const
 Returns true if the editor is in multi-line mode.
void setReturnKeyStartsNewLine (bool shouldStartNewLine)
 Changes the behaviour of the return key.
bool getReturnKeyStartsNewLine () const
 Returns the value set by setReturnKeyStartsNewLine().
void setTabKeyUsedAsCharacter (bool shouldTabKeyBeUsed)
 Indicates whether the tab key should be accepted and used to input a tab character, or whether it gets ignored.
bool isTabKeyUsedAsCharacter () const
 Returns true if the tab key is being used for input.
void setReadOnly (bool shouldBeReadOnly)
 Changes the editor to read-only mode.
bool isReadOnly () const
 Returns true if the editor is in read-only mode.
void setCaretVisible (bool shouldBeVisible)
 Makes the caret visible or invisible.
bool isCaretVisible () const
 Returns true if the caret is enabled.
void setScrollbarsShown (bool shouldBeEnabled)
 Enables/disables a vertical scrollbar.
bool areScrollbarsShown () const
 Returns true if scrollbars are enabled.
void setPasswordCharacter (juce_wchar passwordCharacter)
 Changes the password character used to disguise the text.
juce_wchar getPasswordCharacter () const
 Returns the current password character.
void setPopupMenuEnabled (bool menuEnabled)
 Allows a right-click menu to appear for the editor.
bool isPopupMenuEnabled () const
 Returns true if the right-click menu is enabled.
bool isPopupMenuCurrentlyActive () const
 Returns true if a popup-menu is currently being displayed.
void setFont (const Font &newFont)
 Sets the font to use for newly added text.
void applyFontToAllText (const Font &newFont)
 Applies a font to all the text in the editor.
const FontgetFont () const
 Returns the font that's currently being used for new text.
void setSelectAllWhenFocused (bool b)
 If set to true, focusing on the editor will highlight all its text.
void setInputRestrictions (int maxTextLength, const String &allowedCharacters=String::empty)
 Sets limits on the characters that can be entered.
void setTextToShowWhenEmpty (const String &text, const Colour &colourToUse)
 When the text editor is empty, it can be set to display a message.
void setScrollBarThickness (int newThicknessPixels)
 Changes the size of the scrollbars that are used.
void setScrollBarButtonVisibility (bool buttonsVisible)
 Shows or hides the buttons on any scrollbars that are used.
void addListener (Listener *newListener)
 Registers a listener to be told when things happen to the text.
void removeListener (Listener *listenerToRemove)
 Deregisters a listener.
String getText () const
 Returns the entire contents of the editor.
String getTextInRange (const Range< int > &textRange) const
 Returns a section of the contents of the editor.
bool isEmpty () const
 Returns true if there are no characters in the editor.
void setText (const String &newText, bool sendTextChangeMessage=true)
 Sets the entire content of the editor.
ValuegetTextValue ()
 Returns a Value object that can be used to get or set the text.
void insertTextAtCaret (const String &textToInsert)
 Inserts some text at the current caret position.
void clear ()
 Deletes all the text from the editor.
void cut ()
 Deletes the currently selected region.
void copy ()
 Copies the currently selected region to the clipboard.
void paste ()
 Pastes the contents of the clipboard into the editor at the caret position.
int getCaretPosition () const
 Returns the current index of the caret.
void setCaretPosition (int newIndex)
 Moves the caret to be in front of a given character.
void moveCaretToEnd ()
 Moves the caret to be the end of all the text.
void scrollEditorToPositionCaret (int desiredCaretX, int desiredCaretY)
 Attempts to scroll the text editor so that the caret ends up at a specified position.
Rectangle< int > getCaretRectangle ()
 Get the graphical position of the caret.
void setHighlightedRegion (const Range< int > &newSelection)
 Selects a section of the text.
Range< int > getHighlightedRegion () const
 Returns the range of characters that are selected.
String getHighlightedText () const
 Returns the section of text that is currently selected.
int getTextIndexAt (int x, int y)
 Finds the index of the character at a given position.
int getTotalNumChars () const
 Counts the number of characters in the text.
int getTextWidth () const
 Returns the total width of the text, as it is currently laid-out.
int getTextHeight () const
 Returns the maximum height of the text, as it is currently laid-out.
void setIndents (int newLeftIndent, int newTopIndent)
 Changes the size of the gap at the top and left-edge of the editor.
void setBorder (const BorderSize< int > &border)
 Changes the size of border left around the edge of the component.
BorderSize< int > getBorder () const
 Returns the size of border around the edge of the component.
void setScrollToShowCursor (bool shouldScrollToShowCaret)
 Used to disable the auto-scrolling which keeps the caret visible.
void paint (Graphics &g)
void paintOverChildren (Graphics &g)
void mouseDown (const MouseEvent &e)
void mouseUp (const MouseEvent &e)
void mouseDrag (const MouseEvent &e)
void mouseDoubleClick (const MouseEvent &e)
void mouseWheelMove (const MouseEvent &e, float wheelIncrementX, float wheelIncrementY)
bool keyPressed (const KeyPress &key)
bool keyStateChanged (bool isKeyDown)
void focusGained (FocusChangeType cause)
void focusLost (FocusChangeType cause)
void resized ()
void enablementChanged ()
void colourChanged ()
void lookAndFeelChanged ()
bool isTextInputActive () const
void setTemporaryUnderlining (const Array< Range< int > > &)
bool moveCaretLeft (bool moveInWholeWordSteps, bool selecting)
bool moveCaretRight (bool moveInWholeWordSteps, bool selecting)
bool moveCaretUp (bool selecting)
bool moveCaretDown (bool selecting)
bool pageUp (bool selecting)
bool pageDown (bool selecting)
bool scrollDown ()
bool scrollUp ()
bool moveCaretToTop (bool selecting)
bool moveCaretToStartOfLine (bool selecting)
bool moveCaretToEnd (bool selecting)
bool moveCaretToEndOfLine (bool selecting)
bool deleteBackwards (bool moveInWholeWordSteps)
bool deleteForwards (bool moveInWholeWordSteps)
bool copyToClipboard ()
bool cutToClipboard ()
bool pasteFromClipboard ()
bool selectAll ()
bool undo ()
bool redo ()
virtual void addPopupMenuItems (PopupMenu &menuToAddTo, const MouseEvent *mouseClickEvent)
 This adds the items to the popup menu.
virtual void performPopupMenuAction (int menuItemID)
 This is called to perform one of the items that was shown on the popup menu.
void refreshFromValueTree (const ValueTree &, ComponentBuilder &)

Protected Member Functions

void scrollToMakeSureCursorIsVisible ()
 Scrolls the minimum distance needed to get the caret into view.
void moveCaret (int newCaretPos)
void moveCaretTo (int newPosition, bool isSelecting)
void textChanged ()
 Used internally to dispatch a text-change message.
void newTransaction ()
 Begins a new transaction in the UndoManager.
void doUndoRedo (bool isRedo)
 Used internally to trigger an undo or redo.
virtual void returnPressed ()
 Can be overridden to intercept return key presses directly.
virtual void escapePressed ()
 Can be overridden to intercept escape key presses directly.
void handleCommandMessage (int commandId)

Detailed Description

A component containing text that can be edited.

A TextEditor can either be in single- or multi-line mode, and supports mixed fonts and colours.

See also:
TextEditor::Listener, Label

Member Enumeration Documentation

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

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 colour to use for the text component's background - this can be transparent if necessary.

textColourId 

The colour that will be used when text is added to the editor.

Note that because the editor can contain multiple colours, calling this method won't change the colour of existing text - to do that, call applyFontToAllText() after calling this method.

highlightColourId 

The colour with which to fill the background of highlighted sections of the text - this can be transparent if you don't want to show any highlighting.

highlightedTextColourId 

The colour with which to draw the text in highlighted sections.

outlineColourId 

If this is non-transparent, it will be used to draw a box around the edge of the component.

focusedOutlineColourId 

If this is non-transparent, it will be used to draw a box around the edge of the component when it has focus.

shadowColourId 

If this is non-transparent, it'll be used to draw an inner shadow around the edge of the editor.


Constructor & Destructor Documentation

TextEditor::TextEditor ( const String componentName = String::empty,
juce_wchar  passwordCharacter = 0 
) [explicit]

Creates a new, empty text editor.

Parameters:
componentNamethe name to pass to the component for it to use as its name
passwordCharacterif this is not zero, this character will be used as a replacement for all characters that are drawn on screen - e.g. to create a password-style textbox containing circular blobs instead of text, you could set this value to 0x25cf, which is the unicode character for a black splodge (not all fonts include this, though), or 0x2022, which is a bullet (probably the best choice for linux).
virtual TextEditor::~TextEditor ( ) [virtual]

Destructor.


Member Function Documentation

void TextEditor::setMultiLine ( bool  shouldBeMultiLine,
bool  shouldWordWrap = true 
)

Puts the editor into either multi- or single-line mode.

By default, the editor will be in single-line mode, so use this if you need a multi-line editor.

See also the setReturnKeyStartsNewLine() method, which will also need to be turned on if you want a multi-line editor with line-breaks.

See also:
isMultiLine, setReturnKeyStartsNewLine
bool TextEditor::isMultiLine ( ) const

Returns true if the editor is in multi-line mode.

void TextEditor::setReturnKeyStartsNewLine ( bool  shouldStartNewLine)

Changes the behaviour of the return key.

If set to true, the return key will insert a new-line into the text; if false it will trigger a call to the TextEditor::Listener::textEditorReturnKeyPressed() method. By default this is set to false, and when true it will only insert new-lines when in multi-line mode (see setMultiLine()).

Returns the value set by setReturnKeyStartsNewLine().

See setReturnKeyStartsNewLine() for more info.

void TextEditor::setTabKeyUsedAsCharacter ( bool  shouldTabKeyBeUsed)

Indicates whether the tab key should be accepted and used to input a tab character, or whether it gets ignored.

By default the tab key is ignored, so that it can be used to switch keyboard focus between components.

Returns true if the tab key is being used for input.

See also:
setTabKeyUsedAsCharacter
void TextEditor::setReadOnly ( bool  shouldBeReadOnly)

Changes the editor to read-only mode.

By default, the text editor is not read-only. If you're making it read-only, you might also want to call setCaretVisible (false) to get rid of the caret.

The text can still be highlighted and copied when in read-only mode.

See also:
isReadOnly, setCaretVisible
bool TextEditor::isReadOnly ( ) const

Returns true if the editor is in read-only mode.

void TextEditor::setCaretVisible ( bool  shouldBeVisible)

Makes the caret visible or invisible.

By default the caret is visible.

See also:
setCaretColour, setCaretPosition

Returns true if the caret is enabled.

See also:
setCaretVisible
void TextEditor::setScrollbarsShown ( bool  shouldBeEnabled)

Enables/disables a vertical scrollbar.

(This only applies when in multi-line mode). When the text gets too long to fit in the component, a scrollbar can appear to allow it to be scrolled. Even when this is enabled, the scrollbar will be hidden unless it's needed.

By default the scrollbar is enabled.

Returns true if scrollbars are enabled.

See also:
setScrollbarsShown
void TextEditor::setPasswordCharacter ( juce_wchar  passwordCharacter)

Changes the password character used to disguise the text.

Parameters:
passwordCharacterif this is not zero, this character will be used as a replacement for all characters that are drawn on screen - e.g. to create a password-style textbox containing circular blobs instead of text, you could set this value to 0x25cf, which is the unicode character for a black splodge (not all fonts include this, though), or 0x2022, which is a bullet (probably the best choice for linux).

Returns the current password character.

See also:
setPasswordCharacter
void TextEditor::setPopupMenuEnabled ( bool  menuEnabled)

Allows a right-click menu to appear for the editor.

(This defaults to being enabled).

If enabled, right-clicking (or command-clicking on the Mac) will pop up a menu of options such as cut/copy/paste, undo/redo, etc.

Returns true if the right-click menu is enabled.

See also:
setPopupMenuEnabled

Returns true if a popup-menu is currently being displayed.

void TextEditor::setFont ( const Font newFont)

Sets the font to use for newly added text.

This will change the font that will be used next time any text is added or entered into the editor. It won't change the font of any existing text - to do that, use applyFontToAllText() instead.

See also:
applyFontToAllText
void TextEditor::applyFontToAllText ( const Font newFont)

Applies a font to all the text in the editor.

This will also set the current font to use for any new text that's added.

See also:
setFont
const Font& TextEditor::getFont ( ) const

Returns the font that's currently being used for new text.

See also:
setFont

If set to true, focusing on the editor will highlight all its text.

(Set to false by default).

This is useful for boxes where you expect the user to re-enter all the text when they focus on the component, rather than editing what's already there.

void TextEditor::setInputRestrictions ( int  maxTextLength,
const String allowedCharacters = String::empty 
)

Sets limits on the characters that can be entered.

Parameters:
maxTextLengthif this is > 0, it sets a maximum length limit; if 0, no limit is set
allowedCharactersif this is non-empty, then only characters that occur in this string are allowed to be entered into the editor.
void TextEditor::setTextToShowWhenEmpty ( const String text,
const Colour colourToUse 
)

When the text editor is empty, it can be set to display a message.

This is handy for things like telling the user what to type in the box - the string is only displayed, it's not taken to actually be the contents of the editor.

void TextEditor::setScrollBarThickness ( int  newThicknessPixels)

Changes the size of the scrollbars that are used.

Handy if you need smaller scrollbars for a small text box.

void TextEditor::setScrollBarButtonVisibility ( bool  buttonsVisible)

Shows or hides the buttons on any scrollbars that are used.

See also:
ScrollBar::setButtonVisibility
void TextEditor::addListener ( Listener newListener)

Registers a listener to be told when things happen to the text.

See also:
removeListener
void TextEditor::removeListener ( Listener listenerToRemove)

Deregisters a listener.

See also:
addListener

Returns the entire contents of the editor.

String TextEditor::getTextInRange ( const Range< int > &  textRange) const [virtual]

Returns a section of the contents of the editor.

Implements TextInputTarget.

bool TextEditor::isEmpty ( ) const

Returns true if there are no characters in the editor.

This is more efficient than calling getText().isEmpty().

void TextEditor::setText ( const String newText,
bool  sendTextChangeMessage = true 
)

Sets the entire content of the editor.

This will clear the editor and insert the given text (using the current text colour and font). You can set the current text colour using

Parameters:
newTextthe text to add
sendTextChangeMessageif true, this will cause a change message to be sent to all the listeners.
See also:
insertText

Returns a Value object that can be used to get or set the text.

Bear in mind that this operate quite slowly if your text box contains large amounts of text, as it needs to dynamically build the string that's involved. It's best used for small text boxes.

void TextEditor::insertTextAtCaret ( const String textToInsert) [virtual]

Inserts some text at the current caret position.

If a section of the text is highlighted, it will be replaced by this string, otherwise it will be inserted.

To delete a section of text, you can use setHighlightedRegion() to highlight it, and call insertTextAtCursor (String::empty).

See also:
setCaretPosition, getCaretPosition, setHighlightedRegion

Implements TextInputTarget.

Deletes all the text from the editor.

void TextEditor::cut ( )

Deletes the currently selected region.

This doesn't copy the deleted section to the clipboard - if you need to do that, call copy() first.

See also:
copy, paste, SystemClipboard
void TextEditor::copy ( )

Copies the currently selected region to the clipboard.

See also:
cut, paste, SystemClipboard

Pastes the contents of the clipboard into the editor at the caret position.

See also:
cut, copy, SystemClipboard

Returns the current index of the caret.

See also:
setCaretPosition
void TextEditor::setCaretPosition ( int  newIndex)

Moves the caret to be in front of a given character.

See also:
getCaretPosition, moveCaretToEnd

Moves the caret to be the end of all the text.

See also:
setCaretPosition
void TextEditor::scrollEditorToPositionCaret ( int  desiredCaretX,
int  desiredCaretY 
)

Attempts to scroll the text editor so that the caret ends up at a specified position.

This won't affect the caret's position within the text, it tries to scroll the entire editor vertically and horizontally so that the caret is sitting at the given position (relative to the top-left of this component).

Depending on the amount of text available, it might not be possible to scroll far enough for the caret to reach this exact position, but it will go as far as it can in that direction.

Get the graphical position of the caret.

The rectangle returned is relative to the component's top-left corner.

See also:
scrollEditorToPositionCaret

Implements TextInputTarget.

void TextEditor::setHighlightedRegion ( const Range< int > &  newSelection) [virtual]

Selects a section of the text.

Implements TextInputTarget.

Range<int> TextEditor::getHighlightedRegion ( ) const [virtual]

Returns the range of characters that are selected.

If nothing is selected, this will return an empty range.

See also:
setHighlightedRegion

Implements TextInputTarget.

Returns the section of text that is currently selected.

int TextEditor::getTextIndexAt ( int  x,
int  y 
)

Finds the index of the character at a given position.

The co-ordinates are relative to the component's top-left.

Counts the number of characters in the text.

This is quicker than getting the text as a string if you just need to know the length.

int TextEditor::getTextWidth ( ) const

Returns the total width of the text, as it is currently laid-out.

This may be larger than the size of the TextEditor, and can change when the TextEditor is resized or the text changes.

Returns the maximum height of the text, as it is currently laid-out.

This may be larger than the size of the TextEditor, and can change when the TextEditor is resized or the text changes.

void TextEditor::setIndents ( int  newLeftIndent,
int  newTopIndent 
)

Changes the size of the gap at the top and left-edge of the editor.

By default there's a gap of 4 pixels.

void TextEditor::setBorder ( const BorderSize< int > &  border)

Changes the size of border left around the edge of the component.

See also:
getBorder

Returns the size of border around the edge of the component.

See also:
setBorder
void TextEditor::setScrollToShowCursor ( bool  shouldScrollToShowCaret)

Used to disable the auto-scrolling which keeps the caret visible.

If true (the default), the editor will scroll when the caret moves offscreen. If set to false, it won't.

void TextEditor::paint ( Graphics g) [virtual]

Reimplemented from Component.

void TextEditor::paintOverChildren ( Graphics g) [virtual]

Reimplemented from Component.

void TextEditor::mouseDown ( const MouseEvent e) [virtual]

Reimplemented from Component.

void TextEditor::mouseUp ( const MouseEvent e) [virtual]

Reimplemented from Component.

void TextEditor::mouseDrag ( const MouseEvent e) [virtual]

Reimplemented from Component.

void TextEditor::mouseDoubleClick ( const MouseEvent e) [virtual]

Reimplemented from Component.

void TextEditor::mouseWheelMove ( const MouseEvent e,
float  wheelIncrementX,
float  wheelIncrementY 
) [virtual]

Reimplemented from Component.

bool TextEditor::keyPressed ( const KeyPress key) [virtual]

Reimplemented from Component.

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

Reimplemented from Component.

void TextEditor::focusGained ( FocusChangeType  cause) [virtual]

Reimplemented from Component.

void TextEditor::focusLost ( FocusChangeType  cause) [virtual]

Reimplemented from Component.

void TextEditor::resized ( ) [virtual]

Reimplemented from Component.

void TextEditor::enablementChanged ( ) [virtual]

Reimplemented from Component.

void TextEditor::colourChanged ( ) [virtual]

Reimplemented from Component.

void TextEditor::lookAndFeelChanged ( ) [virtual]

Reimplemented from Component.

bool TextEditor::isTextInputActive ( ) const [virtual]

Implements TextInputTarget.

void TextEditor::setTemporaryUnderlining ( const Array< Range< int > > &  ) [virtual]

Implements TextInputTarget.

bool TextEditor::moveCaretLeft ( bool  moveInWholeWordSteps,
bool  selecting 
)
bool TextEditor::moveCaretRight ( bool  moveInWholeWordSteps,
bool  selecting 
)
bool TextEditor::moveCaretUp ( bool  selecting)
bool TextEditor::moveCaretDown ( bool  selecting)
bool TextEditor::pageUp ( bool  selecting)
bool TextEditor::pageDown ( bool  selecting)
bool TextEditor::moveCaretToTop ( bool  selecting)
bool TextEditor::moveCaretToStartOfLine ( bool  selecting)
bool TextEditor::moveCaretToEnd ( bool  selecting)
bool TextEditor::moveCaretToEndOfLine ( bool  selecting)
bool TextEditor::deleteBackwards ( bool  moveInWholeWordSteps)
bool TextEditor::deleteForwards ( bool  moveInWholeWordSteps)
bool TextEditor::undo ( )
bool TextEditor::redo ( )
virtual void TextEditor::addPopupMenuItems ( PopupMenu menuToAddTo,
const MouseEvent mouseClickEvent 
) [virtual]

This adds the items to the popup menu.

By default it adds the cut/copy/paste items, but you can override this if you need to replace these with your own items.

If you want to add your own items to the existing ones, you can override this, call the base class's addPopupMenuItems() method, then append your own items.

When the menu has been shown, performPopupMenuAction() will be called to perform the item that the user has chosen.

The default menu items will be added using item IDs in the range 0x7fff0000 - 0x7fff1000, so you should avoid those values for your own menu IDs.

If this was triggered by a mouse-click, the mouseClickEvent parameter will be a pointer to the info about it, or may be null if the menu is being triggered by some other means.

See also:
performPopupMenuAction, setPopupMenuEnabled, isPopupMenuEnabled
virtual void TextEditor::performPopupMenuAction ( int  menuItemID) [virtual]

This is called to perform one of the items that was shown on the popup menu.

If you've overridden addPopupMenuItems(), you should also override this to perform the actions that you've added.

If you've overridden addPopupMenuItems() but have still left the default items on the menu, remember to call the superclass's performPopupMenuAction() so that it can perform the default actions if that's what the user clicked on.

See also:
addPopupMenuItems, setPopupMenuEnabled, isPopupMenuEnabled

Scrolls the minimum distance needed to get the caret into view.

void TextEditor::moveCaret ( int  newCaretPos) [protected]
void TextEditor::moveCaretTo ( int  newPosition,
bool  isSelecting 
) [protected]
void TextEditor::textChanged ( ) [protected]

Used internally to dispatch a text-change message.

void TextEditor::newTransaction ( ) [protected]

Begins a new transaction in the UndoManager.

void TextEditor::doUndoRedo ( bool  isRedo) [protected]

Used internally to trigger an undo or redo.

virtual void TextEditor::returnPressed ( ) [protected, virtual]

Can be overridden to intercept return key presses directly.

virtual void TextEditor::escapePressed ( ) [protected, virtual]

Can be overridden to intercept escape key presses directly.

void TextEditor::handleCommandMessage ( int  commandId) [protected, virtual]

Reimplemented from Component.


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