KTextEditor::Document

View on LXR

#include <KTextEditor/Document>

Inheritance diagram for KTextEditor::Document:

[legend]

Classes
class	EditingTransaction

Signals
void	configChanged (KTextEditor::Document *document)

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 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

BrowserExtension *	browserExtension () 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 Part *	hitTest (QWidget *widget, const QPoint &globalPos)

KIconLoader *	iconLoader ()

bool	isSelectable () const

PartManager *	manager () const

KPluginMetaData	metaData () const

void	setAutoDeletePart (bool autoDeletePart)

void	setAutoDeleteWidget (bool autoDeleteWidget)

virtual void	setManager (PartManager *manager)

virtual void	setSelectable (bool selectable)

virtual QWidget *	widget ()

Public Member Functions inherited from QObject
	QObject (QObject *parent)

bool	blockSignals (bool block)

const QObjectList &	children () 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< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	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 QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () 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

T	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)

T	qobject_cast (QObject *object)

T	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)

QThread *	thread () const const

Public Member Functions inherited from KParts::PartBase
KAboutData	componentData () const

void	setPartObject (QObject *object)

Public Member Functions inherited from KXMLGUIClient
	KXMLGUIClient (KXMLGUIClient *parent)

QAction *	action (const char *name) const

virtual QAction *	action (const QDomElement &element) const

virtual KActionCollection *	actionCollection () const

QList< KXMLGUIClient * >	childClients ()

KXMLGUIBuilder *	clientBuilder () const

virtual QString	componentName () const

virtual QDomDocument	domDocument () const

KXMLGUIFactory *	factory () const

void	insertChildClient (KXMLGUIClient *child)

KXMLGUIClient *	parentClient () 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

QWidget *	hostContainer (const QString &containerName)

void	loadPlugins ()

virtual void	partActivateEvent (PartActivateEvent *event)

virtual void	partSelectEvent (PartSelectEvent *event)

void	setMetaData (const KPluginMetaData &metatData)

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

QObject *	sender () 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)

void	loadPlugins (QObject parent, KXMLGUIClient parentGUIClient, const QString &parentInstanceName)

virtual void	setComponentData (const KAboutData &pluginData, bool loadPlugins)

virtual void	setComponentData (const KAboutData &componentData)

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 View *	createView (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::Range >	searchText (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

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)

Static Public Member Functions inherited from KXMLGUIClient
static QString	findVersionNumber (const QString &xml)

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 185 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

impl	d-pointer to use
parent	parent object

See also: Editor::createDocument()

Definition at line 12 of file document.cpp.

Document::~Document ( )

virtual

Virtual destructor.

Definition at line 18 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

document the 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

document the document being reloaded

virtual QChar KTextEditor::Document::characterAt ( const Cursor & position ) const

pure virtual

Get the character at text position cursor.

Parameters

position the 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()

void KTextEditor::Document::configChanged ( KTextEditor::Document * document )

signal

This signal is emitted whenever the current document configuration is changed.

Parameters

document the document which's config has changed

Since: 5.79

virtual View* KTextEditor::Document::createView	(	QWidget *	parent,
		KTextEditor::MainWindow *	mainWindow = `nullptr`
	)

pure virtual

Create a new view attached to parent.

Parameters

parent	parent widget
mainWindow	the 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

position text 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

document document 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 679 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

document document 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

document document which emitted this signal

See also: textChanged()

void KTextEditor::Document::editingStarted ( KTextEditor::Document * document )

signal

Editing transaction has started.

Parameters

document document 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

line line

See also: lineLength(), line()

Definition at line 711 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

document the 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

index the 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

insertLine( lines(), text )

Parameters

line	line where to insert the text
text	text 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

insertLine( lines(), text )

Parameters

line	line where to insert the text
text	text 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

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()

virtual bool KTextEditor::Document::insertText	(	const Cursor &	position,
		const QStringList &	text,
		bool	block = `false`
	)

pure virtual

Insert text at position.

Parameters

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()

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 110 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

line	line 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

line	line 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

line	line 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

cursor cursor 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

line	the 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

line	line 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

document	document which emitted this signal
line	line where the unwrap occurred

void KTextEditor::Document::lineWrapped	(	KTextEditor::Document *	document,
		const KTextEditor::Cursor &	position
	)

signal

A line got wrapped.

Parameters

document	document which emitted this signal
position	position 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

document the 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

index the 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

document document 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 82 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 87 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

message the 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 = `QSet< QString >()`
	)

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

config	read the session settings from this KConfigGroup
flags	additional 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

document the 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

document the document that was reloaded.

Since: 4.6

virtual bool KTextEditor::Document::removeLine ( int line )

pure virtual

Remove line from the document.

Parameters

line	line 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

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()

bool KTextEditor::Document::replaceText	(	const Range &	range,
		const QString &	text,
		bool	block = `false`
	)

virtual

Replace text from range with specified text.

Parameters

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()

Definition at line 92 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

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()

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

range	Input range to search in
pattern	Text pattern to search for
options	Combination 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

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()

virtual bool KTextEditor::Document::setHighlightingMode ( const QString & name )

pure virtual

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

Parameters

name	name 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

name	name 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

text	new 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

text	new 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

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()

void KTextEditor::Document::textChanged ( KTextEditor::Document * document )

signal

The document emits this signal whenever its text changes.

Parameters

document document 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

document	document which emitted this signal
position	position where the insertion occurred
text	inserted text

virtual QStringList KTextEditor::Document::textLines	(	const Range &	range,
		bool	block = `false`
	)		const

pure virtual

Get the document content within the given range.

Parameters

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()

void KTextEditor::Document::textRemoved	(	KTextEditor::Document *	document,
		const KTextEditor::Range &	range,
		const QString &	text
	)

signal

Text got removed.

Parameters

document	document which emitted this signal
range	range where the removal occurred
text	removed 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

document	the document for which a new view is created
view	the 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

cursor requested 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.

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

cursor requested 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 = `QSet< QString >()`
	)

pure virtual

Write session settings to the config.

See readSessionConfig() for more details about available flags.

Parameters

config	write the session settings to this KConfigGroup
flags	additional flags

See also: readSessionConfig()

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

KTextEditor::Document Submit

Classes

Signals

Public Member Functions

Protected Member Functions

Manage Views of this Document

General Information about this Document

File Loading and Saving

Text Manipulation

Highlighting and Related Information

Additional Inherited Members

Detailed Description

Introduction

Text Manipulation

Document Views

Read-Only Mode

Notifications in Documents and Views

Crash Recovery for Documents

Document Extension Interfaces

Constructor & Destructor Documentation

Member Function Documentation

KTextEditor::Document