1 /*
2     Nested list helper
3     SPDX-FileCopyrightText: 2008 Stephen Kelly <steveire@gmail.com>
4 
5     SPDX-License-Identifier: LGPL-2.1-or-later
6 */
7 
8 #ifndef NESTEDLISTHELPER_H
9 #define NESTEDLISTHELPER_H
10 
11 //@cond PRIVATE
12 
13 class QTextEdit;
14 
15 class QKeyEvent;
16 class QDropEvent;
17 class QTextCursor;
18 class QTextList;
19 class QTextBlock;
20 
21 /**
22  *
23  * @short Helper class for automatic handling of nested lists in a text edit
24  *
25  *
26  * @author Stephen Kelly
27  * @since 4.1
28  * @internal
29  */
30 class NestedListHelper
31 {
32 public:
33     /**
34      * Create a helper
35      *
36      * @param te The text edit object to handle lists in.
37      */
38     explicit NestedListHelper(QTextEdit *te);
39 
40     /**
41      * Destructor
42      */
43     ~NestedListHelper();
44 
45     /**
46      *
47      * Handles a key press before it is processed by the text edit widget.
48      *
49      * This includes:
50      *   1. Backspace at the beginning of a line decreases nesting level
51      *   2. Return at the empty list element decreases nesting level
52      *   3. Tab at the beginning of a line OR with a multi-line selection
53      * increases nesting level
54      *
55      * @param event The event to be handled
56      * @return Whether the event was completely handled by this method.
57      */
58     bool handleKeyPressEvent(QKeyEvent *event);
59 
60     bool handleAfterDropEvent(QDropEvent *event);
61 
62     /**
63      * Changes the indent (nesting level) on a current list item or selection
64      * by the value @p delta (typically, +1 or -1)
65      */
66     void changeIndent(int delta);
67 
68     /**
69      * Changes the style of the current list or creates a new list with
70      * the specified style.
71      *
72      * @param styleIndex The QTextListStyle of the list.
73      */
74     void handleOnBulletType(int styleIndex);
75 
76     /**
77      * @brief Check whether the current item in the list may be indented.
78      *
79      * An list item must have an item above it on the same or greater level
80      * if it can be indented.
81      *
82      * Also, a block which is currently part of a list can be indented.
83      *
84      * @sa canDedent
85      *
86      * @return Whether the item can be indented.
87      */
88     bool canIndent() const;
89 
90     /**
91      * \brief Check whether the current item in the list may be dedented.
92      *
93      * An item may be dedented if it is part of a list.
94      * The next item must be at the same or lesser level.
95      *
96      * @sa canIndent
97      *
98      * @return Whether the item can be dedented.
99      */
100     bool canDedent() const;
101 
102 private:
103     QTextCursor topOfSelection() const;
104     QTextCursor bottomOfSelection() const;
105     void processList(QTextList *list);
106     void reformatList(QTextBlock block);
107     void reformatList();
108 
109     QTextEdit *const textEdit;
110 };
111 
112 //@endcond
113 
114 #endif
115