Differential D8708 Diff 42903 src/include/ktexteditor/abstractannotationitemdelegate.h

Changeset View

Standalone View

View Options

src/include/ktexteditor/abstractannotationitemdelegate.h

  • This file was added.
1​/* This file is part of the KDE libraries
2​ * Copyright 2017-2018 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 QPoint;
30​
31​
32​namespace KTextEditor
33​{
34​class AnnotationModel;
35​class View;
36​
37​/**
38​ * \brief The style option set for an annotation item, as painted by AbstractAnnotationItemDelegate
39​ *
40​ * \since 5.52
dhaumannUnsubmitted
Done

@since 5.52 :-)

dhaumann: @since 5.52 :-)
41​ * \see KTextEditor::AbstractAnnotationItemDelegate
42​ */
43​class KTEXTEDITOR_EXPORT StyleOptionAnnotationItem : public QStyleOption
44​{
45​public:
46​ // TODO: not sure what SO_Default implies, but no clue how to maintain a user type registry?
47​ enum StyleOptionType { Type = SO_Default };
48​ enum StyleOptionVersion { Version = 1 };
49​
50​ /**
51​ * Index of the displayed line in the wrapped lines for the given real line
52​ */
53​ int wrappedLine = 0;
dhaumannUnsubmitted
Not Done

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…
kossebauAuthorUnsubmitted
Not Done

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​ /**
55​ * Number of wrapped lines for the given real line
56​ *
57​ * A value of 1 means no wrapping has happened and the real line is displayed as one line.
58​ */
59​ int wrappedLineCount = 1;
60​ /**
61​ * Index of the displayed line in the displayed lines for the same group
62​ */
63​ int visibleWrappedLineInGroup = 0;
64​
65​ /**
66​ * The view where the annotation is shown
dhaumannUnsubmitted
Not Done

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…
kossebauAuthorUnsubmitted
Not Done

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​ */
dhaumannUnsubmitted
Done

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​ KTextEditor::View* view = nullptr;
69​ /**
70​ * Recommended size for icons or other symbols that will be rendered by the delegate
71​ *
72​ * The default value is QSize(-1, -1).
73​ */
74​ QSize decorationSize;
75​ /**
76​ * The metrics of the font used for rendering the text document
77​ */
78​ QFontMetricsF contentFontMetrics;
79​
80​ // TODO: make delegate always care for background?
81​ // QBrush backgroundBrush;
dhaumannUnsubmitted
Not Done

Is this a bitmask? The << 0, <<1, <<2 notation implies that it is.

dhaumann: Is this a bitmask? The << 0, <<1, <<2 notation implies that it is.
kossebauAuthorUnsubmitted
Not Done

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.
Not sure these days, perhaps I should retry. Need to recheck what similar enumas there are in the Qt world, so at least things are consistent.

kossebau: Yes, as a line could be both begin and end of an annotation grouping (if both neighbour lines…
82​
83​ /**
84​ * Enum for describing the relative position of a real line in the row of consecutive
85​ * displayed lines which belong to the same group of annotation items
86​ */
87​ enum AnnotationItemGroupPosition {
88​ InvalidGroupPosition = 0, ///< Position not specified or not belonging to a group
89​ InGroup = 0x1 << 0, ///< Real line belongs to a group
90​ GroupBegin = 0x1 << 1, ///< Real line is first of consecutive lines from same group
91​ GroupEnd = 0x1 << 2, ///< Real line is last of consecutive lines from same group
92​ };
93​ Q_DECLARE_FLAGS(AnnotationItemGroupPositions, AnnotationItemGroupPosition)
94​
95​ /**
96​ * Relative position of the real line in the row of consecutive displayed lines
dhaumannUnsubmitted
Done

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…
kossebauAuthorUnsubmitted
Not Done

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​ * which belong to the same group of annotation items
98​ */
99​ AnnotationItemGroupPositions annotationItemGroupingPosition = InvalidGroupPosition;
100​
101​public:
102​ StyleOptionAnnotationItem();
103​ StyleOptionAnnotationItem(const StyleOptionAnnotationItem &other);
104​
105​protected:
106​ explicit StyleOptionAnnotationItem(int version);
107​};
108​
109​
110​/**
111​ * \brief A delegate for rendering line annotation information and handling events
112​ *
113​ * \section annodelegate_intro Introduction
114​ *
115​ * AbstractAnnotationItemDelegate is a base class that can be reimplemented
dhaumannUnsubmitted
Done

Typ: A delegate ...
And: I suggest to remove "for them".

dhaumann: Typ: A delegate ... And: I suggest to remove "for them".
116​ * to customize the rendering of annotation information for each line in a document.
117​ * It provides also the hooks to define handling of help events like tooltip or of
118​ * the request for a context menu.
119​ *
120​ * \section annodelegate_impl Implementing an AbstractAnnotationItemDelegate
121​ *
122​ * The public interface of this class is loosely based on the QAbstractItemDelegate
123​ * interfaces. It has five methods to implement.
124​ *
125​ * \since 5.52
126​ * \see KTextEditor::AnnotationModel, KTextEditor::AnnotationViewInterfaceV2
127​ */
128​class KTEXTEDITOR_EXPORT AbstractAnnotationItemDelegate : public QObject
129​{
130​ Q_OBJECT
131​
132​protected:
133​ explicit AbstractAnnotationItemDelegate(QObject *parent = nullptr);
134​
135​public:
136​ ~AbstractAnnotationItemDelegate() override;
137​
dhaumannUnsubmitted
Done

Same here: Could you move the implementation to ktexteditor.cpp?

dhaumann: Same here: Could you move the implementation to ktexteditor.cpp?
138​public:
139​ /**
140​ * This pure abstract function must be reimplemented to provide custom rendering.
141​ * Use the painter and style option to render the annotation information for the line
142​ * specified by the arguments @p model and @p line.
dhaumannUnsubmitted
Done

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​ * @param painter the painter object
144​ * @param option the option object with the info needed for styling
145​ * @param model the annotation model providing the annotation information
146​ * @param line index of the real line the annotation information should be painted for
147​ *
148​ * Reimplement this in line with sizeHint().
149​ */
150​ virtual void paint(QPainter *painter, const KTextEditor::StyleOptionAnnotationItem &option,
151​ KTextEditor::AnnotationModel *model, int line) const = 0;
152​ /**
153​ * This pure abstract function must be reimplemented to provide custom rendering.
154​ * Use the style option to calculate the best size for the annotation information
155​ * for the line specified by the arguments @p model and @p line.
156​ * This should be the size for the display for a single displayed content line,
157​ * i.e. with no line wrapping or consecutive multiple annotation item of the same group assumed.
158​ *
159​ * @note If AnnotationViewInterfaceV2::uniformAnnotationItemSizes() is @c true for the view
160​ * this delegate is used by, it is assumed that the returned value is the same for
161​ * any line.
162​ *
163​ * @param option the option object with the info needed for styling
164​ * @param model the annotation model providing the annotation information
165​ * @param line index of the real line the annotation information should be painted for
166​ * @return best size for the annotation information
167​ *
168​ * Reimplement this in line with paint().
169​ */
170​ virtual QSize sizeHint(const KTextEditor::StyleOptionAnnotationItem &option,
171​ KTextEditor::AnnotationModel *model, int line) const = 0;
172​ /**
173​ * Whenever a help event occurs, this function is called with the event view option
174​ * and @p model and @p line specifying the item where the event occurs.
175​ * This pure abstract function must be reimplemented to provide custom tooltips.
176​ * @param event the help event
177​ * @param view the view for which the help event is requested
178​ * @param option the style option object with the info needed for styling, including the rect of the annotation
179​ * @param model the annotation model providing the annotation information
180​ * @param line index of the real line the annotation information should be painted for
dhaumannUnsubmitted
Done

typo: specifying

dhaumann: typo: specifying
181​ * @return @c true if the event could be handled (implies that the data obtained from the model had the required role), @c false otherwise
182​ *
183​ * Reimplement this in line with hideTooltip().
184​ */
dhaumannUnsubmitted
Done

inlc. -> including. No need for abbreviations

dhaumann: inlc. -> including. No need for abbreviations
185​ virtual bool helpEvent(QHelpEvent *event, KTextEditor::View *view,
186​ const KTextEditor::StyleOptionAnnotationItem &option,
187​ KTextEditor::AnnotationModel *model, int line) = 0;
188​ /**
189​ * This pure abstract function must be reimplemented to provide custom tooltips.
190​ * It is called whenever a possible still shown tooltip no longer is valid,
191​ * e.g. if the annotations have been hidden.
192​ * @param view the view for which the tooltip was requested
193​ *
194​ * Reimplement this in line with helpEvent().
195​ */
196​ virtual void hideTooltip(KTextEditor::View *view) = 0;
197​
198​Q_SIGNALS:
199​ /**
200​ * This signal must be emitted when the sizeHint() for @p model and @p line changed.
201​ * The view automatically connects to this signal and relayouts as necessary.
202​ * If AnnotationViewInterfaceV2::uniformAnnotationItemSizes is set on the view,
203​ * it is sufficient to emit sizeHintChanged only for one line.
204​ * @param model the annotation model providing the annotation information
205​ * @param line index of the real line the annotation information should be painted for
206​ */
207​ void sizeHintChanged(KTextEditor::AnnotationModel *model, int line);
208​};
209​
210​}
211​
212​#endif