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

Changeset View

Standalone View

View Options

src/include/ktexteditor/annotationinterface.h

Show All 25 Lines
26#include <QObject> 26​#include <QObject>
27 27​
28class QMenu; 28​class QMenu;
29 29​
30namespace KTextEditor 30​namespace KTextEditor
31{ 31​{
32 32​
33class View; 33​class View;
34​class AbstractAnnotationItemDelegate;
34 35​
35/** 36​/**
36 * \brief An model for providing line annotation information 37​ * \brief An model for providing line annotation information
37 * 38​ *
38 * \section annomodel_intro Introduction 39​ * \section annomodel_intro Introduction
39 * 40​ *
40 * AnnotationModel is a model-like interface that can be implemented 41​ * AnnotationModel is a model-like interface that can be implemented
41 * to provide annotation information for each line in a document. It provides 42​ * to provide annotation information for each line in a document. It provides
Show All 13 Lines55{
55 Q_OBJECT 56​ Q_OBJECT
56public: 57​public:
57 58​
58 virtual ~AnnotationModel() {} 59​ virtual ~AnnotationModel() {}
59 60​
60 enum { 61​ enum {
61 GroupIdentifierRole = Qt::UserRole 62​ GroupIdentifierRole = Qt::UserRole
62 }; 63​ };
64​ // KF6: add AnnotationModelUserRole = Qt::UserRole + 0x100
63 65​
64 /** 66​ /**
65 * data() is used to retrieve the information needed to present the 67​ * data() is used to retrieve the information needed to present the
66 * annotation information from the annotation model. The provider 68​ * annotation information from the annotation model. The provider
67 * should return useful information for the line and the data role. 69​ * should return useful information for the line and the data role.
68 * 70​ *
69 * The following roles are supported: 71​ * The following roles are supported:
70 * - Qt::DisplayRole - a short display text to be placed in the border 72​ * - Qt::DisplayRole - a short display text to be placed in the border
71 * - Qt::TooltipRole - a tooltip information, longer text possible 73​ * - Qt::TooltipRole - a tooltip information, longer text possible
72 * - Qt::BackgroundRole - a brush to be used to paint the background on the border 74​ * - 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 75​ * - Qt::ForegroundRole - a brush to be used to paint the text on the border
74 * - AnnotationModel::GroupIdentifierRole - a string which identifies a 76​ * - AnnotationModel::GroupIdentifierRole - a string which identifies a
75 * group of items which will be highlighted on mouseover; return the same 77​ * 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) 78​ * string for all items in a group (KDevelop uses a VCS revision number, for example)
77 * 79​ *
78 * 80​ *
79 * \param line the line for which the data is to be retrieved 81​ * \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 82​ * \param role the role to identify which kind of annotation is to be retrieved
81 * 83​ *
82 * \returns a QVariant that contains the data for the given role. 84​ * \returns a QVariant that contains the data for the given role.
83 */ 85​ */
84 virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; 86​ virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; //KF6: use int for role
85 87​
86Q_SIGNALS: 88​Q_SIGNALS:
87 /** 89​ /**
88 * The model should emit the signal reset() when the text of almost all 90​ * 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(). 91​ * lines changes. In most cases it is enough to call lineChanged().
90 * 92​ *
91 * \note Kate Part implementation details: Whenever reset() is emitted Kate 93​ * \note Kate Part implementation details: Whenever reset() is emitted Kate
92 * Part iterates over all lines of the document. Kate Part searches 94​ * Part iterates over all lines of the document. Kate Part searches
▲ Show 20 Lines • Show All 172 Lines • ▼ Show 20 Line(s)241public:
265 * 267​ *
266 * \param view the view to which the border belongs to 268​ * \param view the view to which the border belongs to
267 * \param visible the current visibility state 269​ * \param visible the current visibility state
268 */ 270​ */
269 virtual void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible) = 0; 271​ virtual void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible) = 0;
270 272​
271}; 273​};
272 274​
275​/**
276​ * \brief Annotation interface for the View, version 2
277​ *
278​ * \ingroup kte_group_view_extensions
279​ *
280​ * \section annoview_intro Introduction
281​ *
282​ * The AnnotationViewInterfaceV2 allows to do the same as AnnotationViewInterface
283​ * and additionally
284​ * - (1) set a custom AbstractAnnotationItemDelegate for the View:
dhaumannUnsubmitted
Done

Change trailing ':' to '.'

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

typo: fpr

dhaumann: typo: fpr
288​ * AbstractAnnotationItemDelegate.
289​ *
290​ * \section annoview_access Accessing the AnnotationViewInterfaceV2
291​ *
292​ * The AnnotationViewInterfaceV2 is an extension interface for a
293​ * View, i.e. the View inherits the interface \e provided that the
294​ * used KTextEditor library implements the interface. Use qobject_cast to
295​ * access the interface:
296​ * \code
297​ * // view is of type KTextEditor::View*
298​ * auto iface = qobject_cast<KTextEditor::AnnotationViewInterfaceV2*>(view);
299​ *
300​ * if (iface) {
301​ * // the implementation supports the interface
302​ * // do stuff
303​ * iface->setAnnotationItemDelegate(myDelegate);
304​ * iface->setAnnotationUniformItemSizes(true);
305​ * } else {
306​ * // the implementation does not support the interface
307​ * }
308​ * \endcode
309​ *
310​ * \since 5.51
311​ */
312​class KTEXTEDITOR_EXPORT AnnotationViewInterfaceV2 : public AnnotationViewInterface
313​{
314​public:
315​ virtual ~AnnotationViewInterfaceV2() {}
316​
317​ /**
318​ * Sets the \ref AbstractAnnotationItemDelegate for this view and the model
319​ * to provide custom rendering of annotation information for each line.
320​ * Ownership is not transferred.
321​ *
322​ * \param delegate the new AbstractAnnotationItemDelegate, or \c nullptr to reset to the default delegate
323​ */
324​ virtual void setAnnotationItemDelegate(KTextEditor::AbstractAnnotationItemDelegate *delegate) = 0;
325​
326​ /**
327​ * Returns the currently used \ref AbstractAnnotationItemDelegate
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.
328​ *
329​ * @returns the current \ref AbstractAnnotationItemDelegate
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…
330​ */
331​ virtual KTextEditor::AbstractAnnotationItemDelegate* annotationItemDelegate() const = 0;
332​
333​ /**
334​ * This function can be used to declare whether it is known that the annotation items
335​ * rendered by the set delegate all have the same size.
336​ * This enables the view to do some optimizations for performance purposes.
337​ *
338​ * By default the value of this property is \c false .
339​ *
340​ * @param uniformItemSizes if \c true the annotation items are considered to all have the same size
341​ */
342​ virtual void setAnnotationUniformItemSizes(bool uniformItemSizes) = 0;
343​
344​ /**
345​ * Checks whether the annotation items all have the same size.
346​ */
347​ virtual bool uniformAnnotationItemSizes() const = 0;
348​};
349​
273} 350​}
274 351​
275Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface") 352​Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface")
276Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface") 353​Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface")
354​Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterfaceV2, "org.kde.KTextEditor.AnnotationViewInterfaceV2")
277 355​
278#endif 356​#endif
279 357​