← Back to branch summary

~ubuntu-branches/ubuntu/vivid/kate/vivid-proposed

« back to all changes in this revision

Viewing changes to ktexteditor/document.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/document.h
1
 
/* This file is part of the KDE libraries
2
 
   Copyright (C) 2001 Christoph Cullmann <cullmann@kde.org>
3
 
   Copyright (C) 2005 Dominik Haumann (dhdev@gmx.de) (documentation)
4
 
 
5
 
   This library is free software; you can redistribute it and/or
6
 
   modify it under the terms of the GNU Library General Public
7
 
   License as published by the Free Software Foundation; either
8
 
   version 2 of the License, or (at your option) any later version.
9
 
 
10
 
   This library is distributed in the hope that it will be useful,
11
 
   but WITHOUT ANY WARRANTY; without even the implied warranty of
12
 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13
 
   Library General Public License for more details.
14
 
 
15
 
   You should have received a copy of the GNU Library General Public License
16
 
   along with this library; see the file COPYING.LIB.  If not, write to
17
 
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18
 
   Boston, MA 02110-1301, USA.
19
 
*/
20
 
 
21
 
#ifndef KDELIBS_KTEXTEDITOR_DOCUMENT_H
22
 
#define KDELIBS_KTEXTEDITOR_DOCUMENT_H
23
 
 
24
 
#include <ktexteditor/ktexteditor_export.h>
25
 
// the very important KTextEditor::Cursor class
26
 
#include <ktexteditor/cursor.h>
27
 
#include <ktexteditor/range.h>
28
 
 
29
 
// our main baseclass of the KTextEditor::Document
30
 
#include <kparts/part.h>
31
 
 
32
 
// the list of views
33
 
#include <QtCore/QList>
34
 
#include <QtCore/QMetaType>
35
 
 
36
 
namespace KTextEditor
37
 
