KTextEditor::Document

KTextEditor::Document Class Referenceabstract

#include <KTextEditor/Document>

Inheritance diagram for KTextEditor::Document:

Classes

class  EditingTransaction
 

Public Member Functions

virtual ~Document ()
 
Printing
virtual bool print ()=0
 
virtual void printPreview ()=0
 
Showing Interactive Notifications
virtual bool postMessage (Message *message)=0
 
Session Configuration
virtual void readSessionConfig (const KConfigGroup &config, const QSet< QString > &flags=QSet< QString >())=0
 
virtual void writeSessionConfig (KConfigGroup &config, const QSet< QString > &flags=QSet< QString >())=0
 
Crash Recovery
virtual bool isDataRecoveryAvailable () const =0
 
virtual void recoverData ()=0
 
virtual void discardDataRecovery ()=0
 
- Public Member Functions inherited from KParts::ReadWritePart
 ReadWritePart (QObject *parent=nullptr)
 
virtual bool closeUrl (bool promptToSave)
 
bool closeUrl () override
 
bool isModified () const
 
bool isReadWrite () const
 
virtual bool queryClose ()
 
virtual bool saveAs (const QUrl &url)
 
virtual void setModified (bool modified)
 
virtual void setReadWrite (bool readwrite=true)
 
- Public Member Functions inherited from KParts::ReadOnlyPart
 ReadOnlyPart (QObject *parent=nullptr)
 
OpenUrlArguments arguments () const
 
BrowserExtensionbrowserExtension () const
 
bool closeStream ()
 
bool isProgressInfoEnabled () const
 
bool openStream (const QString &mimeType, const QUrl &url)
 
void setArguments (const OpenUrlArguments &arguments)
 
void setProgressInfoEnabled (bool show)
 
void showProgressInfo (bool show)
 
QUrl url () const
 
bool writeStream (const QByteArray &data)
 
- Public Member Functions inherited from KParts::Part
 Part (QObject *parent=nullptr)
 
virtual void embed (QWidget *parentWidget)
 
virtual ParthitTest (QWidget *widget, const QPoint &globalPos)
 
KIconLoadericonLoader ()
 
bool isSelectable () const
 
PartManagermanager () const
 
void setAutoDeletePart (bool autoDeletePart)
 
void setAutoDeleteWidget (bool autoDeleteWidget)
 
virtual void setManager (PartManager *manager)
 
virtual void setSelectable (bool selectable)
 
virtual QWidgetwidget ()
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 
- Public Member Functions inherited from KParts::PartBase
void setPartObject (QObject *object)
 
- Public Member Functions inherited from KXMLGUIClient
 KXMLGUIClient (KXMLGUIClient *parent)
 
QActionaction (const char *name) const
 
virtual QActionaction (const QDomElement &element) const
 
virtual KActionCollectionactionCollection () const
 
QList< KXMLGUIClient * > childClients ()
 
KXMLGUIBuilderclientBuilder () const
 
virtual QString componentName () const
 
virtual QDomDocument domDocument () const
 
KXMLGUIFactoryfactory () const
 
void insertChildClient (KXMLGUIClient *child)
 
KXMLGUIClientparentClient () const
 
void plugActionList (const QString &name, const QList< QAction * > &actionList)
 
void reloadXML ()
 
void removeChildClient (KXMLGUIClient *child)
 
void replaceXMLFile (const QString &xmlfile, const QString &localxmlfile, bool merge=false)
 
void setClientBuilder (KXMLGUIBuilder *builder)
 
void setFactory (KXMLGUIFactory *factory)
 
void setXMLGUIBuildDocument (const QDomDocument &doc)
 
void unplugActionList (const QString &name)
 
virtual QString xmlFile () const
 
QDomDocument xmlguiBuildDocument () const
 

Protected Member Functions

 Document (DocumentPrivate *impl, QObject *parent)
 
- Protected Member Functions inherited from KParts::ReadWritePart
virtual bool saveFile ()=0
 
virtual bool saveToUrl ()
 
- Protected Member Functions inherited from KParts::ReadOnlyPart
void abortLoad ()
 
virtual bool doCloseStream ()
 
virtual bool doOpenStream (const QString &mimeType)
 
virtual bool doWriteStream (const QByteArray &data)
 
void guiActivateEvent (GUIActivateEvent *event) override
 
