← Back to branch summary

~ubuntu-branches/ubuntu/vivid/kate/vivid-updates

« back to all changes in this revision

Viewing changes to ktexteditor/smartcursor.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2014-12-04 16:49:41 UTC
  • mfrom: (1.6.6)
  • Revision ID: package-import@ubuntu.com-20141204164941-l3qbvsly83hhlw2v
Tags: 4:14.11.97-0ubuntu1
* New upstream release
* Update build-deps and use pkg-kde v3 for Qt 5 build
* kate-data now kate5-data for co-installability

Show diffs side-by-side

added added

removed removed

Lines of Context:
ktexteditor/smartcursor.h
1
 
/* This file is part of the KDE project
2
 
   Copyright (C) 2003-2005 Hamish Rodda <rodda@kde.org>
3
 
 
4
 
   This library is free software; you can redistribute it and/or
5
 
   modify it under the terms of the GNU Library General Public
6
 
   License version 2 as published by the Free Software Foundation.
7
 
 
8
 
   This library is distributed in the hope that it will be useful,
9
 
   but WITHOUT ANY WARRANTY; without even the implied warranty of
10
 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
11
 
   Library General Public License for more details.
12
 
 
13
 
   You should have received a copy of the GNU Library General Public License
14
 
   along with this library; see the file COPYING.LIB.  If not, write to
15
 
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16
 
   Boston, MA 02110-1301, USA.
17
 
*/
18
 
 
19
 
#ifndef KDELIBS_KTEXTEDITOR_SMARTCURSOR_H
20
 
#define KDELIBS_KTEXTEDITOR_SMARTCURSOR_H
21
 
 
22
 
#include <ktexteditor/ktexteditor_export.h>
23
 
#include <ktexteditor/cursor.h>
24
 
 
25
 
namespace KTextEditor
26
 
