KTextEditor

inlinenoteprovider.h
1/*
2 SPDX-FileCopyrightText: 2018 Sven Brauch <mail@svenbrauch.de>
3 SPDX-FileCopyrightText: 2018 Michal Srb <michalsrb@gmail.com>
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
15namespace 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 KTextEditor::View
26 * @since 5.50
27 */
28class KTEXTEDITOR_EXPORT InlineNoteProvider : public QObject
29{
30 Q_OBJECT
31
32public:
33 /**
34 * Default constructor.
35 */
37
38 /**
39 * Virtual destructor to allow inheritance.
40 */
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 QList's index.
54 *
55 * @param line Line number
56 * @returns vector of columns where inline notes appear in this line
57 */
58 virtual QList<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 * @param direction direction of the line i.e., right to left/left to right
96 */
97 virtual void paintInlineNote(const InlineNote &note, QPainter &painter, Qt::LayoutDirection direction) const = 0;
98
99 /**
100 * Invoked when a note is activated by the user.
101 *
102 * This method is called when a user activates a note, i.e. clicks on it.
103 * Coordinates of @p pos are in note coordinates, i.e. relative to the note's
104 * top-left corner (same coordinate system as the painter has in paintInlineNote()).
105 *
106 * The default implementation does nothing.
107 *
108 * @param note the note which was activated
109 * @param buttons the button(s) the note was clicked with
110 * @param globalPos the point the note was clicked at in global screen coordinates
111 */
112 virtual void inlineNoteActivated(const InlineNote &note, Qt::MouseButtons buttons, const QPoint &globalPos);
113
114 /**
115 * Invoked when the mouse cursor moves into the @p note when it was outside before.
116 *
117 * The default implementation does nothing.
118 *
119 * @param note the note which was activated
120 * @param globalPos the location of the mouse cursor in global screen coordinates
121 */
122 virtual void inlineNoteFocusInEvent(const InlineNote &note, const QPoint &globalPos);
123
124 /**
125 * Invoked when the mouse cursor leaves the note.
126 *
127 * The default implementation does nothing.
128 *
129 * @param note the note which was deactivated
130 */
131 virtual void inlineNoteFocusOutEvent(const InlineNote &note);
132
133 /**
134 * Invoked when the mouse cursor moves inside the note.
135 *
136 * The default implementation does nothing.
137 *
138 * @param note the note which was hovered
139 * @param globalPos the location of the mouse cursor in global screen coordinates
140 */
141 virtual void inlineNoteMouseMoveEvent(const InlineNote &note, const QPoint &globalPos);
142
143Q_SIGNALS:
144 /**
145 * The provider should emit the signal inlineNotesReset() when almost all inline notes
146 * changed.
147 */
149
150 /**
151 * The provider should emit the signal inlineNotesChanged() whenever one
152 * or more InlineNote%s on the line changed.
153 */
154 void inlineNotesChanged(int line);
155
156private:
157 class InlineNoteProviderPrivate *const d = nullptr;
158};
159
160}
161
162#endif
A source of inline notes for a document.
virtual QSize inlineNoteSize(const InlineNote &note) const =0
Width to be reserved for the note in the text.
void inlineNotesReset()
The provider should emit the signal inlineNotesReset() when almost all inline notes changed.
void inlineNotesChanged(int line)
The provider should emit the signal inlineNotesChanged() whenever one or more InlineNotes on the line...
virtual QList< int > inlineNotes(int line) const =0
Get list of inline notes for given line.
virtual void paintInlineNote(const InlineNote &note, QPainter &painter, Qt::LayoutDirection direction) const =0
Paint the note into the line.
~InlineNoteProvider() override
Virtual destructor to allow inheritance.
InlineNoteProvider()
Default constructor.
Describes an inline note.
Definition inlinenote.h:40
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
LayoutDirection
typedef MouseButtons
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:53:31 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.