# class KTextEditor.Document

### abstract class

Table of contents
Modules
ktexteditor Classes
All Classes

Module | ktexteditor
Namespace | ktexteditor
Class | KTextEditor.Document
Inherits | KParts.ReadWritePart

A KParts derived class representing a text document.

Topics: - doc_intro - doc_manipulation - doc_views - doc_extensions

Introduction

The Document class represents a pure text document providing methods to modify the content and create views. A document can have any number of views, each view representing the same content, i.e. all views are synchronized. Support for text selection is handeled by a View and text format attribues by the Attribute class.

To load a document call KParts.ReadOnlyPart.openUrl(). To reload a document from a file call documentReload(), to save the document call documentSave() or documentSaveAs(). Whenever the modified state of the document changes the signal modifiedChanged() is emitted. Check the modified state with KParts.ReadWritePart.isModified(). Further signals are documentUrlChanged(). The encoding can be specified with setEncoding(), however this will only take effect on file reload and file save.

Text Manipulation

Get the whole content with text() and set new content with setText(). Call insertText() or insertLine() to insert new text or removeText() and removeLine() to remove content. Whenever the document's content changed the signal textChanged() is emitted. Additional signals are textInserted() and textRemoved().

If the editor part supports it a document provides full undo/redo history. Text manipulation actions can be grouped together using startEditing() and endEditing(). All actions inbetween are grouped together to only one undo/redo action. Due to internal reference counting you can call startEditing() and endEditing() as often as you wish, but make sure you call endEditing() exactly as often as you call startEditing(), otherwise the reference counter gets confused.

Document Views

A View displays the document's content. As already mentioned a document can have any number of views, all synchronized. Get a list of all views with views(). Only one of the views can be active (i.e. has focus), get it by using activeView(). Create a new view with createView(). Everytime a new view is created the signal viewCreated() is emitted.

Document Extension Interfaces

A simple document represents text and provides text manipulation methods. However, a real text editor should support advanced concepts like session support, textsearch support, bookmark/general mark support etc. That is why the KTextEditor library provides several additional interfaces to extend a document's capabilities via multiple inheritance.

More information about interfaces for the document can be found in kte_group_doc_extensions.

See also KParts.ReadWritePart, KTextEditor.Editor, KTextEditor.View, KTextEditor.MarkInterface, KTextEditor.ModificationInterface, KTextEditor.SearchInterface, KTextEditor.SessionConfigInterface, KTextEditor.SmartInterface, KTextEditor.VariableInterface Author Christoph Cullmann \<cullmann@kde.org\>

### methods

- Document (parent)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  parent | QObject | None

  Constructor.

  Create a new document with parent.

  parent - parent object

  See also Editor.createDocument()