{
38
 
 
39
 
class Editor;
40
 
class View;
41
 
 
42
 
/**
43
 
 * \brief A KParts derived class representing a text document.
44
 
 *
45
 
 * Topics:
46
 
 *  - \ref doc_intro
47
 
 *  - \ref doc_manipulation
48
 
 *  - \ref doc_views
49
 
 *  - \ref doc_extensions
50
 
 *
51
 
 * \section doc_intro Introduction
52
 
 *
53
 
 * The Document class represents a pure text document providing methods to
54
 
 * modify the content and create views. A document can have any number
55
 
 * of views, each view representing the same content, i.e. all views are
56
 
 * synchronized. Support for text selection is handled by a View and text
57
 
 * format attributes by the Attribute class.
58
 
 *
59
 
 * To load a document call KParts::ReadOnlyPart::openUrl().
60
 
 * To reload a document from a file call documentReload(), to save the
61
 
 * document call documentSave() or documentSaveAs(). Whenever the modified
62
 
 * state of the document changes the signal modifiedChanged() is emitted.
63
 
 * Check the modified state with KParts::ReadWritePart::isModified().
64
 
 * Further signals are documentUrlChanged(). The encoding can be specified
65
 
 * with setEncoding(), however this will only take effect on file reload and
66
 
 * file save.
67
 
 *
68
 
 * \section doc_manipulation Text Manipulation
69
 
 *
70
 
 * Get the whole content with text() and set new content with setText().
71
 
 * Call insertText() or insertLine() to insert new text or removeText()
72
 
 * and removeLine() to remove content. Whenever the document's content
73
 
 * changed the signal textChanged() is emitted. Additional signals are
74
 
 * textInserted() and textRemoved(). Note, that the first line in the
75
 
 * document is line 0.
76
 
 *
77
 
 * If the editor part supports it, a document provides full undo/redo history.
78
 
 * Text manipulation actions can be grouped together using startEditing()
79
 
 * and endEditing(). All actions in between are grouped together to only one
80
 
 * undo/redo action. Due to internal reference counting you can call
81
 
 * startEditing() and endEditing() as often as you wish, but make sure you
82
 
 * call endEditing() exactly as often as you call startEditing(), otherwise
83
 
 * the reference counter gets confused.
84
 
 *
85
 
 * \section doc_views Document Views
86
 
 *
87
 
 * A View displays the document's content. As already mentioned, a document
88
 
 * can have any number of views, all synchronized. Get a list of all views
89
 
 * with views(). Only one of the views can be active (i.e. has focus), get
90
 
 * it by using activeView(). Create a new view with createView(). Every time
91
 
 * a new view is created the signal viewCreated() is emitted.
92
 
 *
93
 
 * \section doc_extensions Document Extension Interfaces
94
 
 *
95
 
 * A simple document represents text and provides text manipulation methods.
96
 
 * However, a real text editor should support advanced concepts like session
97
 
 * support, textsearch support, bookmark/general mark support etc. That is why
98
 
 * the KTextEditor library provides several additional interfaces to extend
99
 
 * a document's capabilities via multiple inheritance.
100
 
 *
101
 
 * More information about interfaces for the document can be found in
102
 
 * \ref kte_group_doc_extensions.
103
 
 *
104
 
 * \see KParts::ReadWritePart, KTextEditor::Editor, KTextEditor::View,
105
 
 *      KTextEditor::MarkInterface,
106
 
 *      KTextEditor::ModificationInterface, KTextEditor::SearchInterface,
107
 
 *      KTextEditor::SessionConfigInterface, KTextEditor::MovingInterface,
108
 
 *      KTextEditor::VariableInterface
109
 
 * \author Christoph Cullmann \<cullmann@kde.org\>
110
 
 */
111
 
class KTEXTEDITOR_EXPORT Document : public KParts::ReadWritePart
112
 
{
113
 
  Q_OBJECT
114
 
 
115
 
  public:
116
 
    /**
117
 
     * Constructor.
118
 
     *
119
 
     * Create a new document with \p parent.
120
 
     * \param parent parent object
121
 
     * \see Editor::createDocument()
122
 
     */
123
 
    Document ( QObject *parent = 0);
124
 
 
125
 
    /**
126
 
     * Virtual destructor.
127
 
     */
128
 
    virtual ~Document ();
129
 
 
130
 
  /*
131
 
   * Methods to create and manage the views of this document and access the
132
 
   * global editor object.
133
 
   */
134
 
  public:
135
 
    /**
136
 
     * Get the global editor object. The editor part implementation must
137
 
     * ensure that this object exists as long as any factory or document
138
 
     * object exists.
139
 
     * \return global KTextEditor::Editor object
140
 
     * \see KTextEditor::Editor
141
 
     */
142
 
    virtual Editor *editor () = 0;
143
 
 
144
 
    /**
145
 
     * Create a new view attached to @p parent.
146
 
     * @param parent parent widget
147
 
     * @return the new view
148
 
     */
149
 
    virtual View *createView ( QWidget *parent ) = 0;
150
 
 
151
 
    /**
152
 
     * Return the view which currently has user focus, if any.
153
 
     */
154
 
    virtual View* activeView() const = 0;
155
 
 
156
 
    /**
157
 
     * Returns the views pre-casted to KTextEditor::View%s
158
 
     */
159
 
    virtual const QList<View*> &views() const = 0;
160
 
 
161
 
  Q_SIGNALS:
162
 
   /**
163
 
    * This signal is emitted whenever the \p document creates a new \p view.
164
 
    * It should be called for every view to help applications / plugins to
165
 
    * attach to the \p view.
166
 
    * \attention This signal should be emitted after the view constructor is
167
 
    *            completed, e.g. in the createView() method.
168
 
    * \param document the document for which a new view is created
169
 
    * \param view the new view
170
 
    * \see createView()
171
 
    */
172
 
    void viewCreated (KTextEditor::Document *document, KTextEditor::View *view);
173
 
 
174
 
  /*
175
 
   * General information about this document and its content.
176
 
   */
177
 
  public:
178
 
    /**
179
 
     * Get this document's name.
180
 
     * The editor part should provide some meaningful name, like some unique
181
 
     * "Untitled XYZ" for the document - \e without URL or basename for
182
 
     * documents with url.
183
 
     * \return readable document name
184
 
     */
185
 
    virtual const QString &documentName () const = 0;
186
 
 
187
 
    /**
188
 
     * Get this document's mimetype.
189
 
     * \return mimetype
190
 
     */
191
 
    virtual QString mimeType() = 0;
192
 
 
193
 
  /*
194
 
   * SIGNALS
195
 
   * following signals should be emitted by the editor document.
196
 
   */
197
 
  Q_SIGNALS:
198
 
    /**
199
 
     * This signal is emitted whenever the \p document name changes.
200
 
     * \param document document which changed its name
201
 
     * \see documentName()
202
 
     */
203
 
    void documentNameChanged ( KTextEditor::Document *document );
204
 
 
205
 
    /**
206
 
     * This signal is emitted whenever the \p document URL changes.
207
 
     * \param document document which changed its URL
208
 
     * \see KParts::ReadOnlyPart::url()
209
 
     */
210
 
    void documentUrlChanged ( KTextEditor::Document *document );
211
 
 
212
 
    /**
213
 
     * This signal is emitted whenever the \p document's buffer changed from
214
 
     * either state \e unmodified to \e modified or vice versa.
215
 
     *
216
 
     * \param document document which changed its modified state
217
 
     * \see KParts::ReadWritePart::isModified().
218
 
     * \see KParts::ReadWritePart::setModified()
219
 
     */
220
 
    void modifiedChanged ( KTextEditor::Document *document );
221
 
 
222
 
    /**
223
 
     * This signal is emitted whenever the readWrite state of a document changes
224
 
     */
225
 
//warning ADD IN KDE5
226
 
//    void readWriteChanged (KTextEditor::Document *document);
227
 
 
228
 
  /*
229
 
   * VERY IMPORTANT: Methods to set and query the current encoding of the
230
 
   * document
231
 
   */
232
 
  public:
233
 
    /**
234
 
     * Set the encoding for this document. This encoding will be used
235
 
     * while loading and saving files, it will \e not affect the already
236
 
     * existing content of the document, e.g. if the file has already been
237
 
     * opened without the correct encoding, this will \e not fix it, you
238
 
     * would for example need to trigger a reload for this.
239
 
     * \param encoding new encoding for the document, the name must be
240
 
     *        accepted by QTextCodec, if an empty encoding name is given, the
241
 
     *        part should fallback to its own default encoding, e.g. the
242
 
     *        system encoding or the global user settings
243
 
     * \return \e true on success, or \e false, if the encoding could not be set.
244
 
     * \see encoding()
245
 
     */
246
 
    virtual bool setEncoding (const QString &encoding) = 0;
247
 
 
248
 
    /**
249
 
     * Get the current chosen encoding. The return value is an empty string,
250
 
     * if the document uses the default encoding of the editor and no own
251
 
     * special encoding.
252
 
     * \return current encoding of the document
253
 
     * \see setEncoding()
254
 
     */
255
 
    virtual const QString &encoding () const = 0;
256
 
 
257
 
  /*
258
 
   * General file related actions.
259
 
   * All this actions cause user interaction in some cases.
260
 
   */
261
 
  public:
262
 
    /**
263
 
     * Reload the current file.
264
 
     * The user will be prompted by the part on changes and more and can
265
 
     * cancel this action if it can harm.
266
 
     * \return \e true if the reload has been done, otherwise \e false. If
267
 
     *         the document has no url set, it will just return \e false.
268
 
     */
269
 
    virtual bool documentReload () = 0;
270
 
 
271
 
    /**
272
 
     * Save the current file.
273
 
     * The user will be asked for a filename if needed and more.
274
 
     * \return \e true on success, i.e. the save has been done, otherwise
275
 
     *         \e false
276
 
     */
277
 
    virtual bool documentSave () = 0;
278
 
 
279
 
    /**
280
 
     * Save the current file to another location.
281
 
     * The user will be asked for a filename and more.
282
 
     * \return \e true on success, i.e. the save has been done, otherwise
283
 
     *         \e false
284
 
     */
285
 
    virtual bool documentSaveAs () = 0;
286
 
 
287
 
 Q_SIGNALS:
288
 
    /**
289
 
    * This signal should be emitted after a document has been saved to disk or for remote files uploaded.
290
 
    * saveAs should be set to true, if the operation is a save as operation
291
 
    */
292
 
    void documentSavedOrUploaded(KTextEditor::Document* document,bool saveAs);
293
 
 
294
 
 /*
295
 
  * Methodes to create/end editing sequences.
296
 
  */
297
 
 public:
298
 
    /**
299
 
     * Begin an editing sequence.
300
 
     * Edit commands during this sequence will be bunched together so that
301
 
     * they represent a single undo command in the editor, and so that
302
 
     * repaint events do not occur inbetween.
303
 
     *
304
 
     * Your application should \e not return control to the event loop while
305
 
     * it has an unterminated (i.e. no matching endEditing() call) editing
306
 
     * sequence (result undefined) - so do all of your work in one go!
307
 
     *
308
 
     * This call stacks, like the endEditing() calls, this means you can
309
 
     * safely call it three times in a row for example if you call
310
 
     * endEditing() three times, too, it internaly just does counting the
311
 
     * running editing sessions.
312
 
     *
313
 
     * If the texteditor part does not support these transactions,
314
 
     * both calls just do nothing.
315
 
     *
316
 
     * \return \e true on success, otherwise \e false. Parts not supporting
317
 
     *         it should return \e false
318
 
     * \see endEditing()
319
 
     */
320
 
    virtual bool startEditing () = 0;
321
 
 
322
 
    /**
323
 
     * End an editing sequence.
324
 
     * \return \e true on success, otherwise \e false. Parts not supporting
325
 
     *         it should return \e false.
326
 
     * \see startEditing() for more details
327
 
     */
328
 
    virtual bool endEditing () = 0;
329
 
 
330
 
  /*
331
 
   * General access to the document's text content.
332
 
   */
333
 
  public:
334
 
    /**
335
 
     * Get the document content.
336
 
     * \return the complete document content
337
 
     * \see setText()
338
 
     */
339
 
    virtual QString text () const = 0;
340
 
 
341
 
    /**
342
 
     * Get the document content within the given \p range.
343
 
     * \param range the range of text to retrieve
344
 
     * \param block Set this to \e true to receive text in a visual block,
345
 
     *        rather than everything inside \p range.
346
 
     * \return the requested text part, or QString() for invalid ranges.
347
 
     * \see setText()
348
 
     */
349
 
    virtual QString text ( const Range& range, bool block = false ) const = 0;
350
 
 
351
 
    /**
352
 
     * Get the character at \p cursor.
353
 
     * \param position the location of the character to retrieve
354
 
     * \return the requested character, or QChar() for invalid cursors.
355
 
     * \see setText()
356
 
     * \todo KDE5: rename to characterAt() for consistency with wordAt() and wordRangeAt()
357
 
     */
358
 
    virtual QChar character( const Cursor& position ) const = 0;
359
 
 
360
 
    // TODO: KDE5, add wordAt(), implementation already exists in KateDocument::getWord().
361
 
    //       In the implementation, reuse wordRangeAt() to avoid code duplication.
362
 
    /*
363
 
     * Get the word at the text position \p cursor.
364
 
     * The returned word is defined by the word boundaries to the left and
365
 
     * right starting at \p cursor. The algorithm takes highlighting information
366
 
     * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
367
 
     * whereas e.g. CSS allows identifiers with dash ('-').
368
 
     *
369
 
     * If \p cursor is not a valid text position or if there is no word
370
 
     * under the requested position \p cursor, an empty string is returned.
371
 
     *
372
 
     * \param cursor requested cursor position for the word
373
 
     * \return the word under the cursor or an empty string if there is no word.
374
 
     *
375
 
     * \see wordRangeAt(), characterAt()
376
 
     */
377
 
    //QString wordAt(const KTextEditor::Cursor& cursor) const = 0;
378
 
 
379
 
    // TODO: KDE5, add wordRangeAt(), implementation for the range already exists in KateDocument::getWord()
380
 
    /*
381
 
     * Get the text range for the word located under the text position \p cursor.
382
 
     * The returned word is defined by the word boundaries to the left and
383
 
     * right starting at \p cursor. The algorithm takes highlighting information
384
 
     * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
385
 
     * whereas e.g. CSS allows identifiers with dash ('-').
386
 
     *
387
 
     * If \p cursor is not a valid text position or if there is no word
388
 
     * under the requested position \p cursor, an invalid text range is returned.
389
 
     * If the text range is valid, it is \e always on a single line.
390
 
     *
391
 
     * \param cursor requested cursor position for the word
392
 
     * \return the Range spanning the word under the cursor or an invalid range if there is no word.
393
 
     *
394
 
     * \see wordAt(), characterAt(), KTextEditor::Range::isValid()
395
 
     */
396
 
    //KTextEditor::Range wordRangeAt(const KTextEditor::Cursor& cursor) const = 0;
397
 
 
398
 
    // TODO: KDE5 add this function (Sven Brauch, Dominik Haumann, Milian Wolff)
399
 
    //       and use this in Kate Part's text selection to disallow seleting
400
 
    //       half surrogates.
401
 
    /*
402
 
     * Get whether \p cursor is a valid text position.
403
 
     * A cursor position at (line, column) is valid, if
404
 
     * - line >= 0 and line < lines() holds, and
405
 
     * - column >= 0 and column <= lineLength(column).
406
 
     *
407
 
     * The text position \p cursor is also invalid if it is inside a Unicode surrogate.
408
 
     * Therefore, use this function when iterating over the characters of a line.
409
 
     *
410
 
     * \param cursor cursor position to check for validity
411
 
     * \return true, if \p cursor is a valid text position, otherwise \p false
412
 
     *
413
 
     * \see KTextEditor::Range::isValid()
414
 
     */
415
 
    // in impl, use QChar::isHighSurrogate() + QChar::isLowSurrogate()
416
 
    //bool isValidTextPosition(const KTextEditor::Cursor& cursor) const = 0;
417
 
 
418
 
    /**
419
 
     * Get the document content within the given \p range.
420
 
     * \param range the range of text to retrieve
421
 
     * \param block Set this to \e true to receive text in a visual block,
422
 
     *        rather than everything inside \p range.
423
 
     * \return the requested text lines, or QStringList() for invalid ranges.
424
 
     *         no end of line termination is included.
425
 
     * \see setText()
426
 
     */
427
 
    virtual QStringList textLines ( const Range& range, bool block = false ) const = 0;
428
 
 
429
 
    /**
430
 
     * Get a single text line.
431
 
     * \param line the wanted line
432
 
     * \return the requested line, or "" for invalid line numbers
433
 
     * \see text(), lineLength()
434
 
     */
435
 
    virtual QString line ( int line ) const = 0;
436
 
 
437
 
    /**
438
 
     * Get the count of lines of the document.
439
 
     * \return the current number of lines in the document
440
 
     * \see length()
441
 
     */
442
 
    virtual int lines () const = 0;
443
 
 
444
 
    /**
445
 
     * End position of the document.
446
 
     * \return The last column on the last line of the document
447
 
     * \see all()
448
 
     */
449
 
    virtual Cursor documentEnd() const = 0;
450
 
 
451
 
    /**
452
 
     * A Range which encompasses the whole document.
453
 
     * \return A range from the start to the end of the document
454
 
     */
455
 
    inline Range documentRange() const { return Range(Cursor::start(), documentEnd()); }
456
 
 
457
 
    /**
458
 
     * Get the count of characters in the document. A TAB character counts as
459
 
     * only one character.
460
 
     * \return the number of characters in the document
461
 
     * \see lines()
462
 
     */
463
 
    virtual int totalCharacters() const = 0;
464
 
 
465
 
    /**
466
 
     * Returns if the document is empty.
467
 
     */
468
 
    virtual bool isEmpty() const;
469
 
 
470
 
    /**
471
 
     * Get the length of a given line in characters.
472
 
     * \param line line to get length from
473
 
     * \return the number of characters in the line or -1 if the line was
474
 
     *         invalid
475
 
     * \see line()
476
 
     */
477
 
    virtual int lineLength ( int line ) const = 0;
478
 
 
479
 
    /**
480
 
     * Get the end cursor position of line \p line.
481
 
     * \param line line
482
 
     * \see lineLength(), line()
483
 
     */
484
 
    inline Cursor endOfLine(int line) const { return Cursor(line, lineLength(line)); }
485
 
 
486
 
    /**
487
 
     * Set the given text as new document content.
488
 
     * \param text new content for the document
489
 
     * \return \e true on success, otherwise \e false
490
 
     * \see text()
491
 
     */
492
 
    virtual bool setText ( const QString &text ) = 0;
493
 
 
494
 
    /**
495
 
     * Set the given text as new document content.
496
 
     * \param text new content for the document
497
 
     * \return \e true on success, otherwise \e false
498
 
     * \see text()
499
 
     */
500
 
    virtual bool setText ( const QStringList &text ) = 0;
501
 
 
502
 
    /**
503
 
     * Remove the whole content of the document.
504
 
     * \return \e true on success, otherwise \e false
505
 
     * \see removeText(), removeLine()
506
 
     */
507
 
    virtual bool clear () = 0;
508
 
 
509
 
    /**
510
 
     * Insert \p text at \p position.
511
 
     * \param position position to insert the text
512
 
     * \param text text to insert
513
 
     * \param block insert this text as a visual block of text rather than a linear sequence
514
 
     * \return \e true on success, otherwise \e false
515
 
     * \see setText(), removeText()
516
 
     */
517
 
    virtual bool insertText ( const Cursor &position, const QString &text, bool block = false ) = 0;
518
 
 
519
 
    /**
520
 
     * Insert \p text at \p position.
521
 
     * \param position position to insert the text
522
 
     * \param text text to insert
523
 
     * \param block insert this text as a visual block of text rather than a linear sequence
524
 
     * \return \e true on success, otherwise \e false
525
 
     * \see setText(), removeText()
526
 
     */
527
 
    virtual bool insertText ( const Cursor &position, const QStringList &text, bool block = false ) = 0;
528
 
 
529
 
    /**
530
 
     * Replace text from \p range with specified \p text.
531
 
     * \param range range of text to replace
532
 
     * \param text text to replace with
533
 
     * \param block replace text as a visual block of text rather than a linear sequence
534
 
     * \return \e true on success, otherwise \e false
535
 
     * \see setText(), removeText(), insertText()
536
 
     */
537
 
    virtual bool replaceText ( const Range &range, const QString &text, bool block = false );
538
 
 
539
 
    /**
540
 
     * Replace text from \p range with specified \p text.
541
 
     * \param range range of text to replace
542
 
     * \param text text to replace with
543
 
     * \param block replace text as a visual block of text rather than a linear sequence
544
 
     * \return \e true on success, otherwise \e false
545
 
     * \see setText(), removeText(), insertText()
546
 
     */
547
 
    virtual bool replaceText ( const Range &range, const QStringList &text, bool block = false );
548
 
 
549
 
    /**
550
 
     * Remove the text specified in \p range.
551
 
     * \param range range of text to remove
552
 
     * \param block set this to true to remove a text block on the basis of columns, rather than everything inside \p range
553
 
     * \return \e true on success, otherwise \e false
554
 
     * \see setText(), insertText()
555
 
     */
556
 
    virtual bool removeText ( const Range &range, bool block = false ) = 0;
557
 
 
558
 
    /**
559
 
     * Checks whether the \p cursor specifies a valid position in a document.
560
 
     * It can optionally be overridden by an implementation.
561
 
     * \param cursor which should be checked
562
 
     * \return \e true, if the cursor is valid, otherwise \e false
563
 
     * \see DocumentCursor::isValid()
564
 
     */
565
 
    virtual bool cursorInText(const Cursor &cursor);
566
 
 
567
 
    /**
568
 
     * Insert line(s) at the given line number. The newline character '\\n'
569
 
     * is treated as line delimiter, so it is possible to insert multiple
570
 
     * lines. To append lines at the end of the document, use
571
 
     * \code
572
 
     * insertLine( lines(), text )
573
 
     * \endcode
574
 
     * \param line line where to insert the text
575
 
     * \param text text which should be inserted
576
 
     * \return \e true on success, otherwise \e false
577
 
     * \see insertText()
578
 
     */
579
 
    virtual bool insertLine ( int line, const QString &text ) = 0;
580
 
 
581
 
    /**
582
 
     * Insert line(s) at the given line number. The newline character '\\n'
583
 
     * is treated as line delimiter, so it is possible to insert multiple
584
 
     * lines. To append lines at the end of the document, use
585
 
     * \code
586
 
     * insertLine( lines(), text )
587
 
     * \endcode
588
 
     * \param line line where to insert the text
589
 
     * \param text text which should be inserted
590
 
     * \return \e true on success, otherwise \e false
591
 
     * \see insertText()
592
 
     */
593
 
    virtual bool insertLines ( int line, const QStringList &text ) = 0;
594
 
 
595
 
    /**
596
 
     * Remove \p line from the document.
597
 
     * \param line line to remove
598
 
     * \return \e true on success, otherwise \e false
599
 
     * \see removeText(), clear()
600
 
     */
601
 
    virtual bool removeLine ( int line ) = 0;
602
 
 
603
 
  /*
604
 
   * SIGNALS
605
 
   * Following signals should be emitted by the document if the text content
606
 
   * is changed.
607
 
   */
608
 
  Q_SIGNALS:
609
 
    /**
610
 
     * The \p document emits this signal whenever its text changes.
611
 
     * \param document document which emitted this signal
612
 
     * \see text(), textLine()
613
 
     */
614
 
    void textChanged(KTextEditor::Document *document);
615
 
 
616
 
    /**
617
 
     * The \p document emits this signal whenever text was inserted.  The
618
 
     * insertion occurred at range.start(), and new text now occupies up to
619
 
     * range.end().
620
 
     * \param document document which emitted this signal
621
 
     * \param range range that the newly inserted text occupies
622
 
     * \see insertText(), insertLine()
623
 
     */
624
 
    void textInserted(KTextEditor::Document *document, const KTextEditor::Range& range);
625
 
 
626
 
    /**
627
 
     * The \p document emits this signal whenever \p range was removed, i.e.
628
 
     * text was removed.
629
 
     * \param document document which emitted this signal
630
 
     * \param range range that the removed text previously occupied
631
 
     * \see removeText(), removeLine(), clear()
632
 
     */
633
 
    void textRemoved(KTextEditor::Document *document, const KTextEditor::Range& range);
634
 
 
635
 
    /**
636
 
     * The \p document emits this signal whenever \p range was removed, i.e.
637
 
     * text was removed.
638
 
     * \param document document which emitted this signal
639
 
     * \param range range that the removed text previously occupied
640
 
     * \param oldText the text that has been removed
641
 
     * \see removeText(), removeLine(), clear()
642
 
     */
643
 
    void textRemoved(KTextEditor::Document *document, const KTextEditor::Range& range, const QString& oldText);
644
 
    
645
 
    /**
646
 
     * The \p document emits this signal whenever the text in range
647
 
     * \p oldRange was removed and replaced with the text now in \e newRange,
648
 
     * e.g. the user selects text and pastes new text to replace the selection.
649
 
     * \note \p oldRange.start() is guaranteed to equal \p newRange.start().
650
 
     * \param document document which emitted this signal
651
 
     * \param oldRange range that the text previously occupied
652
 
     * \param newRange range that the changed text now occupies
653
 
     * \see insertText(), insertLine(), removeText(), removeLine(), clear()
654
 
     */
655
 
    void textChanged(KTextEditor::Document *document, const KTextEditor::Range& oldRange, const KTextEditor::Range& newRange);
656
 
 
657
 
    /**
658
 
     * The \p document emits this signal whenever the text in range
659
 
     * \p oldRange was removed and replaced with the text now in \e newRange,
660
 
     * e.g. the user selects text and pastes new text to replace the selection.
661
 
     * \note \p oldRange.start() is guaranteed to equal \p newRange.start().
662
 
     * \param document document which emitted this signal
663
 
     * \param oldRange range that the text previously occupied
664
 
     * \param oldText old text that has been replaced
665
 
     * \param newRange range that the changed text now occupies
666
 
     * \see insertText(), insertLine(), removeText(), removeLine(), clear()
667
 
     */
668
 
    void textChanged(KTextEditor::Document *document, const KTextEditor::Range& oldRange, const QString& oldText, const KTextEditor::Range& newRange);
669
 
    
670
 
    /**
671
 
     * Warn anyone listening that the current document is about to close.
672
 
     * At this point all of the information is still accessible, such as the text,
673
 
     * cursors and ranges.
674
 
     *
675
 
     * Any modifications made to the document at this point will be lost.
676
 
     *
677
 
     * \param document the document being closed
678
 
     */
679
 
    void aboutToClose(KTextEditor::Document *document);
680
 
 
681
 
    /**
682
 
     * Warn anyone listening that the current document is about to reload.
683
 
     * At this point all of the information is still accessible, such as the text,
684
 
     * cursors and ranges.
685
 
     *
686
 
     * Any modifications made to the document at this point will be lost.
687
 
     *
688
 
     * \param document the document being reloaded
689
 
     */
690
 
    void aboutToReload(KTextEditor::Document *document);
691
 
 
692
 
    /**
693
 
     * Emitted after the current document was reloaded.
694
 
     * At this point, some information might have been invalidated, like
695
 
     * for example the editing history.
696
 
     *
697
 
     * \param document the document that was reloaded.
698
 
     * 
699
 
     * @since 4.6
700
 
     */
701
 
    void reloaded(KTextEditor::Document *document);
702
 
 
703
 
    /**
704
 
     * Upon emission, the document's content may only be changed by the initiator
705
 
     * of this signal until exclusiveEditEnd() is signalled. It is, however,
706
 
     * possible to listen to changes of the content.
707
 
     *
708
 
     * Signalled e.g. on undo or redo.
709
 
     *
710
 
     * @since 4.5
711
 
     */
712
 
    void exclusiveEditStart(KTextEditor::Document *document);
713
 
 
714
 
    /**
715
 
     * In conjunction with exclusiveEditStart(), signals that the document's content
716
 
     * may be changed again without restriction.
717
 
     *
718
 
     * @since 4.5
719
 
     */
720
 
    void exclusiveEditEnd(KTextEditor::Document *document);
721
 
 
722
 
  /*
723
 
   * Access to the mode/highlighting subsystem
724
 
   */
725
 
  public:
726
 
    /**
727
 
     * Return the name of the currently used mode
728
 
     * \return name of the used mode
729
 
     * \see modes(), setMode()
730
 
     */
731
 
    virtual QString mode() const = 0;
732
 
 
733
 
    /**
734
 
     * Return the name of the currently used mode
735
 
     * \return name of the used mode
736
 
     * \see highlightingModes(), setHighlightingMode()
737
 
     */
738
 
    virtual QString highlightingMode() const = 0;
739
 
 
740
 
    /**
741
 
     * Return a list of the names of all possible modes
742
 
     * \return list of mode names
743
 
     * \see mode(), setMode()
744
 
     */
745
 
    virtual QStringList modes() const = 0;
746
 
 
747
 
    /**
748
 
     * Return a list of the names of all possible modes
749
 
     * \return list of mode names
750
 
     * \see highlightingMode(), setHighlightingMode()
751
 
     */
752
 
    virtual QStringList highlightingModes() const = 0;
753
 
 
754
 
    /**
755
 
     * Set the current mode of the document by giving its name
756
 
     * \param name name of the mode to use for this document
757
 
     * \return \e true on success, otherwise \e false
758
 
     * \see mode(), modes(), modeChanged()
759
 
     */
760
 
    virtual bool setMode(const QString &name) = 0;
761
 
 
762
 
    /**
763
 
     * Set the current mode of the document by giving its name
764
 
     * \param name name of the mode to use for this document
765
 
     * \return \e true on success, otherwise \e false
766
 
     * \see highlightingMode(), highlightingModes(), highlightingModeChanged()
767
 
     */
768
 
    virtual bool setHighlightingMode(const QString &name) = 0;
769
 
 
770
 
    /**
771
 
     * Returns the name of the section for a highlight given its index in the highlight
772
 
     * list (as returned by highlightModes()).
773
 
     *
774
 
     * You can use this function to build a tree of the highlight names, organized in sections.
775
 
     *
776
 
     * \param index the index of the highlight in the list returned by modes()
777
 
     */
778
 
    virtual QString highlightingModeSection( int index ) const = 0;
779
 
 
780
 
    /**
781
 
     * Returns the name of the section for a mode given its index in the highlight
782
 
     * list (as returned by modes()).
783
 
     *
784
 
     * You can use this function to build a tree of the mode names, organized in sections.
785
 
     *
786
 
     * \param index the index of the highlight in the list returned by modes()
787
 
     */
788
 
    virtual QString modeSection( int index ) const = 0;
789
 
 
790
 
  /*
791
 
   * SIGNALS
792
 
   * Following signals should be emitted by the document if the mode
793
 
   * of the document changes
794
 
   */
795
 
  Q_SIGNALS:
796
 
    /**
797
 
     * Warn anyone listening that the current document's mode has
798
 
     * changed.
799
 
     *
800
 
     * \param document the document whose mode has changed
801
 
     * \see setMode()
802
 
     */
803
 
    void modeChanged(KTextEditor::Document *document);
804
 
 
805
 
    /**
806
 
     * Warn anyone listening that the current document's highlighting mode has
807
 
     * changed.
808
 
     *
809
 
     * \param document the document which's mode has changed
810
 
     * \see setHighlightingMode()
811
 
     */
812
 
    void highlightingModeChanged(KTextEditor::Document *document);
813
 
 
814
 
  private:
815
 
    class DocumentPrivate* const d;
816
 
 
817
 
  public:
818
 
    /**
819
 
     * by default dialogs should be displayed.
820
 
     * In any case (dialog shown or suppressed)
821
 
     * openingErrors and openingErrorMessage should have meaningfull values
822
 
     *
823
 
     * \param suppress true/false value if dialogs should be displayed
824
 
     */
825
 
    void setSuppressOpeningErrorDialogs(bool suppress);
826
 
    bool suppressOpeningErrorDialogs() const;
827
 
    /**
828
 
     * True, eg if the file for opening could not be read
829
 
     * This doesn't have to handle the KPart job cancled cases
830
 
     */
831
 
    bool openingError() const;
832
 
    QString openingErrorMessage() const;
833
 
 
834
 
  protected:
835
 
    void setOpeningError(bool errors);
836
 
    void setOpeningErrorMessage(const QString& message);
837
 
};
838
 
 
839
 
}
840
 
 
841
 
Q_DECLARE_METATYPE(KTextEditor::Document*)
842
 
 
843
 
#endif
844
 
 
845
 
// kate: space-indent on; indent-width 2; replace-tabs on;
846