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

Changeset View

Standalone View

View Options

src/include/ktexteditor/annotationinterface.h

1/* This file is part of the KDE libraries 1​/* This file is part of the KDE libraries
2 * Copyright 2008 Andreas Pakulat <apaku@gmx.de> 2​ * Copyright 2008 Andreas Pakulat <apaku@gmx.de>
3 * Copyright 2008-2018 Dominik Haumann <dhaumann@kde.org> 3​ * Copyright 2008-2018 Dominik Haumann <dhaumann@kde.org>
4​ * Copyright 2017-2018 Friedrich W. H. Kossebau <kossebau@kde.org>
4 * 5​ *
5 * This library is free software; you can redistribute it and/or 6​ * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public 7​ * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either 8​ * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version. 9​ * version 2 of the License, or (at your option) any later version.
9 * 10​ *
10 * This library is distributed in the hope that it will be useful, 11​ * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12​ * but WITHOUT ANY WARRANTY; without even the implied warranty of
Show All 14 Lines
26#include <QObject> 27​#include <QObject>
27 28​
28class QMenu; 29​class QMenu;
29 30​
30namespace KTextEditor 31​namespace KTextEditor
31{ 32​{
32 33​
33class View; 34​class View;
35​class AbstractAnnotationItemDelegate;
34 36​
35/** 37​/**
36 * \brief An model for providing line annotation information 38​ * \brief An model for providing line annotation information
37 * 39​ *
38 * \section annomodel_intro Introduction 40​ * \section annomodel_intro Introduction
39 * 41​ *
40 * AnnotationModel is a model-like interface that can be implemented 42​ * AnnotationModel is a model-like interface that can be implemented
41 * to provide annotation information for each line in a document. It provides 43​ * to provide annotation information for each line in a document. It provides
Show All 13 Lines56{
55 Q_OBJECT 57​ Q_OBJECT
56public: 58​public:
57 59​
58 virtual ~AnnotationModel() {} 60​ virtual ~AnnotationModel() {}
59 61​
60 enum { 62​ enum {
61 GroupIdentifierRole = Qt::UserRole 63​ GroupIdentifierRole = Qt::UserRole
62 }; 64​ };
65​ // KF6: add AnnotationModelUserRole = Qt::UserRole + 0x100
63 66​
64 /** 67​ /**
65 * data() is used to retrieve the information needed to present the 68​ * data() is used to retrieve the information needed to present the
66 * annotation information from the annotation model. The provider 69​ * annotation information from the annotation model. The provider
67 * should return useful information for the line and the data role. 70​ * should return useful information for the line and the data role.
68 * 71​ *
69 * The following roles are supported: 72​ * The following roles are supported:
70 * - Qt::DisplayRole - a short display text to be placed in the border 73​ * - Qt::DisplayRole - a short display text to be placed in the border
71 * - Qt::TooltipRole - a tooltip information, longer text possible 74​ * - Qt::TooltipRole - a tooltip information, longer text possible
72 * - Qt::BackgroundRole - a brush to be used to paint the background on the border 75​ * - Qt::BackgroundRole - a brush to be used to paint the background on the border
73 * - Qt::ForegroundRole - a brush to be used to paint the text on the border 76​ * - Qt::ForegroundRole - a brush to be used to paint the text on the border
74 * - AnnotationModel::GroupIdentifierRole - a string which identifies a 77​ * - AnnotationModel::GroupIdentifierRole - a string which identifies a
75 * group of items which will be highlighted on mouseover; return the same 78​ * group of items which will be highlighted on mouseover; return the same
76 * string for all items in a group (KDevelop uses a VCS revision number, for example) 79​ * string for all items in a group (KDevelop uses a VCS revision number, for example)
77 * 80​ *
78 * 81​ *
79 * \param line the line for which the data is to be retrieved 82​ * \param line the line for which the data is to be retrieved
80 * \param role the role to identify which kind of annotation is to be retrieved 83​ * \param role the role to identify which kind of annotation is to be retrieved
81 * 84​ *
82 * \returns a QVariant that contains the data for the given role. 85​ * \returns a QVariant that contains the data for the given role.
83 */ 86​ */
84 virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; 87​ virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; //KF6: use int for role
85 88​
86Q_SIGNALS: 89​Q_SIGNALS:
87 /** 90​ /**
88 * The model should emit the signal reset() when the text of almost all 91​ * The model should emit the signal reset() when the text of almost all
89 * lines changes. In most cases it is enough to call lineChanged(). 92​ * lines changes. In most cases it is enough to call lineChanged().
90 * 93​ *
91 * \note Kate Part implementation details: Whenever reset() is emitted Kate 94​ * \note Kate Part implementation details: Whenever reset() is emitted Kate
92 * Part iterates over all lines of the document. Kate Part searches 95​ * Part iterates over all lines of the document. Kate Part searches
▲ Show 20 Lines • Show All 172 Lines • ▼ Show 20 Line(s)242public:
265 * 268​ *
266 * \param view the view to which the border belongs to 269​ * \param view the view to which the border belongs to
267 * \param visible the current visibility state 270​ * \param visible the current visibility state
268 */ 271​ */
269 virtual void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible) = 0; 272​ virtual void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible) = 0;
270 273​
271}; 274​};
272 275​
276​/**
277​ * \brief Annotation interface for the View, version 2
278​ *
279​ * \ingroup kte_group_view_extensions
280​ *
281​ * \section annoview_intro Introduction
282​ *
283​ * The AnnotationViewInterfaceV2 allows to do the same as AnnotationViewInterface
284​ * and additionally
285​ * - (1) set a custom AbstractAnnotationItemDelegate for the View.
dhaumannUnsubmitted
Done

Change trailing ':' to '.'

dhaumann: Change trailing ':' to '.'
286​ *
287​ * For a more detailed explanation about whether you want to set a custom
288​ * delegate for rendering the annotations, read the detailed documentation about the
dhaumannUnsubmitted
Done

typo: fpr

dhaumann: typo: fpr
289​ * AbstractAnnotationItemDelegate.
290​ *
291​ * \section annoview_access Accessing the AnnotationViewInterfaceV2
292​ *
293​ * The AnnotationViewInterfaceV2 is an extension interface for a
294​ * View, i.e. the View inherits the interface \e provided that the
295​ * used KTextEditor library implements the interface. Use qobject_cast to
296​ * access the interface:
297​ * \code
298​ * // view is of type KTextEditor::View*
299​ * auto iface = qobject_cast<KTextEditor::AnnotationViewInterfaceV2*>(view);
300​ *
301​ * if (iface) {
302​ * // the implementation supports the interface
303​ * // do stuff
304​ * iface->setAnnotationItemDelegate(myDelegate);
305​ * iface->setAnnotationUniformItemSizes(true);
306​ * } else {
307​ * // the implementation does not support the interface
308​ * }
309​ * \endcode
310​ *
311​ * \since 5.52
312​ */
313​class KTEXTEDITOR_EXPORT AnnotationViewInterfaceV2 : public AnnotationViewInterface
314​{
315​ // KF6: Merge KTextEditor::AnnotationViewInterfaceV2 into KTextEditor::AnnotationViewInterface (kossebau)
316​public:
317​ virtual ~AnnotationViewInterfaceV2() {}
318​
319​ /**
320​ * Sets the AbstractAnnotationItemDelegate for this view and the model
321​ * to provide custom rendering of annotation information for each line.
322​ * Ownership is not transferred.
323​ *
324​ * \param delegate the new AbstractAnnotationItemDelegate, or \c nullptr to reset to the default delegate
325​ */
326​ virtual void setAnnotationItemDelegate(KTextEditor::AbstractAnnotationItemDelegate *delegate) = 0;
327​
328​ /**
dhaumannUnsubmitted
Done

I think you don't need to type "\ref". doxygen will create the link for you anyways. Same below.

dhaumann: I think you don't need to type "\ref". doxygen will create the link for you anyways. Same below.
329​ * Returns the currently used AbstractAnnotationItemDelegate
330​ *
dhaumannUnsubmitted
Done

... or a nullptr, if no delegate was set. maybe? I am asking, since it could also return some default implementation.

dhaumann: ... or a nullptr, if no delegate was set. maybe? I am asking, since it could also return some…
331​ * @returns the current AbstractAnnotationItemDelegate
332​ */
333​ virtual KTextEditor::AbstractAnnotationItemDelegate* annotationItemDelegate() const = 0;
334​
335​ /**
336​ * This function can be used to declare whether it is known that the annotation items
337​ * rendered by the set delegate all have the same size.
338​ * This enables the view to do some optimizations for performance purposes.
339​ *
340​ * By default the value of this property is \c false .
341​ *
342​ * @param uniformItemSizes if \c true the annotation items are considered to all have the same size
343​ */
344​ virtual void setAnnotationUniformItemSizes(bool uniformItemSizes) = 0;
345​
346​ /**
347​ * Checks whether the annotation items all have the same size.
348​ */
349​ virtual bool uniformAnnotationItemSizes() const = 0;
350​};
351​
273} 352​}
274 353​
275Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface") 354​Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface")
276Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface") 355​Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface")
356​Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterfaceV2, "org.kde.KTextEditor.AnnotationViewInterfaceV2")
277 357​
278#endif 358​#endif
279 359​