1/* This file is part of the KDE libraries
2 Copyright (C) 2001-2014 Christoph Cullmann <cullmann@kde.org>
3 Copyright (C) 2005-2014 Dominik Haumann (dhaumann@kde.org)
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 KTEXTEDITOR_DOCUMENT_H
22#define KTEXTEDITOR_DOCUMENT_H
23
24#include <ktexteditor_export.h>
25
26#include <ktexteditor/attribute.h>
27#include <ktexteditor/cursor.h>
28#include <ktexteditor/range.h>
29
30// our main baseclass of the KTextEditor::Document
31#include <KParts/ReadWritePart>
32
33// the list of views
34#include <QList>
35#include <QMetaType>
36
37class KConfigGroup;
38
39namespace KTextEditor
40{
41
42class DocumentPrivate;
43class EditingTransactionPrivate;
44class MainWindow;
45class Message;
46class View;
47
48/**
49 * \brief Search flags for use with searchText.
50 *
51 * Modifies the behavior of searchText.
52 * By default it is searched for a case-sensitive plaintext pattern,
53 * without processing of escape sequences, with "whole words" off,
54 * in forward direction, within a non-block-mode text range.
55 *
56 * \author Sebastian Pipping \<webmaster@hartwork.org\>
57 */
58enum SearchOption {
59 Default = 0, ///< Default settings
60
61 // modes
62 Regex = 1 << 1, ///< Treats the pattern as a regular expression
63
64 // options for all modes
65 CaseInsensitive = 1 << 4, ///< Ignores cases, e.g. "a" matches "A"
66 Backwards = 1 << 5, ///< Searches in backward direction
67
68 // options for plaintext
69 EscapeSequences = 1 << 10, ///< Plaintext mode: Processes escape sequences
70 WholeWords = 1 << 11, ///< Plaintext mode: Whole words only, e.g. @em not &quot;amp&quot; in &quot;example&quot;
71
72 MaxSearchOption = 1 << 31 ///< Placeholder for binary compatibility
73};
74
75Q_DECLARE_FLAGS(SearchOptions, SearchOption)
76Q_DECLARE_OPERATORS_FOR_FLAGS(SearchOptions)
77
78/**
79 * \brief A KParts derived class representing a text document.
80 *
81 * Topics:
82 * - \ref doc_intro
83 * - \ref doc_manipulation
84 * - \ref doc_views
85 * - \ref doc_readwrite
86 * - \ref doc_notifications
87 * - \ref doc_recovery
88 * - \ref doc_extensions
89 *
90 * \section doc_intro Introduction
91 *
92 * The Document class represents a pure text document providing methods to
93 * modify the content and create views. A document can have any number
94 * of views, each view representing the same content, i.e. all views are
95 * synchronized. Support for text selection is handled by a View and text
96 * format attributes by the Attribute class.
97 *
98 * To load a document call KParts::ReadOnlyPart::openUrl().
99 * To reload a document from a file call documentReload(), to save the
100 * document call documentSave() or documentSaveAs(). Whenever the modified
101 * state of the document changes the signal modifiedChanged() is emitted.
102 * Check the modified state with KParts::ReadWritePart::isModified().
103 * Further signals are documentUrlChanged(). The encoding can be specified
104 * with setEncoding(), however this will only take effect on file reload and
105 * file save.
106 *
107 * \section doc_manipulation Text Manipulation
108 *
109 * Get the whole content with text() and set new content with setText().
110 * Call insertText() or insertLine() to insert new text or removeText()
111 * and removeLine() to remove content. Whenever the document's content
112 * changed the signal textChanged() is emitted. Additional signals are
113 * textInserted() and textRemoved(). Note, that the first line in the
114 * document is line 0.
115 *
116 * A Document provides full undo/redo history.
117 * Text manipulation actions can be grouped together to one undo/redo action by
118 * using an the class EditingTransaction. You can stack multiple EditingTransaction%s.
119 * Internally, the Document has a reference counter. If this reference counter
120 * is increased the first time (by creating an instance of EditingTransaction),
121 * the signal editingStarted() is emitted. Only when the internal reference counter
122 * reaches zero again, the signal editingFinished() and optionally the signal
123 * textChanged() are emitted. Whether an editing transaction is currently active
124 * can be checked by calling isEditingTransactionRunning().
125 *
126 * @note The signal editingFinished() is always emitted when the last instance
127 * of EditingTransaction is destroyed. Contrary, the signal textChanged()
128 * is emitted only if text changed. Hence, textChanged() is more accurate
129 * with respect to changes in the Document.
130 *
131 * Every text editing transaction is also available through the signals
132 * lineWrapped(), lineUnwrapped(), textInserted() and textRemoved().
133 * However, these signals should be used with care. Please be aware of the
134 * following warning:
135 *
136 * @warning Never change the Document's contents when edit actions are active,
137 * i.e. in between of (foreign) editing transactions. In case you
138 * violate this, the currently active edit action may perform edits
139 * that lead to undefined behavior.
140 *
141 * \section doc_views Document Views
142 *
143 * A View displays the document's content. As already mentioned, a document
144 * can have any number of views, all synchronized. Get a list of all views
145 * with views(). Create a new view with createView(). Every time a new view
146 * is created the signal viewCreated() is emitted.
147 *
148 * \section doc_readwrite Read-Only Mode
149 *
150 * A Document may be in read-only mode, for instance due to missing file
151 * permissions. The read-only mode can be checked with isReadWrite(). Further,
152 * the signal readWriteChanged() is emitted whenever the state changes either
153 * to read-only mode or to read/write mode. The read-only mode can be controlled
154 * with setReadWrite().
155 *
156 * \section doc_notifications Notifications in Documents and Views
157 *
158 * A Document has the ability to show a Message to the user in a View.
159 * The Message then is shown either the specified View if Message::setView()
160 * was called, or in all View%s of the Document.
161 *
162 * To post a message just create a new Message and send it with postMessage().
163 * Further information is available in the API documentation of Message.
164 *
165 * @see Message
166 *
167 * \section doc_recovery Crash Recovery for Documents
168 *
169 * When the system or the application using the editor component crashed
170 * with unsaved changes in the Document, the View notifies the user about
171 * the lost data and asks, whether the data should be recovered.
172 *
173 * This Document gives you control over the data recovery process. Use
174 * isDataRecoveryAvailable() to check for lost data. If you do not want the
175 * editor component to handle the data recovery process automatically, you can
176 * either trigger the data recovery by calling recoverData() or discard it
177 * through discardDataRecovery().
178 *
179 * \section doc_extensions Document Extension Interfaces
180 *
181 * A simple document represents text and provides text manipulation methods.
182 * However, a real text editor should support advanced concepts like session
183 * support, textsearch support, bookmark/general mark support etc. That is why
184 * the KTextEditor library provides several additional interfaces to extend
185 * a document's capabilities via multiple inheritance.
186 *
187 * More information about interfaces for the document can be found in
188 * \ref kte_group_doc_extensions.
189 *
190 * \see KParts::ReadWritePart, KTextEditor::Editor, KTextEditor::View,
191 * KTextEditor::MarkInterface, KTextEditor::ModificationInterface,
192 * KTextEditor::MovingInterface
193 * \author Christoph Cullmann \<cullmann@kde.org\>
194 */
195class KTEXTEDITOR_EXPORT Document : public KParts::ReadWritePart
196{
197 Q_OBJECT
198
199protected:
200 /**
201 * Constructor.
202 *
203 * Create a new document with \p parent.
204 *
205 * Pass it the internal implementation to store a d-pointer.
206 *
207 * \param impl d-pointer to use
208 * \param parent parent object
209 * \see Editor::createDocument()
210 */
211 Document(DocumentPrivate *impl, QObject *parent);
212
213public:
214 /**
215 * Virtual destructor.
216 */
217 virtual ~Document();
218
219 /**
220 * \name Manage View%s of this Document
221 *
222 * \{
223 */
224public:
225 /**
226 * Create a new view attached to @p parent.
227 * @param parent parent widget
228 * @param mainWindow the main window responsible for this view, if any
229 * @return the new view
230 */
231 virtual View *createView(QWidget *parent, KTextEditor::MainWindow *mainWindow = nullptr) = 0;
232
233 /**
234 * Returns the views pre-casted to KTextEditor::View%s
235 */
236 virtual QList<View *> views() const = 0;
237
238Q_SIGNALS:
239 /**
240 * This signal is emitted whenever the \p document creates a new \p view.
241 * It should be called for every view to help applications / plugins to
242 * attach to the \p view.
243 * \attention This signal should be emitted after the view constructor is
244 * completed, e.g. in the createView() method.
245 * \param document the document for which a new view is created
246 * \param view the new view
247 * \see createView()
248 */
249 void viewCreated(KTextEditor::Document *document, KTextEditor::View *view);
250
251 //!\}
252
253 /**
254 * \name General Information about this Document
255 *
256 * \{
257 */
258public:
259 /**
260 * Get this document's name.
261 * The editor part should provide some meaningful name, like some unique
262 * "Untitled XYZ" for the document - \e without URL or basename for
263 * documents with url.
264 * \return readable document name
265 */
266 virtual QString documentName() const = 0;
267
268 /**
269 * Get this document's mimetype.
270 * \return mimetype
271 */
272 virtual QString mimeType() = 0;
273
274 /**
275 * Get the git hash of the Document's contents on disk.
276 * The returned hash equals the git hash of the file written to disk.
277 * If the document is a remote document, the checksum may not be
278 * available. In this case, QByteArray::isNull() returns \e true.
279 *
280 * git hash is defined as:
281 *
282 * sha1("blob " + filesize + "\0" + filecontent)
283 *
284 * \return the git hash of the document
285 */
286 virtual QByteArray checksum() const = 0;
287
288 /*
289 * SIGNALS
290 * following signals should be emitted by the editor document.
291 */
292Q_SIGNALS:
293 /**
294 * This signal is emitted whenever the \p document name changes.
295 * \param document document which changed its name
296 * \see documentName()
297 */
298 void documentNameChanged(KTextEditor::Document *document);
299
300 /**
301 * This signal is emitted whenever the \p document URL changes.
302 * \param document document which changed its URL
303 * \see KParts::ReadOnlyPart::url()
304 */
305 void documentUrlChanged(KTextEditor::Document *document);
306
307 /**
308 * This signal is emitted whenever the \p document's buffer changed from
309 * either state \e unmodified to \e modified or vice versa.
310 *
311 * \param document document which changed its modified state
312 * \see KParts::ReadWritePart::isModified().
313 * \see KParts::ReadWritePart::setModified()
314 */
315 void modifiedChanged(KTextEditor::Document *document);
316
317 /**
318 * This signal is emitted whenever the readWrite state of a document
319 * changes.
320 * \param document the document whose read/write property changed
321 * \see KParts::ReadWritePart::setReadWrite()
322 */
323 void readWriteChanged(KTextEditor::Document *document);
324
325 /*
326 * VERY IMPORTANT: Methods to set and query the current encoding of the
327 * document
328 */
329public:
330 /**
331 * Set the encoding for this document. This encoding will be used
332 * while loading and saving files, it will \e not affect the already
333 * existing content of the document, e.g. if the file has already been
334 * opened without the correct encoding, this will \e not fix it, you
335 * would for example need to trigger a reload for this.
336 * \param encoding new encoding for the document, the name must be
337 * accepted by QTextCodec, if an empty encoding name is given, the
338 * part should fallback to its own default encoding, e.g. the
339 * system encoding or the global user settings
340 * \return \e true on success, or \e false, if the encoding could not be set.
341 * \see encoding()
342 */
343 virtual bool setEncoding(const QString &encoding) = 0;
344
345 /**
346 * Get the current chosen encoding. The return value is an empty string,
347 * if the document uses the default encoding of the editor and no own
348 * special encoding.
349 * \return current encoding of the document
350 * \see setEncoding()
351 */
352 virtual QString encoding() const = 0;
353
354 //!\}
355
356 /**
357 * \name File Loading and Saving
358 *
359 * All this actions cause user interaction in some cases.
360 * \{
361 */
362public:
363 /**
364 * Reload the current file.
365 * The user will be prompted by the part on changes and more and can
366 * cancel this action if it can harm.
367 * \return \e true if the reload has been done, otherwise \e false. If
368 * the document has no url set, it will just return \e false.
369 */
370 virtual bool documentReload() = 0;
371
372 /**
373 * Save the current file.
374 * The user will be asked for a filename if needed and more.
375 * \return \e true on success, i.e. the save has been done, otherwise
376 * \e false
377 */
378 virtual bool documentSave() = 0;
379
380 /**
381 * Save the current file to another location.
382 * The user will be asked for a filename and more.
383 * \return \e true on success, i.e. the save has been done, otherwise
384 * \e false
385 */
386 virtual bool documentSaveAs() = 0;
387
388 /**
389 * True, eg if the file for opening could not be read
390 * This doesn't have to handle the KPart job canceled cases.
391 * @return was there some problem loading the file?
392 */
393 bool openingError() const;
394
395 /**
396 * Error message if any problem occurred on last load.
397 * @return error message what went wrong on loading
398 */
399 // TODO KF6: Not needed anymore since we show load trouble as KTextEditor::Message.
400 // Remove all code which set m_openingErrorMessage
401 QString openingErrorMessage() const;
402
403 /*
404 * SIGNALS
405 * Following signals should be emitted by the document if the text content
406 * is changed.
407 */
408Q_SIGNALS:
409 /**
410 * This signal should be emitted after a document has been saved to disk or for remote files uploaded.
411 * saveAs should be set to true, if the operation is a save as operation
412 */
413 void documentSavedOrUploaded(KTextEditor::Document *document, bool saveAs);
414
415 /**
416 * Warn anyone listening that the current document is about to close.
417 * At this point all of the information is still accessible, such as the text,
418 * cursors and ranges.
419 *
420 * Any modifications made to the document at this point will be lost.
421 *
422 * \param document the document being closed
423 */
424 void aboutToClose(KTextEditor::Document *document);
425
426 /**
427 * Warn anyone listening that the current document is about to reload.
428 * At this point all of the information is still accessible, such as the text,
429 * cursors and ranges.
430 *
431 * Any modifications made to the document at this point will be lost.
432 *
433 * \param document the document being reloaded
434 */
435 void aboutToReload(KTextEditor::Document *document);
436
437 /**
438 * Emitted after the current document was reloaded.
439 * At this point, some information might have been invalidated, like
440 * for example the editing history.
441 *
442 * \param document the document that was reloaded.
443 *
444 * @since 4.6
445 */
446 void reloaded(KTextEditor::Document *document);
447
448 //!\}
449
450 /**
451 * \name Text Manipulation
452 *
453 * \{
454 */
455public:
456 /**
457 * Editing transaction support.
458 *
459 * Edit commands during this sequence will be bunched together so that
460 * they represent a single undo command in the editor, and so that
461 * repaint events do not occur in between.
462 *
463 * Your application should \e not return control to the event loop while
464 * it has an unterminated (i.e. this object is not destructed) editing
465 * sequence (result undefined) - so do all of your work in one go!
466 *
467 * Using this class typically looks as follows:
468 * @code
469 * void foo() {
470 * KTextEditor::Document::EditingTransaction transaction(document);
471 * // now call editing functions
472 * document->removeText(...)
473 * document->insertText(...)
474 * }
475 * @endcode
476 *
477 * Although usually not required, the EditingTransaction additionally
478 * allows to manually call finish() and start() in between.
479 *
480 * @see editingStarted(), editingFinished()
481 */
482 class KTEXTEDITOR_EXPORT EditingTransaction {
483 public:
484 /**
485 * Constructs the object and starts an editing transaction by
486 * calling start().
487 *
488 * @param document document for the transaction
489 * @see start()
490 */
491 explicit EditingTransaction(Document *document);
492
493 /**
494 * Destructs the object and, if needed, finishes a running editing
495 * transaction by calling finish().
496 *
497 * @see finish()
498 */
499 ~EditingTransaction();
500
501 /**
502 * By calling start(), the editing transaction can be started again.
503 * This function only is of use in combination with finish().
504 *
505 * @see finish()
506 */
507 void start();
508
509 /**
510 * By calling finish(), the editing transaction can be finished
511 * already before destruction of this instance.
512 *
513 * @see start()
514 */
515 void finish();
516
517 private:
518 /**
519 * no copying allowed
520 */
521 Q_DISABLE_COPY(EditingTransaction)
522
523 /**
524 * private d-pointer
525 */
526 EditingTransactionPrivate *const d;
527 };
528
529 /**
530 * Check whether an editing transaction is currently running.
531 *
532 * @see EditingTransaction
533 */
534 virtual bool isEditingTransactionRunning() const = 0;
535
536 /*
537 * General access to the document's text content.
538 */
539public:
540 /**
541 * Get the document content.
542 * \return the complete document content
543 * \see setText()
544 */
545 virtual QString text() const = 0;
546
547 /**
548 * Get the document content within the given \p range.
549 * \param range the range of text to retrieve
550 * \param block Set this to \e true to receive text in a visual block,
551 * rather than everything inside \p range.
552 * \return the requested text part, or QString() for invalid ranges.
553 * \see setText()
554 */
555 virtual QString text(const Range &range, bool block = false) const = 0;
556
557 /**
558 * Get the character at text position \p cursor.
559 * \param position the location of the character to retrieve
560 * \return the requested character, or QChar() for invalid cursors.
561 * \see setText()
562 */
563 virtual QChar characterAt(const Cursor &position) const = 0;
564
565 /**
566 * Get the word at the text position \p cursor.
567 * The returned word is defined by the word boundaries to the left and
568 * right starting at \p cursor. The algorithm takes highlighting information
569 * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
570 * whereas e.g. CSS allows identifiers with dash ('-').
571 *
572 * If \p cursor is not a valid text position or if there is no word
573 * under the requested position \p cursor, an empty string is returned.
574 *
575 * \param cursor requested cursor position for the word
576 * \return the word under the cursor or an empty string if there is no word.
577 *
578 * \see wordRangeAt(), characterAt()
579 */
580 virtual QString wordAt(const KTextEditor::Cursor &cursor) const = 0;
581
582 /**
583 * Get the text range for the word located under the text position \p cursor.
584 * The returned word is defined by the word boundaries to the left and
585 * right starting at \p cursor. The algorithm takes highlighting information
586 * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
587 * whereas e.g. CSS allows identifiers with dash ('-').
588 *
589 * If \p cursor is not a valid text position or if there is no word
590 * under the requested position \p cursor, an invalid text range is returned.
591 * If the text range is valid, it is \e always on a single line.
592 *
593 * \param cursor requested cursor position for the word
594 * \return the Range spanning the word under the cursor or an invalid range if there is no word.
595 *
596 * \see wordAt(), characterAt(), KTextEditor::Range::isValid()
597 */
598 virtual KTextEditor::Range wordRangeAt(const KTextEditor::Cursor &cursor) const = 0;
599
600 /**
601 * Get whether \p cursor is a valid text position.
602 * A cursor position at (line, column) is valid, if
603 * - line >= 0 and line < lines() holds, and
604 * - column >= 0 and column <= lineLength(column).
605 *
606 * The text position \p cursor is also invalid if it is inside a Unicode surrogate.
607 * Therefore, use this function when iterating over the characters of a line.
608 *
609 * \param cursor cursor position to check for validity
610 * \return true, if \p cursor is a valid text position, otherwise \p false
611 *
612 * \since 5.0
613 */
614 virtual bool isValidTextPosition(const KTextEditor::Cursor& cursor) const = 0;
615
616 /**
617 * Get the document content within the given \p range.
618 * \param range the range of text to retrieve
619 * \param block Set this to \e true to receive text in a visual block,
620 * rather than everything inside \p range.
621 * \return the requested text lines, or QStringList() for invalid ranges.
622 * no end of line termination is included.
623 * \see setText()
624 */
625 virtual QStringList textLines(const Range &range, bool block = false) const = 0;
626
627 /**
628 * Get a single text line.
629 * \param line the wanted line
630 * \return the requested line, or "" for invalid line numbers
631 * \see text(), lineLength()
632 */
633 virtual QString line(int line) const = 0;
634
635 /**
636 * Get the count of lines of the document.
637 * \return the current number of lines in the document
638 * \see length()
639 */
640 virtual int lines() const = 0;
641
642 /**
643 * Check whether \p line currently contains unsaved data.
644 * If \p line contains unsaved data, \e true is returned, otherwise \e false.
645 * When the user saves the file, a modified line turns into a \e saved line.
646 * In this case isLineModified() returns \e false and in its stead isLineSaved()
647 * returns \e true.
648 * \param line line to query
649 * \see isLineSaved(), isLineTouched()
650 * \since 5.0
651 */
652 virtual bool isLineModified(int line) const = 0;
653
654 /**
655 * Check whether \p line currently contains only saved text.
656 * Saved text in this case implies that a line was touched at some point
657 * by the user and then then changes were either undone or the user saved
658 * the file.
659 *
660 * In case \p line was touched and currently contains only saved data,
661 * \e true is returned, otherwise \e false.
662 * \param line line to query
663 * \see isLineModified(), isLineTouched()
664 * \since 5.0
665 */
666 virtual bool isLineSaved(int line) const = 0;
667
668 /**
669 * Check whether \p line was touched since the file was opened.
670 * This equals the statement isLineModified() || isLineSaved().
671 * \param line line to query
672 * \see isLineModified(), isLineSaved()
673 * \since 5.0
674 */
675 virtual bool isLineTouched(int line) const = 0;
676
677 /**
678 * End position of the document.
679 * \return The last column on the last line of the document
680 * \see all()
681 */
682 virtual Cursor documentEnd() const = 0;
683
684 /**
685 * A Range which encompasses the whole document.
686 * \return A range from the start to the end of the document
687 */
688 inline Range documentRange() const {
689 return Range(Cursor::start(), documentEnd());
690 }
691
692 /**
693 * Get the count of characters in the document. A TAB character counts as
694 * only one character.
695 * \return the number of characters in the document
696 * \see lines()
697 */
698 virtual int totalCharacters() const = 0;
699
700 /**
701 * Returns if the document is empty.
702 */
703 virtual bool isEmpty() const;
704
705 /**
706 * Get the length of a given line in characters.
707 * \param line line to get length from
708 * \return the number of characters in the line or -1 if the line was
709 * invalid
710 * \see line()
711 */
712 virtual int lineLength(int line) const = 0;
713
714 /**
715 * Get the end cursor position of line \p line.
716 * \param line line
717 * \see lineLength(), line()
718 */
719 inline Cursor endOfLine(int line) const {
720 return Cursor(line, lineLength(line));
721 }
722
723 /**
724 * Set the given text as new document content.
725 * \param text new content for the document
726 * \return \e true on success, otherwise \e false
727 * \see text()
728 */
729 virtual bool setText(const QString &text) = 0;
730
731 /**
732 * Set the given text as new document content.
733 * \param text new content for the document
734 * \return \e true on success, otherwise \e false
735 * \see text()
736 */
737 virtual bool setText(const QStringList &text) = 0;
738
739 /**
740 * Remove the whole content of the document.
741 * \return \e true on success, otherwise \e false
742 * \see removeText(), removeLine()
743 */
744 virtual bool clear() = 0;
745
746 /**
747 * Insert \p text at \p position.
748 * \param position position to insert the text
749 * \param text text to insert
750 * \param block insert this text as a visual block of text rather than a linear sequence
751 * \return \e true on success, otherwise \e false
752 * \see setText(), removeText()
753 */
754 virtual bool insertText(const Cursor &position, const QString &text, bool block = false) = 0;
755
756 /**
757 * Insert \p text at \p position.
758 * \param position position to insert the text
759 * \param text text to insert
760 * \param block insert this text as a visual block of text rather than a linear sequence
761 * \return \e true on success, otherwise \e false
762 * \see setText(), removeText()
763 */
764 virtual bool insertText(const Cursor &position, const QStringList &text, bool block = false) = 0;
765
766 /**
767 * Replace text from \p range with specified \p text.
768 * \param range range of text to replace
769 * \param text text to replace with
770 * \param block replace text as a visual block of text rather than a linear sequence
771 * \return \e true on success, otherwise \e false
772 * \see setText(), removeText(), insertText()
773 */
774 virtual bool replaceText(const Range &range, const QString &text, bool block = false);
775
776 /**
777 * Replace text from \p range with specified \p text.
778 * \param range range of text to replace
779 * \param text text to replace with
780 * \param block replace text as a visual block of text rather than a linear sequence
781 * \return \e true on success, otherwise \e false
782 * \see setText(), removeText(), insertText()
783 */
784 virtual bool replaceText(const Range &range, const QStringList &text, bool block = false);
785
786 /**
787 * Remove the text specified in \p range.
788 * \param range range of text to remove
789 * \param block set this to true to remove a text block on the basis of columns, rather than everything inside \p range
790 * \return \e true on success, otherwise \e false
791 * \see setText(), insertText()
792 */
793 virtual bool removeText(const Range &range, bool block = false) = 0;
794
795 /**
796 * Insert line(s) at the given line number. The newline character '\\n'
797 * is treated as line delimiter, so it is possible to insert multiple
798 * lines. To append lines at the end of the document, use
799 * \code
800 * insertLine( lines(), text )
801 * \endcode
802 * \param line line where to insert the text
803 * \param text text which should be inserted
804 * \return \e true on success, otherwise \e false
805 * \see insertText()
806 */
807 virtual bool insertLine(int line, const QString &text) = 0;
808
809 /**
810 * Insert line(s) at the given line number. The newline character '\\n'
811 * is treated as line delimiter, so it is possible to insert multiple
812 * lines. To append lines at the end of the document, use
813 * \code
814 * insertLine( lines(), text )
815 * \endcode
816 * \param line line where to insert the text
817 * \param text text which should be inserted
818 * \return \e true on success, otherwise \e false
819 * \see insertText()
820 */
821 virtual bool insertLines(int line, const QStringList &text) = 0;
822
823 /**
824 * Remove \p line from the document.
825 * \param line line to remove
826 * \return \e true on success, otherwise \e false
827 * \see removeText(), clear()
828 */
829 virtual bool removeLine(int line) = 0;
830
831 /**
832 * \brief Searches the given input range for a text pattern.
833 *
834 * Searches for a text pattern within the given input range.
835 * The kind of search performed depends on the \p options
836 * used. Use this function for plaintext searches as well as
837 * regular expression searches. If no match is found the first
838 * (and only) element in the vector return is the invalid range.
839 * When searching for regular expressions, the first element holds
840 * the range of the full match, the subsequent elements hold
841 * the ranges of the capturing parentheses.
842 *
843 * \param range Input range to search in
844 * \param pattern Text pattern to search for
845 * \param options Combination of search flags
846 * \return List of ranges (length >=1)
847 *
848 * \author Sebastian Pipping \<webmaster@hartwork.org\>
849 *
850 * \since 5.11
851 */
852 QVector<KTextEditor::Range> searchText(const KTextEditor::Range &range,
853 const QString &pattern,
854 const SearchOptions options = Default) const;
855
856 /*
857 * SIGNALS
858 * Following signals should be emitted by the document if the text content
859 * is changed.
860 */
861Q_SIGNALS:
862 /**
863 * Editing transaction has started.
864 * \param document document which emitted this signal
865 */
866 void editingStarted(KTextEditor::Document *document);
867
868 /**
869 * Editing transaction has finished.
870 *
871 * @note This signal is emitted also for editing actions that maybe do not
872 * modify the @p document contents (think of having an empty
873 * EditingTransaction). If you want to get notified only
874 * after text really changed, connect to the signal textChanged().
875 *
876 * \param document document which emitted this signal
877 * @see textChanged()
878 */
879 void editingFinished(KTextEditor::Document *document);
880
881 /**
882 * A line got wrapped.
883 * \param document document which emitted this signal
884 * @param position position where the wrap occurred
885 */
886 void lineWrapped(KTextEditor::Document *document, const KTextEditor::Cursor &position);
887
888 /**
889 * A line got unwrapped.
890 * \param document document which emitted this signal
891 * @param line line where the unwrap occurred
892 */
893 void lineUnwrapped(KTextEditor::Document *document, int line);
894
895 /**
896 * Text got inserted.
897 * \param document document which emitted this signal
898 * @param position position where the insertion occurred
899 * @param text inserted text
900 */
901 void textInserted(KTextEditor::Document *document, const KTextEditor::Cursor &position, const QString &text);
902
903 /**
904 * Text got removed.
905 * \param document document which emitted this signal
906 * @param range range where the removal occurred
907 * @param text removed text
908 */
909 void textRemoved(KTextEditor::Document *document, const KTextEditor::Range &range, const QString &text);
910
911 /**
912 * The \p document emits this signal whenever its text changes.
913 * \param document document which emitted this signal
914 * \see text(), textLine()
915 */
916 void textChanged(KTextEditor::Document *document);
917
918 //!\}
919
920 /**
921 * \name Highlighting and Related Information
922 *
923 * \{
924 */
925public:
926 /**
927 * Get the default style of the character located at @p position.
928 * If @p position is not a valid text position, the default style
929 * DefaultStyle::dsNormal is returned.
930 *
931 * @note Further information about the colors of default styles depend on
932 * the currently chosen schema. Since each View may have a different
933 * color schema, the color information can be obtained through
934 * View::defaultStyleAttribute() and View::lineAttributes().
935 *
936 * @param position text position
937 * @return default style, see enum KTextEditor::DefaultStyle
938 * @see View::defaultStyleAttribute(), View::lineAttributes()
939 */
940 virtual DefaultStyle defaultStyleAt(const KTextEditor::Cursor &position) const = 0;
941
942 /**
943 * Return the name of the currently used mode
944 * \return name of the used mode
945 * \see modes(), setMode()
946 */
947 virtual QString mode() const = 0;
948
949 /**
950 * Return the name of the currently used mode
951 * \return name of the used mode
952 * \see highlightingModes(), setHighlightingMode()
953 */
954 virtual QString highlightingMode() const = 0;
955
956 /**
957 * \brief Get all available highlighting modes for the current document.
958 *
959 * Each document can be highlighted using an arbitrary number of highlighting
960 * contexts. This method will return the names for each of the used modes.
961 *
962 * Example: The "PHP (HTML)" mode includes the highlighting for PHP, HTML, CSS and JavaScript.
963 *
964 * \return Returns a list of embedded highlighting modes for the current Document.
965 *
966 * \see KTextEditor::Document::highlightingMode()
967 */
968 virtual QStringList embeddedHighlightingModes() const = 0;
969
970 /**
971 * \brief Get the highlight mode used at a given position in the document.
972 *
973 * Retrieve the name of the applied highlight mode at a given \p position
974 * in the current document.
975 *
976 * Calling this might trigger re-highlighting up to the given line.
977 * Therefore this is not const.
978 *
979 * \see highlightingModes()
980 */
981 virtual QString highlightingModeAt(const Cursor &position) = 0;
982
983 /**
984 * Return a list of the names of all possible modes
985 * \return list of mode names
986 * \see mode(), setMode()
987 */
988 virtual QStringList modes() const = 0;
989
990 /**
991 * Return a list of the names of all possible modes
992 * \return list of mode names
993 * \see highlightingMode(), setHighlightingMode()
994 */
995 virtual QStringList highlightingModes() const = 0;
996
997 /**
998 * Set the current mode of the document by giving its name
999 * \param name name of the mode to use for this document
1000 * \return \e true on success, otherwise \e false
1001 * \see mode(), modes(), modeChanged()
1002 */
1003 virtual bool setMode(const QString &name) = 0;
1004
1005 /**
1006 * Set the current mode of the document by giving its name
1007 * \param name name of the mode to use for this document
1008 * \return \e true on success, otherwise \e false
1009 * \see highlightingMode(), highlightingModes(), highlightingModeChanged()
1010 */
1011 virtual bool setHighlightingMode(const QString &name) = 0;
1012
1013 /**
1014 * Returns the name of the section for a highlight given its index in the highlight
1015 * list (as returned by highlightModes()).
1016 *
1017 * You can use this function to build a tree of the highlight names, organized in sections.
1018 *
1019 * \param index the index of the highlight in the list returned by modes()
1020 */
1021 virtual QString highlightingModeSection(int index) const = 0;
1022
1023 /**
1024 * Returns the name of the section for a mode given its index in the highlight
1025 * list (as returned by modes()).
1026 *
1027 * You can use this function to build a tree of the mode names, organized in sections.
1028 *
1029 * \param index the index of the highlight in the list returned by modes()
1030 */
1031 virtual QString modeSection(int index) const = 0;
1032
1033 /*
1034 * SIGNALS
1035 * Following signals should be emitted by the document if the mode
1036 * of the document changes
1037 */
1038Q_SIGNALS:
1039 /**
1040 * Warn anyone listening that the current document's mode has
1041 * changed.
1042 *
1043 * \param document the document whose mode has changed
1044 * \see setMode()
1045 */
1046 void modeChanged(KTextEditor::Document *document);
1047
1048 /**
1049 * Warn anyone listening that the current document's highlighting mode has
1050 * changed.
1051 *
1052 * \param document the document which's mode has changed
1053 * \see setHighlightingMode()
1054 */
1055 void highlightingModeChanged(KTextEditor::Document *document);
1056
1057 //!\}
1058
1059 /**
1060 * \name Printing
1061 *
1062 * \{
1063 */
1064public:
1065 /**
1066 * Print the document. This should result in showing the print dialog.
1067 *
1068 * @returns true if document was printed
1069 */
1070 virtual bool print() = 0;
1071
1072 /**
1073 * Shows the print preview dialog/
1074 */
1075 virtual void printPreview() = 0;
1076
1077 //!\}
1078
1079 /**
1080 * \name Showing Interactive Notifications
1081 *
1082 * \{
1083 */
1084public:
1085 /**
1086 * Post @p message to the Document and its View%s.
1087 * If multiple Message%s are posted, the one with the highest priority
1088 * is shown first.
1089 *
1090 * Usually, you can simply forget the pointer, as the Message is deleted
1091 * automatically, once it is processed or the document gets closed.
1092 *
1093 * If the Document does not have a View yet, the Message is queued and
1094 * shown, once a View for the Document is created.
1095 *
1096 * @param message the message to show
1097 * @return @e true, if @p message was posted. @e false, if message == 0.
1098 */
1099 virtual bool postMessage(Message *message) = 0;
1100
1101 //!\}
1102
1103 /**
1104 * \name Session Configuration
1105 *
1106 * \{
1107 */
1108public:
1109 /**
1110 * Read session settings from the given \p config.
1111 *
1112 * Known flags:
1113 * - \p SkipUrl => do not save/restore the file
1114 * - \p SkipMode => do not save/restore the mode
1115 * - \p SkipHighlighting => do not save/restore the highlighting
1116 * - \p SkipEncoding => do not save/restore the encoding
1117 *
1118 * \param config read the session settings from this KConfigGroup
1119 * \param flags additional flags
1120 * \see writeSessionConfig()
1121 */
1122 virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
1123
1124 /**
1125 * Write session settings to the \p config.
1126 * See readSessionConfig() for more details about available \p flags.
1127 *
1128 * \param config write the session settings to this KConfigGroup
1129 * \param flags additional flags
1130 * \see readSessionConfig()
1131 */
1132 virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
1133
1134 //!\}
1135
1136 /**
1137 * \name Crash Recovery
1138 *
1139 * \{
1140 */
1141public:
1142 /**
1143 * Returns whether a recovery is available for the current document.
1144 *
1145 * \see recoverData(), discardDataRecovery()
1146 */
1147 virtual bool isDataRecoveryAvailable() const = 0;
1148
1149 /**
1150 * If recover data is available, calling recoverData() will trigger the
1151 * recovery of the data. If isDataRecoveryAvailable() returns \e false,
1152 * calling this function does nothing.
1153 *
1154 * \see isDataRecoveryAvailable(), discardDataRecovery()
1155 */
1156 virtual void recoverData() = 0;
1157
1158 /**
1159 * If recover data is available, calling discardDataRecovery() will discard
1160 * the recover data and the recover data is lost.
1161 * If isDataRecoveryAvailable() returns \e false, calling this function
1162 * does nothing.
1163 *
1164 * \see isDataRecoveryAvailable(), recoverData()
1165 */
1166 virtual void discardDataRecovery() = 0;
1167
1168 //!\}
1169
1170private:
1171 /**
1172 * private d-pointer, pointing to the internal implementation
1173 */
1174 DocumentPrivate *const d;
1175};
1176
1177}
1178
1179Q_DECLARE_METATYPE(KTextEditor::Document *)
1180
1181#endif
1182
1183