bool isLocalFileTemporary () const
 
QString localFilePath () const
 
virtual bool openFile ()
 
void setLocalFilePath (const QString &localFilePath)
 
void setLocalFileTemporary (bool temp)
 
void setUrl (const QUrl &url)
 
- Protected Member Functions inherited from KParts::Part
void customEvent (QEvent *event) override
 
QWidgethostContainer (const QString &containerName)
 
void loadPlugins ()
 
virtual void partActivateEvent (PartActivateEvent *event)
 
virtual void partSelectEvent (PartSelectEvent *event)
 
virtual void setWidget (QWidget *widget)
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 
- Protected Member Functions inherited from KParts::PartBase
void loadPlugins (QObject *parent, KXMLGUIClient *parentGUIClient, const KAboutData &aboutData)
 
virtual void setComponentData (const KAboutData &componentData)
 
virtual void setComponentData (const KAboutData &pluginData, bool loadPlugins)
 
void setPluginInterfaceVersion (int version)
 
void setPluginLoadingMode (PluginLoadingMode loadingMode)
 
- Protected Member Functions inherited from KXMLGUIClient
void loadStandardsXmlFile ()
 
virtual void setComponentName (const QString &componentName, const QString &componentDisplayName)
 
virtual void setDOMDocument (const QDomDocument &document, bool merge=false)
 
virtual void setLocalXMLFile (const QString &file)
 
virtual void setXML (const QString &document, bool merge=false)
 
virtual void setXMLFile (const QString &file, bool merge=false, bool setXMLDoc=true)
 
virtual void stateChanged (const QString &newstate, ReverseStateChange reverse=StateNoReverse)
 

Manage Views of this Document

virtual ViewcreateView (QWidget *parent, KTextEditor::MainWindow *mainWindow=nullptr)=0
 
virtual QList< View * > views () const =0
 
void viewCreated (KTextEditor::Document *document, KTextEditor::View *view)
 

General Information about this Document

virtual QString documentName () const =0
 
virtual QString mimeType ()=0
 
virtual QByteArray checksum () const =0
 
virtual bool setEncoding (const QString &encoding)=0
 
virtual QString encoding () const =0
 
void documentNameChanged (KTextEditor::Document *document)
 
void documentUrlChanged (KTextEditor::Document *document)
 
void modifiedChanged (KTextEditor::Document *document)
 
void readWriteChanged (KTextEditor::Document *document)
 

File Loading and Saving

All this actions cause user interaction in some cases.

virtual bool documentReload ()=0
 
virtual bool documentSave ()=0
 
virtual bool documentSaveAs ()=0
 
bool openingError () const
 
QString openingErrorMessage () const
 
void documentSavedOrUploaded (KTextEditor::Document *document, bool saveAs)
 
void aboutToClose (KTextEditor::Document *document)
 
void aboutToReload (KTextEditor::Document *document)
 
void reloaded (KTextEditor::Document *document)
 

Text Manipulation

virtual bool isEditingTransactionRunning () const =0
 
virtual QString text () const =0
 
virtual QString text (const Range &range, bool block=false) const =0
 
virtual QChar characterAt (const Cursor &position) const =0
 
virtual QString wordAt (const KTextEditor::Cursor &cursor) const =0
 
virtual KTextEditor::Range wordRangeAt (const KTextEditor::Cursor &cursor) const =0
 
virtual bool isValidTextPosition (const KTextEditor::Cursor &cursor) const =0
 
virtual QStringList textLines (const Range &range, bool block=false) const =0
 
virtual QString line (int line) const =0
 
virtual int lines () const =0
 
virtual bool isLineModified (int line) const =0
 
virtual bool isLineSaved (int line) const =0
 
virtual bool isLineTouched (int line) const =0
 
virtual Cursor documentEnd () const =0
 
Range documentRange () const
 
virtual int totalCharacters () const =0
 
virtual bool isEmpty () const
 
virtual int lineLength (int line) const =0
 
Cursor endOfLine (int line) const
 
virtual bool setText (const QString &text)=0
 
virtual bool setText (const QStringList &text)=0
 
virtual bool clear ()=0
 
virtual bool insertText (const Cursor &position, const QString &text, bool block=false)=0
 
virtual bool insertText (const Cursor &position, const QStringList &text, bool block=false)=0
 
