KTextEditor

annotationinterface.h
1 /*
2  SPDX-FileCopyrightText: 2008 Andreas Pakulat <[email protected]>
3  SPDX-FileCopyrightText: 2008-2018 Dominik Haumann <[email protected]>
4  SPDX-FileCopyrightText: 2017-2018 Friedrich W. H. Kossebau <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KTEXTEDITOR_ANNOTATIONINTERFACE_H
10 #define KTEXTEDITOR_ANNOTATIONINTERFACE_H
11 
12 #include <ktexteditor_export.h>
13 
14 #include <QObject>
15 
16 class QMenu;
17 
18 namespace KTextEditor
19 {
20 class View;
21 class AbstractAnnotationItemDelegate;
22 
23 /**
24  * \brief An model for providing line annotation information
25  *
26  * \section annomodel_intro Introduction
27  *
28  * AnnotationModel is a model-like interface that can be implemented
29  * to provide annotation information for each line in a document. It provides
30  * means to retrieve several kinds of data for a given line in the document.
31  *
32  * \section annomodel_impl Implementing a AnnotationModel
33  *
34  * The public interface of this class is loosely based on the QAbstractItemModel
35  * interfaces. It only has a single method to override which is the \ref data()
36  * method to provide the actual data for a line and role combination.
37  *
38  * \since 4.1
39  * \see KTextEditor::AnnotationInterface, KTextEditor::AnnotationViewInterface
40  */
41 class KTEXTEDITOR_EXPORT AnnotationModel : public QObject
42 {
43  Q_OBJECT
44 public:
45  ~AnnotationModel() override
46  {
47  }
48 
49  enum { GroupIdentifierRole = Qt::UserRole };
50  // KF6: add AnnotationModelUserRole = Qt::UserRole + 0x100
51 
52  /**
53  * data() is used to retrieve the information needed to present the
54  * annotation information from the annotation model. The provider
55  * should return useful information for the line and the data role.
56  *
57  * The following roles are supported:
58  * - Qt::DisplayRole - a short display text to be placed in the border
59  * - Qt::TooltipRole - a tooltip information, longer text possible
60  * - Qt::BackgroundRole - a brush to be used to paint the background on the border
61  * - Qt::ForegroundRole - a brush to be used to paint the text on the border
62  * - AnnotationModel::GroupIdentifierRole - a string which identifies a
63  * group of items which will be highlighted on mouseover; return the same
64  * string for all items in a group (KDevelop uses a VCS revision number, for example)
65  *
66  *
67  * \param line the line for which the data is to be retrieved
68  * \param role the role to identify which kind of annotation is to be retrieved
69  *
70  * \returns a QVariant that contains the data for the given role.
71  */
72  virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; // KF6: use int for role
73 
74 Q_SIGNALS:
75  /**
76  * The model should emit the signal reset() when the text of almost all
77  * lines changes. In most cases it is enough to call lineChanged().
78  *
79  * \note Kate Part implementation details: Whenever reset() is emitted Kate
80  * Part iterates over all lines of the document. Kate Part searches
81  * for the longest text to determine the annotation border's width.
82  *
83  * \see lineChanged()
84  */
85  void reset();
86 
87  /**
88  * The model should emit the signal lineChanged() when a line has to be
89  * updated.
90  *
91  * \note Kate Part implementation details: lineChanged() repaints the whole
92  * annotation border automatically.
93  */
94  void lineChanged(int line);
95 };
96 
97 /**
98  * \class AnnotationInterface annotationinterface.h <KTextEditor/AnnotationInterface>
99  *
100  * \brief A Document extension interface for handling Annotation%s
101  *
102  * \ingroup kte_group_doc_extensions
103  *
104  * \section annoiface_intro Introduction
105  *
106  * The AnnotationInterface is designed to provide line annotation information
107  * for a document. This interface provides means to associate a document with a
108  * annotation model, which provides some annotation information for each line
109  * in the document.
110  *
111  * Setting a model for a Document makes the model data available for all views.
112  * If you only want to provide annotations in exactly one view, you can use
113  * the AnnotationViewInterface directly. See the AnnotationViewInterface for
114  * further details. To summarize, the two use cases are
115  * - (1) show annotations in all views. This means you set an AnnotationModel
116  * with this interface, and then call setAnnotationBorderVisible() for
117  * each view.
118  * - (2) show annotations only in one view. This means to \e not use this
119  * interface. Instead, use the AnnotationViewInterface, which inherits
120  * this interface. This means you set a model for the specific View.
121  *
122  * If you set a model to the Document \e and the View, the View's model has
123  * higher priority.
124  *
125  * \section annoiface_access Accessing the AnnotationInterface
126  *
127  * The AnnotationInterface is an extension interface for a Document, i.e. the
128  * Document inherits the interface \e provided that the
129  * used KTextEditor library implements the interface. Use qobject_cast to
130  * access the interface:
131  * \code
132  * // document is of type KTextEditor::Document*
133  * auto iface = qobject_cast<KTextEditor::AnnotationInterface*>(document);
134  *
135  * if (iface) {
136  * // the implementation supports the interface
137  * // do stuff
138  * } else {
139  * // the implementation does not support the interface
140  * }
141  * \endcode
142  *
143  * \section annoiface_usage Using the AnnotationInterface
144  *
145  * \since 4.1
146  * \see KTextEditor::AnnotationModel, KTextEditor::AnnotationViewInterface
147  */
148 class KTEXTEDITOR_EXPORT AnnotationInterface
149 {
150 public:
151  virtual ~AnnotationInterface()
152  {
153  }
154 
155  /**
156  * Sets a new \ref AnnotationModel for this document to provide
157  * annotation information for each line.
158  *
159  * \param model the new AnnotationModel
160  */
161  virtual void setAnnotationModel(AnnotationModel *model) = 0;
162 
163  /**
164  * returns the currently set \ref AnnotationModel or 0 if there's none
165  * set
166  * @returns the current \ref AnnotationModel
167  */
168  virtual AnnotationModel *annotationModel() const = 0;
169 };
170 
171 /**
172  * \brief Annotation interface for the View
173  *
174  * \ingroup kte_group_view_extensions
175  *
176  * \section annoview_intro Introduction
177  *
178  * The AnnotationViewInterface allows to do two things:
179  * - (1) show/hide the annotation border along with the possibility to add actions
180  * into its context menu.
181  * - (2) set a separate AnnotationModel for the View: Note that this interface
182  * inherits the AnnotationInterface.
183  *
184  * For a more detailed explanation about whether you want an AnnotationModel
185  * in the Document or the View, read the detailed documentation about the
186  * AnnotationInterface.
187  *
188  * \section annoview_access Accessing the AnnotationViewInterface
189  *
190  * The AnnotationViewInterface is an extension interface for a
191  * View, i.e. the View inherits the interface \e provided that the
192  * used KTextEditor library implements the interface. Use qobject_cast to
193  * access the interface:
194  * \code
195  * // view is of type KTextEditor::View*
196  * auto iface = qobject_cast<KTextEditor::AnnotationViewInterface*>(view);
197  *
198  * if (iface) {
199  * // the implementation supports the interface
200  * // do stuff
201  * iface->setAnnotationBorderVisible(true);
202  * } else {
203  * // the implementation does not support the interface
204  * }
205  * \endcode
206  *
207  * \since 4.1
208  */
209 class KTEXTEDITOR_EXPORT AnnotationViewInterface : public AnnotationInterface
210 {
211 public:
212  ~AnnotationViewInterface() override
213  {
214  }
215 
216  /**
217  * This function can be used to show or hide the annotation border
218  * The annotation border is hidden by default.
219  *
220  * @param visible if \e true the annotation border is shown, otherwise hidden
221  */
222  virtual void setAnnotationBorderVisible(bool visible) = 0;
223 
224  /**
225  * Checks whether the View's annotation border is visible.
226  */
227  virtual bool isAnnotationBorderVisible() const = 0;
228 
229  //
230  // SIGNALS!!!
231  //
232 public:
233  /**
234  * This signal is emitted before a context menu is shown on the annotation
235  * border for the given line and view.
236  *
237  * \note Kate Part implementation detail: In Kate Part, the menu has an
238  * entry to hide the annotation border.
239  *
240  * \param view the view that the annotation border belongs to
241  * \param menu the context menu that will be shown
242  * \param line the annotated line for which the context menu is shown
243  */
244  virtual void annotationContextMenuAboutToShow(KTextEditor::View *view, QMenu *menu, int line) = 0;
245 
246  /**
247  * This signal is emitted when an entry on the annotation border was activated,
248  * for example by clicking or double-clicking it. This follows the KDE wide
249  * setting for activation via click or double-clcik
250  *
251  * \param view the view to which the activated border belongs to
252  * \param line the document line that the activated position belongs to
253  */
254  virtual void annotationActivated(KTextEditor::View *view, int line) = 0;
255 
256  /**
257  * This signal is emitted when the annotation border is shown or hidden.
258  *
259  * \param view the view to which the border belongs to
260  * \param visible the current visibility state
261  */
262  virtual void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible) = 0;
263 };
264 
265 /**
266  * \brief Annotation interface for the View, version 2
267  *
268  * \ingroup kte_group_view_extensions
269  *
270  * \section annoview_intro Introduction
271  *
272  * The AnnotationViewInterfaceV2 allows to do the same as AnnotationViewInterface
273  * and additionally
274  * - (1) set a custom AbstractAnnotationItemDelegate for the View.
275  *
276  * For a more detailed explanation about whether you want to set a custom
277  * delegate for rendering the annotations, read the detailed documentation about the
278  * AbstractAnnotationItemDelegate.
279  *
280  * \section annoview_access Accessing the AnnotationViewInterfaceV2
281  *
282  * The AnnotationViewInterfaceV2 is an extension interface for a
283  * View, i.e. the View inherits the interface \e provided that the
284  * used KTextEditor library implements the interface. Use qobject_cast to
285  * access the interface:
286  * \code
287  * // view is of type KTextEditor::View*
288  * auto iface = qobject_cast<KTextEditor::AnnotationViewInterfaceV2*>(view);
289  *
290  * if (iface) {
291  * // the implementation supports the interface
292  * // do stuff
293  * iface->setAnnotationItemDelegate(myDelegate);
294  * iface->setAnnotationUniformItemSizes(true);
295  * } else {
296  * // the implementation does not support the interface
297  * }
298  * \endcode
299  *
300  * \since 5.53
301  */
302 class KTEXTEDITOR_EXPORT AnnotationViewInterfaceV2 : public AnnotationViewInterface
303 {
304  // KF6: Merge KTextEditor::AnnotationViewInterfaceV2 into KTextEditor::AnnotationViewInterface (kossebau)
305 public:
306  ~AnnotationViewInterfaceV2() override
307  {
308  }
309 
310  /**
311  * Sets the AbstractAnnotationItemDelegate for this view and the model
312  * to provide custom rendering of annotation information for each line.
313  * Ownership is not transferred.
314  *
315  * \param delegate the new AbstractAnnotationItemDelegate, or \c nullptr to reset to the default delegate
316  */
317  virtual void setAnnotationItemDelegate(KTextEditor::AbstractAnnotationItemDelegate *delegate) = 0;
318 
319  /**
320  * Returns the currently used AbstractAnnotationItemDelegate
321  *
322  * @returns the current AbstractAnnotationItemDelegate
323  */
324  virtual KTextEditor::AbstractAnnotationItemDelegate *annotationItemDelegate() const = 0;
325 
326  /**
327  * This function can be used to declare whether it is known that the annotation items
328  * rendered by the set delegate all have the same size.
329  * This enables the view to do some optimizations for performance purposes.
330  *
331  * By default the value of this property is \c false .
332  *
333  * @param uniformItemSizes if \c true the annotation items are considered to all have the same size
334  */
335  virtual void setAnnotationUniformItemSizes(bool uniformItemSizes) = 0;
336 
337  /**
338  * Checks whether the annotation items all have the same size.
339  */
340  virtual bool uniformAnnotationItemSizes() const = 0;
341 };
342 
343 }
344 
345 Q_DECLARE_INTERFACE(KTextEditor::AnnotationInterface, "org.kde.KTextEditor.AnnotationInterface")
346 Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterface, "org.kde.KTextEditor.AnnotationViewInterface")
347 Q_DECLARE_INTERFACE(KTextEditor::AnnotationViewInterfaceV2, "org.kde.KTextEditor.AnnotationViewInterfaceV2")
348 
349 #endif
A delegate for rendering line annotation information and handling events.
UserRole
An model for providing line annotation information.
Annotation interface for the View.
KTextEditor::AnnotationModel * annotationModel() const override
returns the currently set AnnotationModel or 0 if there's none set
void setAnnotationModel(KTextEditor::AnnotationModel *model) override
Sets a new AnnotationModel for this document to provide annotation information for each line.
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
A Document extension interface for handling Annotations.
Annotation interface for the View, version 2.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:52:04 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.