KTextEditor

abstractannotationitemdelegate.h
1 /*
2  SPDX-FileCopyrightText: 2017-2018 Friedrich W. H. Kossebau <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef KTEXTEDITOR_ABSTRACTANNOTATIONITEMDELEGATE_H
8 #define KTEXTEDITOR_ABSTRACTANNOTATIONITEMDELEGATE_H
9 
10 #include <ktexteditor_export.h>
11 
12 #include <QObject>
13 #include <QStyleOption>
14 
15 class QHelpEvent;
16 class QPoint;
17 
18 namespace KTextEditor
19 {
20 class AnnotationModel;
21 class View;
22 
23 /**
24  * \brief The style option set for an annotation item, as painted by AbstractAnnotationItemDelegate
25  *
26  * \since 5.53
27  * \see KTextEditor::AbstractAnnotationItemDelegate
28  */
29 class KTEXTEDITOR_EXPORT StyleOptionAnnotationItem : public QStyleOption
30 {
31 public:
32  // TODO: not sure what SO_Default implies, but no clue how to maintain a user type registry?
33  enum StyleOptionType { Type = SO_Default };
34  enum StyleOptionVersion { Version = 1 };
35 
36  /**
37  * Index of the displayed line in the wrapped lines for the given real line
38  */
39  int wrappedLine = 0;
40  /**
41  * Number of wrapped lines for the given real line
42  *
43  * A value of 1 means no wrapping has happened and the real line is displayed as one line.
44  */
45  int wrappedLineCount = 1;
46  /**
47  * Index of the displayed line in the displayed lines for the same group
48  */
49  int visibleWrappedLineInGroup = 0;
50 
51  /**
52  * The view where the annotation is shown
53  *
54  * There is always a view set.
55  */
56  KTextEditor::View *view = nullptr;
57  /**
58  * Recommended size for icons or other symbols that will be rendered by the delegate
59  *
60  * The default value is QSize(-1, -1).
61  */
63  /**
64  * The metrics of the font used for rendering the text document
65  */
67 
68  /**
69  * Enum for describing the relative position of a real line in the row of consecutive
70  * displayed lines which belong to the same group of annotation items
71  * @see AnnotationItemGroupPositions
72  */
74  InvalidGroupPosition = 0, ///< Position not specified or not belonging to a group
75  InGroup = 0x1 << 0, ///< Real line belongs to a group
76  GroupBegin = 0x1 << 1, ///< Real line is first of consecutive lines from same group
77  GroupEnd = 0x1 << 2, ///< Real line is last of consecutive lines from same group
78  };
79  /// Stores a combination of #AnnotationItemGroupPosition values.
81 
82  /**
83  * Relative position of the real line in the row of consecutive displayed lines
84  * which belong to the same group of annotation items
85  */
86  AnnotationItemGroupPositions annotationItemGroupingPosition = InvalidGroupPosition;
87 
88 public:
91  StyleOptionAnnotationItem &operator=(const StyleOptionAnnotationItem &) = default;
92 
93 protected:
94  explicit StyleOptionAnnotationItem(int version);
95 };
96 
97 /**
98  * \class AbstractAnnotationItemDelegate abstractannotationitemdelegate.h <KTextEditor/AbstractAnnotationItemDelegate>
99  *
100  * \brief A delegate for rendering line annotation information and handling events
101  *
102  * \section annodelegate_intro Introduction
103  *
104  * AbstractAnnotationItemDelegate is a base class that can be reimplemented
105  * to customize the rendering of annotation information for each line in a document.
106  * It provides also the hooks to define handling of help events like tooltip or of
107  * the request for a context menu.
108  *
109  * \section annodelegate_impl Implementing an AbstractAnnotationItemDelegate
110  *
111  * The public interface of this class is loosely based on the QAbstractItemDelegate
112  * interfaces. It has five methods to implement.
113  *
114  * \since 5.53
115  * \see KTextEditor::AnnotationModel, KTextEditor::AnnotationViewInterfaceV2
116  */
117 class KTEXTEDITOR_EXPORT AbstractAnnotationItemDelegate : public QObject
118 {
119  Q_OBJECT
120 
121 protected:
122  explicit AbstractAnnotationItemDelegate(QObject *parent = nullptr);
123 
124 public:
125  ~AbstractAnnotationItemDelegate() override;
126 
127 public:
128  /**
129  * This pure abstract function must be reimplemented to provide custom rendering.
130  * Use the painter and style option to render the annotation information for the line
131  * specified by the arguments @p model and @p line.
132  * @param painter the painter object
133  * @param option the option object with the info needed for styling
134  * @param model the annotation model providing the annotation information
135  * @param line index of the real line the annotation information should be painted for
136  *
137  * Reimplement this in line with sizeHint().
138  */
139  virtual void paint(QPainter *painter, const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line) const = 0;
140  /**
141  * This pure abstract function must be reimplemented to provide custom rendering.
142  * Use the style option to calculate the best size for the annotation information
143  * for the line specified by the arguments @p model and @p line.
144  * This should be the size for the display for a single displayed content line,
145  * i.e. with no line wrapping or consecutive multiple annotation item of the same group assumed.
146  *
147  * @note If AnnotationViewInterfaceV2::uniformAnnotationItemSizes() is @c true for the view
148  * this delegate is used by, it is assumed that the returned value is the same for
149  * any line.
150  *
151  * @param option the option object with the info needed for styling
152  * @param model the annotation model providing the annotation information
153  * @param line index of the real line the annotation information should be painted for
154  * @return best size for the annotation information
155  *
156  * Reimplement this in line with paint().
157  */
158  virtual QSize sizeHint(const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line) const = 0;
159  /**
160  * Whenever a help event occurs, this function is called with the event view option
161  * and @p model and @p line specifying the item where the event occurs.
162  * This pure abstract function must be reimplemented to provide custom tooltips.
163  * @param event the help event
164  * @param view the view for which the help event is requested
165  * @param option the style option object with the info needed for styling, including the rect of the annotation
166  * @param model the annotation model providing the annotation information
167  * @param line index of the real line the annotation information should be painted for
168  * @return @c true if the event could be handled (implies that the data obtained from the model had the required role), @c false otherwise
169  *
170  * Reimplement this in line with hideTooltip().
171  */
172  virtual bool helpEvent(QHelpEvent *event,
173  KTextEditor::View *view,
176  int line) = 0;
177  /**
178  * This pure abstract function must be reimplemented to provide custom tooltips.
179  * It is called whenever a possible still shown tooltip no longer is valid,
180  * e.g. if the annotations have been hidden.
181  * @param view the view for which the tooltip was requested
182  *
183  * Reimplement this in line with helpEvent().
184  */
185  virtual void hideTooltip(KTextEditor::View *view) = 0;
186 
187 Q_SIGNALS:
188  /**
189  * This signal must be emitted when the sizeHint() for @p model and @p line changed.
190  * The view automatically connects to this signal and relayouts as necessary.
191  * If AnnotationViewInterfaceV2::uniformAnnotationItemSizes is set on the view,
192  * it is sufficient to emit sizeHintChanged only for one line.
193  * @param model the annotation model providing the annotation information
194  * @param line index of the real line the annotation information should be painted for
195  */
196  void sizeHintChanged(KTextEditor::AnnotationModel *model, int line);
197 };
198 
199 }
200 
201 #endif
A delegate for rendering line annotation information and handling events.
An model for providing line annotation information.
The style option set for an annotation item, as painted by AbstractAnnotationItemDelegate.
QSize decorationSize
Recommended size for icons or other symbols that will be rendered by the delegate.
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
QFontMetricsF contentFontMetrics
The metrics of the font used for rendering the text document.
AnnotationItemGroupPosition
Enum for describing the relative position of a real line in the row of consecutive displayed lines wh...
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 03:51:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.