virtual bool replaceText (const Range &range, const QString &text, bool block=false)
 
virtual bool replaceText (const Range &range, const QStringList &text, bool block=false)
 
virtual bool removeText (const Range &range, bool block=false)=0
 
virtual bool insertLine (int line, const QString &text)=0
 
virtual bool insertLines (int line, const QStringList &text)=0
 
virtual bool removeLine (int line)=0
 
QVector< KTextEditor::RangesearchText (const KTextEditor::Range &range, const QString &pattern, const SearchOptions options=Default) const
 
void editingStarted (KTextEditor::Document *document)
 
void editingFinished (KTextEditor::Document *document)
 
void lineWrapped (KTextEditor::Document *document, const KTextEditor::Cursor &position)
 
void lineUnwrapped (KTextEditor::Document *document, int line)
 
void textInserted (KTextEditor::Document *document, const KTextEditor::Cursor &position, const QString &text)
 
void textRemoved (KTextEditor::Document *document, const KTextEditor::Range &range, const QString &text)
 
void textChanged (KTextEditor::Document *document)
 

Highlighting and Related Information

virtual DefaultStyle defaultStyleAt (const KTextEditor::Cursor &position) const =0
 
virtual QString mode () const =0
 
virtual QString highlightingMode () const =0
 
virtual QStringList embeddedHighlightingModes () const =0
 
virtual QString highlightingModeAt (const Cursor &position)=0
 
virtual QStringList modes () const =0
 
virtual QStringList highlightingModes () const =0
 
virtual bool setMode (const QString &name)=0
 
virtual bool setHighlightingMode (const QString &name)=0
 
virtual QString highlightingModeSection (int index) const =0
 
virtual QString modeSection (int index) const =0
 
void modeChanged (KTextEditor::Document *document)
 
void highlightingModeChanged (KTextEditor::Document *document)
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Signals inherited from KParts::ReadWritePart
void sigQueryClose (bool *handled, bool *abortClosing)
 
- Signals inherited from KParts::ReadOnlyPart
void canceled (const QString &errMsg)
 
void completed ()
 
void completed (bool pendingAction)
 
void started (KIO::Job *job)
 
void urlChanged (const QUrl &url)
 
- Signals inherited from KParts::Part
void setStatusBarText (const QString &text)
 
void setWindowCaption (const QString &caption)
 
- Public Slots inherited from KParts::ReadWritePart
virtual bool save ()
 
void setModified ()
 
bool waitSaveComplete ()
 
- Public Slots inherited from KParts::ReadOnlyPart
virtual bool openUrl (const QUrl &url)
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Types inherited from KParts::PartBase
enum  PluginLoadingMode
 
- Protected Slots inherited from KParts::Part
void slotWidgetDestroyed ()
 
- Static Protected Member Functions inherited from KXMLGUIClient
static QString standardsXmlFileLocation ()
 
- Protected Attributes inherited from KParts::PartBase
 DoNotLoadPlugins
 
 LoadPlugins
 
 LoadPluginsIfEnabled
 

Detailed Description

A KParts derived class representing a text document.

Topics:

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 handled by a View and text format attributes 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(). Note, that the first line in the document is line 0.

A Document provides full undo/redo history. Text manipulation actions can be grouped together to one undo/redo action by using an the class EditingTransaction. You can stack multiple EditingTransactions. Internally, the Document has a reference counter. If this reference counter is increased the first time (by creating an instance of EditingTransaction), the signal editingStarted() is emitted. Only when the internal reference counter reaches zero again, the signal editingFinished() and optionally the signal textChanged() are emitted. Whether an editing transaction is currently active can be checked by calling isEditingTransactionRunning().

Note
The signal editingFinished() is always emitted when the last instance of EditingTransaction is destroyed. Contrary, the signal textChanged() is emitted only if text changed. Hence, textChanged() is more accurate with respect to changes in the Document.

Every text editing transaction is also available through the signals lineWrapped(), lineUnwrapped(), textInserted() and textRemoved(). However, these signals should be used with care. Please be aware of the following warning:

Warning
Never change the Document's contents when edit actions are active, i.e. in between of (foreign) editing transactions. In case you violate this, the currently active edit action may perform edits that lead to undefined behavior.

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(). Create a new view with createView(). Every time a new view is created the signal viewCreated() is emitted.

Read-Only Mode

