KTextEditor

inlinenoteprovider.h
1 /*
2  SPDX-FileCopyrightText: 2018 Sven Brauch <[email protected]>
3  SPDX-FileCopyrightText: 2018 Michal Srb <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KTEXTEDITOR_INLINENOTEPROVIDER_H
9 #define KTEXTEDITOR_INLINENOTEPROVIDER_H
10 
11 #include <ktexteditor_export.h>
12 
13 #include <ktexteditor/inlinenote.h>
14 
15 namespace KTextEditor
16 {
17 /**
18  * @class InlineNoteProvider inlinenoteprovider.h <KTextEditor/InlineNoteProvider>
19  *
20  * @brief A source of inline notes for a document.
21  *
22  * InlineNoteProvider is a object that can be queried for inline notes in the
23  * view. It emits signals when the notes change and should be queried again.
24  *
25  * @see InlineNoteInterface
26  * @since 5.50
27  */
28 class KTEXTEDITOR_EXPORT InlineNoteProvider : public QObject
29 {
30  Q_OBJECT
31 
32 public:
33  /**
34  * Default constructor.
35  */
37 
38  /**
39  * Virtual destructor to allow inheritance.
40  */
41  virtual ~InlineNoteProvider();
42 
43  /**
44  * Get list of inline notes for given line.
45  *
46  * Should return a vector of columns on which the notes are located.
47  * 0 means the note is located before the first character of the line.
48  * 1 means the note is located after the first character, etc. If the
49  * returned number is greater than the length of the line, the note will be
50  * placed behind the text as if there were additional spaces.
51  *
52  * @note When returning multiple InlineNote%s, use InlineNote::index() to
53  * map the InlineNote to this QVector's index.
54  *
55  * @param line Line number
56  * @returns vector of columns where inline notes appear in this line
57  */
58  virtual QVector<int> inlineNotes(int line) const = 0;
59 
60  /**
61  * Width to be reserved for the note in the text.
62  *
63  * Typically, a custom width with the current line height can be returned.
64  * If the width depends on the font size, note.font() can be used to obtain
65  * the font metrics.
66  *
67  * Example to reserve a square size for painting:
68  * @code
69  * return QSize(note.lineHeight(), lineHeight());
70  * @endcode
71  *
72  * @note Do not return heights that are larger than note.lineHeight(),
73  * since the painting code clips to the line height anyways.
74  *
75  * @param note the InlineNote for which the size is queried
76  * @return the required size of the InlineNote
77  */
78  virtual QSize inlineNoteSize(const InlineNote &note) const = 0;
79 
80  /**
81  * Paint the note into the line.
82  *
83  * The method should use the given painter to render the note into the
84  * line. The painter is translated such that coordinates 0x0 mark the top
85  * left corner of the note. The method should not paint outside rectangle
86  * given by the size previously returned by inlineNoteSize().
87  *
88  * The method is given the height of the line, the metrics of current font
89  * and the font which it may use during painting.
90  *
91  * If wanted, you can use note.underMouse() to e.g. highlight the
92  *
93  * @param note note to paint, containing location and index
94  * @param painter painter prepared for rendering the note
95  */
96  virtual void paintInlineNote(const InlineNote &note, QPainter &painter) const = 0;
97 
98  /**
99  * Invoked when a note is activated by the user.
100  *
101  * This method is called when a user activates a note, i.e. clicks on it.
102  * Coordinates of @p pos are in note coordinates, i.e. relative to the note's
103  * top-left corner (same coordinate system as the painter has in paintInlineNote()).
104  *
105  * The default implementation does nothing.
106  *
107  * @param note the note which was activated
108  * @param buttons the button(s) the note was clicked with
109  * @param globalPos the point the note was clicked at in global screen coordinates
110  */
111  virtual void inlineNoteActivated(const InlineNote &note, Qt::MouseButtons buttons, const QPoint &globalPos);
112 
113  /**
114  * Invoked when the mouse cursor moves into the @p note when it was outside before.
115  *
116  * The default implementation does nothing.
117  *
118  * @param note the note which was activated
119  * @param globalPos the location of the mouse cursor in global screen coordinates
120  */
121  virtual void inlineNoteFocusInEvent(const InlineNote &note, const QPoint &globalPos);
122 
123  /**
124  * Invoked when the mouse cursor leaves the note.
125  *
126  * The default implementation does nothing.
127  *
128  * @param note the note which was deactivated
129  */
130  virtual void inlineNoteFocusOutEvent(const InlineNote &note);
131 
132  /**
133  * Invoked when the mouse cursor moves inside the note.
134  *
135  * The default implementation does nothing.
136  *
137  * @param note the note which was hovered
138  * @param globalPos the location of the mouse cursor in global screen coordinates
139  */
140  virtual void inlineNoteMouseMoveEvent(const InlineNote &note, const QPoint &globalPos);
141 
142 Q_SIGNALS:
143  /**
144  * The provider should emit the signal inlineNotesReset() when almost all inline notes
145  * changed.
146  */
147  void inlineNotesReset();
148 
149  /**
150  * The provider should emit the signal inlineNotesChanged() whenever one
151  * or more InlineNote%s on the line changed.
152  */
153  void inlineNotesChanged(int line);
154 
155 private:
156  class InlineNoteProviderPrivate *const d = nullptr;
157 };
158 
159 }
160 
161 #endif
A source of inline notes for a document.
typedef MouseButtons
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:20
Describes an inline note.
Definition: inlinenote.h:39
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Oct 15 2021 22:59:48 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.