Differential D14826 Diff 39721 src/include/ktexteditor/inlinenoteinterface.h

Changeset View

Standalone View

View Options

src/include/ktexteditor/inlinenoteinterface.h

  • This file was added.
PropertyOld ValueNew Value
File Modenull100755
1​/* This file is part of the KDE libraries
2​
3​ This library is free software; you can redistribute it and/or
dhaumannUnsubmitted
Done

author missing

dhaumann: author missing
4​ modify it under the terms of the GNU Library General Public
5​ License as published by the Free Software Foundation; either
dhaumannUnsubmitted
Done

Btw, as license I would previer LGPLv2+ (as it currently is stated) +e.V. option to relicense.

dhaumann: Btw, as license I would previer LGPLv2+ (as it currently is stated) +e.V. option to relicense.
6​ version 2 of the License, or (at your option) any later version.
7​
8​ This library is distributed in the hope that it will be useful,
9​ but WITHOUT ANY WARRANTY; without even the implied warranty of
10​ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11​ Library General Public License for more details.
12​
13​ You should have received a copy of the GNU Library General Public License
14​ along with this library; see the file COPYING.LIB. If not, write to
15​ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16​ Boston, MA 02110-1301, USA.
17​*/
18​#ifndef KTEXTEDITOR_INLINENOTEINTERFACE_H
19​#define KTEXTEDITOR_INLINENOTEINTERFACE_H
20​
21​#include <QString>
22​
23​#include <ktexteditor_export.h>
24​
25​#include <ktexteditor/cursor.h>
26​
27​class QFont;
28​class QFontMetricsF;
29​class QPainter;
30​
31​namespace KTextEditor
32​{
33​
34​class InlineNoteProvider;
35​class View;
36​
37​/**
38​ * \brief Inline notes interface for rendering notes in the text.
39​ *
40​ * \ingroup kte_group_view_extensions
41​ *
42​ * \section inlinenote_introduction Introduction
43​ *
44​ * The inline notes interface provides a way to render arbitrary things in
45​ * the text. The layout of the line is adapted to create space for the note.
46​ * Possible applications include showing a name of a function parameter on
47​ * call side or rendering square with color preview next to CSS color
48​ * property.
49​ *
50​ * To register as inline note provider, call registerInlineNoteProvider() with
51​ * an instance that inherits InlineNoteProvider. Finally, make sure you remove
52​ * your inline note provider by calling unregisterInlineNoteProvider().
53​ *
54​ * \section inlinenote_access Accessing the InlineNoteInterface
55​ *
56​ * The InlineNoteInterface is an extension interface for a
57​ * View, i.e. the View inherits the interface. Use qobject_cast to access the
58​ * interface:
59​ * \code
60​ * // view is of type KTextEditor::View*
61​ * KTextEditor::InlineNoteInterface *iface =
62​ * qobject_cast<KTextEditor::InlineNoteInterface*>(view);
63​ *
64​ * if (iface) {
65​ * // the implementation supports the interface
66​ * // myProvider inherits KTextEditor::InlineNoteProvider
67​ * iface->registerInlineNoteProvider(myProvider);
68​ * }
69​ * \endcode
70​ *
71​ * \see InlineNoteProvider
72​ */
dhaumannUnsubmitted
Done

@author Sven Brauch, Michal Srb

dhaumann: @author Sven Brauch, Michal Srb
73​class KTEXTEDITOR_EXPORT InlineNoteInterface
74​{
dhaumannUnsubmitted
Done

@since 5.50

dhaumann: @since 5.50
75​public:
76​ InlineNoteInterface();
77​ virtual ~InlineNoteInterface();
78​
79​ /**
80​ * Register the inline note provider \p provider.
81​ *
82​ * Whenever a line is painted, the \p provider will be queried for notes
83​ * that should be painted in it. When the provider is about to be
84​ * destroyed, make sure to call unregisterTextHintProvider() to avoid a
85​ * dangling pointer.
86​ *
87​ * \param provider inline note provider
88​ * \see unregisterInlineNoteProvider(), InlineNoteProvider
89​ */
90​ virtual void registerInlineNoteProvider(KTextEditor::InlineNoteProvider *provider) = 0;
91​
92​ /**
93​ * Unregister the inline note provider \p provider.
94​ *
95​ * \param provider inline note provider to unregister
96​ * \see registerInlineNoteProvider(), InlineNoteProvider
97​ */
98​ virtual void unregisterInlineNoteProvider(KTextEditor::InlineNoteProvider *provider) = 0;
99​};
100​
101​class InlineNote;
dhaumannUnsubmitted
Done

Please add a d-pointer as placeholder.

private:

/**
 * private d-pointer
 */
class InlineNoteInterfacePrivate *const d = nullptr;
dhaumann: Please add a d-pointer as placeholder. private: /** * private d-pointer */…
102​
103​/**
104​ * \brief A source of inline notes for a document.
105​ *
106​ * InlineNoteProvider is object that can be queried for inline notes in the
107​ * document. It emits signals when the notes change and should be queried again.
108​ *
109​ * \see InlineNoteInterface
110​ */
111​class KTEXTEDITOR_EXPORT InlineNoteProvider : public QObject
112​{
113​ Q_OBJECT
114​
115​public:
116​ enum ActivationType {
117​ Inactive, ///< The note is inactive (the default)
118​ Focus, ///< The note has received focus or has focus
dhaumannUnsubmitted
Done
  • move to InlineNote
  • turn into enum class
dhaumann: - move to InlineNote - turn into enum class
119​ Click, ///< The note was clicked
120​ ShortcutActivate, ///< The note was activated by a shortcut
121​ };
122​
123​ /**
124​ * Default constructor.
125​ */
126​ InlineNoteProvider();
127​
128​ /**
129​ * Virtual destructor to allow inheritance.
130​ */
131​ virtual ~InlineNoteProvider();
132​
133​ /**
134​ * Get list of inline notes for given line.
135​ *
136​ * Should return a vector of columns on which the notes are located.
137​ * 0 means the note is located before the first character of the line.
138​ * 1 means the note is located after the first character, etc. If the
139​ * returned number is bigger than the length of the line, the note will be
140​ * placed behind the text as if there were additional spaces.
141​ *
142​ * \param line Line number
143​ * \returns vector of columns where inline notes appear in this line
144​ */
145​ virtual QVector<int> inlineNotes(int line) const = 0;
146​
michalsrbUnsubmitted
Done

Perhaps this could be QVarLengthArray of some size too?

michalsrb: Perhaps this could be `QVarLengthArray` of some size too?
dhaumannUnsubmitted
Done

We discussed that here, and let's use QVector for now. If this turns out to be an issue, we will change for KF6.

dhaumann: We discussed that here, and let's use QVector for now. If this turns out to be an issue, we…
147​ /**
148​ * Width to be reserved for the note in the text.
149​ *
dhaumannUnsubmitted
Done

There is only one @param note

dhaumann: There is only one @param note
150​ * The method is given the height of the line and the metrics of current
151​ * font which it may use for calculating the width.
152​ *
153​ * \param height the height of the line in pixels
154​ * \param font the font used by the editor
155​ *
156​ * \return the width of the note in pixels
157​ */
158​ virtual QSize inlineNoteSize(const InlineNote& note, qreal height, QFont font) const = 0;
159​
160​ /**
161​ * Paint the note into the line.
162​ *
163​ * The method should use the given painter to render the note into the
164​ * line. The painter is translated such that coordinates 0x0 mark the top
165​ * left corner of the note. The method should not paint outside rectangle
166​ * given by the height parameter and the width previously returned by the
167​ * width method.
168​ *
169​ * The method is given the height of the line, the metrics of current font
170​ * and the font which it may use during painting.
171​ *
172​ * \param note note to paint, containing location and index
173​ * \param height the height of the line in pixels
174​ * \param font the QFont used in the editor
175​ * \param painter painter prepared for rendering the note
176​ */
177​ virtual void paintInlineNote(const InlineNote& note, qreal height, QFont font, QPainter& painter) const = 0;
dhaumannUnsubmitted
Done
  • API documentation is wrong
  • please use @param instead of \param everywhere, i.e. we prefer @xyz over \xyz
dhaumann: - API documentation is wrong - please use @param instead of \param everywhere, i.e. we prefer…
178​
179​ /**
180​ * Invoked when a note is activated by the user.
181​ *
182​ * This method is called when a user activates a note, i.e. clicks on it or otherwise
183​ * interacts with it. Coordinates of \p pos are relative to the note's
184​ * top-left corner (same coordinate system as the painter has in paintInlineNote()).
185​ *
186​ * In case of a focus-out event, this method is called with \p type set to Inactive.
187​ *
188​ * The default implementation does nothing.
189​ *
190​ * \param note the note which was activated
191​ * \param type The type of activation
192​ * \param pos the point the note was clicked at, or {-1,-1} if \p type is ShortcutActivate
193​ */
194​ virtual void noteActivated(const InlineNote& note, ActivationType type, QPoint pos) {
195​ Q_UNUSED(note);
196​ Q_UNUSED(type);
dhaumannUnsubmitted
Not Done

noteActivated -> inlineNoteActivated()

dhaumann: noteActivated -> inlineNoteActivated()
197​ Q_UNUSED(pos);
198​ }
199​
200​Q_SIGNALS:
dhaumannUnsubmitted
Not Done

I would prefer two functions:

virtual void inlineNoteFocusInEvent(const InlineNote& note, const QPoint& pos);
virtual void inlineNoteMoveEvent(const InlineNote& note, const QPoint& pos);
virtual void inlineNoteFocusOutEvent(const InlineNote& note);
dhaumann: I would prefer two functions: virtual void inlineNoteFocusInEvent(const InlineNote& note…
201​ /**
202​ * The provider should emit the signal reset() when almost all inline notes
203​ * changed.
204​ */
205​ void reset();
206​
207​ /**
208​ * The provider should emit the signal lineChanged() when any of the
209​ * inline notes on the line changed.
210​ */
211​ void lineChanged(int line);
212​};
213​
214​class KTEXTEDITOR_EXPORT InlineNote
215​{
216​public:
dhaumannUnsubmitted
Done

API docs missing for InlineNote, but we can add that later.

dhaumann: API docs missing for InlineNote, but we can add that later.
217​ InlineNote(InlineNoteProvider* provider, const KTextEditor::Cursor& location, int index)
218​ : provider(provider)
219​ , location(location)
220​ , index(index)
221​ , activeState(InlineNoteProvider::Inactive)
222​ {
223​ }
224​
225​ InlineNote()
226​ : provider(nullptr)
227​ , location({})
228​ , index(-1)
229​ , activeState(InlineNoteProvider::Inactive)
230​ {
231​ }
232​
233​ int column() const {
234​ return location.column();
235​ }
236​
237​ qreal width(qreal height, const QFont &font) const {
238​ return provider->inlineNoteSize(*this, height, font).width();
239​ }
240​
241​ void paint(qreal height, const QFont &font, QPainter &painter) const {
242​ provider->paintInlineNote(*this, height, font, painter);
243​ }
244​
245​ void activate(InlineNoteProvider::ActivationType type, QPoint pos) {
246​ provider->noteActivated(*this, type, pos);
247​ }
248​
249​ bool isValid() const {
250​ return provider != nullptr && location.isValid();
251​ }
252​
253​ operator bool() const {
254​ return isValid();
255​ }
256​
257​ // Does not compare activeState.
258​ bool operator==(const InlineNote& other) const {
259​ return provider == other.provider && location == other.location && index == other.index;
260​ }
261​
262​ InlineNoteProvider* provider;
263​ KTextEditor::Cursor location;
264​ int index;
265​ InlineNoteProvider::ActivationType activeState;
266​};
267​
268​}
269​
270​Q_DECLARE_INTERFACE(KTextEditor::InlineNoteInterface, "org.kde.KTextEditor.InlineNoteInterface")
271​
272​#endif
dhaumannUnsubmitted
Done

please add d-pointer:

private:
    class InlineNotePrivate * const d = nullptr;
dhaumann: please add d-pointer: private: class InlineNotePrivate * const d = nullptr;
dhaumannUnsubmitted
Done

can you try making all variables private?

dhaumann: can you try making all variables private?
dhaumannUnsubmitted
Done

please initialize all members in-class.

dhaumann: please initialize all members in-class.