--- --- TGUI: include/TGUI/Widgets/TextArea.hpp Source File
TGUI  1.x-dev
Loading...
Searching...
No Matches
TextArea.hpp
1
2//
3// TGUI - Texus' Graphical User Interface
4// Copyright (C) 2012-2024 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/CopiedSharedPtr.hpp>
29#include <TGUI/Widgets/Scrollbar.hpp>
30#include <TGUI/Renderers/TextAreaRenderer.hpp>
31#include <TGUI/Text.hpp>
32
34
35TGUI_MODULE_EXPORT namespace tgui
36{
43 class TGUI_API TextArea : public Widget
44 {
45 public:
46
47 using Ptr = std::shared_ptr<TextArea>;
48 using ConstPtr = std::shared_ptr<const TextArea>;
49
50 static constexpr const char StaticWidgetType[] = "TextArea";
51
59 TextArea(const char* typeName = StaticWidgetType, bool initRenderer = true);
60
66 TGUI_NODISCARD static TextArea::Ptr create();
67
75 TGUI_NODISCARD static TextArea::Ptr copy(const TextArea::ConstPtr& textArea);
76
81 TGUI_NODISCARD TextAreaRenderer* getSharedRenderer() override;
82 TGUI_NODISCARD const TextAreaRenderer* getSharedRenderer() const override;
83
89 TGUI_NODISCARD TextAreaRenderer* getRenderer() override;
90
98 void setSize(const Layout2d& size) override;
99 using Widget::setSize;
100
106 void setText(String text);
107
113 void addText(String text);
114
120 TGUI_NODISCARD String getText() const;
121
127 void setDefaultText(const String& text);
128
134 TGUI_NODISCARD const String& getDefaultText() const;
135
142 void setSelectedText(std::size_t selectionStartIndex, std::size_t selectionEndIndex);
143
149 TGUI_NODISCARD String getSelectedText() const;
150
161 TGUI_NODISCARD std::size_t getSelectionStart() const;
162
173 TGUI_NODISCARD std::size_t getSelectionEnd() const;
174
183 void setMaximumCharacters(std::size_t maxChars = 0);
184
193 TGUI_NODISCARD std::size_t getMaximumCharacters() const;
194
206 void setTabString(String tabText);
207
215 TGUI_NODISCARD String getTabString() const;
216
224 void setCaretPosition(std::size_t charactersBeforeCaret);
225
233 TGUI_NODISCARD std::size_t getCaretPosition() const;
234
246 TGUI_NODISCARD std::size_t getCaretLine() const;
247
259 TGUI_NODISCARD std::size_t getCaretColumn() const;
260
269 void setReadOnly(bool readOnly = true);
270
279 TGUI_NODISCARD bool isReadOnly() const;
280
288
296
304
312
320 TGUI_NODISCARD std::size_t getLinesCount() const;
321
330 void setFocused(bool focused) override;
331
343 void enableMonospacedFontOptimization(bool enable = true);
344
350 void setVerticalScrollbarValue(unsigned int value);
351
357 TGUI_NODISCARD unsigned int getVerticalScrollbarValue() const;
358
366 TGUI_NODISCARD unsigned int getVerticalScrollbarMaxValue() const;
367
373 void setHorizontalScrollbarValue(unsigned int value);
374
380 TGUI_NODISCARD unsigned int getHorizontalScrollbarValue() const;
381
389 TGUI_NODISCARD unsigned int getHorizontalScrollbarMaxValue() const;
390
396 TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override;
397
401 bool leftMousePressed(Vector2f pos) override;
402
406 void leftMouseReleased(Vector2f pos) override;
407
411 void mouseMoved(Vector2f pos) override;
412
416 void keyPressed(const Event::KeyEvent& event) override;
417
427 bool canHandleKeyPress(const Event::KeyEvent& event) override;
428
432 void textEntered(char32_t key) override;
433
437 bool scrolled(float delta, Vector2f pos, bool touch) override;
438
442 void mouseNoLongerOnWidget() override;
443
447 void leftMouseButtonNoLongerDown() override;
448
450 protected:
451
453 // This function will search after which character the caret should be placed. It will not change the caret position.
455 TGUI_NODISCARD Vector2<std::size_t> findCaretPosition(Vector2f position) const;
456
458 // Gets the index of either m_selStart or m_selEnd
460 TGUI_NODISCARD std::size_t getIndexOfSelectionPos(Vector2<std::size_t> selectionPos) const;
461
463 // Removes the selected characters. This function is called when pressing backspace, delete or a letter while there were
464 // some characters selected.
466 void deleteSelectedCharacters();
467
469 // Inserts text at the current caret position.
470 // If the given string exceeds the maximum character limit,
471 // excess characters from the right side of the string will not be inserted.
473 void insertTextAtCaretPosition(String text);
474
476 // Rearrange the text inside the text area (by using word wrap).
478 void rearrangeText(bool keepSelection, const bool emitCaretChangedPosition = true);
479
481 // Updates the physical size of the scrollbars, as well as the viewport size.
483 void updateScrollbars();
484
486 // This function will split the text into five pieces so that the text can be easily drawn.
488 void updateSelectionTexts();
489
491 // Handles "Backspace" key press
493 void backspaceKeyPressed();
494
496 // Handles "Delete" key press
498 void deleteKeyPressed();
499
501 // Handles "Ctrl+C" key press (or equivalent on macOS)
503 void copySelectedTextToClipboard();
504
506 // Handles "Ctrl+X" key press (or equivalent on macOS)
508 void cutSelectedTextToClipboard();
509
511 // Handles "Ctrl+V" key press (or equivalent on macOS)
513 void pasteTextFromClipboard();
514
516 // Handles "Ctrl+A" key press (or equivalent on macOS)
518 void selectAllText();
519
521 // Handles "PageUp" key press
523 void moveCaretPageUp();
524
526 // Handles "PageDown" key press
528 void moveCaretPageDown();
529
531 // Handles "ArrowLeft" key press
533 void moveCaretLeft(bool shiftPressed);
534
536 // Handles "ArrowRight" key press
538 void moveCaretRight(bool shiftPressed);
539
541 // Handles "Ctrl+ArrowLeft" key press (or equivalent on macOS)
543 void moveCaretWordBegin();
544
546 // Handles "Ctrl+ArrowRight" key press (or equivalent on macOS)
548 void moveCaretWordEnd();
549
556 void draw(BackendRenderTarget& target, RenderStates states) const override;
557
559 private:
560
562 // Implementation of setCaretPosition() that either updates or retains the m_selEnd value.
564 void setCaretPositionImpl(std::size_t charactersBeforeCaret, bool selEndNeedUpdate, bool emitCaretChangedPosition);
565
567 protected:
568
570 // Returns the size without the borders
572 TGUI_NODISCARD Vector2f getInnerSize() const;
573
575 // This function is called every frame with the time passed since the last frame.
577 bool updateTime(Duration elapsedTime) override;
578
580 // Recalculates the positions of the contents of the text area.
582 void recalculatePositions();
583
585 // Recalculates which lines are currently visible.
587 void recalculateVisibleLines();
588
598 TGUI_NODISCARD Signal& getSignal(String signalName) override;
599
605 void rendererChanged(const String& property) override;
606
610 TGUI_NODISCARD std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
611
615 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
616
620 void updateTextSize() override;
621
623 // Makes a copy of the widget
625 TGUI_NODISCARD Widget::Ptr clone() const override;
626
628 // Updates m_selEnd with a new value and emits the onCaretPositionChange signal
629 // @param newValue the value to assign to m_selEnd.
631 void updateSelEnd(const Vector2<std::size_t>& newValue);
632
634 public:
635
636 SignalString onTextChange = {"TextChanged"};
637 Signal onSelectionChange = {"SelectionChanged"};
638 Signal onCaretPositionChange = {"CaretPositionChanged"};
639
641 protected:
642
643 String m_text;
644 float m_lineHeight = 24;
645
646 // The width of the largest line
647 float m_maxLineWidth = 0;
648
649 std::vector<String> m_lines;
650
651 // The maximum characters (0 by default, which means no limit)
652 std::size_t m_maxChars = 0;
653
654 // What is known about the visible lines?
655 std::size_t m_topLine = 1;
656 std::size_t m_visibleLines = 1;
657
658 // Information about the selection
659 Vector2<std::size_t> m_selStart;
660 Vector2<std::size_t> m_selEnd;
661 std::pair<Vector2<std::size_t>, Vector2<std::size_t>> m_lastSelection;
662
663 // Information about the caret
664 Vector2f m_caretPosition;
665 bool m_caretVisible = true;
666
667 // The text to insert when Tab is pressed
668 String m_tabText = U"\t";
669
670 Text m_textBeforeSelection;
671 Text m_textSelection1;
672 Text m_textSelection2;
673 Text m_textAfterSelection1;
674 Text m_textAfterSelection2;
675 Text m_defaultText;
676
677 std::vector<FloatRect> m_selectionRects;
678
679 // The scrollbars
680 CopiedSharedPtr<ScrollbarChildWidget> m_verticalScrollbar;
681 CopiedSharedPtr<ScrollbarChildWidget> m_horizontalScrollbar;
682 Scrollbar::Policy m_verticalScrollbarPolicy = Scrollbar::Policy::Automatic;
683 Scrollbar::Policy m_horizontalScrollbarPolicy = Scrollbar::Policy::Never;
684
685 // Is there a possibility that the user is going to double click?
686 bool m_possibleDoubleClick = false;
687
688 bool m_readOnly = false;
689
690 bool m_monospacedFontOptimizationEnabled = false;
691
692 Sprite m_spriteBackground;
693
694 // Cached renderer properties
695 Borders m_bordersCached;
696 Padding m_paddingCached;
697 Color m_borderColorCached;
698 Color m_backgroundColorCached;
699 Color m_caretColorCached;
700 Color m_selectedTextBackgroundColorCached;
701 float m_caretWidthCached = 1;
702
704 };
705
707}
708
710
711#endif // TGUI_TEXT_AREA_HPP
Base class for render targets.
Definition BackendRenderTarget.hpp:46
Wrapper for colors.
Definition Color.hpp:73
Definition CopiedSharedPtr.hpp:42
Wrapper for durations.
Definition Duration.hpp:55
Class to store the position or size of a widget.
Definition Layout.hpp:313
Definition Outline.hpp:38
Policy
Defines when the scrollbar shows up.
Definition Scrollbar.hpp:53
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:61
Definition Sprite.hpp:47
Wrapper class to store strings.
Definition String.hpp:96
Text area widget.
Definition TextArea.hpp:44
void setTabString(String tabText)
Changes the string that is inserted when the Tab key is pressed.
TGUI_NODISCARD unsigned int getVerticalScrollbarValue() const
Returns the thumb position of the vertical scrollbar.
void setReadOnly(bool readOnly=true)
Makes the text area read-only or make it writable again.
void enableMonospacedFontOptimization(bool enable=true)
Changes whether an optimization is made that only works when using a monospaced font.
bool leftMousePressed(Vector2f pos) override
Called by the parent when the left mouse button goes down on top of the widget.
void load(const std::unique_ptr< DataIO::Node > &node, const LoadingRenderersMap &renderers) override
Loads the widget from a tree of nodes.
TGUI_NODISCARD unsigned int getVerticalScrollbarMaxValue() const
Returns the maximum thumb position of the vertical scrollbar.
void setFocused(bool focused) override
Focus or unfocus the widget.
TGUI_NODISCARD 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.
std::shared_ptr< const TextArea > ConstPtr
Shared constant widget pointer.
Definition TextArea.hpp:48
void setHorizontalScrollbarValue(unsigned int value)
Changes the thumb position of the horizontal scrollbar.
TGUI_NODISCARD std::size_t getCaretColumn() const
Returns which column the blinking cursor is currently located on.
static TGUI_NODISCARD TextArea::Ptr create()
Creates a new text area widget.
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:47
void setText(String text)
Changes the text of the text area.
TGUI_NODISCARD std::size_t getCaretPosition() const
Returns after which character the blinking cursor is currently located.
TGUI_NODISCARD Widget::Ptr clone() const override
Makes a copy of the widget if you don't know its exact type.
TGUI_NODISCARD TextAreaRenderer * getSharedRenderer() override
Returns the renderer, which gives access to functions that determine how the widget is displayed.
static TGUI_NODISCARD TextArea::Ptr copy(const TextArea::ConstPtr &textArea)
Makes a copy of another text area.
TGUI_NODISCARD bool isReadOnly() const
Checks if the text area read-only or writable.
void setMaximumCharacters(std::size_t maxChars=0)
Changes the maximum character limit.
TGUI_NODISCARD const String & getDefaultText() const
Returns the default text of the text area. This is the text drawn when the text area is empty.
void setCaretPosition(std::size_t charactersBeforeCaret)
Sets the blinking caret to after a specific character.
TGUI_NODISCARD TextAreaRenderer * getRenderer() override
Returns the renderer, which gives access to functions that determine how the widget is displayed.
TGUI_NODISCARD Signal & getSignal(String signalName) override
Retrieves a signal based on its name.
void setSelectedText(std::size_t selectionStartIndex, std::size_t selectionEndIndex)
Changes which part of the text is selected.
void setHorizontalScrollbarPolicy(Scrollbar::Policy policy)
Changes when the horizontal scrollbar should be displayed.
TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override
Returns whether the mouse position (which is relative to the parent widget) lies on top of the widget...
void setVerticalScrollbarValue(unsigned int value)
Changes the thumb position of the vertical scrollbar.
TGUI_NODISCARD std::size_t getSelectionEnd() const
Returns the index where the selection ends.
TGUI_NODISCARD std::size_t getSelectionStart() const
Returns the index where the selection starts.
TGUI_NODISCARD std::size_t getMaximumCharacters() const
Returns the maximum character limit.
bool canHandleKeyPress(const Event::KeyEvent &event) override
Called by the parent of the widget to check if keyPressed would process the event.
void rendererChanged(const String &property) override
Function called when one of the properties of the renderer is changed.
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...
TGUI_NODISCARD std::size_t getLinesCount() const
Returns the amount of lines that the text occupies in the TextArea.
void draw(BackendRenderTarget &target, RenderStates states) const override
Draw the widget to a render target.
void setDefaultText(const String &text)
Changes the default text of the text area. This is the text drawn when the text area is empty.
void setSize(const Layout2d &size) override
Changes the size of the text area.
void setVerticalScrollbarPolicy(Scrollbar::Policy policy)
Changes when the vertical scrollbar should be displayed.
TGUI_NODISCARD unsigned int getHorizontalScrollbarValue() const
Returns the thumb position of the horizontal scrollbar.
TGUI_NODISCARD unsigned int getHorizontalScrollbarMaxValue() const
Returns the maximum thumb position of the horizontal scrollbar.
TGUI_NODISCARD std::size_t getCaretLine() const
Returns which line the blinking cursor is currently located on.
TGUI_NODISCARD String getText() const
Returns the text of the text area.
TGUI_NODISCARD String getTabString() const
Returns the string that is inserted when the Tab key is pressed.
void updateTextSize() override
Called when the text size is changed (either by setTextSize or via the renderer)
TGUI_NODISCARD Scrollbar::Policy getHorizontalScrollbarPolicy() const
Returns when the horizontal scrollbar should be displayed.
TGUI_NODISCARD String getSelectedText() const
Returns the text that you currently have selected.
TGUI_NODISCARD Scrollbar::Policy getVerticalScrollbarPolicy() const
Returns when the vertical scrollbar should be displayed.
Definition TextAreaRenderer.hpp:35
Backend-independent wrapper around the backend-specific text class.
Definition Text.hpp:48
The parent class for every widget.
Definition Widget.hpp:83
std::shared_ptr< Widget > Ptr
Shared widget pointer.
Definition Widget.hpp:86
Namespace that contains all TGUI functions and classes.
Definition AbsoluteOrRelativeValue.hpp:38
KeyPressed event parameters.
Definition Event.hpp:168
States used for drawing.
Definition RenderStates.hpp:38