KTextEditor

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

KDE's Doxygen guidelines are available online.