1/* This file is part of the KDE project
2 *
3 * Copyright (C) 2010 Christoph Cullmann <cullmann@kde.org>
4 *
5 * Based on code of the SmartCursor/Range by:
6 * Copyright (C) 2003-2005 Hamish Rodda <rodda@kde.org>
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
17 *
18 * You should have received a copy of the GNU Library General Public License
19 * along with this library; see the file COPYING.LIB. If not, write to
20 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
22 */
23
24#ifndef KTEXTEDITOR_MOVINGINTERFACE_H
25#define KTEXTEDITOR_MOVINGINTERFACE_H
26
27#include <ktexteditor_export.h>
28#include <ktexteditor/movingcursor.h>
29#include <ktexteditor/movingrange.h>
30#include <ktexteditor/movingrangefeedback.h>
31
32namespace KTextEditor
33{
34
35/**
36 * \brief Document interface for MovingCursor%s and MovingRange%s.
37 *
38 * \ingroup kte_group_doc_extensions
39 * \ingroup kte_group_moving_classes
40 *
41 * This class provides the interface for KTextEditor::Documents to create MovingCursors/Ranges.
42 *
43 * \author Christoph Cullmann \<cullmann@kde.org\>
44 *
45 * \since 4.5
46 */
47class KTEXTEDITOR_EXPORT MovingInterface
48{
49 //
50 // Constructor/Destructor
51 //
52public:
53 /**
54 * Default constructor
55 */
56 MovingInterface();
57
58 /**
59 * Virtual destructor
60 */
61 virtual ~MovingInterface();
62
63 //
64 // Normal API
65 //
66public:
67 /**
68 * Create a new moving cursor for this document.
69 * @param position position of the moving cursor to create
70 * @param insertBehavior insertion behavior
71 * @return new moving cursor for the document
72 */
73 virtual MovingCursor *newMovingCursor(const Cursor &position,
74 MovingCursor::InsertBehavior insertBehavior = MovingCursor::MoveOnInsert) = 0;
75
76 /**
77 * Create a new moving range for this document.
78 * @param range range of the moving range to create
79 * @param insertBehaviors insertion behaviors
80 * @param emptyBehavior behavior on becoming empty
81 * @return new moving range for the document
82 */
83 virtual MovingRange *newMovingRange(const Range &range,
84 MovingRange::InsertBehaviors insertBehaviors = MovingRange::DoNotExpand,
85 MovingRange::EmptyBehavior emptyBehavior = MovingRange::AllowEmpty) = 0;
86
87 /**
88 * Current revision
89 * @return current revision
90 */
91 virtual qint64 revision() const = 0;
92
93 /**
94 * Last revision the buffer got successful saved
95 * @return last revision buffer got saved, -1 if none
96 */
97 virtual qint64 lastSavedRevision() const = 0;
98
99 /**
100 * Lock a revision, this will keep it around until released again.
101 * But all revisions will always be cleared on buffer clear() (and therefor load())
102 * @param revision revision to lock
103 */
104 virtual void lockRevision(qint64 revision) = 0;
105
106 /**
107 * Release a revision.
108 * @param revision revision to release
109 */
110 virtual void unlockRevision(qint64 revision) = 0;
111
112 /**
113 * Transform a cursor from one revision to an other.
114 * @param cursor cursor to transform
115 * @param insertBehavior behavior of this cursor on insert of text at its position
116 * @param fromRevision from this revision we want to transform
117 * @param toRevision to this revision we want to transform, default of -1 is current revision
118 */
119 virtual void transformCursor(KTextEditor::Cursor &cursor,
120 KTextEditor::MovingCursor::InsertBehavior insertBehavior,
121 qint64 fromRevision,
122 qint64 toRevision = -1) = 0;
123
124 /**
125 * Transform a cursor from one revision to an other.
126 * @param line line number of the cursor to transform
127 * @param column column number of the cursor to transform
128 * @param insertBehavior behavior of this cursor on insert of text at its position
129 * @param fromRevision from this revision we want to transform
130 * @param toRevision to this revision we want to transform, default of -1 is current revision
131 */
132 virtual void transformCursor(int &line,
133 int &column,
134 KTextEditor::MovingCursor::InsertBehavior insertBehavior,
135 qint64 fromRevision,
136 qint64 toRevision = -1) = 0;
137
138 /**
139 * Transform a range from one revision to an other.
140 * @param range range to transform
141 * @param insertBehaviors behavior of this range on insert of text at its position
142 * @param emptyBehavior behavior on becoming empty
143 * @param fromRevision from this revision we want to transform
144 * @param toRevision to this revision we want to transform, default of -1 is current revision
145 */
146 virtual void transformRange(KTextEditor::Range &range,
147 KTextEditor::MovingRange::InsertBehaviors insertBehaviors,
148 MovingRange::EmptyBehavior emptyBehavior,
149 qint64 fromRevision,
150 qint64 toRevision = -1) = 0;
151
152 //
153 // Signals
154 //
155public:
156 /**
157 * This signal is emitted before the cursors/ranges/revisions of a document
158 * are destroyed as the document is deleted.
159 * @param document the document which the interface belongs to which is in the process of being deleted
160 */
161 void aboutToDeleteMovingInterfaceContent(KTextEditor::Document *document);
162
163 /**
164 * This signal is emitted before the ranges of a document are invalidated
165 * and the revisions are deleted as the document is cleared (for example on
166 * load/reload). While this signal is emitted, the old document content is
167 * still valid and accessible before the clear.
168 * @param document the document which the interface belongs to which will invalidate its data
169 */
170 void aboutToInvalidateMovingInterfaceContent(KTextEditor::Document *document);
171
172private:
173 /**
174 * private d-pointer
175 */
176 class MovingInterfacePrivate *const d = nullptr;
177};
178
179}
180
181Q_DECLARE_INTERFACE(KTextEditor::MovingInterface, "org.kde.KTextEditor.MovingInterface")
182
183#endif
184
185