juce_TextEditor.h

Go to the documentation of this file.

 /*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  TextEditor  : public TextInputTarget,
                              public Component,
                              public SettableTooltipClient
{
public:
    //==============================================================================
    explicit TextEditor (const String& componentName = String(),
                         juce_wchar passwordCharacter = 0);
 
    ~TextEditor() override;
 
    //==============================================================================
    void setMultiLine (bool shouldBeMultiLine,
                       bool shouldWordWrap = true);
 
    bool isMultiLine() const;
 
    //==============================================================================
    void setReturnKeyStartsNewLine (bool shouldStartNewLine);
 
    bool getReturnKeyStartsNewLine() const                      { return returnKeyStartsNewLine; }
 
    void setTabKeyUsedAsCharacter (bool shouldTabKeyBeUsed);
 
    bool isTabKeyUsedAsCharacter() const                        { return tabKeyUsed; }
 
    void setEscapeAndReturnKeysConsumed (bool shouldBeConsumed) noexcept;
 
    //==============================================================================
    void setReadOnly (bool shouldBeReadOnly);
 
    bool isReadOnly() const noexcept;
 
    //==============================================================================
    void setCaretVisible (bool shouldBeVisible);
 
    bool isCaretVisible() const noexcept                            { return caretVisible && ! isReadOnly(); }
 
    //==============================================================================
    void setScrollbarsShown (bool shouldBeEnabled);
 
    bool areScrollbarsShown() const noexcept                        { return scrollbarVisible; }
 
    void setPasswordCharacter (juce_wchar passwordCharacter);
 
    juce_wchar getPasswordCharacter() const noexcept                { return passwordCharacter; }
 
    //==============================================================================
    void setPopupMenuEnabled (bool menuEnabled);
 
    bool isPopupMenuEnabled() const noexcept                        { return popupMenuEnabled; }
 
    bool isPopupMenuCurrentlyActive() const noexcept                { return menuActive; }
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId       = 0x1000200, 
        textColourId             = 0x1000201, 
        highlightColourId        = 0x1000202, 
        highlightedTextColourId  = 0x1000203, 
        outlineColourId          = 0x1000205, 
        focusedOutlineColourId   = 0x1000206, 
        shadowColourId           = 0x1000207, 
    };
 
    //==============================================================================
    void setFont (const Font& newFont);
 
    void applyFontToAllText (const Font& newFont, bool changeCurrentFont = true);
 
    const Font& getFont() const noexcept  { return currentFont; }
 
    void applyColourToAllText (const Colour& newColour, bool changeCurrentTextColour = true);
 
    void setWhitespaceUnderlined (bool shouldUnderlineWhitespace) noexcept  { underlineWhitespace = shouldUnderlineWhitespace; }
 
    bool isWhitespaceUnderlined() const noexcept                            { return underlineWhitespace; }
 
    //==============================================================================
    void setSelectAllWhenFocused (bool shouldSelectAll);
 
    void setTextToShowWhenEmpty (const String& text, Colour colourToUse);
 
    String getTextToShowWhenEmpty() const noexcept    { return textToShowWhenEmpty; }
 
    //==============================================================================
    void setScrollBarThickness (int newThicknessPixels);
 
    //==============================================================================
    class JUCE_API  Listener
    {
    public:
        virtual ~Listener() = default;
 
        virtual void textEditorTextChanged (TextEditor&) {}
 
        virtual void textEditorReturnKeyPressed (TextEditor&) {}
 
        virtual void textEditorEscapeKeyPressed (TextEditor&) {}
 
        virtual void textEditorFocusLost (TextEditor&) {}
    };
 
    void addListener (Listener* newListener);
 
    void removeListener (Listener* listenerToRemove);
 
    //==============================================================================
    std::function<void()> onTextChange;
 
    std::function<void()> onReturnKey;
 
    std::function<void()> onEscapeKey;
 
    std::function<void()> onFocusLost;
 
    //==============================================================================
    String getText() const;
 
    String getTextInRange (const Range<int>& textRange) const override;
 
    bool isEmpty() const;
 
    void setText (const String& newText,
                  bool sendTextChangeMessage = true);
 
    Value& getTextValue();
 
    void insertTextAtCaret (const String& textToInsert) override;
 
    void clear();
 
    void cut();
 
    void copy();
 
    void paste();
 
    //==============================================================================
    int getCaretPosition() const override;
 
    void setCaretPosition (int newIndex);
 
    void scrollEditorToPositionCaret (int desiredCaretX, int desiredCaretY);
 
    Rectangle<int> getCaretRectangleForCharIndex (int index) const override;
 
    void setHighlightedRegion (const Range<int>& newSelection) override;
 
    Range<int> getHighlightedRegion() const override            { return selection; }
 
    String getHighlightedText() const;
 
    int getTextIndexAt (int x, int y) const;
 
    int getTextIndexAt (Point<int>) const;
 
    int getCharIndexForPoint (Point<int> point) const override;
 
    int getTotalNumChars() const override;
 
    int getTextWidth() const;
 
    int getTextHeight() const;
 
    void setIndents (int newLeftIndent, int newTopIndent);
 
    int getTopIndent() const noexcept   { return topIndent; }
 
    int getLeftIndent() const noexcept  { return leftIndent; }
 
    void setBorder (BorderSize<int> border);
 
    BorderSize<int> getBorder() const;
 
    void setScrollToShowCursor (bool shouldScrollToShowCaret);
 
    void setJustification (Justification newJustification);
 
    Justification getJustificationType() const noexcept             { return justification; }
 
    void setLineSpacing (float newLineSpacing) noexcept             { lineSpacing = jmax (1.0f, newLineSpacing); }
 
    float getLineSpacing() const noexcept                           { return lineSpacing; }
 
    RectangleList<int> getTextBounds (Range<int> textRange) const override;
 
    //==============================================================================
    void moveCaretToEnd();
    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);
 
    virtual void performPopupMenuAction (int menuItemID);
 
    //==============================================================================
    class JUCE_API  InputFilter
    {
    public:
        InputFilter() = default;
        virtual ~InputFilter() = default;
 
        virtual String filterNewText (TextEditor&, const String& newInput) = 0;
    };
 
    class JUCE_API  LengthAndCharacterRestriction  : public InputFilter
    {
    public:
        LengthAndCharacterRestriction (int maxNumChars, const String& allowedCharacters);
 
        String filterNewText (TextEditor&, const String&) override;
 
    private:
        String allowedCharacters;
        int maxLength;
 
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (LengthAndCharacterRestriction)
    };
 
    void setInputFilter (InputFilter* newFilter, bool takeOwnership);
 
    InputFilter* getInputFilter() const noexcept                { return inputFilter; }
 
    void setInputRestrictions (int maxTextLength,
                               const String& allowedCharacters = String());
 
    void setKeyboardType (VirtualKeyboardType type) noexcept    { keyboardType = type; }
 
    void setClicksOutsideDismissVirtualKeyboard (bool);
 
    bool getClicksOutsideDismissVirtualKeyboard() const     { return clicksOutsideDismissVirtualKeyboard; }
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() = default;
 
        virtual void fillTextEditorBackground (Graphics&, int width, int height, TextEditor&) = 0;
        virtual void drawTextEditorOutline (Graphics&, int width, int height, TextEditor&) = 0;
 
        virtual CaretComponent* createCaretComponent (Component* keyFocusOwner) = 0;
    };
 
    //==============================================================================
    void paint (Graphics&) override;
    void paintOverChildren (Graphics&) override;
    void mouseDown (const MouseEvent&) override;
    void mouseUp (const MouseEvent&) override;
    void mouseDrag (const MouseEvent&) override;
    void mouseDoubleClick (const MouseEvent&) override;
    void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
    bool keyPressed (const KeyPress&) override;
    bool keyStateChanged (bool) override;
    void focusGained (FocusChangeType) override;
    void focusLost (FocusChangeType) override;
    void resized() override;
    void enablementChanged() override;
    void lookAndFeelChanged() override;
    void parentHierarchyChanged() override;
    bool isTextInputActive() const override;
    void setTemporaryUnderlining (const Array<Range<int>>&) override;
    VirtualKeyboardType getKeyboardType() override;
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 
protected:
    //==============================================================================
    void scrollToMakeSureCursorIsVisible();
 
    void textChanged();
 
    void newTransaction();
 
    virtual void returnPressed();
 
    virtual void escapePressed();
 
private:
    //==============================================================================
    JUCE_PUBLIC_IN_DLL_BUILD (class UniformTextSection)
    struct Iterator;
    struct TextHolderComponent;
    struct TextEditorViewport;
    struct InsertAction;
    struct RemoveAction;
    class EditorAccessibilityHandler;
 
    class GlobalMouseListener : private MouseListener
    {
    public:
        explicit GlobalMouseListener (Component& e) : editor (e) { Desktop::getInstance().addGlobalMouseListener    (this); }
        ~GlobalMouseListener() override                          { Desktop::getInstance().removeGlobalMouseListener (this); }
 
        bool lastMouseDownInEditor() const { return mouseDownInEditor; }
 
    private:
        void mouseDown (const MouseEvent& event) override { mouseDownInEditor = event.originalComponent == &editor; }
 
        Component& editor;
        bool mouseDownInEditor = false;
    };
 
    std::unique_ptr<Viewport> viewport;
    TextHolderComponent* textHolder;
    BorderSize<int> borderSize { 1, 1, 1, 3 };
    Justification justification { Justification::topLeft };
    const GlobalMouseListener globalMouseListener { *this };
 
    bool readOnly = false;
    bool caretVisible = true;
    bool multiline = false;
    bool wordWrap = false;
    bool returnKeyStartsNewLine = false;
    bool popupMenuEnabled = true;
    bool selectAllTextWhenFocused = false;
    bool scrollbarVisible = true;
    bool wasFocused = false;
    bool keepCaretOnScreen = true;
    bool tabKeyUsed = false;
    bool menuActive = false;
    bool valueTextNeedsUpdating = false;
    bool consumeEscAndReturnKeys = true;
    bool underlineWhitespace = true;
    bool clicksOutsideDismissVirtualKeyboard = false;
 
    UndoManager undoManager;
    std::unique_ptr<CaretComponent> caret;
    Range<int> selection;
    int leftIndent = 4, topIndent = 4;
    unsigned int lastTransactionTime = 0;
    Font currentFont { 14.0f };
    mutable int totalNumChars = 0;
    int caretPosition = 0;
    OwnedArray<UniformTextSection> sections;
    String textToShowWhenEmpty;
    Colour colourForTextWhenEmpty;
    juce_wchar passwordCharacter;
    OptionalScopedPointer<InputFilter> inputFilter;
    Value textValue;
    VirtualKeyboardType keyboardType = TextInputTarget::textKeyboard;
    float lineSpacing = 1.0f;
 
    enum DragType
    {
        notDragging,
        draggingSelectionStart,
        draggingSelectionEnd
    };
 
    DragType dragType = notDragging;
 
    ListenerList<Listener> listeners;
    Array<Range<int>> underlinedSections;
 
    void moveCaret (int newCaretPos);
    void moveCaretTo (int newPosition, bool isSelecting);
    void recreateCaret();
    void handleCommandMessage (int) override;
    void coalesceSimilarSections();
    void splitSection (int sectionIndex, int charToSplitAt);
    void clearInternal (UndoManager*);
    void insert (const String&, int insertIndex, const Font&, Colour, UndoManager*, int newCaretPos);
    void reinsert (int insertIndex, const OwnedArray<UniformTextSection>&);
    void remove (Range<int>, UndoManager*, int caretPositionToMoveTo);
    void getCharPosition (int index, Point<float>&, float& lineHeight) const;
    void updateCaretPosition();
    void updateValueFromText();
    void textWasChangedByValue();
    int indexAtPosition (float x, float y) const;
    int findWordBreakAfter (int position) const;
    int findWordBreakBefore (int position) const;
    bool moveCaretWithTransaction (int newPos, bool selecting);
    void drawContent (Graphics&);
    void checkLayout();
    int getWordWrapWidth() const;
    int getMaximumTextWidth() const;
    int getMaximumTextHeight() const;
    void timerCallbackInt();
    void checkFocus();
    void repaintText (Range<int>);
    void scrollByLines (int deltaLines);
    bool undoOrRedo (bool shouldUndo);
    UndoManager* getUndoManager() noexcept;
    void setSelection (Range<int>) noexcept;
    Point<int> getTextOffset() const noexcept;
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TextEditor)
};
 
 
} // namespace juce