1/* This file is part of the KDE libraries
2
3 Copyright 2018 Sven Brauch <mail@svenbrauch.de>
4 Copyright 2018 Michal Srb <michalsrb@gmail.com>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) version 3, or any
10 later version accepted by the membership of KDE e.V. (or its
11 successor approved by the membership of KDE e.V.), which shall
12 act as a proxy defined in Section 6 of version 3 of the license.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Library General Public License
20 along with this library; see the file COPYING.LIB. If not, write to
21 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 Boston, MA 02110-1301, USA.
23*/
24#ifndef KTEXTEDITOR_INLINENOTEINTERFACE_H
25#define KTEXTEDITOR_INLINENOTEINTERFACE_H
26
27#include <QString>
28
29#include <ktexteditor_export.h>
30
31#include <ktexteditor/cursor.h>
32#include <ktexteditor/view.h>
33
34class QPainter;
35
36namespace KTextEditor
37{
38
39class InlineNoteProvider;
40
41/**
42 * @brief Inline notes interface for rendering notes in the text.
43 *
44 * @ingroup kte_group_view_extensions
45 *
46 * @section inlinenote_introduction Introduction
47 *
48 * The inline notes interface provides a way to render arbitrary things in
49 * the text. The text layout of the line is adapted to create space for the
50 * note. Possible applications include showing a name of a function parameter
51 * in a function call or rendering a square with a color preview next to CSS
52 * color property.
53 *
54 * \image html inlinenote.png "Inline note showing a CSS color preview"
55 *
56 * To register as inline note provider, call registerInlineNoteProvider() with
57 * an instance that inherits InlineNoteProvider. Finally, make sure you remove
58 * your inline note provider by calling unregisterInlineNoteProvider().
59 *
60 * @section inlinenote_access Accessing the InlineNoteInterface
61 *
62 * The InlineNoteInterface is an extension interface for a
63 * View, i.e. the View inherits the interface. Use qobject_cast to access the
64 * interface:
65 * @code
66 * // view is of type KTextEditor::View*
67 * auto iface = qobject_cast<KTextEditor::InlineNoteInterface*>(view);
68 *
69 * if (iface) {
70 * // the implementation supports the interface
71 * // myProvider inherits KTextEditor::InlineNoteProvider
72 * iface->registerInlineNoteProvider(myProvider);
73 * } else {
74 * // the implementation does not support the interface
75 * }
76 * @endcode
77 *
78 * @see InlineNoteProvider
79 * @see InlineNote
80 *
81 * @author Sven Brauch, Michal Srb
82 * @since 5.50
83 */
84class KTEXTEDITOR_EXPORT InlineNoteInterface
85{
86public:
87 InlineNoteInterface();
88 virtual ~InlineNoteInterface();
89
90 /**
91 * Register the inline note provider @p provider.
92 *
93 * Whenever a line is painted, the @p provider will be queried for notes
94 * that should be painted in it. When the provider is about to be
95 * destroyed, make sure to call unregisterInlineNoteProvider() to avoid a
96 * dangling pointer.
97 *
98 * @param provider inline note provider
99 * @see unregisterInlineNoteProvider(), InlineNoteProvider
100 */
101 virtual void registerInlineNoteProvider(KTextEditor::InlineNoteProvider *provider) = 0;
102
103 /**
104 * Unregister the inline note provider @p provider.
105 *
106 * @param provider inline note provider to unregister
107 * @see registerInlineNoteProvider(), InlineNoteProvider
108 */
109 virtual void unregisterInlineNoteProvider(KTextEditor::InlineNoteProvider *provider) = 0;
110};
111
112}
113
114Q_DECLARE_INTERFACE(KTextEditor::InlineNoteInterface, "org.kde.KTextEditor.InlineNoteInterface")
115
116#endif
117