Changeset View
Standalone View
src/include/ktexteditor/abstractannotationitemdelegate.h
- This file was added.
1 | /* This file is part of the KDE libraries | ||||
---|---|---|---|---|---|
2 | * Copyright 2017 Friedrich W. H. Kossebau <kossebau kde org> | ||||
3 | * | ||||
4 | * This library is free software; you can redistribute it and/or | ||||
5 | * modify it under the terms of the GNU Library General Public | ||||
6 | * License as published by the Free Software Foundation; either | ||||
7 | * version 2 of the License, or (at your option) any later version. | ||||
8 | * | ||||
9 | * This library is distributed in the hope that it will be useful, | ||||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||||
12 | * Library General Public License for more details. | ||||
13 | * | ||||
14 | * You should have received a copy of the GNU Library General Public License | ||||
15 | * along with this library; see the file COPYING.LIB. If not, write to | ||||
16 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, | ||||
17 | * Boston, MA 02110-1301, USA | ||||
18 | */ | ||||
19 | | ||||
20 | #ifndef KTEXTEDITOR_ABSTRACTANNOTATIONITEMDELEGATE_H | ||||
21 | #define KTEXTEDITOR_ABSTRACTANNOTATIONITEMDELEGATE_H | ||||
22 | | ||||
23 | #include <ktexteditor_export.h> | ||||
24 | | ||||
25 | #include <QObject> | ||||
26 | #include <QStyleOption> | ||||
27 | | ||||
28 | class QHelpEvent; | ||||
29 | class QSize; | ||||
30 | class QPoint; | ||||
31 | | ||||
32 | | ||||
33 | namespace KTextEditor | ||||
34 | { | ||||
35 | class AnnotationModel; | ||||
36 | class View; | ||||
37 | | ||||
38 | class KTEXTEDITOR_EXPORT StyleOptionAnnotationItem : public QStyleOption | ||||
39 | { | ||||
40 | public: | ||||
dhaumann: @since 5.52 :-) | |||||
41 | // TODO: not sure what SO_Default implies, but no clue how to maintain a user type registry? | ||||
42 | enum StyleOptionType { Type = SO_Default }; | ||||
43 | enum StyleOptionVersion { Version = 1 }; | ||||
44 | | ||||
45 | /** | ||||
46 | * Index of the displayed line in the wrapped lines for the given real line | ||||
47 | */ | ||||
48 | int wrappedLine = 0; | ||||
49 | /** | ||||
50 | * Number of wrapped lines for the given real line | ||||
51 | */ | ||||
52 | int wrappedLineCount = 1; | ||||
53 | /** | ||||
I am asking myself: Is wrappedLineCount >= 1 always true? If so, can you add this as documentation? wrappedLineCount == 1 means no wrapping line? dhaumann: I am asking myself: Is wrappedLineCount >= 1 always true? If so, can you add this as… | |||||
Yes. I see now that this can be confusing and semantically strange, if wrappedLineCount == 1 means actually no wrapping here. Unsure what ould be a better way to express this. One ould use the same name and define 0 to mean that no wrapping is done. And 1 would just be a bogus value? Proposals very welcome. kossebau: Yes. I see now that this can be confusing and semantically strange, if wrappedLineCount == 1… | |||||
54 | * Index of the displayed line in the displayed lines for the same group | ||||
55 | */ | ||||
56 | int visibleWrappedLineInGroup = 0; | ||||
57 | | ||||
58 | /** | ||||
59 | * The view where the annotation is shown | ||||
60 | */ | ||||
61 | KTextEditor::View* view = nullptr; | ||||
62 | /** | ||||
63 | * Recommended size for icons or other symbols | ||||
64 | */ | ||||
65 | QSize decorationSize; | ||||
66 | QFontMetricsF contentFontMetrics; | ||||
Is this to be set by the user, and if so, is there any special meaning to a default-constructed QSize()? dhaumann: Is this to be set by the user, and if so, is there any special meaning to a default-constructed… | |||||
This parameter was inspired by QStyleOptionViewItem::decorationSize. I imagined it could be e.g. used if one ever starts to show avatar icons for commit authors in the annotations, or for other icon-based indicators which could be shown (bug fix, reviewed, etc). There is no specification on the meaning of an invalid QSize with QStyleOptionViewItem::decorationSize. I would tend to leave this here unspecified as well for now, until this gets in real use or the QStyleOptionViewItem one gets specified? kossebau: This parameter was inspired by QStyleOptionViewItem::decorationSize. I imagined it could be e.g. | |||||
67 | | ||||
Is the view pointer always valid when the style option is passed as argument? If so, I suggest to add this as comment to avoid unnecessary if() calls / error handling etc... dhaumann: Is the view pointer always valid when the style option is passed as argument? If so, I suggest… | |||||
68 | /** | ||||
69 | * Enum for escribing the relative position of a real line in the row of consecutive | ||||
70 | * displayed lines which belong to the same group of annotation items | ||||
71 | */ | ||||
72 | enum AnnotationItemGroupPosition { | ||||
73 | InvalidGroupPosition = 0, ///< Position not specified or not belonging to a group | ||||
74 | InGroup = 0x1 << 0, ///< Real line belongs to a group | ||||
75 | GroupBegin = 0x1 << 1, ///< Real line is first of consecutive lines from same group | ||||
76 | GroupEnd = 0x1 << 2, ///< Real line is last of consecutive lines from same group | ||||
77 | }; | ||||
78 | Q_DECLARE_FLAGS(AnnotationItemGroupPositions, AnnotationItemGroupPosition) | ||||
79 | | ||||
80 | /** | ||||
81 | * Relative position of the real line in the row of consecutive displayed lines | ||||
dhaumann: Is this a bitmask? The << 0, <<1, <<2 notation implies that it is. | |||||
Yes, as a line could be both begin and end of an annotation grouping (if both neighbour lines belong to different groups). Of course InGroup is mutually exclusive to GroupBegin and GroupEnd. IIRC (been some time since Nob 2017 :) ) I had used normal enum values, with another value GroupBeginAndEnd. But the resulting code using the enum was more complicated. kossebau: Yes, as a line could be both begin and end of an annotation grouping (if both neighbour lines… | |||||
82 | * which belong to the same group of annotation items | ||||
83 | */ | ||||
84 | AnnotationItemGroupPositions annotationItemGroupingPosition = InvalidGroupPosition; | ||||
85 | // TODO: make delegate always care for background? | ||||
86 | // QBrush backgroundBrush; | ||||
87 | | ||||
88 | StyleOptionAnnotationItem() : contentFontMetrics(QFont()) {} | ||||
89 | StyleOptionAnnotationItem(const StyleOptionAnnotationItem& other) | ||||
90 | : QStyleOption(Version, Type), contentFontMetrics(QFont()) { *this = other; } | ||||
91 | | ||||
92 | protected: | ||||
93 | StyleOptionAnnotationItem(int version) : QStyleOption(version, Type), contentFontMetrics(QFont()) {} | ||||
94 | }; | ||||
95 | | ||||
96 | | ||||
You export the class, but then the constructors are inlined. Could you please move the implementation to the cpp file? That leaves us more room to fixes by shipping an updated version of the library. dhaumann: You export the class, but then the constructors are inlined. Could you please move the… | |||||
Okay. I had looked at the other interface classes, those I looked at, even if QObject-based, are header-only, that's why it was done like this. Will change, as I remember from other projets e,g. Windows has issues with this. kossebau: Okay. I had looked at the other interface classes, those I looked at, even if QObject-based… | |||||
97 | /** | ||||
98 | * \brief An delegate for rendering line annotation information and handling events for them | ||||
99 | * | ||||
100 | * \section annodelegate_intro Introduction | ||||
101 | * | ||||
102 | * AbstractAnnotationItemDelegate is an base class that can be reimplemented | ||||
103 | * to customize the rendering of annotation information for each line in a document. | ||||
104 | * It provides also the hooks to define handling of help events like tooltip or of | ||||
105 | * the request for a context menu. | ||||
106 | * | ||||
107 | * \section annodelegate_impl Implementing an AbstractAnnotationItemDelegate | ||||
108 | * | ||||
109 | * The public interface of this class is loosely based on the QAbstractItemDelegate | ||||
110 | * interfaces. It has four methods to implement. | ||||
111 | * | ||||
112 | * \since 5.51 | ||||
113 | * \see KTextEditor::AnnotationModel, KTextEditor::AnnotationViewInterfaceV2 | ||||
114 | */ | ||||
115 | class KTEXTEDITOR_EXPORT AbstractAnnotationItemDelegate : public QObject | ||||
dhaumann: Typ: A delegate ...
And: I suggest to remove "for them". | |||||
116 | { | ||||
117 | Q_OBJECT | ||||
118 | | ||||
119 | protected: | ||||
120 | explicit AbstractAnnotationItemDelegate(QObject* parent = nullptr) : QObject(parent) {} | ||||
121 | public: | ||||
122 | virtual ~AbstractAnnotationItemDelegate() = default; | ||||
123 | | ||||
124 | public: | ||||
125 | /** | ||||
126 | * This pure abstract function must be reimplemented to provide custom rendering. | ||||
127 | * Use the painter and style option to render the annotation information for the line | ||||
128 | * specified by the arguments @p model and @p line. | ||||
129 | * @param painter the painter object | ||||
130 | * @param option the option object with the info needed for styling | ||||
131 | * @param model the annotation model providing the annotation information | ||||
132 | * @param line index of the real line the annotation information should be painted for | ||||
133 | * | ||||
134 | * Reimplement this in line with sizeHint(). | ||||
135 | */ | ||||
136 | virtual void paint(QPainter *painter, const KTextEditor::StyleOptionAnnotationItem &option, | ||||
137 | KTextEditor::AnnotationModel *model, int line) const = 0; | ||||
dhaumann: Same here: Could you move the implementation to ktexteditor.cpp? | |||||
138 | /** | ||||
139 | * This pure abstract function must be reimplemented to provide custom rendering. | ||||
140 | * Use the style option to calculate the best size for the annotation information | ||||
141 | * for the line specified by the arguments @p model and @p line. | ||||
142 | * This should be the size for the display for a single displayed content line, | ||||
Same here: Please move the destructor to ktexteditor.cpp. You can keep = default there, but not here. dhaumann: Same here: Please move the destructor to ktexteditor.cpp. You can keep = default there, but not… | |||||
143 | * i.e. with no line wrapping or consecutive multiple annotation item of the same group assumed. | ||||
144 | * | ||||
145 | * @note If AnnotationViewInterfaceV2::uniformAnnotationItemSizes() is @c true for the view | ||||
146 | * this delegate is used by, it is assumed that the returned value is the same for | ||||
147 | * any line. | ||||
148 | * | ||||
149 | * @param option the option object with the info needed for styling | ||||
150 | * @param model the annotation model providing the annotation information | ||||
151 | * @param line index of the real line the annotation information should be painted for | ||||
152 | * @return best size for the annotation information | ||||
153 | * | ||||
154 | * Reimplement this in line with paint(). | ||||
155 | */ | ||||
156 | virtual QSize sizeHint(const KTextEditor::StyleOptionAnnotationItem &option, | ||||
157 | KTextEditor::AnnotationModel *model, int line) const = 0; | ||||
158 | /** | ||||
159 | * Whenever a help event occurs, this function is called with the event view option | ||||
160 | * and @p model and @p line specifiying the item where the event occurs. | ||||
161 | | ||||
162 | Returns true if the delegate can handle the event; otherwise returns false. A return value of true indicates that the data obtained using the index had the required role. | ||||
163 | | ||||
164 | For QEvent::ToolTip and QEvent::WhatsThis events that were handled successfully, the relevant popup may be shown depending on the user's system configuration. | ||||
165 | | ||||
166 | | ||||
167 | * This pure abstract function must be reimplemented to provide custom rendering. | ||||
168 | * Use the painter and style option to render the item specified by the @p model and @p line. | ||||
169 | * @param event the help event | ||||
170 | * @param view the view for which the context menu is requested | ||||
171 | * @param option the style option object with the info needed for styling | ||||
172 | * @param model the annotation model providing the annotation information | ||||
173 | * @param line index of the real line the annotation information should be painted for | ||||
174 | * @return @c true if the event could be handled (implies that the data obtained from the model had the required role), @ c false otherwise | ||||
175 | * | ||||
176 | * Reimplement this togther with sizeHint(). | ||||
177 | */ | ||||
178 | virtual bool helpEvent(QHelpEvent *event, KTextEditor::View *view, | ||||
179 | const KTextEditor::StyleOptionAnnotationItem &option, | ||||
180 | KTextEditor::AnnotationModel *model, int line) = 0; | ||||
dhaumann: typo: specifying | |||||
181 | | ||||
182 | virtual void hideTooltip(KTextEditor::View *view) = 0; | ||||
183 | /** | ||||
184 | * This pure abstract function must be reimplemented to provide custom rendering. | ||||
dhaumann: inlc. -> including. No need for abbreviations | |||||
185 | * Use the painter and style option to render the item specified by the @p model and @p line. | ||||
186 | * @param view the view for which the context menu is requested | ||||
187 | * @param pos the position of the context menu event that the widget receives, in widget @p view coordinates | ||||
188 | * @param option the style option object with the info used for styling | ||||
189 | * @param model the annotation model providing the annotation information | ||||
190 | * @param line index of the real line the annotation information should be painted for | ||||
191 | */ | ||||
192 | virtual void contextMenuRequested(KTextEditor::View *view, const QPoint &pos, | ||||
193 | const KTextEditor::StyleOptionAnnotationItem &option, | ||||
194 | KTextEditor::AnnotationModel *model, int line) = 0; | ||||
195 | | ||||
196 | Q_SIGNALS: | ||||
197 | /** | ||||
198 | * This signal must be emitted when the sizeHint() for @p model and @p line changed. | ||||
199 | * The view automatically connects to this signal and relayout as necessary. | ||||
200 | * @param model the annotation model providing the annotation information | ||||
201 | * @param line index of the real line the annotation information should be painted for | ||||
202 | */ | ||||
203 | void sizeHintChanged(KTextEditor::AnnotationModel *model, int line); | ||||
204 | }; | ||||
205 | | ||||
206 | } | ||||
207 | | ||||
208 | #endif |
@since 5.52 :-)