A Document may be in read-only mode, for instance due to missing file permissions. The read-only mode can be checked with isReadWrite(). Further, the signal readWriteChanged() is emitted whenever the state changes either to read-only mode or to read/write mode. The read-only mode can be controlled with setReadWrite().

Notifications in Documents and Views

A Document has the ability to show a Message to the user in a View. The Message then is shown either the specified View if Message::setView() was called, or in all Views of the Document.

To post a message just create a new Message and send it with postMessage(). Further information is available in the API documentation of Message.

See also
Message

Crash Recovery for Documents

When the system or the application using the editor component crashed with unsaved changes in the Document, the View notifies the user about the lost data and asks, whether the data should be recovered.

This Document gives you control over the data recovery process. Use isDataRecoveryAvailable() to check for lost data. If you do not want the editor component to handle the data recovery process automatically, you can either trigger the data recovery by calling recoverData() or discard it through discardDataRecovery().

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 Document Extension Interfaces.

See also
KParts::ReadWritePart, KTextEditor::Editor, KTextEditor::View, KTextEditor::MarkInterface, KTextEditor::ModificationInterface, KTextEditor::MovingInterface
Author
Christoph Cullmann <cullm[email protected][email protected][email protected]kde.o[email protected]rg>

Definition at line 199 of file document.h.

Constructor & Destructor Documentation

Document::Document ( DocumentPrivate *  impl,
QObject parent 
)
protected

Constructor.

Create a new document with parent.

Pass it the internal implementation to store a d-pointer.

Parameters
impld-pointer to use
parentparent object
See also
Editor::createDocument()

Definition at line 26 of file document.cpp.

Document::~Document ( )
virtual

Virtual destructor.

Definition at line 32 of file document.cpp.

Member Function Documentation

void KTextEditor::Document::aboutToClose ( KTextEditor::Document document)
signal

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.

Parameters
documentthe document being closed
void KTextEditor::Document::aboutToReload ( KTextEditor::Document document)
signal

Warn anyone listening that the current document is about to reload.

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.

Parameters
documentthe document being reloaded
virtual QChar KTextEditor::Document::characterAt ( const Cursor position) const
pure virtual

Get the character at text position cursor.

Parameters
positionthe location of the character to retrieve
Returns
the requested character, or QChar() for invalid cursors.
See also
setText()
virtual QByteArray KTextEditor::Document::checksum ( ) const
pure virtual

Get the git hash of the Document's contents on disk.

The returned hash equals the git hash of the file written to disk. If the document is a remote document, the checksum may not be available. In this case, QByteArray::isNull() returns true.

git hash is defined as:

sha1("blob " + filesize + "\0" + filecontent)

Returns
the git hash of the document
virtual bool KTextEditor::Document::clear ( )
pure virtual

Remove the whole content of the document.

Returns
true on success, otherwise false
See also
removeText(), removeLine()
virtual View* KTextEditor::Document::createView ( QWidget parent,
KTextEditor::MainWindow mainWindow = nullptr 
)
pure virtual

Create a new view attached to parent.

Parameters
parentparent widget
mainWindowthe main window responsible for this view, if any
Returns
the new view
virtual DefaultStyle KTextEditor::Document::defaultStyleAt ( const KTextEditor::Cursor position) const
pure virtual

Get the default style of the character located at position.

If position is not a valid text position, the default style DefaultStyle::dsNormal is returned.

Note
Further information about the colors of default styles depend on the currently chosen schema. Since each View may have a different color schema, the color information can be obtained through View::defaultStyleAttribute() and View::lineAttributes().
Parameters
positiontext position
Returns
default style, see enum KTextEditor::DefaultStyle
See also
View::defaultStyleAttribute(), View::lineAttributes()
virtual void KTextEditor::Document::discardDataRecovery ( )
pure virtual

If recover data is available, calling discardDataRecovery() will discard the recover data and the recover data is lost.

If isDataRecoveryAvailable() returns false, calling this function does nothing.

See also
isDataRecoveryAvailable(), recoverData()
virtual Cursor KTextEditor::Document::documentEnd ( ) const
pure virtual

End position of the document.

Returns
The last column on the last line of the document
See also
all()
virtual QString KTextEditor::Document::documentName ( ) const
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
void KTextEditor::Document::documentNameChanged ( KTextEditor::Document document)
signal

