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