- aboutToClose (document) signal

  returns nothing
  SIGNAL ("aboutToClose (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  Warn anyone listening that the current document is about to close. At this point all of the information is still accessible, such as the text, cursors and ranges.

  Any modifications made to the document at this point will be lost.

  document - the document being closed

- activeView ()

  returns (KTextEditor.View)
  pure virtual

  Return the view which currently has user focus, if any.

- character (position)

  returns (QChar)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  position | KTextEditor.Cursor |

  Get the character at cursor.

  position - the location of the character to retrieve Returns the requested character, or QChar() for invalid cursors.

  See also setText()

- clear ()

  returns (bool)
  pure virtual

  Remove the whole content of the document. Returns true on success, otherwise false

  See also removeText(), removeLine()

- createView (parent)

  returns (KTextEditor.View)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  parent | QWidget |

  Create a new view attached to parent.

  parent - parent widget Returns the new view

- cursorInText (cursor)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.Cursor |

  Checks whether the cursor specifies a valid position in a document. It can optionally be overridden by an implementation.

  cursor - which should be checked Returns true, if the cursor is valid, otherwise false

  See also SmartCursor.isValid()

- documentEnd ()

  returns (KTextEditor.Cursor)
  pure virtual

  End position of the document. Returns The last column on the last line of the document

  See also all()

- documentName ()

  returns (QString)
  pure virtual

  Get this document's name. The editor part should provide some meaningful name, like some unique "Untitled XYZ" for the document - without URL or basename for documents with url. Returns readable document name

- documentNameChanged (document) signal

  returns nothing
  SIGNAL ("documentNameChanged (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  This signal is emitted whenever the document name changes.

  document - document which changed its name

  See also documentName()

- documentRange ()

  returns (KTextEditor.Range)

  A Range which encompasses the whole document. Returns A range from the start to the end of the document

- documentReload ()

  returns (bool)
  pure virtual

  Reload the current file. The user will be prompted by the part on changes and more and can cancel this action if it can harm. Returns true if the reload has been done, otherwise false. If the document has no url set, it will just return false.

- documentSave ()

  returns (bool)
  pure virtual

  Save the current file. The user will be asked for a filename if needed and more. Returns true on success, i.e. the save has been done, otherwise false

- documentSaveAs ()

  returns (bool)
  pure virtual

  Save the current file to another location. The user will be asked for a filename and more. Returns true on success, i.e. the save has been done, otherwise false

- documentUrlChanged (document) signal

  returns nothing
  SIGNAL ("documentUrlChanged (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  This signal is emitted whenever the document URL changes.

  document - document which changed its URL

  See also KParts.ReadOnlyPart.url()

- editor ()

  returns (KTextEditor.Editor)
  pure virtual

  Get the global editor object. The editor part implementation must ensure that this object exists as long as any factory or document object exists. Returns global KTextEditor.Editor object

  See also KTextEditor.Editor

- encoding ()

  returns (QString)
  pure virtual

  Get the current chosen encoding. The return value is an empty string, if the document uses the default encoding of the editor and no own special encoding. Returns current encoding of the document

  See also setEncoding()

- endEditing ()

  returns (bool)
  pure virtual

  End an editing sequence. Returns true on success, otherwise false. Parts not supporting it should return false.

  See also startEditing() for more details

- endOfLine (line)

  returns (KTextEditor.Cursor)

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Get the end cursor position of line line.

  line - line

  See also lineLength(), line()

- highlightingMode ()

  returns (QString)
  pure virtual

  Return the name of the currently used mode Returns name of the used mode

  See also highlightingModes(), setHighlightingMode()

- highlightingModeChanged (document) signal

  returns nothing
  SIGNAL ("highlightingModeChanged (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  Warn anyone listening that the current document's highlighting mode has changed.

  document - the document which's mode has changed

  See also setHighlightingMode()

- highlightingModes ()

  returns (QStringList)
  pure virtual

  Return a list of the names of all possible modes Returns list of mode names

  See also highlightingMode(), setHighlightingMode()

- insertLine (line, text)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  line | int |
  text | QString |

  Insert line(s) at the given line number. The newline character '\\n' is treated as line delimiter, so it is possible to insert multiple lines. To append lines at the end of the document, use

      insertLine( numLines(), text )

  line - line where to insert the text

  text - text which should be inserted Returns true on success, otherwise false

  See also insertText()

- insertLines (line, text)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  line | int |
  text | QStringList |

  Insert line(s) at the given line number. The newline character '\\n' is treated as line delimiter, so it is possible to insert multiple lines. To append lines at the end of the document, use

      insertLine( numLines(), text )

  line - line where to insert the text

  text - text which should be inserted Returns true on success, otherwise false

  See also insertText()

- insertText (position, text, block)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  position | KTextEditor.Cursor |
  text | QString |
  block | bool | False

  Insert text at position.

  position - position to insert the text

  text - text to insert

  block - insert this text as a visual block of text rather than a linear sequence Returns true on success, otherwise false

  See also setText(), removeText()

- insertText (position, text, block)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  position | KTextEditor.Cursor |
  text | QStringList |
  block | bool | False

  Insert text at position.

  position - position to insert the text

  text - text to insert

  block - insert this text as a visual block of text rather than a linear sequence Returns true on success, otherwise false

  See also setText(), removeText()

- isEmpty ()

  returns (bool)

  Returns if the document is empty.

- line (line)

  returns (QString)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Get a single text line.

  line - the wanted line Returns the requested line, or "" for invalid line numbers

  See also text(), lineLength()

- lineLength (line)

  returns (int)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Get the length of a given line in characters.

  line - line to get length from Returns the number of characters in the line or -1 if the line was invalid

  See also line()

- lines ()

  returns (int)
  pure virtual

  Get the count of lines of the document. Returns the current number of lines in the document

  See also length()

- mimeType ()

  returns (QString)
  pure virtual

  Get this document's mimetype. Returns mimetype

- mode ()

  returns (QString)
  pure virtual

  Return the name of the currently used mode Returns name of the used mode

  See also modes(), setMode()

- modeChanged (document) signal

  returns nothing
  SIGNAL ("modeChanged (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  Warn anyone listening that the current document's mode has changed.

  document - the document whose mode has changed

  See also setMode()

- modes ()

  returns (QStringList)
  pure virtual

  Return a list of the names of all possible modes Returns list of mode names

  See also mode(), setMode()

- modifiedChanged (document) signal

  returns nothing
  SIGNAL ("modifiedChanged (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  This signal is emitted whenever the document's buffer changed from either state unmodified to modified or vice versa.

  document - document which changed its modified state

  See also KParts.ReadWritePart.isModified().

  See also KParts.ReadWritePart.setModified()

- openingError ()

  returns (bool)

  True, eg if the file for opening could not be read This doesn't have to handle the KPart job cancled cases

- openingErrorMessage ()

  returns (QString)

- removeLine (line)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Remove line from the document.

  line - line to remove Returns true on success, otherwise false

  See also removeText(), clear()

- removeText (range, block)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |
  block | bool | False

  Remove the text specified in range.

  range - range of text to remove

  block - set this to true to remove a text block on the basis of columns, rather than everything inside range Returns true on success, otherwise false

  See also setText(), insertText()

- replaceText (range, text, block)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |
  text | QString |
  block | bool | False

  Replace text from range with specified text.

  range - range of text to replace

  text - text to replace with

  block - replace text as a visual block of text rather than a linear sequence Returns true on success, otherwise false

  See also setText(), removeText(), insertText()

- replaceText (range, text, block)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |
  text | QStringList |
  block | bool | False

  Replace text from range with specified text.

  range - range of text to replace

  text - text to replace with

  block - replace text as a visual block of text rather than a linear sequence Returns true on success, otherwise false

  See also setText(), removeText(), insertText()

- setEncoding (encoding)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  encoding | QString |

  Set the encoding for this document. This encoding will be used while loading and saving files, it will not affect the already existing content of the document, e.g. if the file has already been opened without the correct encoding, this will not fix it, you would for example need to trigger a reload for this.

  encoding - new encoding for the document, the name must be accepted by QTextCodec, if an empty encoding name is given, the part should fallback to its own default encoding, e.g. the system encoding or the global user settings Returns true on success, or false, if the encoding could not be set.

  See also encoding()

- setHighlightingMode (name)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  name | QString |

  Set the current mode of the document by giving its name

  name - name of the mode to use for this document Returns true on success, otherwise false

  See also highlightingMode(), highlightingModes(), highlightingModeChanged()

- setMode (name)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  name | QString |

  Set the current mode of the document by giving its name

  name - name of the mode to use for this document Returns true on success, otherwise false

  See also mode(), modes(), modeChanged()

- setOpeningError (errors)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  errors | bool |

- setOpeningErrorMessage (message)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  message | QString |

- setSuppressOpeningErrorDialogs (suppress)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  suppress | bool |

  by default dialogs should be displayed. In any case (dialog shown or suppressed) openingErrors and openingErrorMessage should have meaningfull values

  suppress - true/false value if dialogs should be displayed

- setText (text)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  text | QString |

  Set the given text as new document content.

  text - new content for the document Returns true on success, otherwise false

  See also text()

- setText (text)

  returns (bool)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  text | QStringList |

  Set the given text as new document content.

  text - new content for the document Returns true on success, otherwise false

  See also text()

- startEditing ()

  returns (bool)
  pure virtual

  Begin an editing sequence. Edit commands during this sequence will be bunched together so that they represent a single undo command in the editor, and so that repaint events do not occur inbetween.

  Your application should not return control to the event loop while it has an unterminated (i.e. no matching endEditing() call) editing sequence (result undefined) - so do all of your work in one go!

  This call stacks, like the endEditing() calls, this means you can safely call it three times in a row for example if you call endEditing() three times, too, it internaly just does counting the running editing sessions.

  If the texteditor part does not support these transactions, both calls just do nothing.

  Returns true on success, otherwise false. Parts not supporting it should return false

  See also endEditing()

- suppressOpeningErrorDialogs ()

  returns (bool)

- text ()

  returns (QString)
  pure virtual

  Get the document content. Returns the complete document content

  See also setText()

- text (range, block)

  returns (QString)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |
  block | bool | False

  Get the document content within the given range.

  range - the range of text to retrieve

  block - Set this to true to receive text in a visual block, rather than everything inside range. Returns the requested text part, or QString() for invalid ranges.

  See also setText()

- textChanged (document) signal

  returns nothing
  SIGNAL ("textChanged (KTextEditor.Document*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |

  The document emits this signal whenever its text changes.

  document - document which emitted this signal

  See also text(), textLine()

- textChanged (document, oldRange, newRange) signal

  returns nothing
  SIGNAL ("textChanged (KTextEditor.Document*, const KTextEditor.Range&, const KTextEditor.Range&)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |
  oldRange | KTextEditor.Range |
  newRange | KTextEditor.Range |

  The document emits this signal whenever the text in range oldRange was removed and replaced with the text now in newRange, e.g. the user selects text and pastes new text to replace the selection. oldRange.start() is guaranteed to equal newRange.start().

  document - document which emitted this signal

  oldRange - range that the text previously occupied

  newRange - range that the changed text now occupies

  See also insertText(), insertLine(), removeText(), removeLine(), clear()

- textInserted (document, range) signal

  returns nothing
  SIGNAL ("textInserted (KTextEditor.Document*, const KTextEditor.Range&)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |
  range | KTextEditor.Range |

  The document emits this signal whenever text was inserted. The insertion occurred at range.start(), and new text now occupies up to range.end().

  document - document which emitted this signal

  range - range that the newly inserted text occupies

  See also insertText(), insertLine()

- textLines (range, block)

  returns (QStringList)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |
  block | bool | False

  Get the document content within the given range.

  range - the range of text to retrieve

  block - Set this to true to receive text in a visual block, rather than everything inside range. Returns the requested text lines, or QStringList() for invalid ranges. no end of line termination is included.

  See also setText()

- textRemoved (document, range) signal

  returns nothing
  SIGNAL ("textRemoved (KTextEditor.Document*, const KTextEditor.Range&)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |
  range | KTextEditor.Range |

  The document emits this signal whenever range was removed, i.e. text was removed.

  document - document which emitted this signal

  range - range that the removed text previously occupied

  See also removeText(), removeLine(), clear()

- totalCharacters ()

  returns (int)
  pure virtual

  Get the count of characters in the document. A TAB character counts as only one character. Returns the number of characters in the document

  See also lines()

- viewCreated (document, view) signal

  returns nothing
  SIGNAL ("viewCreated (KTextEditor.Document*, KTextEditor.View*)")

  Argument | Type | Default
  --- | --- | ---
  document | KTextEditor.Document |
  view | KTextEditor.View |

  This signal is emitted whenever the document creates a new view. It should be called for every view to help applications / plugins to attach to the view. \attention This signal should be emitted after the view constructor is completed, e.g. in the createView() method.

  document - the document for which a new view is created

  view - the new view

  See also createView()

- views ()

  returns (list of KTextEditor.View)
  pure virtual

  Returns the views pre-casted to KTextEditor.View%s