KTextEditor

document.h
1/*
2 SPDX-FileCopyrightText: 2001-2014 Christoph Cullmann <cullmann@kde.org>
3 SPDX-FileCopyrightText: 2005-2014 Dominik Haumann <dhaumann@kde.org>
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/cursor.h>
14#include <ktexteditor/movingcursor.h>
15#include <ktexteditor/movingrange.h>
16#include <ktexteditor/range.h>
17
18// our main baseclass of the KTextEditor::Document
19#include <KParts/ReadWritePart>
20#include <KSyntaxHighlighting/Theme>
21
22// the list of views
23#include <QList>
24
25class KConfigGroup;
26
27namespace KTextEditor
28{
29class DocumentPrivate;
30class EditingTransactionPrivate;
31class MainWindow;
32class Message;
33class View;
34class AnnotationModel;
35
36/**
37 * \brief Search flags for use with searchText.
38 *
39 * Modifies the behavior of searchText.
40 * By default it is searched for a case-sensitive plaintext pattern,
41 * without processing of escape sequences, with "whole words" off,
42 * in forward direction, within a non-block-mode text range.
43 *
44 * \see SearchOptions
45 * \author Sebastian Pipping <webmaster@hartwork.org>
46 */
48 Default = 0, ///< Default settings
49
50 // modes
51 Regex = 1 << 1, ///< Treats the pattern as a regular expression
52
53 // options for all modes
54 CaseInsensitive = 1 << 4, ///< Ignores cases, e.g. "a" matches "A"
55 Backwards = 1 << 5, ///< Searches in backward direction
56
57 // options for plaintext
58 EscapeSequences = 1 << 10, ///< Plaintext mode: Processes escape sequences
59 WholeWords = 1 << 11, ///< Plaintext mode: Whole words only, e.g. @em not &quot;amp&quot; in &quot;example&quot;
60
61 MaxSearchOption = 1 << 31 ///< Placeholder for binary compatibility
62};
63
64/// Stores a combination of #SearchOption values.
65Q_DECLARE_FLAGS(SearchOptions, SearchOption)
66Q_DECLARE_OPERATORS_FOR_FLAGS(SearchOptions)
67
68/**
69 * \class Mark
70 * \see doc_marktext
71 */
72class Mark
73{
74public:
75 /** The line that contains the mark. */
76 int line;
77
78 /** The mark types in the line, combined with logical OR. */
79 uint type;
80};
81
82/**
83 * \class Document document.h <KTextEditor/Document>
84 *
85 * \brief A KParts derived class representing a text document.
86 *
87 * Topics:
88 * - \ref doc_intro
89 * - \ref doc_manipulation
90 * - \ref doc_views
91 * - \ref doc_readwrite
92 * - \ref doc_notifications
93 * - \ref doc_recovery
94 * - \ref doc_movinginterface
95 * - \ref doc_config
96 * - \ref doc_modiface
97 * - \ref doc_marktext
98 * - \ref doc_annoiface
99 *
100 * \section doc_intro Introduction
101 *
102 * The Document class represents a pure text document providing methods to
103 * modify the content and create views. A document can have any number
104 * of views, each view representing the same content, i.e. all views are
105 * synchronized. Support for text selection is handled by a View and text
106 * format attributes by the Attribute class.
107 *
108 * To load a document call KParts::ReadOnlyPart::openUrl().
109 * To reload a document from a file call documentReload(), to save the
110 * document call documentSave() or documentSaveAs(). Whenever the modified
111 * state of the document changes the signal modifiedChanged() is emitted.
112 * Check the modified state with KParts::ReadWritePart::isModified().
113 * Further signals are documentUrlChanged(). The encoding can be specified
114 * with setEncoding(), however this will only take effect on file reload and
115 * file save.
116 *
117 * \section doc_manipulation Text Manipulation
118 *
119 * Get the whole content with text() and set new content with setText().
120 * Call insertText() or insertLine() to insert new text or removeText()
121 * and removeLine() to remove content. Whenever the document's content
122 * changed the signal textChanged() is emitted. Additional signals are
123 * textInserted() and textRemoved(). Note, that the first line in the
124 * document is line 0.
125 *
126 * A Document provides full undo/redo history.
127 * Text manipulation actions can be grouped together to one undo/redo action by
128 * using an the class EditingTransaction. You can stack multiple EditingTransaction%s.
129 * Internally, the Document has a reference counter. If this reference counter
130 * is increased the first time (by creating an instance of EditingTransaction),
131 * the signal editingStarted() is emitted. Only when the internal reference counter
132 * reaches zero again, the signal editingFinished() and optionally the signal
133 * textChanged() are emitted. Whether an editing transaction is currently active
134 * can be checked by calling isEditingTransactionRunning().
135 *
136 * @note The signal editingFinished() is always emitted when the last instance
137 * of EditingTransaction is destroyed. Contrary, the signal textChanged()
138 * is emitted only if text changed. Hence, textChanged() is more accurate
139 * with respect to changes in the Document.
140 *
141 * Every text editing transaction is also available through the signals
142 * lineWrapped(), lineUnwrapped(), textInserted() and textRemoved().
143 * However, these signals should be used with care. Please be aware of the
144 * following warning:
145 *
146 * @warning Never change the Document's contents when edit actions are active,
147 * i.e. in between of (foreign) editing transactions. In case you
148 * violate this, the currently active edit action may perform edits
149 * that lead to undefined behavior.
150 *
151 * \section doc_views Document Views
152 *
153 * A View displays the document's content. As already mentioned, a document
154 * can have any number of views, all synchronized. Get a list of all views
155 * with views(). Create a new view with createView(). Every time a new view
156 * is created the signal viewCreated() is emitted.
157 *
158 * \section doc_readwrite Read-Only Mode
159 *
160 * A Document may be in read-only mode, for instance due to missing file
161 * permissions. The read-only mode can be checked with isReadWrite(). Further,
162 * the signal readWriteChanged() is emitted whenever the state changes either
163 * to read-only mode or to read/write mode. The read-only mode can be controlled
164 * with setReadWrite().
165 *
166 * \section doc_notifications Notifications in Documents and Views
167 *
168 * A Document has the ability to show a Message to the user in a View.
169 * The Message then is shown either the specified View if Message::setView()
170 * was called, or in all View%s of the Document.
171 *
172 * To post a message just create a new Message and send it with postMessage().
173 * Further information is available in the API documentation of Message.
174 *
175 * @see Message
176 *
177 * \section doc_recovery Crash Recovery for Documents
178 *
179 * When the system or the application using the editor component crashed
180 * with unsaved changes in the Document, the View notifies the user about
181 * the lost data and asks, whether the data should be recovered.
182 *
183 * This Document gives you control over the data recovery process. Use
184 * isDataRecoveryAvailable() to check for lost data. If you do not want the
185 * editor component to handle the data recovery process automatically, you can
186 * either trigger the data recovery by calling recoverData() or discard it
187 * through discardDataRecovery().
188 *
189 * \section doc_movinginterface Document Moving Interface
190 *
191 * Document Moving Interface allows you to create MovingRange and MovingCursor. A
192 * Moving Range or Cursor is a special type of range/cursor because it automatically
193 * moves on text insertion or removal. Additionally, one can use the moving ranges to
194 * change the color of a particular word or give it a different attribute such as bold.
195 * Use newMovingCursor() to create a new moving cursor and newMovingRange() to create
196 * a new moving range.
197 *
198 * Upon destruction or reload, a document will invalidate all its moving ranges. You can
199 * connect to aboutToInvalidateMovingInterfaceContent() signals to know when that is going
200 * to happen and delete the cached ranges accordingly.
201 *
202 * \section doc_config Document Config
203 * Config provides methods to access and modify the low level config information for a given
204 * Document.
205 * KTextEditor::Document has support for the following config keys:
206 * - backup-on-save-local [bool], enable/disable backup when saving local files
207 * - backup-on-save-remote [bool], enable/disable backup when saving remote files
208 * - backup-on-save-suffix [string], set the suffix for file backups, e.g. "~"
209 * - backup-on-save-prefix [string], set the prefix for file backups, e.g. "."
210 * - replace-tabs [bool], whether to replace tabs
211 * - indent-pasted-text [bool], whether to indent pasted text
212 * - tab-width [int], read/set the width for tabs
213 * - indent-width [int], read/set the indentation width
214 * - on-the-fly-spellcheck [bool], enable/disable on the fly spellcheck
215 *
216 * \section doc_modiface External modification extension interface for the Document.
217 *
218 * The class ModificationInterface provides methods to handle modifications
219 * of all opened files caused by external programs. Whenever the
220 * modified-on-disk state changes the signal modifiedOnDisk() is emitted
221 * along with a ModifiedOnDiskReason. Set the state by calling
222 * setModifiedOnDisk(). Whether the Editor should show warning dialogs to
223 * inform the user about external modified files can be controlled with
224 * setModifiedOnDiskWarning(). The slot modifiedOnDisk() is called to ask
225 * the user what to do whenever a file was modified.
226 *
227 * \section doc_marktext
228 *
229 * The Mark Interface provides methods to enable and disable marks in a
230 * Document, a marked line can be visualized for example with a shaded
231 * background color and/or a pixmap in the iconborder of the Document's View.
232 * There are a number of predefined mark types, specified in
233 * reservedMarkersCount(). Additionally it is possible to add custom marks
234 * and set custom pixmaps.
235 *
236 * Get all marks in the document by calling marks(). Use clearMarks() to
237 * remove all marks in the entire document. A single mark can be retrieved
238 * with mark(). To remove all marks from a line call clearMark(). To add
239 * and remove marks from a given line use addMark() and removeMark(). It is
240 * also possible to replace all marks with setMark(), i.e. setMark() is the
241 * same as a call of clearMark() followed by addMark(). The signals
242 * marksChanged() and markChanged() are emitted whenever a line's marks
243 * changed.
244 *
245 * \attention A mark type is represented as an \e uint. An \e uint can have
246 * several mark types combined (see above: logical OR). That means for
247 * all functions/signals with an \e uint parameter, e.g. setMark(),
248 * removeMark(), etc, the \e uint may contain \e multiple marks, i.e.
249 * you can add and remove multiple marks \e simultaneously.
250 *
251 * All marks that should be editable by the user can be specified with a mark
252 * mask via setEditableMarks(). To set a description and pixmap of a mark type
253 * call setMarkDescription() and setMarkPixmap().
254 *
255 * \section doc_annoiface Annotation Interface
256 *
257 * The Annotation Interface is designed to provide line annotation information
258 * for a document. This interface provides means to associate a document with a
259 * annotation model, which provides some annotation information for each line
260 * in the document.
261 *
262 * Setting a model for a Document makes the model data available for all views.
263 * If you only want to provide annotations in exactly one view, you can use
264 * the AnnotationViewInterface directly. See the AnnotationViewInterface for
265 * further details. To summarize, the two use cases are
266 * - (1) show annotations in all views. This means you set an AnnotationModel
267 * with this interface, and then call setAnnotationBorderVisible() for
268 * each view.
269 * - (2) show annotations only in one view. This means to \e not use this
270 * interface. Instead, use the AnnotationViewInterface, which inherits
271 * this interface. This means you set a model for the specific View.
272 *
273 * If you set a model to the Document \e and the View, the View's model has
274 * higher priority.
275 *
276 * More information about interfaces for the document can be found in
277 * \ref kte_group_doc_extensions.
278 *
279 * \see KParts::ReadWritePart, KTextEditor::Editor, KTextEditor::View,
280 * KTextEditor::MarkInterface
281 * \author Christoph Cullmann <cullmann@kde.org>
282 */
283class KTEXTEDITOR_EXPORT Document : public KParts::ReadWritePart
284{
285 Q_OBJECT
286
287protected:
288 /**
289 * Constructor.
290 *
291 * Create a new document with \p parent.
292 *
293 * Pass it the internal implementation to store a d-pointer.
294 *
295 * \param impl d-pointer to use
296 * \param parent parent object
297 * \see Editor::createDocument()
298 */
299 Document(DocumentPrivate *impl, const KPluginMetaData &data, QObject *parent);
300
301public:
302 /**
303 * Virtual destructor.
304 */
305 ~Document() override;
306
307 /**
308 * \name Manage View%s of this Document
309 *
310 * \{
311 */
312public:
313 /**
314 * Create a new view attached to @p parent.
315 * @param parent parent widget
316 * @param mainWindow the main window responsible for this view, if any
317 * @return the new view
318 */
319 virtual View *createView(QWidget *parent, KTextEditor::MainWindow *mainWindow = nullptr) = 0;
320
321 /**
322 * Returns the views pre-casted to KTextEditor::View%s
323 */
324 virtual QList<View *> views() const = 0;
325
326Q_SIGNALS:
327 /**
328 * This signal is emitted whenever the \p document creates a new \p view.
329 * It should be called for every view to help applications / plugins to
330 * attach to the \p view.
331 * \attention This signal should be emitted after the view constructor is
332 * completed, e.g. in the createView() method.
333 * \param document the document for which a new view is created
334 * \param view the new view
335 * \see createView()
336 */
338
339 //!\}
340
341 /**
342 * \name General Information about this Document
343 *
344 * \{
345 */
346public:
347 /**
348 * Get this document's name.
349 * The editor part should provide some meaningful name, like some unique
350 * "Untitled XYZ" for the document - \e without URL or basename for
351 * documents with url.
352 * \return readable document name
353 */
354 virtual QString documentName() const = 0;
355
356 /**
357 * Get this document's mimetype.
358 * \return mimetype
359 */
360 virtual QString mimeType() = 0;
361
362 /**
363 * Get the git hash of the Document's contents on disk.
364 * The returned hash equals the git hash of the file written to disk.
365 * If the document is a remote document, the checksum may not be
366 * available. In this case, QByteArray::isNull() returns \e true.
367 *
368 * git hash is defined as:
369 *
370 * sha1("blob " + filesize + "\0" + filecontent)
371 *
372 * \return the git hash of the document
373 */
374 virtual QByteArray checksum() const = 0;
375
376 /*
377 * SIGNALS
378 * following signals should be emitted by the editor document.
379 */
380Q_SIGNALS:
381 /**
382 * This signal is emitted whenever the \p document name changes.
383 * \param document document which changed its name
384 * \see documentName()
385 */
387
388 /**
389 * This signal is emitted whenever the \p document URL changes.
390 * \param document document which changed its URL
391 * \see KParts::ReadOnlyPart::url()
392 */
394
395 /**
396 * This signal is emitted whenever the \p document's buffer changed from
397 * either state \e unmodified to \e modified or vice versa.
398 *
399 * \param document document which changed its modified state
400 * \see KParts::ReadWritePart::isModified().
401 * \see KParts::ReadWritePart::setModified()
402 */
404
405 /**
406 * This signal is emitted whenever the readWrite state of a document
407 * changes.
408 * \param document the document whose read/write property changed
409 * \see KParts::ReadWritePart::setReadWrite()
410 */
412
413 /*
414 * VERY IMPORTANT: Methods to set and query the current encoding of the
415 * document
416 */
417public:
418 /**
419 * Set the encoding for this document. This encoding will be used
420 * while loading and saving files, it will \e not affect the already
421 * existing content of the document, e.g. if the file has already been
422 * opened without the correct encoding, this will \e not fix it, you
423 * would for example need to trigger a reload for this.
424 * \param encoding new encoding for the document, the name must be
425 * accepted by QStringDecoder/QStringEncoder, if an empty encoding name is given, the
426 * part should fallback to its own default encoding, e.g. the
427 * system encoding or the global user settings
428 * \return \e true on success, or \e false, if the encoding could not be set.
429 * \see encoding()
430 */
431 virtual bool setEncoding(const QString &encoding) = 0;
432
433 /**
434 * Get the current chosen encoding. The return value is an empty string,
435 * if the document uses the default encoding of the editor and no own
436 * special encoding.
437 * \return current encoding of the document
438 * \see setEncoding()
439 */
440 virtual QString encoding() const = 0;
441
442 //!\}
443
444 /**
445 * \name File Loading and Saving
446 *
447 * All this actions cause user interaction in some cases.
448 * \{
449 */
450public:
451 /**
452 * Reload the current file.
453 * The user will be prompted by the part on changes and more and can
454 * cancel this action if it can harm.
455 * \return \e true if the reload has been done, otherwise \e false. If
456 * the document has no url set, it will just return \e false.
457 */
458 virtual bool documentReload() = 0;
459
460 /**
461 * Save the current file.
462 * The user will be asked for a filename if needed and more.
463 * \return \e true on success, i.e. the save has been done, otherwise
464 * \e false
465 */
466 virtual bool documentSave() = 0;
467
468 /**
469 * Save the current file to another location.
470 * The user will be asked for a filename and more.
471 * \return \e true on success, i.e. the save has been done, otherwise
472 * \e false
473 */
474 virtual bool documentSaveAs() = 0;
475
476 /**
477 * True, eg if the file for opening could not be read
478 * This doesn't have to handle the KPart job canceled cases.
479 * @return was there some problem loading the file?
480 */
481 bool openingError() const;
482
483 /*
484 * SIGNALS
485 * Following signals should be emitted by the document if the text content
486 * is changed.
487 */
488Q_SIGNALS:
489 /**
490 * This signal should be emitted after a document has been saved to disk or for remote files uploaded.
491 * saveAs should be set to true, if the operation is a save as operation
492 */
493 void documentSavedOrUploaded(KTextEditor::Document *document, bool saveAs);
494
495 /**
496 * Warn anyone listening that the current document is about to close.
497 * At this point all of the information is still accessible, such as the text,
498 * cursors and ranges.
499 *
500 * Any modifications made to the document at this point will be lost.
501 *
502 * \param document the document being closed
503 */
505
506 /**
507 * Warn anyone listening that the current document is about to reload.
508 * At this point all of the information is still accessible, such as the text,
509 * cursors and ranges.
510 *
511 * Any modifications made to the document at this point will be lost.
512 *
513 * \param document the document being reloaded
514 */
516
517 /**
518 * Emitted after the current document was reloaded.
519 * At this point, some information might have been invalidated, like
520 * for example the editing history.
521 *
522 * \param document the document that was reloaded.
523 *
524 * @since 4.6
525 */
527
528 /**
529 * Emitted just before the document will be saved
530 * Any modifications made to the document at this point
531 * will get stored on disk.
532 *
533 * \param document the document that was reloaded.
534 *
535 * @since 5.91
536 */
538
539 //!\}
540
541 /**
542 * \name Text Manipulation
543 *
544 * \{
545 */
546public:
547 /**
548 * Editing transaction support.
549 *
550 * Edit commands during this sequence will be bunched together so that
551 * they represent a single undo command in the editor, and so that
552 * repaint events do not occur in between.
553 *
554 * Your application should \e not return control to the event loop while
555 * it has an unterminated (i.e. this object is not destructed) editing
556 * sequence (result undefined) - so do all of your work in one go!
557 *
558 * Using this class typically looks as follows:
559 * @code
560 * void foo() {
561 * KTextEditor::Document::EditingTransaction transaction(document);
562 * // now call editing functions
563 * document->removeText(...)
564 * document->insertText(...)
565 * }
566 * @endcode
567 *
568 * Although usually not required, the EditingTransaction additionally
569 * allows to manually call finish() and start() in between.
570 *
571 * @see editingStarted(), editingFinished()
572 */
573 class KTEXTEDITOR_EXPORT EditingTransaction
574 {
575 public:
576 /**
577 * Constructs the object and starts an editing transaction by
578 * calling start().
579 *
580 * @param document document for the transaction
581 * @see start()
582 */
583 explicit EditingTransaction(Document *document);
584
585 /**
586 * No copy constructor, don't allow this to be copied.
587 */
589
590 /**
591 * No assignment operator, no copying around editing transations.
592 */
594
595 /**
596 * Destructs the object and, if needed, finishes a running editing
597 * transaction by calling finish().
598 *
599 * @see finish()
600 */
602
603 /**
604 * By calling start(), the editing transaction can be started again.
605 * This function only is of use in combination with finish().
606 *
607 * @see finish()
608 */
609 void start();
610
611 /**
612 * By calling finish(), the editing transaction can be finished
613 * already before destruction of this instance.
614 *
615 * @see start()
616 */
617 void finish();
618
619 private:
620 /**
621 * private d-pointer
622 */
623 EditingTransactionPrivate *const d;
624 };
625
626 /**
627 * Check whether an editing transaction is currently running.
628 *
629 * @see EditingTransaction
630 */
631 virtual bool isEditingTransactionRunning() const = 0;
632
633 /*
634 * General access to the document's text content.
635 */
636public:
637 /**
638 * Get the document content.
639 * \return the complete document content
640 * \see setText()
641 */
642 virtual QString text() const = 0;
643
644 /**
645 * Get the document content within the given \p range.
646 * \param range the range of text to retrieve
647 * \param block Set this to \e true to receive text in a visual block,
648 * rather than everything inside \p range.
649 * \return the requested text part, or QString() for invalid ranges.
650 * \see setText()
651 */
652 virtual QString text(Range range, bool block = false) const = 0;
653
654 /**
655 * Get the character at text position \p cursor.
656 * \param position the location of the character to retrieve
657 * \return the requested character, or QChar() for invalid cursors.
658 * \see setText()
659 */
660 virtual QChar characterAt(KTextEditor::Cursor position) const = 0;
661
662 /**
663 * Get the word at the text position \p cursor.
664 * The returned word is defined by the word boundaries to the left and
665 * right starting at \p cursor. The algorithm takes highlighting information
666 * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
667 * whereas e.g. CSS allows identifiers with dash ('-').
668 *
669 * If \p cursor is not a valid text position or if there is no word
670 * under the requested position \p cursor, an empty string is returned.
671 *
672 * \param cursor requested cursor position for the word
673 * \return the word under the cursor or an empty string if there is no word.
674 *
675 * \see wordRangeAt(), characterAt()
676 */
677 virtual QString wordAt(KTextEditor::Cursor cursor) const = 0;
678
679 /**
680 * Get the text range for the word located under the text position \p cursor.
681 * The returned word is defined by the word boundaries to the left and
682 * right starting at \p cursor. The algorithm takes highlighting information
683 * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
684 * whereas e.g. CSS allows identifiers with dash ('-').
685 *
686 * If \p cursor is not a valid text position or if there is no word
687 * under the requested position \p cursor, an invalid text range is returned.
688 * If the text range is valid, it is \e always on a single line.
689 *
690 * \param cursor requested cursor position for the word
691 * \return the Range spanning the word under the cursor or an invalid range if there is no word.
692 *
693 * \see wordAt(), characterAt(), KTextEditor::Range::isValid()
694 */
696
697 /**
698 * Get whether \p cursor is a valid text position.
699 * A cursor position at (line, column) is valid, if
700 * - line >= 0 and line < lines() holds, and
701 * - column >= 0 and column <= lineLength(column).
702 *
703 * The text position \p cursor is also invalid if it is inside a Unicode surrogate.
704 * Therefore, use this function when iterating over the characters of a line.
705 *
706 * \param cursor cursor position to check for validity
707 * \return true, if \p cursor is a valid text position, otherwise \p false
708 *
709 * \since 5.0
710 */
711 virtual bool isValidTextPosition(KTextEditor::Cursor cursor) const = 0;
712
713 /**
714 * Get the document content within the given \p range.
715 * \param range the range of text to retrieve
716 * \param block Set this to \e true to receive text in a visual block,
717 * rather than everything inside \p range.
718 * \return the requested text lines, or QStringList() for invalid ranges.
719 * no end of line termination is included.
720 * \see setText()
721 */
722 virtual QStringList textLines(Range range, bool block = false) const = 0;
723
724 /**
725 * Get a single text line.
726 * \param line the wanted line
727 * \return the requested line, or "" for invalid line numbers
728 * \see text(), lineLength()
729 */
730 virtual QString line(int line) const = 0;
731
732 /**
733 * Get the count of lines of the document.
734 * \return the current number of lines in the document
735 * \see length()
736 */
737 virtual int lines() const = 0;
738
739 /**
740 * Check whether \p line currently contains unsaved data.
741 * If \p line contains unsaved data, \e true is returned, otherwise \e false.
742 * When the user saves the file, a modified line turns into a \e saved line.
743 * In this case isLineModified() returns \e false and in its stead isLineSaved()
744 * returns \e true.
745 * \param line line to query
746 * \see isLineSaved(), isLineTouched()
747 * \since 5.0
748 */
749 virtual bool isLineModified(int line) const = 0;
750
751 /**
752 * Check whether \p line currently contains only saved text.
753 * Saved text in this case implies that a line was touched at some point
754 * by the user and then then changes were either undone or the user saved
755 * the file.
756 *
757 * In case \p line was touched and currently contains only saved data,
758 * \e true is returned, otherwise \e false.
759 * \param line line to query
760 * \see isLineModified(), isLineTouched()
761 * \since 5.0
762 */
763 virtual bool isLineSaved(int line) const = 0;
764
765 /**
766 * Check whether \p line was touched since the file was opened.
767 * This equals the statement isLineModified() || isLineSaved().
768 * \param line line to query
769 * \see isLineModified(), isLineSaved()
770 * \since 5.0
771 */
772 virtual bool isLineTouched(int line) const = 0;
773
774 /**
775 * End position of the document.
776 * \return The last column on the last line of the document
777 * \see all()
778 */
779 virtual Cursor documentEnd() const = 0;
780
781 /**
782 * A Range which encompasses the whole document.
783 * \return A range from the start to the end of the document
784 */
785 inline Range documentRange() const
786 {
787 return Range(Cursor::start(), documentEnd());
788 }
789
790 /**
791 * Get the count of characters in the document. A TAB character counts as
792 * only one character.
793 * \return the number of characters in the document
794 * \see lines()
795 */
796 virtual qsizetype totalCharacters() const = 0;
797
798 /**
799 * Returns if the document is empty.
800 */
801 virtual bool isEmpty() const;
802
803 /**
804 * Get the length of a given line in characters.
805 * \param line line to get length from
806 * \return the number of characters in the line or -1 if the line was
807 * invalid
808 * \see line()
809 */
810 virtual int lineLength(int line) const = 0;
811
812 /**
813 * Get the end cursor position of line \p line.
814 * \param line line
815 * \see lineLength(), line()
816 */
817 inline Cursor endOfLine(int line) const
818 {
819 return Cursor(line, lineLength(line));
820 }
821
822 /**
823 * Set the given text as new document content.
824 * \param text new content for the document
825 * \return \e true on success, otherwise \e false
826 * \see text()
827 */
828 virtual bool setText(const QString &text) = 0;
829
830 /**
831 * Set the given text as new document content.
832 * \param text new content for the document
833 * \return \e true on success, otherwise \e false
834 * \see text()
835 */
836 virtual bool setText(const QStringList &text) = 0;
837
838 /**
839 * Remove the whole content of the document.
840 * \return \e true on success, otherwise \e false
841 * \see removeText(), removeLine()
842 */
843 virtual bool clear() = 0;
844
845 /**
846 * Insert \p text at \p position.
847 * \param position position to insert the text
848 * \param text text to insert
849 * \param block insert this text as a visual block of text rather than a linear sequence
850 * \return \e true on success, otherwise \e false
851 * \see setText(), removeText()
852 */
853 virtual bool insertText(KTextEditor::Cursor position, const QString &text, bool block = false) = 0;
854
855 /**
856 * Insert \p text at \p position.
857 * \param position position to insert the text
858 * \param text text to insert
859 * \param block insert this text as a visual block of text rather than a linear sequence
860 * \return \e true on success, otherwise \e false
861 * \see setText(), removeText()
862 */
863 virtual bool insertText(KTextEditor::Cursor position, const QStringList &text, bool block = false) = 0;
864
865 /**
866 * Replace text from \p range with specified \p text.
867 * \param range range of text to replace
868 * \param text text to replace with
869 * \param block replace text as a visual block of text rather than a linear sequence
870 * \return \e true on success, otherwise \e false
871 * \see setText(), removeText(), insertText()
872 */
873 virtual bool replaceText(Range range, const QString &text, bool block = false);
874
875 /**
876 * Replace text from \p range with specified \p text.
877 * \param range range of text to replace
878 * \param text text to replace with
879 * \param block replace text as a visual block of text rather than a linear sequence
880 * \return \e true on success, otherwise \e false
881 * \see setText(), removeText(), insertText()
882 */
883 virtual bool replaceText(Range range, const QStringList &text, bool block = false);
884
885 /**
886 * Remove the text specified in \p range.
887 * \param range range of text to remove
888 * \param block set this to true to remove a text block on the basis of columns, rather than everything inside \p range
889 * \return \e true on success, otherwise \e false
890 * \see setText(), insertText()
891 */
892 virtual bool removeText(Range range, bool block = false) = 0;
893
894 /**
895 * Insert line(s) at the given line number. The newline character '\\n'
896 * is treated as line delimiter, so it is possible to insert multiple
897 * lines. To append lines at the end of the document, use
898 * \code
899 * insertLine( lines(), text )
900 * \endcode
901 * \param line line where to insert the text
902 * \param text text which should be inserted
903 * \return \e true on success, otherwise \e false
904 * \see insertText()
905 */
906 virtual bool insertLine(int line, const QString &text) = 0;
907
908 /**
909 * Insert line(s) at the given line number. The newline character '\\n'
910 * is treated as line delimiter, so it is possible to insert multiple
911 * lines. To append lines at the end of the document, use
912 * \code
913 * insertLine( lines(), text )
914 * \endcode
915 * \param line line where to insert the text
916 * \param text text which should be inserted
917 * \return \e true on success, otherwise \e false
918 * \see insertText()
919 */
920 virtual bool insertLines(int line, const QStringList &text) = 0;
921
922 /**
923 * Remove \p line from the document.
924 * \param line line to remove
925 * \return \e true on success, otherwise \e false
926 * \see removeText(), clear()
927 */
928 virtual bool removeLine(int line) = 0;
929
930 /**
931 * \brief Searches the given input range for a text pattern.
932 *
933 * Searches for a text pattern within the given input range.
934 * The kind of search performed depends on the \p options
935 * used. Use this function for plaintext searches as well as
936 * regular expression searches. If no match is found the first
937 * (and only) element in the vector return is the invalid range.
938 * When searching for regular expressions, the first element holds
939 * the range of the full match, the subsequent elements hold
940 * the ranges of the capturing parentheses.
941 *
942 * \param range Input range to search in
943 * \param pattern Text pattern to search for
944 * \param options Combination of search flags
945 * \return List of ranges (length >=1)
946 *
947 * \author Sebastian Pipping <webmaster@hartwork.org>
948 *
949 * \since 5.11
950 */
951 QList<KTextEditor::Range> searchText(KTextEditor::Range range, const QString &pattern, const SearchOptions options = Default) const;
952
953 /**
954 * \brief Retrives the offset for the given cursor position
955 * NOTE: It will return -1 if the cursor was invalid or out of bounds.
956 * \since 6.0
957 */
958 virtual qsizetype cursorToOffset(KTextEditor::Cursor c) const = 0;
959
960 /**
961 * \brief Retrives the cursor position for given offset
962 * NOTE: It will return an invalid cursor(-1, -1) if offset is invalid.
963 * \since 6.0
964 */
965 virtual KTextEditor::Cursor offsetToCursor(qsizetype offset) const = 0;
966 /*
967 * SIGNALS
968 * Following signals should be emitted by the document if the text content
969 * is changed.
970 */
971Q_SIGNALS:
972 /**
973 * Editing transaction has started.
974 * \param document document which emitted this signal
975 */
977
978 /**
979 * Editing transaction has finished.
980 *
981 * @note This signal is emitted also for editing actions that maybe do not
982 * modify the @p document contents (think of having an empty
983 * EditingTransaction). If you want to get notified only
984 * after text really changed, connect to the signal textChanged().
985 *
986 * \param document document which emitted this signal
987 * @see textChanged()
988 */
990
991 /**
992 * A line got wrapped.
993 * \param document document which emitted this signal
994 * @param position position where the wrap occurred
995 */
997
998 /**
999 * A line got unwrapped.
1000 * \param document document which emitted this signal
1001 * @param line line where the unwrap occurred
1002 */
1003 void lineUnwrapped(KTextEditor::Document *document, int line);
1004
1005 /**
1006 * Text got inserted.
1007 * \param document document which emitted this signal
1008 * @param position position where the insertion occurred
1009 * @param text inserted text
1010 */
1011 void textInserted(KTextEditor::Document *document, KTextEditor::Cursor position, const QString &text);
1012
1013 /**
1014 * Text got removed.
1015 * \param document document which emitted this signal
1016 * @param range range where the removal occurred
1017 * @param text removed text
1018 */
1020
1021 /**
1022 * The \p document emits this signal whenever its text changes.
1023 * \param document document which emitted this signal
1024 * \see text(), textLine()
1025 */
1027
1028 //!\}
1029
1030 /**
1031 * \name Highlighting and Related Information
1032 *
1033 * \{
1034 */
1035public:
1036 /**
1037 * Get the default style of the character located at @p position.
1038 * If @p position is not a valid text position, the default style
1039 * KSyntaxHighlighting::Theme::TextStyle::Normal is returned.
1040 *
1041 * @note Further information about the colors of default styles depend on
1042 * the currently chosen schema. Since each View may have a different
1043 * color schema, the color information can be obtained through
1044 * View::defaultStyleAttribute() and View::lineAttributes().
1045 *
1046 * @param position text position
1047 * @return default style, see enum KSyntaxHighlighting::Theme::TextStyle
1048 * @see View::defaultStyleAttribute(), View::lineAttributes()
1049 */
1051
1052 /**
1053 * Return the name of the currently used mode
1054 * \return name of the used mode
1055 * \see modes(), setMode()
1056 */
1057 virtual QString mode() const = 0;
1058
1059 /**
1060 * Return the name of the currently used mode
1061 * \return name of the used mode
1062 * \see highlightingModes(), setHighlightingMode()
1063 */
1064 virtual QString highlightingMode() const = 0;
1065
1066 /**
1067 * \brief Get all available highlighting modes for the current document.
1068 *
1069 * Each document can be highlighted using an arbitrary number of highlighting
1070 * contexts. This method will return the names for each of the used modes.
1071 *
1072 * Example: The "PHP (HTML)" mode includes the highlighting for PHP, HTML, CSS and JavaScript.
1073 *
1074 * \return Returns a list of embedded highlighting modes for the current Document.
1075 *
1076 * \see KTextEditor::Document::highlightingMode()
1077 */
1079
1080 /**
1081 * \brief Get the highlight mode used at a given position in the document.
1082 *
1083 * Retrieve the name of the applied highlight mode at a given \p position
1084 * in the current document.
1085 *
1086 * Calling this might trigger re-highlighting up to the given line.
1087 * Therefore this is not const.
1088 *
1089 * \see highlightingModes()
1090 */
1092
1093 /**
1094 * Return a list of the names of all possible modes
1095 * \return list of mode names
1096 * \see mode(), setMode()
1097 */
1098 virtual QStringList modes() const = 0;
1099
1100 /**
1101 * Return a list of the names of all possible modes
1102 * \return list of mode names
1103 * \see highlightingMode(), setHighlightingMode()
1104 */
1105 virtual QStringList highlightingModes() const = 0;
1106
1107 /**
1108 * Set the current mode of the document by giving its name
1109 * \param name name of the mode to use for this document
1110 * \return \e true on success, otherwise \e false
1111 * \see mode(), modes(), modeChanged()
1112 */
1113 virtual bool setMode(const QString &name) = 0;
1114
1115 /**
1116 * Set the current mode of the document by giving its name
1117 * \param name name of the mode to use for this document
1118 * \return \e true on success, otherwise \e false
1119 * \see highlightingMode(), highlightingModes(), highlightingModeChanged()
1120 */
1121 virtual bool setHighlightingMode(const QString &name) = 0;
1122
1123 /**
1124 * Returns the name of the section for a highlight given its index in the highlight
1125 * list (as returned by highlightModes()).
1126 *
1127 * You can use this function to build a tree of the highlight names, organized in sections.
1128 *
1129 * \param index the index of the highlight in the list returned by modes()
1130 */
1131 virtual QString highlightingModeSection(int index) const = 0;
1132
1133 /**
1134 * Returns the name of the section for a mode given its index in the highlight
1135 * list (as returned by modes()).
1136 *
1137 * You can use this function to build a tree of the mode names, organized in sections.
1138 *
1139 * \param index the index of the highlight in the list returned by modes()
1140 */
1141 virtual QString modeSection(int index) const = 0;
1142
1143 /*
1144 * SIGNALS
1145 * Following signals should be emitted by the document if the mode
1146 * of the document changes
1147 */
1148Q_SIGNALS:
1149 /**
1150 * Warn anyone listening that the current document's mode has
1151 * changed.
1152 *
1153 * \param document the document whose mode has changed
1154 * \see setMode()
1155 */
1157
1158 /**
1159 * Warn anyone listening that the current document's highlighting mode has
1160 * changed.
1161 *
1162 * \param document the document which's mode has changed
1163 * \see setHighlightingMode()
1164 */
1166
1167 //!\}
1168
1169 /**
1170 * \name Printing
1171 *
1172 * \{
1173 */
1174public:
1175 /**
1176 * Print the document. This should result in showing the print dialog.
1177 *
1178 * @returns true if document was printed
1179 */
1180 virtual bool print() = 0;
1181
1182 /**
1183 * Shows the print preview dialog/
1184 */
1185 virtual void printPreview() = 0;
1186
1187 //!\}
1188
1189 /**
1190 * \name Showing Interactive Notifications
1191 *
1192 * \{
1193 */
1194public:
1195 /**
1196 * Post @p message to the Document and its View%s.
1197 * If multiple Message%s are posted, the one with the highest priority
1198 * is shown first.
1199 *
1200 * Usually, you can simply forget the pointer, as the Message is deleted
1201 * automatically, once it is processed or the document gets closed.
1202 *
1203 * If the Document does not have a View yet, the Message is queued and
1204 * shown, once a View for the Document is created.
1205 *
1206 * @param message the message to show
1207 * @return @e true, if @p message was posted. @e false, if message == 0.
1208 */
1209 virtual bool postMessage(Message *message) = 0;
1210
1211 //!\}
1212
1213 /**
1214 * \name Session Configuration
1215 *
1216 * \{
1217 */
1218public:
1219 /**
1220 * Read session settings from the given \p config.
1221 *
1222 * Known flags:
1223 * - \p SkipUrl => do not save/restore the file
1224 * - \p SkipMode => do not save/restore the mode
1225 * - \p SkipHighlighting => do not save/restore the highlighting
1226 * - \p SkipEncoding => do not save/restore the encoding
1227 *
1228 * \param config read the session settings from this KConfigGroup
1229 * \param flags additional flags
1230 * \see writeSessionConfig()
1231 */
1232 virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
1233
1234 /**
1235 * Write session settings to the \p config.
1236 * See readSessionConfig() for more details about available \p flags.
1237 *
1238 * \param config write the session settings to this KConfigGroup
1239 * \param flags additional flags
1240 * \see readSessionConfig()
1241 */
1242 virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
1243
1244 //!\}
1245
1246 /**
1247 * \name Crash Recovery
1248 *
1249 * \{
1250 */
1251public:
1252 /**
1253 * Returns whether a recovery is available for the current document.
1254 *
1255 * \see recoverData(), discardDataRecovery()
1256 */
1257 virtual bool isDataRecoveryAvailable() const = 0;
1258
1259 /**
1260 * If recover data is available, calling recoverData() will trigger the
1261 * recovery of the data. If isDataRecoveryAvailable() returns \e false,
1262 * calling this function does nothing.
1263 *
1264 * \see isDataRecoveryAvailable(), discardDataRecovery()
1265 */
1266 virtual void recoverData() = 0;
1267
1268 /**
1269 * If recover data is available, calling discardDataRecovery() will discard
1270 * the recover data and the recover data is lost.
1271 * If isDataRecoveryAvailable() returns \e false, calling this function
1272 * does nothing.
1273 *
1274 * \see isDataRecoveryAvailable(), recoverData()
1275 */
1276 virtual void discardDataRecovery() = 0;
1277
1278 //!\}
1279
1280Q_SIGNALS:
1281 /**
1282 * This signal is emitted whenever the current document configuration is changed.
1283 *
1284 * \param document the document which's config has changed
1285 *
1286 * \since 5.79
1287 */
1289
1290 /**
1291 * \name Moving Interface
1292 *
1293 * \{
1294 */
1295public:
1296 /**
1297 * Create a new moving cursor for this document.
1298 * @param position position of the moving cursor to create
1299 * @param insertBehavior insertion behavior
1300 * @return new moving cursor for the document
1301 */
1302 virtual MovingCursor *newMovingCursor(KTextEditor::Cursor position, MovingCursor::InsertBehavior insertBehavior = MovingCursor::MoveOnInsert) = 0;
1303
1304 /**
1305 * Create a new moving range for this document. Ownership of the range that is returned belongs to the caller
1306 * @param range range of the moving range to create
1307 * @param insertBehaviors insertion behaviors
1308 * @param emptyBehavior behavior on becoming empty
1309 * @return new moving range for the document
1310 */
1312 MovingRange::InsertBehaviors insertBehaviors = MovingRange::DoNotExpand,
1313 MovingRange::EmptyBehavior emptyBehavior = MovingRange::AllowEmpty) = 0;
1314
1315 /**
1316 * Current revision
1317 * @return current revision
1318 */
1319 virtual qint64 revision() const = 0;
1320
1321 /**
1322 * Last revision the buffer got successful saved
1323 * @return last revision buffer got saved, -1 if none
1324 */
1325 virtual qint64 lastSavedRevision() const = 0;
1326
1327 /**
1328 * Lock a revision, this will keep it around until released again.
1329 * But all revisions will always be cleared on buffer clear() (and therefor load())
1330 * @param revision revision to lock
1331 */
1332 virtual void lockRevision(qint64 revision) = 0;
1333
1334 /**
1335 * Release a revision.
1336 * @param revision revision to release
1337 */
1338 virtual void unlockRevision(qint64 revision) = 0;
1339
1340 /**
1341 * Transform a cursor from one revision to an other.
1342 * @param cursor cursor to transform
1343 * @param insertBehavior behavior of this cursor on insert of text at its position
1344 * @param fromRevision from this revision we want to transform
1345 * @param toRevision to this revision we want to transform, default of -1 is current revision
1346 */
1347 virtual void
1348 transformCursor(KTextEditor::Cursor &cursor, KTextEditor::MovingCursor::InsertBehavior insertBehavior, qint64 fromRevision, qint64 toRevision = -1) = 0;
1349
1350 /**
1351 * Transform a cursor from one revision to an other.
1352 * @param line line number of the cursor to transform
1353 * @param column column number of the cursor to transform
1354 * @param insertBehavior behavior of this cursor on insert of text at its position
1355 * @param fromRevision from this revision we want to transform
1356 * @param toRevision to this revision we want to transform, default of -1 is current revision
1357 */
1358 virtual void
1359 transformCursor(int &line, int &column, KTextEditor::MovingCursor::InsertBehavior insertBehavior, qint64 fromRevision, qint64 toRevision = -1) = 0;
1360
1361 /**
1362 * Transform a range from one revision to an other.
1363 * @param range range to transform
1364 * @param insertBehaviors behavior of this range on insert of text at its position
1365 * @param emptyBehavior behavior on becoming empty
1366 * @param fromRevision from this revision we want to transform
1367 * @param toRevision to this revision we want to transform, default of -1 is current revision
1368 */
1371 MovingRange::EmptyBehavior emptyBehavior,
1372 qint64 fromRevision,
1373 qint64 toRevision = -1) = 0;
1374
1375Q_SIGNALS:
1376
1377#if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(6, 9)
1378 /**
1379 * This signal is emitted before the cursors/ranges/revisions of a document
1380 * are destroyed as the document is deleted.
1381 * @param document the document which the interface belongs to which is in the process of being deleted
1382 *
1383 * @deprecated since 6.9
1384 */
1385 KTEXTEDITOR_DEPRECATED_VERSION(6, 9, "Not emitted any more. Ownership of the moving interface belongs to the user")
1386 void aboutToDeleteMovingInterfaceContent(KTextEditor::Document *document);
1387#endif
1388
1389 /**
1390 * This signal is emitted before the ranges of a document are invalidated
1391 * and the revisions are deleted as the document is cleared (for example on
1392 * load/reload). While this signal is emitted, the old document content is
1393 * still valid and accessible before the clear.
1394 * @param document the document which the interface belongs to which will invalidate its data
1395 */
1397
1398 //!\}
1399
1400 /**
1401 * \name Config
1402 *
1403 * \{
1404 */
1405public:
1406 /**
1407 * \brief Get a list of all available keys.
1408 */
1409 virtual QStringList configKeys() const = 0;
1410 /**
1411 * \brief Get a value for the \p key.
1412 */
1413 virtual QVariant configValue(const QString &key) = 0;
1414 /**
1415 * \brief Set a the \p key's value to \p value.
1416 */
1417 virtual void setConfigValue(const QString &key, const QVariant &value) = 0;
1418 //!\}
1419
1420 /**
1421 * \name Modification Interface
1422 *
1423 * \{
1424 */
1425public:
1426 /**
1427 * Reasons why a document is modified on disk.
1428 */
1430 OnDiskUnmodified = 0, ///< Not modified
1431 OnDiskModified = 1, ///< The file was modified on disk
1432 OnDiskCreated = 2, ///< The file was created on disk
1433 OnDiskDeleted = 3 ///< The file was deleted or moved on disk
1435
1436 /**
1437 * Set the document's modified-on-disk state to \p reason.
1438 * KTextEditor implementations should emit the signal modifiedOnDisk()
1439 * along with the reason. When the document is in a clean state again the
1440 * reason should be ModifiedOnDiskReason::OnDiskUnmodified.
1441 *
1442 * \param reason the modified-on-disk reason.
1443 * \see ModifiedOnDiskReason, modifiedOnDisk()
1444 */
1445 virtual void setModifiedOnDisk(ModifiedOnDiskReason reason) = 0;
1446
1447 /**
1448 * Control, whether the editor should show a warning dialog whenever a file
1449 * was modified on disk. If \p on is \e true the editor will show warning
1450 * dialogs.
1451 * \param on controls, whether the editor should show a warning dialog for
1452 * files modified on disk
1453 */
1454 virtual void setModifiedOnDiskWarning(bool on) = 0;
1455
1456Q_SIGNALS:
1457 /**
1458 * This signal is emitted whenever the \p document changed its
1459 * modified-on-disk state.
1460 * \param document the Document object that represents the file on disk
1461 * \param isModified if \e true, the file was modified rather than created
1462 * or deleted
1463 * \param reason the reason why the signal was emitted
1464 * \see setModifiedOnDisk()
1465 */
1467 //!\}
1468
1469 /**
1470 * \name Mark Interface
1471 *
1472 * \{
1473 */
1474public:
1475 /**
1476 * Get all marks set on the \p line.
1477 * \param line requested line
1478 * \return a \e uint representing of the marks set in \p line concatenated
1479 * by logical OR
1480 * \see addMark(), removeMark()
1481 */
1482 virtual uint mark(int line) = 0;
1483
1484 /**
1485 * Set the \p line's mark types to \p markType.
1486 * If \p line already contains a mark of the given type it has no effect.
1487 * All other marks are deleted before the mark is set. You can achieve
1488 * the same by calling
1489 * \code
1490 * clearMark(line);
1491 * addMark(line, markType);
1492 * \endcode
1493 * \param line line to set the mark
1494 * \param markType mark type
1495 * \see clearMark(), addMark(), mark()
1496 */
1497 virtual void setMark(int line, uint markType) = 0;
1498
1499 /**
1500 * Clear all marks set in the \p line.
1501 * \param line line to clear marks
1502 * \see clearMarks(), removeMark(), addMark()
1503 */
1504 virtual void clearMark(int line) = 0;
1505
1506 /**
1507 * Add marks of type \p markType to \p line. Existing marks on this line
1508 * are preserved. If the mark \p markType already is set, nothing
1509 * happens.
1510 * \param line line to set the mark
1511 * \param markType mark type
1512 * \see removeMark(), setMark()
1513 */
1514 virtual void addMark(int line, uint markType) = 0;
1515
1516 /**
1517 * Remove the mark mask of type \p markType from \p line.
1518 * \param line line to remove the mark
1519 * \param markType mark type to be removed
1520 * \see clearMark()
1521 */
1522 virtual void removeMark(int line, uint markType) = 0;
1523
1524 /**
1525 * Get a hash holding all marks in the document.
1526 * The hash key for a mark is its line.
1527 * \return a hash holding all marks in the document
1528 *
1529 * KF6 TODO: Change Mark* to Mark. No need for pointer here.
1530 */
1532
1533 /**
1534 * Clear all marks in the entire document.
1535 * \see clearMark(), removeMark()
1536 */
1537 /// TODO: dominik: add argument unit mask = 0
1538 virtual void clearMarks() = 0;
1539
1540 /**
1541 * Get the number of predefined mark types we have so far.
1542 * \note FIXME: If you change this you have to make sure katepart
1543 * supports the new size!
1544 * \return number of reserved marker types
1545 */
1547 {
1548 return 7;
1549 }
1550
1551 /**
1552 * Predefined mark types.
1553 *
1554 * To add a new standard mark type, edit this interface and document
1555 * the type.
1556 */
1558 /** Bookmark */
1559 markType01 = 0x1,
1560 /** Breakpoint active */
1561 markType02 = 0x2,
1562 /** Breakpoint reached */
1563 markType03 = 0x4,
1564 /** Breakpoint disabled */
1565 markType04 = 0x8,
1566 /** Execution mark */
1567 markType05 = 0x10,
1568 /** Warning */
1569 markType06 = 0x20,
1570 /** Error */
1571 markType07 = 0x40,
1572
1573 markType08 = 0x80,
1574 markType09 = 0x100,
1575 markType10 = 0x200,
1576 markType11 = 0x400,
1577 markType12 = 0x800,
1578 markType13 = 0x1000,
1579 markType14 = 0x2000,
1580 markType15 = 0x4000,
1581 markType16 = 0x8000,
1582 markType17 = 0x10000,
1583 markType18 = 0x20000,
1584 markType19 = 0x40000,
1585 markType20 = 0x80000,
1586 markType21 = 0x100000,
1587 markType22 = 0x200000,
1588 markType23 = 0x400000,
1589 markType24 = 0x800000,
1590 markType25 = 0x1000000,
1591 markType26 = 0x2000000,
1592 markType27 = 0x4000000,
1593 markType28 = 0x8000000,
1594 markType29 = 0x10000000,
1595 markType30 = 0x20000000,
1596 markType31 = 0x40000000,
1597 markType32 = 0x80000000,
1598 /* reserved marks */
1599 Bookmark = markType01,
1600 BreakpointActive = markType02,
1601 BreakpointReached = markType03,
1602 BreakpointDisabled = markType04,
1603 Execution = markType05,
1604 Warning = markType06,
1605 Error = markType07,
1606 SearchMatch = markType32,
1607 };
1608
1609 /*
1610 * Methods to modify mark properties.
1611 */
1612public:
1613 /**
1614 * Set the \p mark's description to \p text.
1615 * \param mark mark to set the description
1616 * \param text new descriptive text
1617 * \see markDescription(), setMarkPixmap()
1618 */
1619 virtual void setMarkDescription(MarkTypes mark, const QString &text) = 0;
1620
1621 /**
1622 * Get the \p mark's description to text.
1623 * \param mark mark to set the description
1624 * \return text of the given \p mark or QString(), if the entry does not
1625 * exist
1626 * \see setMarkDescription(), setMarkPixmap()
1627 */
1628 virtual QString markDescription(MarkTypes mark) const = 0;
1629
1630 /**
1631 * Set the mark mask the user is allowed to toggle to \p markMask.
1632 * I.e. concatenate all editable marks with a logical OR. If the user should
1633 * be able to add a bookmark and set a breakpoint with the context menu in
1634 * the icon pane, you have to call
1635 * \code
1636 * // iface is of Type KTextEditor::MarkInterface*
1637 * // only make bookmark and breakpoint editable
1638 * iface->setEditableMarks( MarkInterface::Bookmark |
1639 * MarkInterface::BreakpointActive );
1640 *
1641 * // or preserve last settings, and add bookmark and breakpoint
1642 * iface->setEditableMarks( iface->editableMarks() |
1643 * MarkInterface::Bookmark |
1644 * MarkInterface::BreakpointActive );
1645 * \endcode
1646 * \param markMask bitmap pattern
1647 * \see editableMarks(), setMarkPixmap(), setMarkDescription()
1648 */
1649 virtual void setEditableMarks(uint markMask) = 0;
1650
1651 /**
1652 * Get, which marks can be toggled by the user.
1653 * The returned value is a mark mask containing all editable marks combined
1654 * with a logical OR.
1655 * \return mark mask containing all editable marks
1656 * \see setEditableMarks()
1657 */
1658 virtual uint editableMarks() const = 0;
1659
1660 /**
1661 * Possible actions on a mark.
1662 * \see markChanged()
1663 */
1665 MarkAdded = 0, /**< action: a mark was added. */
1666 MarkRemoved = 1 /**< action: a mark was removed. */
1668
1669 /**
1670 * Set the \p mark's icon to \p icon.
1671 * \param markType mark type to which the icon will be attached
1672 * \param icon new icon
1673 * \see setMarkDescription()
1674 */
1675 virtual void setMarkIcon(MarkTypes markType, const QIcon &icon) = 0;
1676
1677 /**
1678 * Get the \p mark's icon.
1679 * \param markType mark type. If the icon does not exist the resulting is null
1680 * (check with QIcon::isNull()).
1681 * \see setMarkDescription()
1682 */
1683 virtual QIcon markIcon(MarkTypes markType) const = 0;
1684
1685Q_SIGNALS:
1686 /**
1687 * The \p document emits this signal whenever a mark mask changed.
1688 * \param document document which emitted this signal
1689 * \see markChanged()
1690 */
1692
1693 /**
1694 * The \p document emits this signal whenever the \p mark changes.
1695 * \param document the document which emitted the signal
1696 * \param mark changed mark
1697 * \param action action, either removed or added
1698 * \see marksChanged()
1699 */
1701
1702 /**
1703 * The \p document emits this signal whenever the \p mark is hovered using the mouse,
1704 * and the receiver may show a tooltip.
1705 * \param document the document which emitted the signal
1706 * \param mark mark that was hovered
1707 * \param position mouse position during the hovering
1708 * \param handled set this to 'true' if this event was handled externally
1709 */
1710 void markToolTipRequested(KTextEditor::Document *document, KTextEditor::Mark mark, QPoint position, bool &handled);
1711
1712 /**
1713 * The \p document emits this signal whenever the \p mark is right-clicked to show a context menu.
1714 * The receiver may show an own context menu instead of the kate internal one.
1715 * \param document the document which emitted the signal
1716 * \param mark mark that was right-clicked
1717 * \param pos position where the menu should be started
1718 * \param handled set this to 'true' if this event was handled externally, and kate should not create an own context menu.
1719 */
1721
1722 /**
1723 * The \p document emits this signal whenever the \p mark is left-clicked.
1724 * \param document the document which emitted the signal
1725 * \param mark mark that was right-clicked
1726 * \param handled set this to 'true' if this event was handled externally, and kate should not do own handling of the left click.
1727 */
1728 void markClicked(KTextEditor::Document *document, KTextEditor::Mark mark, bool &handled);
1729 //!\}
1730
1731 /**
1732 * \name Annotation Interface
1733 *
1734 * \{
1735 */
1736public:
1737 /**
1738 * Sets a new \ref AnnotationModel for this document to provide
1739 * annotation information for each line.
1740 *
1741 * \param model the new AnnotationModel
1742 */
1743 virtual void setAnnotationModel(AnnotationModel *model) = 0;
1744
1745 /**
1746 * returns the currently set \ref AnnotationModel or 0 if there's none
1747 * set
1748 * @returns the current \ref AnnotationModel
1749 */
1750 virtual AnnotationModel *annotationModel() const = 0;
1751 //!\}
1752
1753private:
1754 /**
1755 * private d-pointer, pointing to the internal implementation
1756 */
1757 DocumentPrivate *const d;
1758};
1759
1760}
1761
1762#endif
An model for providing line annotation information.
The Cursor represents a position in a Document.
Definition cursor.h:75
Backend of KTextEditor::Document related public KTextEditor interfaces.
Editing transaction support.
Definition document.h:574
EditingTransaction(const EditingTransaction &)=delete
No copy constructor, don't allow this to be copied.
EditingTransaction & operator=(const EditingTransaction &)=delete
No assignment operator, no copying around editing transations.
A KParts derived class representing a text document.
Definition document.h:284
void configChanged(KTextEditor::Document *document)
This signal is emitted whenever the current document configuration is changed.
virtual void setAnnotationModel(AnnotationModel *model)=0
Sets a new AnnotationModel for this document to provide annotation information for each line.
virtual QString text(Range range, bool block=false) const =0
Get the document content within the given range.
virtual void setConfigValue(const QString &key, const QVariant &value)=0
Set a the key's value to value.
virtual bool documentSaveAs()=0
Save the current file to another location.
virtual void transformCursor(KTextEditor::Cursor &cursor, KTextEditor::MovingCursor::InsertBehavior insertBehavior, qint64 fromRevision, qint64 toRevision=-1)=0
Transform a cursor from one revision to an other.
virtual void clearMarks()=0
Clear all marks in the entire document.
virtual void clearMark(int line)=0
Clear all marks set in the line.
virtual bool removeLine(int line)=0
Remove line from the document.
virtual QList< View * > views() const =0
Returns the views pre-casted to KTextEditor::Views.
void documentNameChanged(KTextEditor::Document *document)
This signal is emitted whenever the document name changes.
virtual bool insertLine(int line, const QString &text)=0
Insert line(s) at the given line number.
virtual bool setEncoding(const QString &encoding)=0
Set the encoding for this document.
void reloaded(KTextEditor::Document *document)
Emitted after the current document was reloaded.
virtual KTextEditor::Cursor offsetToCursor(qsizetype offset) const =0
Retrives the cursor position for given offset NOTE: It will return an invalid cursor(-1,...
virtual bool isValidTextPosition(KTextEditor::Cursor cursor) const =0
Get whether cursor is a valid text position.
virtual void setModifiedOnDisk(ModifiedOnDiskReason reason)=0
Set the document's modified-on-disk state to reason.
virtual KTextEditor::Range wordRangeAt(KTextEditor::Cursor cursor) const =0
Get the text range for the word located under the text position cursor.
virtual qsizetype totalCharacters() const =0
Get the count of characters in the document.
void textChanged(KTextEditor::Document *document)
The document emits this signal whenever its text changes.
void marksChanged(KTextEditor::Document *document)
The document emits this signal whenever a mark mask changed.
virtual bool isDataRecoveryAvailable() const =0
Returns whether a recovery is available for the current document.
virtual qint64 revision() const =0
Current revision.
void editingFinished(KTextEditor::Document *document)
Editing transaction has finished.
void markClicked(KTextEditor::Document *document, KTextEditor::Mark mark, bool &handled)
The document emits this signal whenever the mark is left-clicked.
virtual QString line(int line) const =0
Get a single text line.
virtual bool setText(const QString &text)=0
Set the given text as new document content.
void markToolTipRequested(KTextEditor::Document *document, KTextEditor::Mark mark, QPoint position, bool &handled)
The document emits this signal whenever the mark is hovered using the mouse, and the receiver may sho...
MarkTypes
Predefined mark types.
Definition document.h:1557
virtual QString documentName() const =0
Get this document's name.
virtual void setMarkDescription(MarkTypes mark, const QString &text)=0
Set the mark's description to text.
void viewCreated(KTextEditor::Document *document, KTextEditor::View *view)
This signal is emitted whenever the document creates a new view.
virtual MovingCursor * newMovingCursor(KTextEditor::Cursor position, MovingCursor::InsertBehavior insertBehavior=MovingCursor::MoveOnInsert)=0
Create a new moving cursor for this document.
void lineUnwrapped(KTextEditor::Document *document, int line)
A line got unwrapped.
virtual void readSessionConfig(const KConfigGroup &config, const QSet< QString > &flags=QSet< QString >())=0
Read session settings from the given config.
virtual bool setText(const QStringList &text)=0
Set the given text as new document content.
virtual QString encoding() const =0
Get the current chosen encoding.
virtual bool setHighlightingMode(const QString &name)=0
Set the current mode of the document by giving its name.
virtual bool insertLines(int line, const QStringList &text)=0
Insert line(s) at the given line number.
virtual void setMarkIcon(MarkTypes markType, const QIcon &icon)=0
Set the mark's icon to icon.
virtual bool isLineTouched(int line) const =0
Check whether line was touched since the file was opened.
virtual void writeSessionConfig(KConfigGroup &config, const QSet< QString > &flags=QSet< QString >())=0
Write session settings to the config.
virtual QString modeSection(int index) const =0
Returns the name of the section for a mode given its index in the highlight list (as returned by mode...
Range documentRange() const
A Range which encompasses the whole document.
Definition document.h:785
virtual QString wordAt(KTextEditor::Cursor cursor) const =0
Get the word at the text position cursor.
virtual qsizetype cursorToOffset(KTextEditor::Cursor c) const =0
Retrives the offset for the given cursor position NOTE: It will return -1 if the cursor was invalid o...
virtual bool clear()=0
Remove the whole content of the document.
virtual QVariant configValue(const QString &key)=0
Get a value for the key.
virtual QString text() const =0
Get the document content.
virtual void discardDataRecovery()=0
If recover data is available, calling discardDataRecovery() will discard the recover data and the rec...
virtual bool removeText(Range range, bool block=false)=0
Remove the text specified in range.
void aboutToInvalidateMovingInterfaceContent(KTextEditor::Document *document)
This signal is emitted before the ranges of a document are invalidated and the revisions are deleted ...
virtual void setEditableMarks(uint markMask)=0
Set the mark mask the user is allowed to toggle to markMask.
static int reservedMarkersCount()
Get the number of predefined mark types we have so far.
Definition document.h:1546
void editingStarted(KTextEditor::Document *document)
Editing transaction has started.
void modeChanged(KTextEditor::Document *document)
Warn anyone listening that the current document's mode has changed.
virtual int lines() const =0
Get the count of lines of the document.
virtual bool documentReload()=0
Reload the current file.
void aboutToClose(KTextEditor::Document *document)
Warn anyone listening that the current document is about to close.
virtual void addMark(int line, uint markType)=0
Add marks of type markType to line.
virtual View * createView(QWidget *parent, KTextEditor::MainWindow *mainWindow=nullptr)=0
Create a new view attached to parent.
virtual void unlockRevision(qint64 revision)=0
Release a revision.
MarkChangeAction
Possible actions on a mark.
Definition document.h:1664
void documentSavedOrUploaded(KTextEditor::Document *document, bool saveAs)
This signal should be emitted after a document has been saved to disk or for remote files uploaded.
virtual void lockRevision(qint64 revision)=0
Lock a revision, this will keep it around until released again.
virtual bool documentSave()=0
Save the current file.
virtual AnnotationModel * annotationModel() const =0
returns the currently set AnnotationModel or 0 if there's none set
virtual QString highlightingMode() const =0
Return the name of the currently used mode.
void highlightingModeChanged(KTextEditor::Document *document)
Warn anyone listening that the current document's highlighting mode has changed.
virtual int lineLength(int line) const =0
Get the length of a given line in characters.
void lineWrapped(KTextEditor::Document *document, KTextEditor::Cursor position)
A line got wrapped.
virtual uint editableMarks() const =0
Get, which marks can be toggled by the user.
virtual QStringList textLines(Range range, bool block=false) const =0
Get the document content within the given range.
virtual void recoverData()=0
If recover data is available, calling recoverData() will trigger the recovery of the data.
virtual bool postMessage(Message *message)=0
Post message to the Document and its Views.
virtual QStringList modes() const =0
Return a list of the names of all possible modes.
virtual void transformCursor(int &line, int &column, KTextEditor::MovingCursor::InsertBehavior insertBehavior, qint64 fromRevision, qint64 toRevision=-1)=0
Transform a cursor from one revision to an other.
virtual QString mimeType()=0
Get this document's mimetype.
virtual QString markDescription(MarkTypes mark) const =0
Get the mark's description to text.
Cursor endOfLine(int line) const
Get the end cursor position of line line.
Definition document.h:817
virtual const QHash< int, KTextEditor::Mark * > & marks()=0
Get a hash holding all marks in the document.
virtual bool insertText(KTextEditor::Cursor position, const QString &text, bool block=false)=0
Insert text at position.
void modifiedOnDisk(KTextEditor::Document *document, bool isModified, KTextEditor::Document::ModifiedOnDiskReason reason)
This signal is emitted whenever the document changed its modified-on-disk state.
~Document() override
Virtual destructor.
virtual QByteArray checksum() const =0
Get the git hash of the Document's contents on disk.
virtual QString highlightingModeSection(int index) const =0
Returns the name of the section for a highlight given its index in the highlight list (as returned by...
void readWriteChanged(KTextEditor::Document *document)
This signal is emitted whenever the readWrite state of a document changes.
void aboutToSave(KTextEditor::Document *document)
Emitted just before the document will be saved Any modifications made to the document at this point w...
virtual QStringList configKeys() const =0
Get a list of all available keys.
void markChanged(KTextEditor::Document *document, KTextEditor::Mark mark, KTextEditor::Document::MarkChangeAction action)
The document emits this signal whenever the mark changes.
virtual Cursor documentEnd() const =0
End position of the document.
virtual KSyntaxHighlighting::Theme::TextStyle defaultStyleAt(KTextEditor::Cursor position) const =0
Get the default style of the character located at position.
virtual void transformRange(KTextEditor::Range &range, KTextEditor::MovingRange::InsertBehaviors insertBehaviors, MovingRange::EmptyBehavior emptyBehavior, qint64 fromRevision, qint64 toRevision=-1)=0
Transform a range from one revision to an other.
void aboutToReload(KTextEditor::Document *document)
Warn anyone listening that the current document is about to reload.
virtual QString highlightingModeAt(KTextEditor::Cursor position)=0
Get the highlight mode used at a given position in the document.
virtual bool print()=0
Print the document.
virtual QStringList embeddedHighlightingModes() const =0
Get all available highlighting modes for the current document.
void modifiedChanged(KTextEditor::Document *document)
This signal is emitted whenever the document's buffer changed from either state unmodified to modifie...
void markContextMenuRequested(KTextEditor::Document *document, KTextEditor::Mark mark, QPoint pos, bool &handled)
The document emits this signal whenever the mark is right-clicked to show a context menu.
virtual bool setMode(const QString &name)=0
Set the current mode of the document by giving its name.
void textInserted(KTextEditor::Document *document, KTextEditor::Cursor position, const QString &text)
Text got inserted.
virtual bool isLineSaved(int line) const =0
Check whether line currently contains only saved text.
ModifiedOnDiskReason
Reasons why a document is modified on disk.
Definition document.h:1429
virtual QStringList highlightingModes() const =0
Return a list of the names of all possible modes.
virtual void printPreview()=0
Shows the print preview dialog/.
virtual bool isEditingTransactionRunning() const =0
Check whether an editing transaction is currently running.
virtual MovingRange * newMovingRange(Range range, MovingRange::InsertBehaviors insertBehaviors=MovingRange::DoNotExpand, MovingRange::EmptyBehavior emptyBehavior=MovingRange::AllowEmpty)=0
Create a new moving range for this document.
virtual QIcon markIcon(MarkTypes markType) const =0
Get the mark's icon.
virtual uint mark(int line)=0
Get all marks set on the line.
virtual QString mode() const =0
Return the name of the currently used mode.
virtual QChar characterAt(KTextEditor::Cursor position) const =0
Get the character at text position cursor.
virtual bool insertText(KTextEditor::Cursor position, const QStringList &text, bool block=false)=0
Insert text at position.
virtual void removeMark(int line, uint markType)=0
Remove the mark mask of type markType from line.
virtual qint64 lastSavedRevision() const =0
Last revision the buffer got successful saved.
virtual bool isLineModified(int line) const =0
Check whether line currently contains unsaved data.
void documentUrlChanged(KTextEditor::Document *document)
This signal is emitted whenever the document URL changes.
virtual void setMark(int line, uint markType)=0
Set the line's mark types to markType.
virtual void setModifiedOnDiskWarning(bool on)=0
Control, whether the editor should show a warning dialog whenever a file was modified on disk.
void textRemoved(KTextEditor::Document *document, KTextEditor::Range range, const QString &text)
Text got removed.
This class allows the application that embeds the KTextEditor component to allow it to access parts o...
Definition mainwindow.h:47
uint type
The mark types in the line, combined with logical OR.
Definition document.h:79
int line
The line that contains the mark.
Definition document.h:76
This class holds a Message to display in Views.
Definition message.h:94
A Cursor which is bound to a specific Document, and maintains its position.
InsertBehavior
Insert behavior of this cursor, should it stay if text is insert at its position or should it move.
A range that is bound to a specific Document, and maintains its position.
EmptyBehavior
Behavior of range if it becomes empty.
An object representing a section of text, from one Cursor to another.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
Q_SCRIPTABLE Q_NOREPLY void start()
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
SearchOption
Search flags for use with searchText.
Definition document.h:47
@ MaxSearchOption
Placeholder for binary compatibility.
Definition document.h:61
@ Default
Default settings.
Definition document.h:48
@ CaseInsensitive
Ignores cases, e.g. "a" matches "A".
Definition document.h:54
@ Regex
Treats the pattern as a regular expression.
Definition document.h:51
@ Backwards
Searches in backward direction.
Definition document.h:55
@ EscapeSequences
Plaintext mode: Processes escape sequences.
Definition document.h:58
@ WholeWords
Plaintext mode: Whole words only, e.g. not "amp" in "example".
Definition document.h:59
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:05:18 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.