This signal is emitted whenever the document name changes.

Parameters
documentdocument which changed its name
See also
documentName()
Range KTextEditor::Document::documentRange ( ) const
inline

A Range which encompasses the whole document.

Returns
A range from the start to the end of the document

Definition at line 693 of file document.h.

virtual bool KTextEditor::Document::documentReload ( )
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.
virtual bool KTextEditor::Document::documentSave ( )
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
virtual bool KTextEditor::Document::documentSaveAs ( )
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
void KTextEditor::Document::documentSavedOrUploaded ( KTextEditor::Document document,
bool  saveAs 
)
signal

This signal should be emitted after a document has been saved to disk or for remote files uploaded.

saveAs should be set to true, if the operation is a save as operation

void KTextEditor::Document::documentUrlChanged ( KTextEditor::Document document)
signal

This signal is emitted whenever the document URL changes.

Parameters
documentdocument which changed its URL
See also
KParts::ReadOnlyPart::url()
void KTextEditor::Document::editingFinished ( KTextEditor::Document document)
signal

Editing transaction has finished.

Note
This signal is emitted also for editing actions that maybe do not modify the document contents (think of having an empty EditingTransaction). If you want to get notified only after text really changed, connect to the signal textChanged().
Parameters
documentdocument which emitted this signal
See also
textChanged()
void KTextEditor::Document::editingStarted ( KTextEditor::Document document)
signal

Editing transaction has started.

Parameters
documentdocument which emitted this signal
virtual QStringList KTextEditor::Document::embeddedHighlightingModes ( ) const
pure virtual

Get all available highlighting modes for the current document.

Each document can be highlighted using an arbitrary number of highlighting contexts. This method will return the names for each of the used modes.

Example: The "PHP (HTML)" mode includes the highlighting for PHP, HTML, CSS and JavaScript.

Returns
Returns a list of embedded highlighting modes for the current Document.
See also
KTextEditor::Document::highlightingMode()
virtual QString KTextEditor::Document::encoding ( ) const
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()
Cursor KTextEditor::Document::endOfLine ( int  line) const
inline

Get the end cursor position of line line.

Parameters
lineline
See also
lineLength(), line()

Definition at line 725 of file document.h.

virtual QString KTextEditor::Document::highlightingMode ( ) const
pure virtual

Return the name of the currently used mode.

Returns
name of the used mode
See also
highlightingModes(), setHighlightingMode()
virtual QString KTextEditor::Document::highlightingModeAt ( const Cursor position)
pure virtual

Get the highlight mode used at a given position in the document.

Retrieve the name of the applied highlight mode at a given position in the current document.

Calling this might trigger re-highlighting up to the given line. Therefore this is not const.

See also
highlightingModes()
void KTextEditor::Document::highlightingModeChanged ( KTextEditor::Document document)
signal

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

Parameters
documentthe document which's mode has changed
See also
setHighlightingMode()
virtual QStringList KTextEditor::Document::highlightingModes ( ) const
pure virtual

Return a list of the names of all possible modes.

Returns
list of mode names
See also
highlightingMode(), setHighlightingMode()
virtual QString KTextEditor::Document::highlightingModeSection ( int  index) const
pure virtual

Returns the name of the section for a highlight given its index in the highlight list (as returned by highlightModes()).

You can use this function to build a tree of the highlight names, organized in sections.

Parameters
indexthe index of the highlight in the list returned by modes()
virtual bool KTextEditor::Document::insertLine ( int  line,
const QString text 
)
pure virtual

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

Parameters
lineline where to insert the text
texttext which should be inserted
Returns
true on success, otherwise false
See also
insertText()
virtual bool KTextEditor::Document::insertLines ( int  line,
const QStringList text 
)
pure virtual

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

Parameters
lineline where to insert the text
texttext which should be inserted
Returns
true on success, otherwise false
See also
insertText()
virtual bool KTextEditor::Document::insertText ( const Cursor position,
const QString text,
bool  block = false 
)
pure virtual

Insert text at position.

Parameters
positionposition to insert the text
texttext to insert
blockinsert this text as a visual block of text rather than a linear sequence
Returns
true on success, otherwise false
See also
setText(), removeText()
virtual bool KTextEditor::Document::insertText ( const Cursor position,
const QStringList text,
bool  block = false 
)
pure virtual

Insert text at position.

