• Skip to content
  • Skip to link menu
KDE API Reference
  • KDE API Reference
  • applications API Reference
  • KDE Home
  • Contact Us
 

KTextEditor

  • sources
  • kde-4.12
  • applications
  • kate
  • ktexteditor
document.h
Go to the documentation of this file.
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 
111 class KTEXTEDITOR_EXPORT Document : public KParts::ReadWritePart
112 {
113  Q_OBJECT
114 
115  public:
123  Document ( QObject *parent = 0);
124 
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:
142  virtual Editor *editor () = 0;
143 
149  virtual View *createView ( QWidget *parent ) = 0;
150 
154  virtual View* activeView() const = 0;
155 
159  virtual const QList<View*> &views() const = 0;
160 
161  Q_SIGNALS:
172  void viewCreated (KTextEditor::Document *document, KTextEditor::View *view);
173 
174  /*
175  * General information about this document and its content.
176  */
177  public:
185  virtual const QString &documentName () const = 0;
186 
191  virtual QString mimeType() = 0;
192 
193  /*
194  * SIGNALS
195  * following signals should be emitted by the editor document.
196  */
197  Q_SIGNALS:
203  void documentNameChanged ( KTextEditor::Document *document );
204 
210  void documentUrlChanged ( KTextEditor::Document *document );
211 
220  void modifiedChanged ( KTextEditor::Document *document );
221 
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:
246  virtual bool setEncoding (const QString &encoding) = 0;
247 
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:
269  virtual bool documentReload () = 0;
270 
277  virtual bool documentSave () = 0;
278 
285  virtual bool documentSaveAs () = 0;
286 
287  Q_SIGNALS:
292  void documentSavedOrUploaded(KTextEditor::Document* document,bool saveAs);
293 
294  /*
295  * Methodes to create/end editing sequences.
296  */
297  public:
320  virtual bool startEditing () = 0;
321 
328  virtual bool endEditing () = 0;
329 
330  /*
331  * General access to the document's text content.
332  */
333  public:
339  virtual QString text () const = 0;
340 
349  virtual QString text ( const Range& range, bool block = false ) const = 0;
350 
358  virtual QChar character( const Cursor& position ) const = 0;
359 
360  // TODO: KDE5, add wordAt(), implementation already exists in KateDocument::getWord().
361  // In the implementation, reuse wordRangeAt() to avoid code duplication.
362  /*
363  * Get the word at the text position \p cursor.
364  * The returned word is defined by the word boundaries to the left and
365  * right starting at \p cursor. The algorithm takes highlighting information
366  * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
367  * whereas e.g. CSS allows identifiers with dash ('-').
368  *
369  * If \p cursor is not a valid text position or if there is no word
370  * under the requested position \p cursor, an empty string is returned.
371  *
372  * \param cursor requested cursor position for the word
373  * \return the word under the cursor or an empty string if there is no word.
374  *
375  * \see wordRangeAt(), characterAt()
376  */
377  //QString wordAt(const KTextEditor::Cursor& cursor) const = 0;
378 
379  // TODO: KDE5, add wordRangeAt(), implementation for the range already exists in KateDocument::getWord()
380  /*
381  * Get the text range for the word located under the text position \p cursor.
382  * The returned word is defined by the word boundaries to the left and
383  * right starting at \p cursor. The algorithm takes highlighting information
384  * into account, e.g. a dash ('-') in C++ is interpreted as word boundary,
385  * whereas e.g. CSS allows identifiers with dash ('-').
386  *
387  * If \p cursor is not a valid text position or if there is no word
388  * under the requested position \p cursor, an invalid text range is returned.
389  * If the text range is valid, it is \e always on a single line.
390  *
391  * \param cursor requested cursor position for the word
392  * \return the Range spanning the word under the cursor or an invalid range if there is no word.
393  *
394  * \see wordAt(), characterAt(), KTextEditor::Range::isValid()
395  */
396  //KTextEditor::Range wordRangeAt(const KTextEditor::Cursor& cursor) const = 0;
397 
407  virtual QStringList textLines ( const Range& range, bool block = false ) const = 0;
408 
415  virtual QString line ( int line ) const = 0;
416 
422  virtual int lines () const = 0;
423 
429  virtual Cursor documentEnd() const = 0;
430 
435  inline Range documentRange() const { return Range(Cursor::start(), documentEnd()); }
436 
443  virtual int totalCharacters() const = 0;
444 
448  virtual bool isEmpty() const;
449 
457  virtual int lineLength ( int line ) const = 0;
458 
464  inline Cursor endOfLine(int line) const { return Cursor(line, lineLength(line)); }
465 
472  virtual bool setText ( const QString &text ) = 0;
473 
480  virtual bool setText ( const QStringList &text ) = 0;
481 
487  virtual bool clear () = 0;
488 
497  virtual bool insertText ( const Cursor &position, const QString &text, bool block = false ) = 0;
498 
507  virtual bool insertText ( const Cursor &position, const QStringList &text, bool block = false ) = 0;
508 
517  virtual bool replaceText ( const Range &range, const QString &text, bool block = false );
518 
527  virtual bool replaceText ( const Range &range, const QStringList &text, bool block = false );
528 
536  virtual bool removeText ( const Range &range, bool block = false ) = 0;
537 
545  virtual bool cursorInText(const Cursor &cursor);
546 
559  virtual bool insertLine ( int line, const QString &text ) = 0;
560 
573  virtual bool insertLines ( int line, const QStringList &text ) = 0;
574 
581  virtual bool removeLine ( int line ) = 0;
582 
583  /*
584  * SIGNALS
585  * Following signals should be emitted by the document if the text content
586  * is changed.
587  */
588  Q_SIGNALS:
594  void textChanged(KTextEditor::Document *document);
595 
604  void textInserted(KTextEditor::Document *document, const KTextEditor::Range& range);
605 
613  void textRemoved(KTextEditor::Document *document, const KTextEditor::Range& range);
614 
623  void textRemoved(KTextEditor::Document *document, const KTextEditor::Range& range, const QString& oldText);
624 
635  void textChanged(KTextEditor::Document *document, const KTextEditor::Range& oldRange, const KTextEditor::Range& newRange);
636 
648  void textChanged(KTextEditor::Document *document, const KTextEditor::Range& oldRange, const QString& oldText, const KTextEditor::Range& newRange);
649 
659  void aboutToClose(KTextEditor::Document *document);
660 
670  void aboutToReload(KTextEditor::Document *document);
671 
681  void reloaded(KTextEditor::Document *document);
682 
692  void exclusiveEditStart(KTextEditor::Document *document);
693 
700  void exclusiveEditEnd(KTextEditor::Document *document);
701 
702  /*
703  * Access to the mode/highlighting subsystem
704  */
705  public:
711  virtual QString mode() const = 0;
712 
718  virtual QString highlightingMode() const = 0;
719 
725  virtual QStringList modes() const = 0;
726 
732  virtual QStringList highlightingModes() const = 0;
733 
740  virtual bool setMode(const QString &name) = 0;
741 
748  virtual bool setHighlightingMode(const QString &name) = 0;
749 
758  virtual QString highlightingModeSection( int index ) const = 0;
759 
768  virtual QString modeSection( int index ) const = 0;
769 
770  /*
771  * SIGNALS
772  * Following signals should be emitted by the document if the mode
773  * of the document changes
774  */
775  Q_SIGNALS:
783  void modeChanged(KTextEditor::Document *document);
784 
792  void highlightingModeChanged(KTextEditor::Document *document);
793 
794  private:
795  class DocumentPrivate* const d;
796 
797  public:
805  void setSuppressOpeningErrorDialogs(bool suppress);
806  bool suppressOpeningErrorDialogs() const;
811  bool openingError() const;
812  QString openingErrorMessage() const;
813 
814  protected:
815  void setOpeningError(bool errors);
816  void setOpeningErrorMessage(const QString& message);
817 };
818 
819 }
820 
821 Q_DECLARE_METATYPE(KTextEditor::Document*)
822 
823 #endif
824 
825 // kate: space-indent on; indent-width 2; replace-tabs on;
826 
saveAs
KAction * saveAs(const QObject *recvr, const char *slot, QObject *parent)
cursor.h
QWidget
KTextEditor::editor
KTEXTEDITOR_EXPORT Editor * editor(const char *libname)
Helper function for the EditorChooser.
Definition: ktexteditor.cpp:174
QString
KTextEditor::Cursor::start
static Cursor start()
Returns a cursor representing the start of any document - i.e., line 0, column 0. ...
Definition: cursor.cpp:57
QObject
KTextEditor::Cursor
An object which represents a position in a Document.
Definition: cursor.h:55
KParts::ReadWritePart
range.h
ktexteditor_export.h
KTextEditor::Document
A KParts derived class representing a text document.
Definition: document.h:111
QStringList
clear
KAction * clear(const QObject *recvr, const char *slot, QObject *parent)
KTEXTEDITOR_EXPORT
#define KTEXTEDITOR_EXPORT
Definition: ktexteditor_export.h:35
KTextEditor::Document::documentRange
Range documentRange() const
A Range which encompasses the whole document.
Definition: document.h:435
KTextEditor::Range
An object representing a section of text, from one Cursor to another.
Definition: range.h:54
KTextEditor::Editor
Accessor interface for Editor part.
Definition: editor.h:102
KTextEditor::View
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:145
part.h
QList
KTextEditor::Document::endOfLine
Cursor endOfLine(int line) const
Get the end cursor position of line line.
Definition: document.h:464
This file is part of the KDE documentation.
Documentation copyright © 1996-2014 The KDE developers.
Generated on Tue Oct 14 2014 22:31:41 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KTextEditor

Skip menu "KTextEditor"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Modules
  • Related Pages

applications API Reference

Skip menu "applications API Reference"
  •   kate
  •       kate
  •   KTextEditor
  •   Kate
  • Applications
  •   Libraries
  •     libkonq
  • Konsole

Search



Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal