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 Component,
                              public TextInputTarget,
                              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;

    void setCaretPosition (int newIndex);

    void scrollEditorToPositionCaret (int desiredCaretX, int desiredCaretY);

    Rectangle<int> getCaretRectangle() 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 getTotalNumChars() const;

    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);
 
    //==============================================================================
    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    { return keyboardType; }
 
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;
 
    std::unique_ptr<Viewport> viewport;
    TextHolderComponent* textHolder;
    BorderSize<int> borderSize { 1, 1, 1, 3 };
    Justification justification { Justification::topLeft };
 
    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 mouseDownInEditor = false;
    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;
 
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
    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;
    Rectangle<float> getCaretRectangleFloat() 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