TGUI  1.3.0
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
26#ifndef TGUI_TEXT_AREA_HPP
27#define TGUI_TEXT_AREA_HPP
28
29
30#include <TGUI/CopiedSharedPtr.hpp>
31#include <TGUI/Widgets/Scrollbar.hpp>
32#include <TGUI/Renderers/TextAreaRenderer.hpp>
33#include <TGUI/Text.hpp>
34
36
37TGUI_MODULE_EXPORT namespace tgui
38{
45 class TGUI_API TextArea : public Widget
46 {
47 public:
48
49 using Ptr = std::shared_ptr<TextArea>;
50 using ConstPtr = std::shared_ptr<const TextArea>;
51
52 static constexpr const char StaticWidgetType[] = "TextArea";
53
54
62 TextArea(const char* typeName = StaticWidgetType, bool initRenderer = true);
63
64
71 TGUI_NODISCARD static TextArea::Ptr create();
72
73
81 TGUI_NODISCARD static TextArea::Ptr copy(const TextArea::ConstPtr& textArea);
82
83
88 TGUI_NODISCARD TextAreaRenderer* getSharedRenderer() override;
89 TGUI_NODISCARD const TextAreaRenderer* getSharedRenderer() const override;
90
96 TGUI_NODISCARD TextAreaRenderer* getRenderer() override;
97
98
107 void setSize(const Layout2d& size) override;
108 using Widget::setSize;
109
110
117 void setText(String text);
118
119
126 void addText(String text);
127
128
135 TGUI_NODISCARD String getText() const;
136
137
143 void setDefaultText(const String& text);
144
145
151 TGUI_NODISCARD const String& getDefaultText() const;
152
153
160 void setSelectedText(std::size_t selectionStartIndex, std::size_t selectionEndIndex);
161
162
169 TGUI_NODISCARD String getSelectedText() const;
170
171
182 TGUI_NODISCARD std::size_t getSelectionStart() const;
183
184
195 TGUI_NODISCARD std::size_t getSelectionEnd() const;
196
197
207 void setMaximumCharacters(std::size_t maxChars = 0);
208
209
219 TGUI_NODISCARD std::size_t getMaximumCharacters() const;
220
221
234 void setTabString(String tabText);
235
236
245 TGUI_NODISCARD String getTabString() const;
246
247
255 void setCaretPosition(std::size_t charactersBeforeCaret);
256
257
265 TGUI_NODISCARD std::size_t getCaretPosition() const;
266
267
279 TGUI_NODISCARD std::size_t getCaretLine() const;
280
281
293 TGUI_NODISCARD std::size_t getCaretColumn() const;
294
295
305 void setReadOnly(bool readOnly = true);
306
307
317 TGUI_NODISCARD bool isReadOnly() const;
318
319
327
328
336
337
345
346
354
355
364 TGUI_NODISCARD std::size_t getLinesCount() const;
365
366
375 void setFocused(bool focused) override;
376
377
389 void enableMonospacedFontOptimization(bool enable = true);
390
391
397 void setVerticalScrollbarValue(unsigned int value);
398
399
405 TGUI_NODISCARD unsigned int getVerticalScrollbarValue() const;
406
407
413 void setHorizontalScrollbarValue(unsigned int value);
414
415
421 TGUI_NODISCARD unsigned int getHorizontalScrollbarValue() const;
422
423
430 TGUI_NODISCARD bool isMouseOnWidget(Vector2f pos) const override;
431
435 bool leftMousePressed(Vector2f pos) override;
436
440 void leftMouseReleased(Vector2f pos) override;
441
445 void mouseMoved(Vector2f pos) override;
446
450 void keyPressed(const Event::KeyEvent& event) override;
451
461 bool canHandleKeyPress(const Event::KeyEvent& event) override;
462
466 void textEntered(char32_t key) override;
467
471 bool scrolled(float delta, Vector2f pos, bool touch) override;
472
476 void mouseNoLongerOnWidget() override;
477
481 void leftMouseButtonNoLongerDown() override;
482
483
485 protected:
486
487
489 // This function will search after which character the caret should be placed. It will not change the caret position.
491 TGUI_NODISCARD Vector2<std::size_t> findCaretPosition(Vector2f position) const;
492
493
495 // Gets the index of either m_selStart or m_selEnd
497 TGUI_NODISCARD std::size_t getIndexOfSelectionPos(Vector2<std::size_t> selectionPos) const;
498
499
501 // Removes the selected characters. This function is called when pressing backspace, delete or a letter while there were
502 // some characters selected.
504 void deleteSelectedCharacters();
505
506
508 // Inserts text at the current caret position.
509 // If the given string exceeds the maximum character limit,
510 // excess characters from the right side of the string will not be inserted.
512 void insertTextAtCaretPosition(String text);
513
514
516 // Rearrange the text inside the text area (by using word wrap).
518 void rearrangeText(bool keepSelection, const bool emitCaretChangedPosition = true);
519
520
522 // Updates the physical size of the scrollbars, as well as the viewport size.
524 void updateScrollbars();
525
526
528 // This function will split the text into five pieces so that the text can be easily drawn.
530 void updateSelectionTexts();
531
532
534 // Handles "Backspace" key press
536 void backspaceKeyPressed();
537
539 // Handles "Delete" key press
541 void deleteKeyPressed();
542
544 // Handles "Ctrl+C" key press (or equivalent on macOS)
546 void copySelectedTextToClipboard();
547
549 // Handles "Ctrl+X" key press (or equivalent on macOS)
551 void cutSelectedTextToClipboard();
552
554 // Handles "Ctrl+V" key press (or equivalent on macOS)
556 void pasteTextFromClipboard();
557
559 // Handles "Ctrl+A" key press (or equivalent on macOS)
561 void selectAllText();
562
564 // Handles "PageUp" key press
566 void moveCaretPageUp();
567
569 // Handles "PageDown" key press
571 void moveCaretPageDown();
572
574 // Handles "ArrowLeft" key press
576 void moveCaretLeft(bool shiftPressed);
577
579 // Handles "ArrowRight" key press
581 void moveCaretRight(bool shiftPressed);
582
584 // Handles "Ctrl+ArrowLeft" key press (or equivalent on macOS)
586 void moveCaretWordBegin();
587
589 // Handles "Ctrl+ArrowRight" key press (or equivalent on macOS)
591 void moveCaretWordEnd();
592
593
601 void draw(BackendRenderTarget& target, RenderStates states) const override;
602
603
605 private:
606
608 // Implementation of setCaretPosition() that either updates or retains the m_selEnd value.
610 void setCaretPositionImpl(std::size_t charactersBeforeCaret, bool selEndNeedUpdate, bool emitCaretChangedPosition);
611
612
614 protected:
615
617 // Returns the size without the borders
619 TGUI_NODISCARD Vector2f getInnerSize() const;
620
621
623 // This function is called every frame with the time passed since the last frame.
625 bool updateTime(Duration elapsedTime) override;
626
627
629 // Recalculates the positions of the contents of the text area.
631 void recalculatePositions();
632
633
635 // Recalculates which lines are currently visible.
637 void recalculateVisibleLines();
638
639
649 TGUI_NODISCARD Signal& getSignal(String signalName) override;
650
651
658 void rendererChanged(const String& property) override;
659
660
664 TGUI_NODISCARD std::unique_ptr<DataIO::Node> save(SavingRenderersMap& renderers) const override;
665
666
670 void load(const std::unique_ptr<DataIO::Node>& node, const LoadingRenderersMap& renderers) override;
671
672
676 void updateTextSize() override;
677
678
680 // Makes a copy of the widget
682 TGUI_NODISCARD Widget::Ptr clone() const override;
683
684
686 // Updates m_selEnd with a new value and emits the onCaretPositionChange signal
687 // @param newValue the value to assign to m_selEnd.
689 void updateSelEnd(const Vector2<std::size_t>& newValue);
690
691
693 public:
694
695 SignalString onTextChange = {"TextChanged"};
696 Signal onSelectionChange = {"SelectionChanged"};
697 Signal onCaretPositionChange = {"CaretPositionChanged"};
698
699
701 protected:
702
703 String m_text;
704 float m_lineHeight = 24;
705
706 // The width of the largest line
707 float m_maxLineWidth = 0;
708
709 std::vector<String> m_lines;
710
711 // The maximum characters (0 by default, which means no limit)
712 std::size_t m_maxChars = 0;
713
714 // What is known about the visible lines?
715 std::size_t m_topLine = 1;
716 std::size_t m_visibleLines = 1;
717
718 // Information about the selection
719 Vector2<std::size_t> m_selStart;
720 Vector2<std::size_t> m_selEnd;
721 std::pair<Vector2<std::size_t>, Vector2<std::size_t>> m_lastSelection;
722
723 // Information about the caret
724 Vector2f m_caretPosition;
725 bool m_caretVisible = true;
726
727 // The text to insert when Tab is pressed
728 String m_tabText = U"\t";
729
730 Text m_textBeforeSelection;
731 Text m_textSelection1;
732 Text m_textSelection2;
733 Text m_textAfterSelection1;
734 Text m_textAfterSelection2;
735 Text m_defaultText;
736
737 std::vector<FloatRect> m_selectionRects;
738
739 // The scrollbars
740 CopiedSharedPtr<ScrollbarChildWidget> m_verticalScrollbar;
741 CopiedSharedPtr<ScrollbarChildWidget> m_horizontalScrollbar;
742 Scrollbar::Policy m_verticalScrollbarPolicy = Scrollbar::Policy::Automatic;
743 Scrollbar::Policy m_horizontalScrollbarPolicy = Scrollbar::Policy::Never;
744
745 // Is there a possibility that the user is going to double click?
746 bool m_possibleDoubleClick = false;
747
748 bool m_readOnly = false;
749
750 bool m_monospacedFontOptimizationEnabled = false;
751
752 Sprite m_spriteBackground;
753
754 // Cached renderer properties
755 Borders m_bordersCached;
756 Padding m_paddingCached;
757 Color m_borderColorCached;
758 Color m_backgroundColorCached;
759 Color m_caretColorCached;
760 Color m_selectedTextBackgroundColorCached;
761 float m_caretWidthCached = 1;
762
764 };
765
767}
768
770
771#endif // TGUI_TEXT_AREA_HPP
Base class for render targets.
Definition BackendRenderTarget.hpp:48
Wrapper for colors.
Definition Color.hpp:74
Definition CopiedSharedPtr.hpp:45
Wrapper for durations.
Definition Duration.hpp:56
Class to store the position or size of a widget.
Definition Layout.hpp:328
Definition Outline.hpp:39
Policy
Defines when the scrollbar shows up.
Definition Scrollbar.hpp:56
Signal to which the user can subscribe to get callbacks from.
Definition Signal.hpp:62
Definition Sprite.hpp:48
Wrapper class to store strings.
Definition String.hpp:101
Definition TextAreaRenderer.hpp:37
Text area widget.
Definition TextArea.hpp:46
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.
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:50
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:49
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 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.
Backend-independent wrapper around the backend-specific text class.
Definition Text.hpp:50
The parent class for every widget.
Definition Widget.hpp:84
std::shared_ptr< Widget > Ptr
Shared widget pointer.
Definition Widget.hpp:87
Namespace that contains all TGUI functions and classes.
Definition AbsoluteOrRelativeValue.hpp:39
KeyPressed event parameters.
Definition Event.hpp:169
States used for drawing.
Definition RenderStates.hpp:39