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  ~Document() override;
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  * Emitted just before the document will be saved
440  * Any modifications made to the document at this point
441  * will get stored on disk.
442  *
443  * \param document the document that was reloaded.
444  *
445  * @since 5.91
446  */
447  void aboutToSave(KTextEditor::Document *document);
448 
449  //!\}
450 
451  /**
452  * \name Text Manipulation
453  *
454  * \{
455  */
456 public:
457  /**
458  * Editing transaction support.
459  *
460  * Edit commands during this sequence will be bunched together so that
461  * they represent a single undo command in the editor, and so that
462  * repaint events do not occur in between.
463  *
464  * Your application should \e not return control to the event loop while
465  * it has an unterminated (i.e. this object is not destructed) editing
466  * sequence (result undefined) - so do all of your work in one go!
467  *
468  * Using this class typically looks as follows:
469  * @code
470  * void foo() {
471  * KTextEditor::Document::EditingTransaction transaction(document);
472  * // now call editing functions
473  * document->removeText(...)
474  * document->insertText(...)
475  * }
476  * @endcode
477  *
478  * Although usually not required, the EditingTransaction additionally
479  * allows to manually call finish() and start() in between.
480  *
481  * @see editingStarted(), editingFinished()
482  */
483  class KTEXTEDITOR_EXPORT EditingTransaction
484  {
485  public:
486  /**
487  * Constructs the object and starts an editing transaction by
488  * calling start().
489  *
490  * @param document document for the transaction
491  * @see start()
492  */
493  explicit EditingTransaction(Document *document);
494 
495  /**
496  * Destructs the object and, if needed, finishes a running editing
497  * transaction by calling finish().
498  *
499  * @see finish()
500  */
502 
503  /**
504  * By calling start(), the editing transaction can be started again.
505  * This function only is of use in combination with finish().
506  *
507  * @see finish()
508  */
509  void start();
510 
511  /**
512  * By calling finish(), the editing transaction can be finished
513  * already before destruction of this instance.
514  *
515  * @see start()
516  */
517  void finish();
518 
519  private:
520  /**
521  * no copying allowed
522  */
523  Q_DISABLE_COPY(EditingTransaction)
524 
525  /**
526  * private d-pointer
527  */
528  EditingTransactionPrivate *const d;
529  };
530 
531  /**
532  * Check whether an editing transaction is currently running.
533  *
534  * @see EditingTransaction
535  */
536  virtual bool isEditingTransactionRunning() const = 0;
537 
538  /*
539  * General access to the document's text content.
540  */
541 public:
542  /**
543  * Get the document content.
544  * \return the complete document content
545  * \see setText()
546  */
547  virtual QString text() const = 0;
548 
549  /**
550  * Get the document content within the given \p range.
551  * \param range the range of text to retrieve
552  * \param block Set this to \e true to receive text in a visual block,
553  * rather than everything inside \p range.
554  * \return the requested text part, or QString() for invalid ranges.
555  * \see setText()
556  */
557  virtual QString text(const Range &range, bool block = false) const = 0;
558 
559  /**
560  * Get the character at text position \p cursor.
561  * \param position the location of the character to retrieve
562  * \return the requested character, or QChar() for invalid cursors.
563  * \see setText()
564  */
565  virtual QChar characterAt(const Cursor &position) const = 0;
566 
567  /**
568  * Get the word at the text position \p cursor.
569  * The returned word is defined by the word boundaries to the left and
570  * right starting at \p cursor. The algorithm takes highlighting information
571  * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
572  * whereas e.g. CSS allows identifiers with dash ('-').
573  *
574  * If \p cursor is not a valid text position or if there is no word
575  * under the requested position \p cursor, an empty string is returned.
576  *
577  * \param cursor requested cursor position for the word
578  * \return the word under the cursor or an empty string if there is no word.
579  *
580  * \see wordRangeAt(), characterAt()
581  */
582  virtual QString wordAt(const KTextEditor::Cursor &cursor) const = 0;
583 
584  /**
585  * Get the text range for the word located under the text position \p cursor.
586  * The returned word is defined by the word boundaries to the left and
587  * right starting at \p cursor. The algorithm takes highlighting information
588  * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
589  * whereas e.g. CSS allows identifiers with dash ('-').
590  *
591  * If \p cursor is not a valid text position or if there is no word
592  * under the requested position \p cursor, an invalid text range is returned.
593  * If the text range is valid, it is \e always on a single line.
594  *
595  * \param cursor requested cursor position for the word
596  * \return the Range spanning the word under the cursor or an invalid range if there is no word.
597  *
598  * \see wordAt(), characterAt(), KTextEditor::Range::isValid()
599  */
600  virtual KTextEditor::Range wordRangeAt(const KTextEditor::Cursor &cursor) const = 0;
601 
602  /**
603  * Get whether \p cursor is a valid text position.
604  * A cursor position at (line, column) is valid, if
605  * - line >= 0 and line < lines() holds, and
606  * - column >= 0 and column <= lineLength(column).
607  *
608  * The text position \p cursor is also invalid if it is inside a Unicode surrogate.
609  * Therefore, use this function when iterating over the characters of a line.
610  *
611  * \param cursor cursor position to check for validity
612  * \return true, if \p cursor is a valid text position, otherwise \p false
613  *
614  * \since 5.0
615  */
616  virtual bool isValidTextPosition(const KTextEditor::Cursor &cursor) const = 0;
617 
618  /**
619  * Get the document content within the given \p range.
620  * \param range the range of text to retrieve
621  * \param block Set this to \e true to receive text in a visual block,
622  * rather than everything inside \p range.
623  * \return the requested text lines, or QStringList() for invalid ranges.
624  * no end of line termination is included.
625  * \see setText()
626  */
627  virtual QStringList textLines(const Range &range, bool block = false) const = 0;
628 
629  /**
630  * Get a single text line.
631  * \param line the wanted line
632  * \return the requested line, or "" for invalid line numbers
633  * \see text(), lineLength()
634  */
635  virtual QString line(int line) const = 0;
636 
637  /**
638  * Get the count of lines of the document.
639  * \return the current number of lines in the document
640  * \see length()
641  */
642  virtual int lines() const = 0;
643 
644  /**
645  * Check whether \p line currently contains unsaved data.
646  * If \p line contains unsaved data, \e true is returned, otherwise \e false.
647  * When the user saves the file, a modified line turns into a \e saved line.
648  * In this case isLineModified() returns \e false and in its stead isLineSaved()
649  * returns \e true.
650  * \param line line to query
651  * \see isLineSaved(), isLineTouched()
652  * \since 5.0
653  */
654  virtual bool isLineModified(int line) const = 0;
655 
656  /**
657  * Check whether \p line currently contains only saved text.
658  * Saved text in this case implies that a line was touched at some point
659  * by the user and then then changes were either undone or the user saved
660  * the file.
661  *
662  * In case \p line was touched and currently contains only saved data,
663  * \e true is returned, otherwise \e false.
664  * \param line line to query
665  * \see isLineModified(), isLineTouched()
666  * \since 5.0
667  */
668  virtual bool isLineSaved(int line) const = 0;
669 
670  /**
671  * Check whether \p line was touched since the file was opened.
672  * This equals the statement isLineModified() || isLineSaved().
673  * \param line line to query
674  * \see isLineModified(), isLineSaved()
675  * \since 5.0
676  */
677  virtual bool isLineTouched(int line) const = 0;
678 
679  /**
680  * End position of the document.
681  * \return The last column on the last line of the document
682  * \see all()
683  */
684  virtual Cursor documentEnd() const = 0;
685 
686  /**
687  * A Range which encompasses the whole document.
688  * \return A range from the start to the end of the document
689  */
690  inline Range documentRange() const
691  {
692  return Range(Cursor::start(), documentEnd());
693  }
694 
695  /**
696  * Get the count of characters in the document. A TAB character counts as
697  * only one character.
698  * \return the number of characters in the document
699  * \see lines()
700  */
701  virtual int totalCharacters() const = 0;
702 
703  /**
704  * Returns if the document is empty.
705  */
706  virtual bool isEmpty() const;
707 
708  /**
709  * Get the length of a given line in characters.
710  * \param line line to get length from
711  * \return the number of characters in the line or -1 if the line was
712  * invalid
713  * \see line()
714  */
715  virtual int lineLength(int line) const = 0;
716 
717  /**
718  * Get the end cursor position of line \p line.
719  * \param line line
720  * \see lineLength(), line()
721  */
722  inline Cursor endOfLine(int line) const
723  {
724  return Cursor(line, lineLength(line));
725  }
726 
727  /**
728  * Set the given text as new document content.
729  * \param text new content for the document
730  * \return \e true on success, otherwise \e false
731  * \see text()
732  */
733  virtual bool setText(const QString &text) = 0;
734 
735  /**
736  * Set the given text as new document content.
737  * \param text new content for the document
738  * \return \e true on success, otherwise \e false
739  * \see text()
740  */
741  virtual bool setText(const QStringList &text) = 0;
742 
743  /**
744  * Remove the whole content of the document.
745  * \return \e true on success, otherwise \e false
746  * \see removeText(), removeLine()
747  */
748  virtual bool clear() = 0;
749 
750  /**
751  * Insert \p text at \p position.
752  * \param position position to insert the text
753  * \param text text to insert
754  * \param block insert this text as a visual block of text rather than a linear sequence
755  * \return \e true on success, otherwise \e false
756  * \see setText(), removeText()
757  */
758  virtual bool insertText(const Cursor &position, const QString &text, bool block = false) = 0;
759 
760  /**
761  * Insert \p text at \p position.
762  * \param position position to insert the text
763  * \param text text to insert
764  * \param block insert this text as a visual block of text rather than a linear sequence
765  * \return \e true on success, otherwise \e false
766  * \see setText(), removeText()
767  */
768  virtual bool insertText(const Cursor &position, const QStringList &text, bool block = false) = 0;
769 
770  /**
771  * Replace text from \p range with specified \p text.
772  * \param range range of text to replace
773  * \param text text to replace with
774  * \param block replace text as a visual block of text rather than a linear sequence
775  * \return \e true on success, otherwise \e false
776  * \see setText(), removeText(), insertText()
777  */
778  virtual bool replaceText(const Range &range, const QString &text, bool block = false);
779 
780  /**
781  * Replace text from \p range with specified \p text.
782  * \param range range of text to replace
783  * \param text text to replace with
784  * \param block replace text as a visual block of text rather than a linear sequence
785  * \return \e true on success, otherwise \e false
786  * \see setText(), removeText(), insertText()
787  */
788  virtual bool replaceText(const Range &range, const QStringList &text, bool block = false);
789 
790  /**
791  * Remove the text specified in \p range.
792  * \param range range of text to remove
793  * \param block set this to true to remove a text block on the basis of columns, rather than everything inside \p range
794  * \return \e true on success, otherwise \e false
795  * \see setText(), insertText()
796  */
797  virtual bool removeText(const Range &range, bool block = false) = 0;
798 
799  /**
800  * Insert line(s) at the given line number. The newline character '\\n'
801  * is treated as line delimiter, so it is possible to insert multiple
802  * lines. To append lines at the end of the document, use
803  * \code
804  * insertLine( lines(), text )
805  * \endcode
806  * \param line line where to insert the text
807  * \param text text which should be inserted
808  * \return \e true on success, otherwise \e false
809  * \see insertText()
810  */
811  virtual bool insertLine(int line, const QString &text) = 0;
812 
813  /**
814  * Insert line(s) at the given line number. The newline character '\\n'
815  * is treated as line delimiter, so it is possible to insert multiple
816  * lines. To append lines at the end of the document, use
817  * \code
818  * insertLine( lines(), text )
819  * \endcode
820  * \param line line where to insert the text
821  * \param text text which should be inserted
822  * \return \e true on success, otherwise \e false
823  * \see insertText()
824  */
825  virtual bool insertLines(int line, const QStringList &text) = 0;
826 
827  /**
828  * Remove \p line from the document.
829  * \param line line to remove
830  * \return \e true on success, otherwise \e false
831  * \see removeText(), clear()
832  */
833  virtual bool removeLine(int line) = 0;
834 
835  /**
836  * \brief Searches the given input range for a text pattern.
837  *
838  * Searches for a text pattern within the given input range.
839  * The kind of search performed depends on the \p options
840  * used. Use this function for plaintext searches as well as
841  * regular expression searches. If no match is found the first
842  * (and only) element in the vector return is the invalid range.
843  * When searching for regular expressions, the first element holds
844  * the range of the full match, the subsequent elements hold
845  * the ranges of the capturing parentheses.
846  *
847  * \param range Input range to search in
848  * \param pattern Text pattern to search for
849  * \param options Combination of search flags
850  * \return List of ranges (length >=1)
851  *
852  * \author Sebastian Pipping <[email protected]>
853  *
854  * \since 5.11
855  */
856  QVector<KTextEditor::Range> searchText(const KTextEditor::Range &range, const QString &pattern, const SearchOptions options = Default) const;
857 
858  /*
859  * SIGNALS
860  * Following signals should be emitted by the document if the text content
861  * is changed.
862  */
863 Q_SIGNALS:
864  /**
865  * Editing transaction has started.
866  * \param document document which emitted this signal
867  */
868  void editingStarted(KTextEditor::Document *document);
869 
870  /**
871  * Editing transaction has finished.
872  *
873  * @note This signal is emitted also for editing actions that maybe do not
874  * modify the @p document contents (think of having an empty
875  * EditingTransaction). If you want to get notified only
876  * after text really changed, connect to the signal textChanged().
877  *
878  * \param document document which emitted this signal
879  * @see textChanged()
880  */
881  void editingFinished(KTextEditor::Document *document);
882 
883  /**
884  * A line got wrapped.
885  * \param document document which emitted this signal
886  * @param position position where the wrap occurred
887  */
888  void lineWrapped(KTextEditor::Document *document, const KTextEditor::Cursor &position);
889 
890  /**
891  * A line got unwrapped.
892  * \param document document which emitted this signal
893  * @param line line where the unwrap occurred
894  */
895  void lineUnwrapped(KTextEditor::Document *document, int line);
896 
897  /**
898  * Text got inserted.
899  * \param document document which emitted this signal
900  * @param position position where the insertion occurred
901  * @param text inserted text
902  */
903  void textInserted(KTextEditor::Document *document, const KTextEditor::Cursor &position, const QString &text);
904 
905  /**
906  * Text got removed.
907  * \param document document which emitted this signal
908  * @param range range where the removal occurred
909  * @param text removed text
910  */
911  void textRemoved(KTextEditor::Document *document, const KTextEditor::Range &range, const QString &text);
912 
913  /**
914  * The \p document emits this signal whenever its text changes.
915  * \param document document which emitted this signal
916  * \see text(), textLine()
917  */
918  void textChanged(KTextEditor::Document *document);
919 
920  //!\}
921 
922  /**
923  * \name Highlighting and Related Information
924  *
925  * \{
926  */
927 public:
928  /**
929  * Get the default style of the character located at @p position.
930  * If @p position is not a valid text position, the default style
931  * DefaultStyle::dsNormal is returned.
932  *
933  * @note Further information about the colors of default styles depend on
934  * the currently chosen schema. Since each View may have a different
935  * color schema, the color information can be obtained through
936  * View::defaultStyleAttribute() and View::lineAttributes().
937  *
938  * @param position text position
939  * @return default style, see enum KTextEditor::DefaultStyle
940  * @see View::defaultStyleAttribute(), View::lineAttributes()
941  */
942  virtual DefaultStyle defaultStyleAt(const KTextEditor::Cursor &position) const = 0;
943 
944  /**
945  * Return the name of the currently used mode
946  * \return name of the used mode
947  * \see modes(), setMode()
948  */
949  virtual QString mode() const = 0;
950 
951  /**
952  * Return the name of the currently used mode
953  * \return name of the used mode
954  * \see highlightingModes(), setHighlightingMode()
955  */
956  virtual QString highlightingMode() const = 0;
957 
958  /**
959  * \brief Get all available highlighting modes for the current document.
960  *
961  * Each document can be highlighted using an arbitrary number of highlighting
962  * contexts. This method will return the names for each of the used modes.
963  *
964  * Example: The "PHP (HTML)" mode includes the highlighting for PHP, HTML, CSS and JavaScript.
965  *
966  * \return Returns a list of embedded highlighting modes for the current Document.
967  *
968  * \see KTextEditor::Document::highlightingMode()
969  */
970  virtual QStringList embeddedHighlightingModes() const = 0;
971 
972  /**
973  * \brief Get the highlight mode used at a given position in the document.
974  *
975  * Retrieve the name of the applied highlight mode at a given \p position
976  * in the current document.
977  *
978  * Calling this might trigger re-highlighting up to the given line.
979  * Therefore this is not const.
980  *
981  * \see highlightingModes()
982  */
983  virtual QString highlightingModeAt(const Cursor &position) = 0;
984 
985  /**
986  * Return a list of the names of all possible modes
987  * \return list of mode names
988  * \see mode(), setMode()
989  */
990  virtual QStringList modes() const = 0;
991 
992  /**
993  * Return a list of the names of all possible modes
994  * \return list of mode names
995  * \see highlightingMode(), setHighlightingMode()
996  */
997  virtual QStringList highlightingModes() const = 0;
998 
999  /**
1000  * Set the current mode of the document by giving its name
1001  * \param name name of the mode to use for this document
1002  * \return \e true on success, otherwise \e false
1003  * \see mode(), modes(), modeChanged()
1004  */
1005  virtual bool setMode(const QString &name) = 0;
1006 
1007  /**
1008  * Set the current mode of the document by giving its name
1009  * \param name name of the mode to use for this document
1010  * \return \e true on success, otherwise \e false
1011  * \see highlightingMode(), highlightingModes(), highlightingModeChanged()
1012  */
1013  virtual bool setHighlightingMode(const QString &name) = 0;
1014 
1015  /**
1016  * Returns the name of the section for a highlight given its index in the highlight
1017  * list (as returned by highlightModes()).
1018  *
1019  * You can use this function to build a tree of the highlight names, organized in sections.
1020  *
1021  * \param index the index of the highlight in the list returned by modes()
1022  */
1023  virtual QString highlightingModeSection(int index) const = 0;
1024 
1025  /**
1026  * Returns the name of the section for a mode given its index in the highlight
1027  * list (as returned by modes()).
1028  *
1029  * You can use this function to build a tree of the mode names, organized in sections.
1030  *
1031  * \param index the index of the highlight in the list returned by modes()
1032  */
1033  virtual QString modeSection(int index) const = 0;
1034 
1035  /*
1036  * SIGNALS
1037  * Following signals should be emitted by the document if the mode
1038  * of the document changes
1039  */
1040 Q_SIGNALS:
1041  /**
1042  * Warn anyone listening that the current document's mode has
1043  * changed.
1044  *
1045  * \param document the document whose mode has changed
1046  * \see setMode()
1047  */
1048  void modeChanged(KTextEditor::Document *document);
1049 
1050  /**
1051  * Warn anyone listening that the current document's highlighting mode has
1052  * changed.
1053  *
1054  * \param document the document which's mode has changed
1055  * \see setHighlightingMode()
1056  */
1057  void highlightingModeChanged(KTextEditor::Document *document);
1058 
1059  //!\}
1060 
1061  /**
1062  * \name Printing
1063  *
1064  * \{
1065  */
1066 public:
1067  /**
1068  * Print the document. This should result in showing the print dialog.
1069  *
1070  * @returns true if document was printed
1071  */
1072  virtual bool print() = 0;
1073 
1074  /**
1075  * Shows the print preview dialog/
1076  */
1077  virtual void printPreview() = 0;
1078 
1079  //!\}
1080 
1081  /**
1082  * \name Showing Interactive Notifications
1083  *
1084  * \{
1085  */
1086 public:
1087  /**
1088  * Post @p message to the Document and its View%s.
1089  * If multiple Message%s are posted, the one with the highest priority
1090  * is shown first.
1091  *
1092  * Usually, you can simply forget the pointer, as the Message is deleted
1093  * automatically, once it is processed or the document gets closed.
1094  *
1095  * If the Document does not have a View yet, the Message is queued and
1096  * shown, once a View for the Document is created.
1097  *
1098  * @param message the message to show
1099  * @return @e true, if @p message was posted. @e false, if message == 0.
1100  */
1101  virtual bool postMessage(Message *message) = 0;
1102 
1103  //!\}
1104 
1105  /**
1106  * \name Session Configuration
1107  *
1108  * \{
1109  */
1110 public:
1111  /**
1112  * Read session settings from the given \p config.
1113  *
1114  * Known flags:
1115  * - \p SkipUrl => do not save/restore the file
1116  * - \p SkipMode => do not save/restore the mode
1117  * - \p SkipHighlighting => do not save/restore the highlighting
1118  * - \p SkipEncoding => do not save/restore the encoding
1119  *
1120  * \param config read the session settings from this KConfigGroup
1121  * \param flags additional flags
1122  * \see writeSessionConfig()
1123  */
1124  virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
1125 
1126  /**
1127  * Write session settings to the \p config.
1128  * See readSessionConfig() for more details about available \p flags.
1129  *
1130  * \param config write the session settings to this KConfigGroup
1131  * \param flags additional flags
1132  * \see readSessionConfig()
1133  */
1134  virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
1135 
1136  //!\}
1137 
1138  /**
1139  * \name Crash Recovery
1140  *
1141  * \{
1142  */
1143 public:
1144  /**
1145  * Returns whether a recovery is available for the current document.
1146  *
1147  * \see recoverData(), discardDataRecovery()
1148  */
1149  virtual bool isDataRecoveryAvailable() const = 0;
1150 
1151  /**
1152  * If recover data is available, calling recoverData() will trigger the
1153  * recovery of the data. If isDataRecoveryAvailable() returns \e false,
1154  * calling this function does nothing.
1155  *
1156  * \see isDataRecoveryAvailable(), discardDataRecovery()
1157  */
1158  virtual void recoverData() = 0;
1159 
1160  /**
1161  * If recover data is available, calling discardDataRecovery() will discard
1162  * the recover data and the recover data is lost.
1163  * If isDataRecoveryAvailable() returns \e false, calling this function
1164  * does nothing.
1165  *
1166  * \see isDataRecoveryAvailable(), recoverData()
1167  */
1168  virtual void discardDataRecovery() = 0;
1169 
1170  //!\}
1171 
1172 Q_SIGNALS:
1173  /**
1174  * This signal is emitted whenever the current document configuration is changed.
1175  *
1176  * \param document the document which's config has changed
1177  *
1178  * \since 5.79
1179  */
1180  void configChanged(KTextEditor::Document *document);
1181 
1182 private:
1183  /**
1184  * private d-pointer, pointing to the internal implementation
1185  */
1186  DocumentPrivate *const d;
1187 };
1188 
1189 }
1190 
1191 Q_DECLARE_METATYPE(KTextEditor::Document *)
1192 
1193 #endif
Q_OBJECTQ_OBJECT
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...
bool setHighlightingMode(const QString &name) override
Set the current mode of the document by giving its name.
DefaultStyle
The following lists all valid default styles that are used for the syntax highlighting files in the i...
Definition: attribute.h:28
QStringList highlightingModes() const override
Return a list of the names of all possible modes.
An object representing a section of text, from one Cursor to another.
Document * document() const
bool documentReload() override
Reloads the current document from disk if possible.
QString highlightingMode() const override
Return the name of the currently used mode.
QString mode() const override
Return the name of the currently used mode.
void writeSessionConfig(KConfigGroup &config, const QSet< QString > &flags=QSet< QString >()) override
Write session settings to the config.
@ Default
Default settings.
Definition: document.h:46
Q_SCRIPTABLE Q_NOREPLY void start()
SearchOption
Search flags for use with searchText.
Definition: document.h:45
The Cursor represents a position in a Document.
Definition: cursor.h:71
@ MaxSearchOption
Placeholder for binary compatibility.
Definition: document.h:59
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
constexpr static 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.
QByteArray checksum() const override
Returns a git compatible sha1 checksum of this document on disk.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
QStringList modes() const override
Return a list of the names of all possible modes.
@ WholeWords
Plaintext mode: Whole words only, e.g. not "amp" in "example".
Definition: document.h:57
Q_SIGNALSQ_SIGNALS
@ EscapeSequences
Plaintext mode: Processes escape sequences.
Definition: document.h:56
@ Regex
Treats the pattern as a regular expression.
Definition: document.h:49
void textRemoved(KTextEditor::Document *document, const KTextEditor::Range &range, const QString &oldText)
The document emits this signal whenever range was removed, i.e.
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:483
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...
@ Backwards
Searches in backward direction.
Definition: document.h:53
Range documentRange() const
A Range which encompasses the whole document.
Definition: document.h:690
Cursor endOfLine(int line) const
Get the end cursor position of line line.
Definition: document.h:722
KateDocumentConfig * config()
Configuration.
QString mimeType() override
Tries to detect mime-type based on file name and content of buffer.
@ CaseInsensitive
Ignores cases, e.g. "a" matches "A".
Definition: document.h:52
bool setMode(const QString &name) override
Set the current mode of the document by giving its name.
This class holds a Message to display in Views.
Definition: message.h:93
QObject * parent() const const
QString message
A KParts derived class representing a text document.
Definition: document.h:185
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 03:48:12 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.