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  enum { GroupIdentifierRole = Qt::UserRole };
48  // KF6: add AnnotationModelUserRole = Qt::UserRole + 0x100
49 
50  /**
51  * data() is used to retrieve the information needed to present the
52  * annotation information from the annotation model. The provider
53  * should return useful information for the line and the data role.
54  *
55  * The following roles are supported:
56  * - Qt::DisplayRole - a short display text to be placed in the border
57  * - Qt::TooltipRole - a tooltip information, longer text possible
58  * - Qt::BackgroundRole - a brush to be used to paint the background on the border
59  * - Qt::ForegroundRole - a brush to be used to paint the text on the border
60  * - AnnotationModel::GroupIdentifierRole - a string which identifies a
61  * group of items which will be highlighted on mouseover; return the same
62  * string for all items in a group (KDevelop uses a VCS revision number, for example)
63  *
64  *
65  * \param line the line for which the data is to be retrieved
66  * \param role the role to identify which kind of annotation is to be retrieved
67  *
68  * \returns a QVariant that contains the data for the given role.
69  */
70  virtual QVariant data(int line, Qt::ItemDataRole role) const = 0; // KF6: use int for role
71 
72 Q_SIGNALS:
73  /**
74  * The model should emit the signal reset() when the text of almost all
75  * lines changes. In most cases it is enough to call lineChanged().
76  *
77  * \note Kate Part implementation details: Whenever reset() is emitted Kate
78  * Part iterates over all lines of the document. Kate Part searches
79  * for the longest text to determine the annotation border's width.
80  *
81  * \see lineChanged()
82  */
83  void reset();
84 
85  /**
86  * The model should emit the signal lineChanged() when a line has to be
87  * updated.
88  *
89  * \note Kate Part implementation details: lineChanged() repaints the whole
90  * annotation border automatically.
91  */
92  void lineChanged(int line);
93 };
94 
95 } // namespace KTextEditor
96 
97 #endif
UserRole
An model for providing line annotation information.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 03:52:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.