TGUI 1.11
Loading...
Searching...
No Matches
TextArea.hpp
1
2//
3// TGUI - Texus' Graphical User Interface
4// Copyright (C) 2012-2025 Bruno Van de Velde (vdv_b@tgui.eu)
5//
6// This software is provided 'as-is', without any express or implied warranty.
7// In no event will the authors be held liable for any damages arising from the use of this software.
8//
9// Permission is granted to anyone to use this software for any purpose,
10// including commercial applications, and to alter it and redistribute it freely,
11// subject to the following restrictions:
12//
13// 1. The origin of this software must not be misrepresented;
14// you must not claim that you wrote the original software.
15// If you use this software in a product, an acknowledgment
16// in the product documentation would be appreciated but is not required.
17//
18// 2. Altered source versions must be plainly marked as such,
19// and must not be misrepresented as being the original software.
20//
21// 3. This notice may not be removed or altered from any source distribution.
22//
24
25#ifndef TGUI_TEXT_AREA_HPP
26#define TGUI_TEXT_AREA_HPP
27
28#include <TGUI/Widgets/Scrollbar.hpp>
29#include <TGUI/Renderers/TextAreaRenderer.hpp>
30#include <TGUI/Text.hpp>
31
33
34namespace tgui
35{
42 class TGUI_API TextArea : public Widget, public DualScrollbarChildInterface
43 {
44 public:
45
46 using Ptr = std::shared_ptr<TextArea>;
47 using ConstPtr = std::shared_ptr<const TextArea>;
48
49 static constexpr const char StaticWidgetType[] = "TextArea";
50
58 TextArea(const char* typeName = StaticWidgetType, bool initRenderer = true);
59
65 TGUI_NODISCARD static TextArea::Ptr create();
66
74 TGUI_NODISCARD static TextArea::Ptr copy(const TextArea::ConstPtr& textArea);
75
80 TGUI_NODISCARD TextAreaRenderer* getSharedRenderer() override;
81 TGUI_NODISCARD const TextAreaRenderer* getSharedRenderer() const override;
82
88 TGUI_NODISCARD TextAreaRenderer* getRenderer() override;
89
97 void setSize(const Layout2d& size) override;
98 using Widget::setSize;
99
105 void setText(String text);
106
112 void addText(String text);
113
119 TGUI_NODISCARD String getText() const;
120
126 void setDefaultText(const String& text);
127
133 TGUI_NODISCARD const String& getDefaultText() const;
134
141 void setSelectedText(std::size_t selectionStartIndex, std::size_t selectionEndIndex);
142
148 TGUI_NODISCARD String getSelectedText() const;
149
160 TGUI_NODISCARD std::size_t getSelectionStart() const;
161
172 TGUI_NODISCARD std::size_t getSelectionEnd() const;
173
182 void setMaximumCharacters(std::size_t maxChars = 0);
183
192 TGUI_NODISCARD std::size_t getMaximumCharacters() const;
193
205 void setTabString(String tabText);
206
214 TGUI_NODISCARD String getTabString() const;
215
223 void setCaretPosition(std::size_t charactersBeforeCaret);
224
232 TGUI_NODISCARD std::size_t getCaretPosition() const;
233
245 TGUI_NODISCARD std::size_t getCaretLine() const;
246
258 TGUI_NODISCARD std::size_t getCaretColumn() const;
259
268 void setReadOnly(bool readOnly = true);
269
278 TGUI_NODISCARD bool isReadOnly() const;
279
286 TGUI_DEPRECATED("Use getVerticalScrollbar->setPolicy(policy) instead") void setVerticalScrollbarPolicy(Scrollbar::Policy policy);
287
294 TGUI_DEPRECATED("Use getVerticalScrollbar->getPolicy() instead") TGUI_NODISCARD Scrollbar::Policy getVerticalScrollbarPolicy() const;
295
302 TGUI_DEPRECATED("Use getHorizontalScrollbar->setPolicy(policy) instead") void setHorizontalScrollbarPolicy(Scrollbar::Policy policy);
303
310 TGUI_DEPRECATED("Use getHorizontalScrollbar->getPolicy() instead") TGUI_NODISCARD Scrollbar::Policy getHorizontalScrollbarPolicy() const;
311
319 TGUI_NODISCARD std::size_t getLinesCount() const;
320
329 void setFocused(bool focused) override;
330
342 void enableMonospacedFontOptimization(bool enable = true);
343
349 TGUI_DEPRECATED("Use getVerticalScrollbar->setValue(value) instead") void setVerticalScrollbarValue(unsigned int value);
350
356 TGUI_DEPRECATED("Use getVerticalScrollbar->getValue() instead") TGUI_NODISCARD unsigned int getVerticalScrollbarValue() const;
357
365 TGUI_DEPRECATED("Use getVerticalScrollbar->getMaxValue() instead") TGUI_NODISCARD unsigned int getVerticalScrollbarMaxValue() const;
366
372 TGUI_DEPRECATED("Use getHorizontalScrollbar->setValue(value) instead") void setHorizontalScrollbarValue(unsigned int value);
373
379 TGUI_DEPRECATED("Use getHorizontalScrollbar->getValue() instead") TGUI_NODISCARD unsigned int getHorizontalScrollbarValue() const;
380
388 TGUI_DEPRECATED("Use getHorizontalScrollbar->getMaxValue() instead") TGUI_NODISCARD unsigned int getHorizontalScrollbarMaxValue() const;
389
395 TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override;
396
400 bool leftMousePressed(Vector2f pos) override;
401
405 void leftMouseReleased(Vector2f pos) override;
406
410 void mouseMoved(Vector2f pos) override;
411
415 void keyPressed(const Event::KeyEvent& event) override;
416
426 bool canHandleKeyPress(const Event::KeyEvent& event) override;
427
431 void textEntered(char32_t key) override;
432
436 bool scrolled(float delta, Vector2f pos, bool touch) override;
437
441 void mouseNoLongerOnWidget() override;
442
446 void leftMouseButtonNoLongerDown() override;
447
449 protected:
450
452 // This function will search after which character the caret should be placed. It will not change the caret position.
454 TGUI_NODISCARD Vector2<std::size_t> findCaretPosition(Vector2f position) const;
455
457 // Gets the index of either m_selStart or m_selEnd
459 TGUI_NODISCARD std::size_t getIndexOfSelectionPos(Vector2<std::size_t> selectionPos) const;
460
462 // Removes the selected characters. This function is called when pressing backspace, delete or a letter while there were
463 // some characters selected.
465 void deleteSelectedCharacters();
466
468 // Inserts text at the current caret position.
469 // If the given string exceeds the maximum character limit,
470 // excess characters from the right side of the string will not be inserted.
472 void insertTextAtCaretPosition(String text);
473
475 // Rearrange the text inside the text area (by using word wrap).
477 void rearrangeText(bool keepSelection, const bool emitCaretChangedPosition = true);
478
480 // Updates the physical size of the scrollbars, as well as the viewport size.
482 void updateScrollbars();
483
485 // This function will split the text into five pieces so that the text can be easily drawn.
487 void updateSelectionTexts();
488
490 // Handles "Ctrl+Backspace" key press (or equivalent on macOS)
492 void deleteWordLeft();
493
495 // Handles "Ctrl+Delete" key press (or equivalent on macOS)
497 void deleteWordRight();
498
500 // Handles "Backspace" key press (when Ctrl isn't being pressed, otherwise deleteWordLeft is called)
502 void backspaceKeyPressed();
503
505 // Handles "Delete" key press (when Ctrl isn't being pressed, otherwise deleteWordRight is called)
507 void deleteKeyPressed();
508
510 // Handles "Ctrl+C" key press (or equivalent on macOS)
512 void copySelectedTextToClipboard();
513
515 // Handles "Ctrl+X" key press (or equivalent on macOS)
517 void cutSelectedTextToClipboard();
518
520 // Handles "Ctrl+V" key press (or equivalent on macOS)
522 void pasteTextFromClipboard();
523
525 // Handles "Ctrl+A" key press (or equivalent on macOS)
527 void selectAllText();
528
530 // Handles "PageUp" key press
532 void moveCaretPageUp();
533
535 // Handles "PageDown" key press
537 void moveCaretPageDown();
538
540 // Handles "ArrowLeft" key press
542 void moveCaretLeft(bool shiftPressed);
543
545 // Handles "ArrowRight" key press
547 void moveCaretRight(bool shiftPressed);
548
550 // Handles "Ctrl+ArrowLeft" key press (or equivalent on macOS)
552 void moveCaretWordBegin();
553
555 // Handles "Ctrl+ArrowRight" key press (or equivalent on macOS)
557 void moveCaretWordEnd();
558
565 void draw(BackendRenderTarget& target, RenderStates states) const override;
566
568 private:
569
571 // Implementation of setCaretPosition() that either updates or retains the m_selEnd value.
573 void setCaretPositionImpl(std::size_t charactersBeforeCaret, bool selEndNeedUpdate, bool emitCaretChangedPosition);
574
576 protected:
577
579 // Returns the size without the borders
581 TGUI_NODISCARD Vector2f getInnerSize() const;
582
584 // This function is called every frame with the time passed since the last frame.
586 bool updateTime(Duration elapsedTime) override;
587
589 // Recalculates the positions of the contents of the text area.
591 void recalculatePositions();
592
594 // Recalculates which lines are currently visible.
596 void recalculateVisibleLines();
597
607 TGUI_NODISCARD Signal& getSignal(String signalName) override;
608
614 void rendererChanged(const String& property) override;
615
619 TGUI_NODISCARD std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
620
624 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
625
629 void updateTextSize() override;
630
637 void scrollbarPolicyChanged(Orientation orientation) override;
638
640 // Makes a copy of the widget
642 TGUI_NODISCARD Widget::Ptr clone() const override;
643
645 // Updates m_selEnd with a new value and emits the onCaretPositionChange signal
646 // @param newValue the value to assign to m_selEnd.
648 void updateSelEnd(const Vector2<std::size_t>& newValue);
649
651 public:
652
653 SignalString onTextChange = {"TextChanged"};
654 Signal onSelectionChange = {"SelectionChanged"};
655 Signal onCaretPositionChange = {"CaretPositionChanged"};
656
658 protected:
659
660 String m_text;
661 float m_lineHeight = 24;
662
663 // The width of the largest line
664 float m_maxLineWidth = 0;
665
666 std::vector<String> m_lines;
667
668 // The maximum characters (0 by default, which means no limit)
669 std::size_t m_maxChars = 0;
670
671 // What is known about the visible lines?
672 std::size_t m_topLine = 1;
673 std::size_t m_visibleLines = 1;
674
675 // Information about the selection
676 Vector2<std::size_t> m_selStart;
677 Vector2<std::size_t> m_selEnd;
678 std::pair<Vector2<std::size_t>, Vector2<std::size_t>> m_lastSelection;
679
680 // Information about the caret
681 Vector2f m_caretPosition;
682 bool m_caretVisible = true;
683
684 // The text to insert when Tab is pressed
685 String m_tabText = U"\t";
686
687 Text m_textBeforeSelection;
688 Text m_textSelection1;
689 Text m_textSelection2;
690 Text m_textAfterSelection1;
691 Text m_textAfterSelection2;
692 Text m_defaultText;
693
694 std::vector<FloatRect> m_selectionRects;
695
696 // Is there a possibility that the user is going to double click?
697 bool m_possibleDoubleClick = false;
698
699 bool m_readOnly = false;
700
701 bool m_monospacedFontOptimizationEnabled = false;
702
703 Sprite m_spriteBackground;
704
705 // Cached renderer properties
706 Borders m_bordersCached;
707 Padding m_paddingCached;
708 Color m_borderColorCached;
709 Color m_backgroundColorCached;
710 Color m_caretColorCached;
711 Color m_selectedTextBackgroundColorCached;
712 float m_caretWidthCached = 1;
713 float m_roundedBorderRadiusCached = 0;
714
716 };
717
719}
720
722
723#endif // TGUI_TEXT_AREA_HPP
Base class for render targets.
Definition BackendRenderTarget.hpp:46
Wrapper for colors.
Definition Color.hpp:71
DualScrollbarChildInterface()
Default constructor.
Wrapper for durations.
Definition Duration.hpp:53
Class to store the position or size of a widget.
Definition Layout.hpp:321
Scrollbar widget.
Definition Scrollbar.hpp:42
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:59
Definition Sprite.hpp:45
Wrapper class to store strings.
Definition String.hpp:94
Definition TextAreaRenderer.hpp:35
void setTabString(String tabText)
Changes the string that is inserted when the Tab key is pressed.
Signal onCaretPositionChange
Caret position changed.
Definition TextArea.hpp:655
void setReadOnly(bool readOnly=true)
Makes the text area read-only or make it writable again.
Signal & getSignal(String signalName) override
Retrieves a signal based on its name.
void enableMonospacedFontOptimization(bool enable=true)
Changes whether an optimization is made that only works when using a monospaced font.
static constexpr const char StaticWidgetType[]
Type name of the widget.
Definition TextArea.hpp:49
bool leftMousePressed(Vector2f pos) override
Called by the parent when the left mouse button goes down on top of the widget.
String getText() const
Returns the text of the text area.
void load(const std::unique_ptr< DataIO::Node > &node, const LoadingRenderersMap &renderers) override
Loads the widget from a tree of nodes.
void setFocused(bool focused) override
Focus or unfocus the widget.
const String & getDefaultText() const
Returns the default text of the text area. This is the text drawn when the text area is empty.
std::shared_ptr< const TextArea > ConstPtr
Shared constant widget pointer.
Definition TextArea.hpp:47
void setHorizontalScrollbarValue(unsigned int value)
Changes the thumb position of the horizontal scrollbar.
TextAreaRenderer * getSharedRenderer() override
Returns the renderer, which gives access to functions that determine how the widget is displayed.
bool isMouseOnWidget(Vector2f pos) const override
Returns whether the mouse position (which is relative to the parent widget) lies on top of the widget...
SignalString onTextChange
The text was changed. Optional parameter: new text.
Definition TextArea.hpp:653
void scrollbarPolicyChanged(Orientation orientation) override
Called when the policy of one of the scrollbars has been changed calling either getVerticalScrollbar(...
Scrollbar::Policy getHorizontalScrollbarPolicy() const
Returns when the horizontal scrollbar should be displayed.
std::size_t getCaretPosition() const
Returns after which character the blinking cursor is currently located.
void addText(String text)
Appends some text to the text that was already in the text area.
std::shared_ptr< TextArea > Ptr
Shared widget pointer.
Definition TextArea.hpp:46
std::size_t getSelectionEnd() const
Returns the index where the selection ends.
static TextArea::Ptr copy(const TextArea::ConstPtr &textArea)
Makes a copy of another text area.
void setText(String text)
Changes the text of the text area.
bool isReadOnly() const
Checks if the text area read-only or writable.
std::size_t getLinesCount() const
Returns the amount of lines that the text occupies in the TextArea.
unsigned int getHorizontalScrollbarValue() const
Returns the thumb position of the horizontal scrollbar.
void setMaximumCharacters(std::size_t maxChars=0)
Changes the maximum character limit.
void setCaretPosition(std::size_t charactersBeforeCaret)
Sets the blinking caret to after a specific character.
String getSelectedText() const
Returns the text that you currently have selected.
void setSelectedText(std::size_t selectionStartIndex, std::size_t selectionEndIndex)
Changes which part of the text is selected.
unsigned int getVerticalScrollbarMaxValue() const
Returns the maximum thumb position of the vertical scrollbar.
void setHorizontalScrollbarPolicy(Scrollbar::Policy policy)
Changes when the horizontal scrollbar should be displayed.
TextAreaRenderer * getRenderer() override
Returns the renderer, which gives access to functions that determine how the widget is displayed.
void setVerticalScrollbarValue(unsigned int value)
Changes the thumb position of the vertical scrollbar.
bool canHandleKeyPress(const Event::KeyEvent &event) override
Called by the parent of the widget to check if keyPressed would process the event.
Widget::Ptr clone() const override
Makes a copy of the widget if you don't know its exact type.
unsigned int getVerticalScrollbarValue() const
Returns the thumb position of the vertical scrollbar.
std::size_t getSelectionStart() const
Returns the index where the selection starts.
void rendererChanged(const String &property) override
Function called when one of the properties of the renderer is changed.
static TextArea::Ptr create()
Creates a new text area widget.
std::size_t getCaretLine() const
Returns which line the blinking cursor is currently located on.
bool scrolled(float delta, Vector2f pos, bool touch) override
Called by the parent on scroll event (either from mouse wheel of from two finger scrolling on a touch...
void draw(BackendRenderTarget &target, RenderStates states) const override
Draw the widget to a render target.
std::size_t getMaximumCharacters() const
Returns the maximum character limit.
void setDefaultText(const String &text)
Changes the default text of the text area. This is the text drawn when the text area is empty.
std::unique_ptr< DataIO::Node > save(SavingRenderersMap &renderers) const override
Saves the widget as a tree node in order to save it to a file.
unsigned int getHorizontalScrollbarMaxValue() const
Returns the maximum thumb position of the horizontal scrollbar.
void setSize(const Layout2d &size) override
Changes the size of the text area.
Scrollbar::Policy getVerticalScrollbarPolicy() const
Returns when the vertical scrollbar should be displayed.
void setVerticalScrollbarPolicy(Scrollbar::Policy policy)
Changes when the vertical scrollbar should be displayed.
String getTabString() const
Returns the string that is inserted when the Tab key is pressed.
std::size_t getCaretColumn() const
Returns which column the blinking cursor is currently located on.
void updateTextSize() override
Called when the text size is changed (either by setTextSize or via the renderer)
Signal onSelectionChange
Selected text changed.
Definition TextArea.hpp:654
Backend-independent wrapper around the backend-specific text class.
Definition Text.hpp:53
Definition Vector2.hpp:41
virtual void setSize(const Layout2d &size)
Changes the size of the widget.
Namespace that contains all TGUI functions and classes.
Definition AbsoluteOrRelativeValue.hpp:36
Orientation
Orientation of the object.
Definition Layout.hpp:50
SignalTyped< const String & > SignalString
Signal with one "String" as optional unbound parameter.
Definition Signal.hpp:426
Definition Event.hpp:38
States used for drawing.
Definition RenderStates.hpp:38