{
27
 
class SmartRange;
28
 
 
29
 
class SmartCursorWatcher;
30
 
class SmartCursorNotifier;
31
 
 
32
 
/**
33
 
 * \short A Cursor which is bound to a specific Document, and maintains its position.
34
 
 *
35
 
 * \ingroup kte_group_smart_classes
36
 
 *
37
 
 * A SmartCursor is an extension of the basic Cursor class. It maintains its
38
 
 * position in the document and provides a number of convenience methods,
39
 
 * including those for accessing and manipulating the content of the associated
40
 
 * Document.  As a result of this, SmartCursor%s may not be copied, as they need
41
 
 * to maintain a connection to the associated Document.
42
 
 *
43
 
 * To receive notifications when the position of the cursor changes, or other
44
 
 * similar notifications, see either SmartCursorNotifier for QObject signal
45
 
 * notification via notifier(), or SmartCursorWatcher for virtual inheritance
46
 
 * notification via setWatcher().
47
 
 *
48
 
 * Create a new SmartCursor like this:
49
 
 * \code
50
 
 * // Retrieve the SmartInterface
51
 
 * KTextEditor::SmartInterface* smart =
52
 
 *     qobject_cast<KTextEditor::SmartInterface*>( yourDocument );
53
 
 *
54
 
 * if ( smart ) {
55
 
 *     KTextEditor::SmartCursor* cursor = smart->newSmartCursor();
56
 
 * }
57
 
 * \endcode
58
 
 *
59
 
 * When finished with a SmartCursor, simply delete it.
60
 
 *
61
 
 * \sa Cursor, SmartCursorNotifier, SmartCursorWatcher, and SmartInterface.
62
 
 *
63
 
 * \author Hamish Rodda \<rodda@kde.org\>
64
 
 */
65
 
class KTEXTEDITOR_EXPORT SmartCursor : public Cursor
66
 
{
67
 
  friend class SmartRange;
68
 
 
69
 
  public:
70
 
    /**
71
 
     * Virtual destructor.
72
 
     *
73
 
     * Subclasses should call SmartCursorNotifier::deleted() and
74
 
     * SmartCursorWatcher::deleted() methods \e before cleaning themselves up.
75
 
     */
76
 
    virtual ~SmartCursor();
77
 
 
78
 
    /**
79
 
     * Returns that this cursor is a SmartCursor.
80
 
     */
81
 
    virtual bool isSmartCursor() const;
82
 
 
83
 
    /**
84
 
     * Returns this cursor as a SmartCursor
85
 
     */
86
 
    virtual SmartCursor* toSmartCursor() const;
87
 
 
88
 
    /**
89
 
     * Returns the range that this cursor belongs to, if any.
90
 
     *
91
 
     * \sa Cursor::range()
92
 
     */
93
 
    SmartRange* smartRange() const;
94
 
 
95
 
    //BEGIN Functionality present from having this cursor associated with a Document
96
 
    /**
97
 
     * \name Document-related functions
98
 
     *
99
 
     * The following functions are provided for convenient access to the
100
 
     * associated Document.
101
 
     * \{
102
 
     */
103
 
    /**
104
 
     * Returns the document to which this cursor is attached.
105
 
     */
106
 
    Document* document() const;
107
 
 
108
 
    /**
109
 
     * Determine if this cursor is located at the end of the current line.
110
 
     *
111
 
     * \return \e true if the cursor is situated at the end of the line, otherwise \e false.
112
 
     */
113
 
    virtual bool atEndOfLine() const;
114
 
 
115
 
    /**
116
 
     * Determine if this cursor is located at the end of the document.
117
 
     *
118
 
     * \return \e true if the cursor is situated at the end of the document, otherwise \e false.
119
 
     */
120
 
    virtual bool atEndOfDocument() const;
121
 
 
122
 
    /**
123
 
     * \reimp
124
 
     * \sa Document::cursorInText()
125
 
     */
126
 
    virtual bool isValid() const;
127
 
 
128
 
    /**
129
 
     * Returns the character in the document immediately after this position,
130
 
     * ie. from this position to this position plus Cursor(0,1).
131
 
     */
132
 
    QChar character() const;
133
 
 
134
 
    /**
135
 
     * Insert \p text into the associated Document.
136
 
     *
137
 
     * \param text text to insert
138
 
     * \param block insert this text as a visual block of text rather than a linear sequence
139
 
     *
140
 
     * \return \e true on success, otherwise \e false
141
 
     */
142
 
    virtual bool insertText(const QStringList &text, bool block = false);
143
 
 
144
 
    /**
145
 
     * Defines the ways in which the cursor can be advanced.
146
 
     * Important for languages where multiple characters are required to
147
 
     * form one letter.
148
 
     */
149
 
    enum AdvanceMode {
150
 
      /// Movement is calculated on the basis of absolute numbers of characters
151
 
      ByCharacter,
152
 
      /// Movement takes into account valid cursor positions only (as defined by bidirectional processing)
153
 
      ByCursorPosition
154
 
    };
155
 
 
156
 
    /**
157
 
     * Move cursor by specified \a distance along the document buffer.
158
 
     *
159
 
     * E.g.:
160
 
     * \code
161
 
     * cursor.advance(1);
162
 
     * \endcode
163
 
     * will move the cursor forward by one character, or, if the cursor is already
164
 
     * on the end of the line, will move it to the start of the next line.
165
 
     *
166
 
     * \note Negative numbers should be accepted, and move backwards.
167
 
     * \note Not all \a mode%s are required to be supported.
168
 
     *
169
 
     * \param distance distance to advance (or go back if \a distance is negative)
170
 
     * \param mode whether to move by character, or by number of valid cursor positions
171
 
     *
172
 
     * \return true if the position could be reached within the document, otherwise false
173
 
     *         (the cursor should not move if \a distance is beyond the end of the document).
174
 
     */
175
 
    virtual bool advance(int distance, AdvanceMode mode = ByCharacter);
176
 
    //END
177
 
 
178
 
    //BEGIN Behavior methods
179
 
    /**
180
 
     * \}
181
 
     *
182
 
     * \name Behavior
183
 
     *
184
 
     * The following functions relate to the behavior of this SmartCursor.
185
 
     * \{
186
 
     */
187
 
    enum InsertBehavior {
188
 
      StayOnInsert = 0,
189
 
      MoveOnInsert
190
 
    };
191
 
    /**
192
 
     * Returns how this cursor behaves when text is inserted at the cursor.
193
 
     * Defaults to moving on insert.
194
 
     */
195
 
    InsertBehavior insertBehavior() const;
196
 
 
197
 
    /**
198
 
     * Change the behavior of the cursor when text is inserted at the cursor.
199
 
     *
200
 
     * If \p moveOnInsert is true, the cursor will end up at the end of the insert.
201
 
     */
202
 
    void setInsertBehavior(InsertBehavior insertBehavior);
203
 
    //END
204
 
 
205
 
    //BEGIN Notification methods
206
 
    /**
207
 
     * \}
208
 
     *
209
 
     * \name Notification
210
 
     *
211
 
     * The following functions allow for changes related to this cursor to be
212
 
     * notified to 3rd party programs.
213
 
     * \{
214
 
     */
215
 
    /**
216
 
     * Determine if a notifier already exists for this smart cursor.
217
 
     *
218
 
     * \return \e true if a notifier already exists, otherwise \e false
219
 
     */
220
 
    virtual bool hasNotifier() const = 0;
221
 
 
222
 
    /**
223
 
     * Returns the current SmartCursorNotifier.  If one does not already exist,
224
 
     * it will be created.
225
 
     *
226
 
     * Connect to the notifier to receive signals indicating change of state of this cursor.
227
 
     * The notifier is created at the time it is first requested.  If you have finished with
228
 
     * notifications for a reasonable period of time you can save memory, and potentially
229
 
     * editor logic processing time, by calling deleteNotifier().
230
 
     *
231
 
     * \return a pointer to the current SmartCursorNotifier for this SmartCursor.
232
 
     *         If one does not already exist, it will be created.
233
 
     */
234
 
    virtual SmartCursorNotifier* notifier() = 0;
235
 
 
236
 
    /**
237
 
     * Deletes the current SmartCursorNotifier.
238
 
     *
239
 
     * When finished with a notifier, call this method to save memory, and potentially
240
 
     * editor logic processing time, by having the SmartCursorNotifier deleted.
241
 
     */
242
 
    virtual void deleteNotifier() = 0;
243
 
 
244
 
    /**
245
 
     * Returns a pointer to the current SmartCursorWatcher, if one has been set.
246
 
     *
247
 
     * \return the current SmartCursorWatcher pointer if one exists, otherwise null.
248
 
     */
249
 
    virtual SmartCursorWatcher* watcher() const = 0;
250
 
 
251
 
    /**
252
 
     * Provide a SmartCursorWatcher to receive calls indicating change of state of this cursor.
253
 
     * To finish receiving notifications, call this function with \p watcher set to 0L.
254
 
     *
255
 
     * \param watcher the class which will receive notifications about changes to this cursor.
256
 
     */
257
 
    virtual void setWatcher(SmartCursorWatcher* watcher = 0L) = 0;
258
 
    //!\}
259
 
    //END
260
 
 
261
 
    /**
262
 
     * Assignment operator. Assigns the current position of the provided cursor, \p c, only;
263
 
     * does not assign watchers, notifiers, behavior, etc.
264
 
     *
265
 
     * \note The assignment will be performed even if the provided cursor belongs to
266
 
     *       another Document.
267
 
     *
268
 
     * \param cursor the position to assign.
269
 
     *
270
 
     * \return a reference to this cursor, after assignment has occurred.
271
 
     *
272
 
     * \sa setPosition()
273
 
     */
274
 
    inline SmartCursor& operator=(const SmartCursor& cursor)
275
 
      { setPosition(cursor); return *this; }
276
 
 
277
 
  protected:
278
 
    /**
279
 
     * \internal
280
 
     *
281
 
     * Constructor for subclasses to utilise.  Protected to prevent direct
282
 
     * instantiation.
283
 
     *
284
 
     * \note 3rd party developers: you do not (and should not) need to subclass
285
 
     *       the Smart* classes; instead, use the SmartInterface to create instances.
286
 
     *
287
 
     * \param position the cursor position to assign
288
 
     * \param doc the Document this cursor is associated with
289
 
     * \param insertBehavior the behavior of this cursor when on the position of an insert.
290
 
     */
291
 
    SmartCursor(const Cursor& position, Document* doc, InsertBehavior insertBehavior);
292
 
 
293
 
  private:
294
 
    /**
295
 
     * \internal
296
 
     * Copy constructor: Disable copying of this class.
297
 
     */
298
 
    SmartCursor(const SmartCursor&);
299
 
 
300
 
    /**
301
 
     * \internal
302
 
     *
303
 
     * The document that this cursor is associated with.
304
 
     */
305
 
    Document* m_doc;
306
 
 
307
 
    /**
308
 
     * \internal
309
 
     *
310
 
     * Retains the behavior of the cursor when an insert takes place at the cursor's position.
311
 
     */
312
 
    bool m_moveOnInsert : 1;
313
 
};
314
 
 
315
 
}
316
 
 
317
 
#endif
318
 
 
319
 
// kate: space-indent on; indent-width 2; replace-tabs on;