KTextEditor

abstractannotationitemdelegate.h
1/*
2 SPDX-FileCopyrightText: 2017-2018 Friedrich W. H. Kossebau <kossebau@kde.org>
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
15class QHelpEvent;
16class QPoint;
17
18namespace KTextEditor
19{
20class AnnotationModel;
21class 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 */
29class KTEXTEDITOR_EXPORT StyleOptionAnnotationItem : public QStyleOption
30{
31public:
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
88public:
91 StyleOptionAnnotationItem &operator=(const StyleOptionAnnotationItem &) = default;
92
93protected:
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::AnnotationViewInterface
116 */
117class KTEXTEDITOR_EXPORT AbstractAnnotationItemDelegate : public QObject
118{
119 Q_OBJECT
120
121protected:
122 explicit AbstractAnnotationItemDelegate(QObject *parent = nullptr);
123
124public:
126
127public:
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 AnnotationViewInterface::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
187Q_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 AnnotationViewInterface::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 */
197};
198
199}
200
201#endif
A delegate for rendering line annotation information and handling events.
virtual void hideTooltip(KTextEditor::View *view)=0
This pure abstract function must be reimplemented to provide custom tooltips.
virtual bool helpEvent(QHelpEvent *event, KTextEditor::View *view, const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line)=0
Whenever a help event occurs, this function is called with the event view option and model and line s...
void sizeHintChanged(KTextEditor::AnnotationModel *model, int line)
This signal must be emitted when the sizeHint() for model and line changed.
virtual QSize sizeHint(const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line) const =0
This pure abstract function must be reimplemented to provide custom rendering.
virtual void paint(QPainter *painter, const KTextEditor::StyleOptionAnnotationItem &option, KTextEditor::AnnotationModel *model, int line) const =0
This pure abstract function must be reimplemented to provide custom rendering.
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.
AnnotationItemGroupPosition
Enum for describing the relative position of a real line in the row of consecutive displayed lines wh...
QFontMetricsF contentFontMetrics
The metrics of the font used for rendering the text document.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:57:25 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.