1 /** @file abstractlineeditor.h  Abstract line editor.
2  *
3  * @authors Copyright (c) 2013-2017 Jaakko Keränen <jaakko.keranen@iki.fi>
4  *
5  * @par License
6  * LGPL: http://www.gnu.org/licenses/lgpl.html
7  *
8  * <small>This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 3 of the License, or (at your
11  * option) any later version. This program is distributed in the hope that it
12  * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
14  * General Public License for more details. You should have received a copy of
15  * the GNU Lesser General Public License along with this program; if not, see:
16  * http://www.gnu.org/licenses</small>
17  */
18 
19 #ifndef LIBSHELL_ABSTRACTLINEEDITOR_H
20 #define LIBSHELL_ABSTRACTLINEEDITOR_H
21 
22 #include "libshell.h"
23 #include "ITextEditor"
24 #include <de/libcore.h>
25 #include <de/String>
26 #include <de/Vector>
27 
28 namespace de { namespace shell {
29 
30 class Lexicon;
31 
32 /**
33  * Abstract line editor.
34  *
35  * It is mandatory to provide a ILineWrapping instance that determines how the
36  * text content gets wrapped onto multiple lines.
37  *
38  * The width of the editor is assumed to stay constant. A concrete
39  * implementation will provide the current width via
40  * AbstractLineEditor::maximumWidth().
41  *
42  * @ingroup abstractUi
43  */
44 class LIBSHELL_PUBLIC AbstractLineEditor : public ITextEditor
45 {
46 public:
47     AbstractLineEditor(ILineWrapping *lineWraps);
48 
49     ILineWrapping const &lineWraps() const;
50 
51     /**
52      * Sets the prompt that is displayed in front of the edited text.
53      *
54      * @param promptText  Text for the prompt.
55      */
56     void   setPrompt(String const &promptText);
57     String prompt() const;
58 
59     void   setText(String const &lineText);
60     String text() const;
61 
62     void setCursor(int index);
63     int  cursor() const;
64 
65     /**
66      * Determines the position of a specific character on the wrapped lines.
67      * The Y component is the wrapped line index and the X component is the
68      * character index on that line.
69      */
70     Vector2i linePos(int index) const;
71 
lineCursorPos()72     Vector2i lineCursorPos() const { return linePos(cursor()); }
73 
74     bool        isSuggestingCompletion() const;
75     Rangei      completionRange() const;
76     QStringList suggestedCompletions() const;
77     void        acceptCompletion();
78 
79     /**
80      * Defines the terms and rules for auto-completion.
81      *
82      * @param lexicon  Lexicon.
83      */
84     void setLexicon(Lexicon const &lexicon);
85 
86     Lexicon const &lexicon() const;
87 
88     enum EchoMode { NormalEchoMode, PasswordEchoMode };
89 
90     /**
91      * Determines how the entered text should be shown to the user.
92      *
93      * @param mode  Echo mode.
94      */
95     void setEchoMode(EchoMode mode);
96 
97     EchoMode echoMode() const;
98 
99     enum KeyModifier { Unmodified = 0, Shift = 0x1, Control = 0x2, Alt = 0x4, Meta = 0x8 };
100     Q_DECLARE_FLAGS(KeyModifiers, KeyModifier)
101 
102     virtual bool handleControlKey(int qtKey, KeyModifiers const &mods = Unmodified);
103 
104     /**
105      * Inserts a fragment of text at the cursor position. The cursor moves
106      * forward.
107      *
108      * @param text  Text to insert.
109      */
110     void insert(String const &text);
111 
112 protected:
113     ILineWrapping &lineWraps();
114 
115     /// Determines the available maximum width of text lines.
116     virtual int maximumWidth() const = 0;
117 
118     // Notifications:
119     virtual void numberOfLinesChanged(int lineCount) = 0;
120     virtual void cursorMoved()                       = 0;
121     virtual void contentChanged()                    = 0;
122     virtual void autoCompletionBegan(String const &wordBase);
123     virtual void autoCompletionEnded(bool accepted);
124 
125     enum LineWrapUpdateBehavior { RewrapNow, WrapUnlessWrappedAlready };
126 
127     /// Request rewrapping the text.
128     void updateLineWraps(LineWrapUpdateBehavior behavior);
129 
130 private:
131     DENG2_PRIVATE(d)
132 };
133 
134 Q_DECLARE_OPERATORS_FOR_FLAGS(AbstractLineEditor::KeyModifiers)
135 
136 }} // namespace de::shell
137 
138 #endif // LIBSHELL_ABSTRACTLINEEDITOR_H
139