Parameters
positionposition to insert the text
texttext to insert
blockinsert this text as a visual block of text rather than a linear sequence
Returns
true on success, otherwise false
See also
setText(), removeText()
virtual bool KTextEditor::Document::isDataRecoveryAvailable ( ) const
pure virtual

Returns whether a recovery is available for the current document.

See also
recoverData(), discardDataRecovery()
virtual bool KTextEditor::Document::isEditingTransactionRunning ( ) const
pure virtual

Check whether an editing transaction is currently running.

See also
EditingTransaction
bool Document::isEmpty ( ) const
virtual

Returns if the document is empty.

Definition at line 128 of file document.cpp.

virtual bool KTextEditor::Document::isLineModified ( int  line) const
pure virtual

Check whether line currently contains unsaved data.

If line contains unsaved data, true is returned, otherwise false. When the user saves the file, a modified line turns into a saved line. In this case isLineModified() returns false and in its stead isLineSaved() returns true.

Parameters
lineline to query
See also
isLineSaved(), isLineTouched()
Since
5.0
virtual bool KTextEditor::Document::isLineSaved ( int  line) const
pure virtual

Check whether line currently contains only saved text.

Saved text in this case implies that a line was touched at some point by the user and then then changes were either undone or the user saved the file.

In case line was touched and currently contains only saved data, true is returned, otherwise false.

Parameters
lineline to query
See also
isLineModified(), isLineTouched()
Since
5.0
virtual bool KTextEditor::Document::isLineTouched ( int  line) const
pure virtual

Check whether line was touched since the file was opened.

This equals the statement isLineModified() || isLineSaved().

Parameters
lineline to query
See also
isLineModified(), isLineSaved()
Since
5.0
virtual bool KTextEditor::Document::isValidTextPosition ( const KTextEditor::Cursor cursor) const
pure virtual

Get whether cursor is a valid text position.

A cursor position at (line, column) is valid, if

  • line >= 0 and line < lines() holds, and
  • column >= 0 and column <= lineLength(column).

The text position cursor is also invalid if it is inside a Unicode surrogate. Therefore, use this function when iterating over the characters of a line.

Parameters
cursorcursor position to check for validity
Returns
true, if cursor is a valid text position, otherwise false
Since
5.0
virtual QString KTextEditor::Document::line ( int  line) const
pure virtual

Get a single text line.

Parameters
linethe wanted line
Returns
the requested line, or "" for invalid line numbers
See also
text(), lineLength()
virtual int KTextEditor::Document::lineLength ( int  line) const
pure virtual

Get the length of a given line in characters.

Parameters
lineline to get length from
Returns
the number of characters in the line or -1 if the line was invalid
See also
line()
virtual int KTextEditor::Document::lines ( ) const
pure virtual

Get the count of lines of the document.

Returns
the current number of lines in the document
See also
length()
void KTextEditor::Document::lineUnwrapped ( KTextEditor::Document document,
int  line 
)
signal

A line got unwrapped.

Parameters
documentdocument which emitted this signal
lineline where the unwrap occurred
void KTextEditor::Document::lineWrapped ( KTextEditor::Document document,
const KTextEditor::Cursor position 
)
signal

A line got wrapped.

Parameters
documentdocument which emitted this signal
positionposition where the wrap occurred
virtual QString KTextEditor::Document::mimeType ( )
pure virtual

Get this document's mimetype.

Returns
mimetype
virtual QString KTextEditor::Document::mode ( ) const
pure virtual

Return the name of the currently used mode.

Returns
name of the used mode
See also
modes(), setMode()
void KTextEditor::Document::modeChanged ( KTextEditor::Document document)
signal

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

Parameters
documentthe document whose mode has changed
See also
setMode()
virtual QStringList KTextEditor::Document::modes ( ) const
pure virtual

Return a list of the names of all possible modes.

Returns
list of mode names
See also
mode(), setMode()
virtual QString KTextEditor::Document::modeSection ( int  index) const
pure virtual

Returns the name of the section for a mode given its index in the highlight list (as returned by modes()).

You can use this function to build a tree of the mode names, organized in sections.

Parameters
indexthe index of the highlight in the list returned by modes()
void KTextEditor::Document::modifiedChanged ( KTextEditor::Document document)
signal

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

