1/* This file is part of the KDE libraries
2 * Copyright 2008 Andreas Pakulat <apaku@gmx.de>
3 * Copyright 2008-2018 Dominik Haumann <dhaumann@kde.org>
4 * Copyright 2017-2018 Friedrich W. H. Kossebau <kossebau@kde.org>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA
20 */
21
22#ifndef KTEXTEDITOR_ANNOTATIONINTERFACE_H
23#define KTEXTEDITOR_ANNOTATIONINTERFACE_H
24
25#include <ktexteditor_export.h>
26
27#include <QObject>
28
29class QMenu;
30
31namespace KTextEditor
32{
33
34class View;
35class AbstractAnnotationItemDelegate;
36
37/**
38 * \brief An model for providing line annotation information
39 *
40 * \section annomodel_intro Introduction
41 *
42 * AnnotationModel is a model-like interface that can be implemented
43 * to provide annotation information for each line in a document. It provides
44 * means to retrieve several kinds of data for a given line in the document.
45 *
46 * \section annomodel_impl Implementing a AnnotationModel
47 *
48 * The public interface of this class is loosely based on the QAbstractItemModel
49 * interfaces. It only has a single method to override which is the \ref data()
50 * method to provide the actual data for a line and role combination.
51 *
52 * \since 4.1
53 * \see KTextEditor::AnnotationInterface, KTextEditor::AnnotationViewInterface
54 */
55class KTEXTEDITOR_EXPORT AnnotationModel : public QObject
56{
57 Q_OBJECT
58public:
59
60 virtual ~AnnotationModel() {}
61
62 enum {
63 GroupIdentifierRole = Qt::UserRole
64 };
65 // KF6: add AnnotationModelUserRole = Qt::UserRole + 0x100
66
67 /**
68 * data() is used to retrieve the information needed to present the
69 * annotation information from the annotation model. The provider
70 * should return useful information for the line and the data role.
71 *
72 * The following roles are supported:
73 * - Qt::DisplayRole - a short display text to be placed in the border
74 * - Qt::TooltipRole - a tooltip information, longer text possible
75 * - Qt::BackgroundRole - a brush to be used to paint the background on the border
76 * - Qt::ForegroundRole - a brush to be used to paint the text on the border
77 * - AnnotationModel::GroupIdentifierRole - a string which identifies a
78 * group of items which will be highlighted on mouseover; return the same
79 * string for all items in a group (KDevelop uses a VCS revision number, for example)
80 *
81 *
82 * \param line the line for which the data is to be retrieved
83 * \param role the role to identify which kind of annotation is to be retrieved
84 *
85 * \returns a QVariant that contains the data for the given role.
86 */
87 virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; //KF6: use int for role
88
89Q_SIGNALS:
90 /**
91 * The model should emit the signal reset() when the text of almost all
92 * lines changes. In most cases it is enough to call lineChanged().
93 *
94 * \note Kate Part implementation details: Whenever reset() is emitted Kate
95 * Part iterates over all lines of the document. Kate Part searches
96 * for the longest text to determine the annotation border's width.
97 *
98 * \see lineChanged()
99 */
100 void reset();
101
102 /**
103 * The model should emit the signal lineChanged() when a line has to be
104 * updated.
105 *
106 * \note Kate Part implementation details: lineChanged() repaints the whole
107 * annotation border automatically.
108 */
109 void lineChanged(int line);
110};
111
112/**
113 * \brief A Document extension interface for handling Annotation%s
114 *
115 * \ingroup kte_group_doc_extensions
116 *
117 * \section annoiface_intro Introduction
118 *
119 * The AnnotationInterface is designed to provide line annotation information
120 * for a document. This interface provides means to associate a document with a
121 * annotation model, which provides some annotation information for each line
122 * in the document.
123 *
124 * Setting a model for a Document makes the model data available for all views.
125 * If you only want to provide annotations in exactly one view, you can use
126 * the AnnotationViewInterface directly. See the AnnotationViewInterface for
127 * further details. To summarize, the two use cases are
128 * - (1) show annotations in all views. This means you set an AnnotationModel
129 * with this interface, and then call setAnnotationBorderVisible() for
130 * each view.
131 * - (2) show annotations only in one view. This means to \e not use this
132 * interface. Instead, use the AnnotationViewInterface, which inherits
133 * this interface. This means you set a model for the specific View.
134 *
135 * If you set a model to the Document \e and the View, the View's model has
136 * higher priority.
137 *
138 * \section annoiface_access Accessing the AnnotationInterface
139 *
140 * The AnnotationInterface is an extension interface for a Document, i.e. the
141 * Document inherits the interface \e provided that the
142 * used KTextEditor library implements the interface. Use qobject_cast to
143 * access the interface:
144 * \code
145 * // document is of type KTextEditor::Document*
146 * auto iface = qobject_cast<KTextEditor::AnnotationInterface*>(document);
147 *
148 * if (iface) {
149 * // the implementation supports the interface
150 * // do stuff
151 * } else {
152 * // the implementation does not support the interface
153 * }
154 * \endcode
155 *
156 * \section annoiface_usage Using the AnnotationInterface
157 *
158 * \since 4.1
159 * \see KTextEditor::AnnotationModel, KTextEditor::AnnotationViewInterface
160 */
161class KTEXTEDITOR_EXPORT AnnotationInterface
162{
163public:
164 virtual ~AnnotationInterface() {}
165
166 /**
167 * Sets a new \ref AnnotationModel for this document to provide
168 * annotation information for each line.
169 *
170 * \param model the new AnnotationModel
171 */
172 virtual void setAnnotationModel(AnnotationModel *model) = 0;
173
174 /**
175 * returns the currently set \ref AnnotationModel or 0 if there's none
176 * set
177 * @returns the current \ref AnnotationModel
178 */
179 virtual AnnotationModel *annotationModel() const = 0;
180
181};
182
183/**
184 * \brief Annotation interface for the View
185 *
186 * \ingroup kte_group_view_extensions
187 *
188 * \section annoview_intro Introduction
189 *
190 * The AnnotationViewInterface allows to do two things:
191 * - (1) show/hide the annotation border along with the possibility to add actions
192 * into its context menu.
193 * - (2) set a separate AnnotationModel for the View: Note that this interface
194 * inherits the AnnotationInterface.
195 *
196 * For a more detailed explanation about whether you want an AnnotationModel
197 * in the Document or the View, read the detailed documentation about the
198 * AnnotationInterface.
199 *
200 * \section annoview_access Accessing the AnnotationViewInterface
201 *
202 * The AnnotationViewInterface is an extension interface for a
203 * View, i.e. the View inherits the interface \e provided that the
204 * used KTextEditor library implements the interface. Use qobject_cast to
205 * access the interface:
206 * \code
207 * // view is of type KTextEditor::View*
208 * auto iface = qobject_cast<KTextEditor::AnnotationViewInterface*>(view);
209 *
210 * if (iface) {
211 * // the implementation supports the interface
212 * // do stuff
213 * iface->setAnnotationBorderVisible(true);
214 * } else {
215 * // the implementation does not support the interface
216 * }
217 * \endcode
218 *
219 * \since 4.1
220 */
221class KTEXTEDITOR_EXPORT AnnotationViewInterface : public AnnotationInterface
222{
223public:
224 virtual ~AnnotationViewInterface() {}
225
226 /**
227 * This function can be used to show or hide the annotation border
228 * The annotation border is hidden by default.
229 *
230 * @param visible if \e true the annotation border is shown, otherwise hidden
231 */
232 virtual void setAnnotationBorderVisible(bool visible) = 0;
233
234 /**
235 * Checks whether the View's annotation border is visible.
236 */
237 virtual bool isAnnotationBorderVisible() const = 0;
238
239 //
240 // SIGNALS!!!
241 //
242public:
243 /**
244 * This signal is emitted before a context menu is shown on the annotation
245 * border for the given line and view.
246 *
247 * \note Kate Part implementation detail: In Kate Part, the menu has an
248 * entry to hide the annotation border.
249 *
250 * \param view the view that the annotation border belongs to
251 * \param menu the context menu that will be shown
252 * \param line the annotated line for which the context menu is shown
253 */
254 virtual void annotationContextMenuAboutToShow(KTextEditor::View *view, QMenu *menu, int line) = 0;
255
256 /**
257 * This signal is emitted when an entry on the annotation border was activated,
258 * for example by clicking or double-clicking it. This follows the KDE wide
259 * setting for activation via click or double-clcik
260 *
261 * \param view the view to which the activated border belongs to
262 * \param line the document line that the activated position belongs to
263 */
264 virtual void annotationActivated(KTextEditor::View *view, int line) = 0;
265
266 /**
267 * This signal is emitted when the annotation border is shown or hidden.
268 *
269 * \param view the view to which the border belongs to
270 * \param visible the current visibility state
271 */
272 virtual void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible) = 0;
273
274};
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.
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
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.53
312 */
313class KTEXTEDITOR_EXPORT AnnotationViewInterfaceV2 : public AnnotationViewInterface
314{
315 // KF6: Merge KTextEditor::AnnotationViewInterfaceV2 into KTextEditor::AnnotationViewInterface (kossebau)
316public:
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 /**
329 * Returns the currently used AbstractAnnotationItemDelegate
330 *
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
352}
353
354Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface")
355Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface")
356Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterfaceV2, "org.kde.KTextEditor.AnnotationViewInterfaceV2")
357
358#endif
359
360