Parameters
documentdocument which changed its modified state
See also
KParts::ReadWritePart::isModified().
KParts::ReadWritePart::setModified()
bool Document::openingError ( ) const

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

Returns
was there some problem loading the file?

Definition at line 100 of file document.cpp.

QString Document::openingErrorMessage ( ) const

Error message if any problem occurred on last load.

Returns
error message what went wrong on loading

Definition at line 105 of file document.cpp.

virtual bool KTextEditor::Document::postMessage ( Message message)
pure virtual

Post message to the Document and its Views.

If multiple Messages are posted, the one with the highest priority is shown first.

Usually, you can simply forget the pointer, as the Message is deleted automatically, once it is processed or the document gets closed.

If the Document does not have a View yet, the Message is queued and shown, once a View for the Document is created.

Parameters
messagethe message to show
Returns
true, if message was posted. false, if message == 0.
virtual bool KTextEditor::Document::print ( )
pure virtual

Print the document.

This should result in showing the print dialog.

Returns
true if document was printed
virtual void KTextEditor::Document::printPreview ( )
pure virtual

Shows the print preview dialog/.

virtual void KTextEditor::Document::readSessionConfig ( const KConfigGroup config,
const QSet< QString > &  flags = QSetQString >() 
)
pure virtual

Read session settings from the given config.

Known flags:

  • SkipUrl => do not save/restore the file
  • SkipMode => do not save/restore the mode
  • SkipHighlighting => do not save/restore the highlighting
  • SkipEncoding => do not save/restore the encoding
Parameters
configread the session settings from this KConfigGroup
flagsadditional flags
See also
writeSessionConfig()
void KTextEditor::Document::readWriteChanged ( KTextEditor::Document document)
signal

This signal is emitted whenever the readWrite state of a document changes.

Parameters
documentthe document whose read/write property changed
See also
KParts::ReadWritePart::setReadWrite()
virtual void KTextEditor::Document::recoverData ( )
pure virtual

If recover data is available, calling recoverData() will trigger the recovery of the data.

If isDataRecoveryAvailable() returns false, calling this function does nothing.

See also
isDataRecoveryAvailable(), discardDataRecovery()
void KTextEditor::Document::reloaded ( KTextEditor::Document document)
signal

Emitted after the current document was reloaded.

At this point, some information might have been invalidated, like for example the editing history.

Parameters
documentthe document that was reloaded.
Since
4.6
virtual bool KTextEditor::Document::removeLine ( int  line)
pure virtual

Remove line from the document.

Parameters
lineline to remove
Returns
true on success, otherwise false
See also
removeText(), clear()
virtual bool KTextEditor::Document::removeText ( const Range range,
bool  block = false 
)
pure virtual

Remove the text specified in range.

Parameters
rangerange of text to remove
blockset 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()
bool KTextEditor::Document::replaceText ( const Range range,
const QString text,
bool  block = false 
)
virtual

Replace text from range with specified text.

Parameters
rangerange of text to replace
texttext to replace with
blockreplace text as a visual block of text rather than a linear sequence
Returns
true on success, otherwise false
See also
setText(), removeText(), insertText()

Definition at line 110 of file document.cpp.

virtual bool KTextEditor::Document::replaceText ( const Range range,
const QStringList text,
bool  block = false 
)
virtual

Replace text from range with specified text.

Parameters
rangerange of text to replace
texttext to replace with
blockreplace text as a visual block of text rather than a linear sequence
Returns
true on success, otherwise false
See also
setText(), removeText(), insertText()
QVector<KTextEditor::Range> KTextEditor::Document::searchText ( const KTextEditor::Range range,
const QString pattern,
const SearchOptions  options = Default 
) const

Searches the given input range for a text pattern.

Searches for a text pattern within the given input range. The kind of search performed depends on the options used. Use this function for plaintext searches as well as regular expression searches. If no match is found the first (and only) element in the vector return is the invalid range. When searching for regular expressions, the first element holds the range of the full match, the subsequent elements hold the ranges of the capturing parentheses.

Parameters
rangeInput range to search in
patternText pattern to search for
optionsCombination of search flags
Returns
List of ranges (length >=1)
Author
Sebastian Pipping <webma[email protected]ster[email protected]@hart[email protected]work[email protected].org>
Since
5.11
virtual bool KTextEditor::Document::setEncoding ( const QString encoding)
pure virtual

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.

Parameters
encodingnew 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()
virtual bool KTextEditor::Document::setHighlightingMode ( const QString name)
pure virtual

Set the current mode of the document by giving its name.

Parameters
namename of the mode to use for this document
Returns
true on success, otherwise false
See also
highlightingMode(), highlightingModes(), highlightingModeChanged()
virtual bool KTextEditor::Document::setMode ( const QString name)
pure virtual

Set the current mode of the document by giving its name.

Parameters
namename of the mode to use for this document
Returns
true on success, otherwise false
See also
mode(), modes(), modeChanged()
virtual bool KTextEditor::Document::setText ( const QString text)
pure virtual

Set the given text as new document content.

Parameters
textnew content for the document
Returns
true on success, otherwise false
See also
text()
virtual bool KTextEditor::Document::setText ( const QStringList text)
pure virtual

Set the given text as new document content.

Parameters
textnew content for the document
Returns
true on success, otherwise false
See also
text()
virtual QString KTextEditor::Document::text ( ) const
pure virtual

Get the document content.

Returns
the complete document content
See also
setText()
virtual QString KTextEditor::Document::text ( const Range range,
bool  block = false 
) const
pure virtual

Get the document content within the given range.

Parameters
rangethe range of text to retrieve
blockSet 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()
void KTextEditor::Document::textChanged ( KTextEditor::Document document)
signal

The document emits this signal whenever its text changes.

Parameters
documentdocument which emitted this signal
See also
text(), textLine()
void KTextEditor::Document::textInserted ( KTextEditor::Document document,
const KTextEditor::Cursor position,
const QString text 
)
signal

Text got inserted.

Parameters
documentdocument which emitted this signal
positionposition where the insertion occurred
textinserted text
virtual QStringList KTextEditor::Document::textLines ( const Range range,
bool  block = false 
) const
pure virtual

Get the document content within the given range.

Parameters
rangethe range of text to retrieve
blockSet 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()
void KTextEditor::Document::textRemoved ( KTextEditor::Document document,
const KTextEditor::Range range,
const QString text 
)
signal

Text got removed.

Parameters
documentdocument which emitted this signal
rangerange where the removal occurred
textremoved text
virtual int KTextEditor::Document::totalCharacters ( ) const
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()
void KTextEditor::Document::viewCreated ( KTextEditor::Document document,
KTextEditor::View view 
)
signal

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.
Parameters
documentthe document for which a new view is created
viewthe new view
See also
createView()
virtual QList<View *> KTextEditor::Document::views ( ) const
pure virtual

Returns the views pre-casted to KTextEditor::Views.

virtual QString KTextEditor::Document::wordAt ( const KTextEditor::Cursor cursor) const
pure virtual

Get the word at the text position cursor.

The returned word is defined by the word boundaries to the left and right starting at cursor. The algorithm takes highlighting information into account, e.g. a dash ('-') in C++ is interpreted as word boundary, whereas e.g. CSS allows identifiers with dash ('-').

If cursor is not a valid text position or if there is no word under the requested position cursor, an empty string is returned.

Parameters
cursorrequested cursor position for the word
Returns
the word under the cursor or an empty string if there is no word.
See also
wordRangeAt(), characterAt()
virtual KTextEditor::Range KTextEditor::Document::wordRangeAt ( const KTextEditor::Cursor cursor) const
pure virtual

Get the text range for the word located under the text position cursor.

The returned word is defined by the word boundaries to the left and right starting at cursor. The algorithm takes highlighting information into account, e.g. a dash ('-') in C++ is interpreted as word boundary, whereas e.g. CSS allows identifiers with dash ('-').

If cursor is not a valid text position or if there is no word under the requested position cursor, an invalid text range is returned. If the text range is valid, it is always on a single line.

Parameters
cursorrequested cursor position for the word
Returns
the Range spanning the word under the cursor or an invalid range if there is no word.
See also
wordAt(), characterAt(), KTextEditor::Range::isValid()
virtual void KTextEditor::Document::writeSessionConfig ( KConfigGroup config,
const QSet< QString > &  flags = QSetQString >() 
)
pure virtual

Write session settings to the config.

See readSessionConfig() for more details about available flags.

Parameters
configwrite the session settings to this KConfigGroup
flagsadditional flags
See also
readSessionConfig()

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Wed Jul 1 2020 22:55:57 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.