Porting to KDE Frameworks 5

Overview | Design | Coding Guidelines | Porting to KDE Frameworks 5

This document describes porting applications using the KTextEditor interfaces from KDE 4 to KDE Frameworks 5. This page does not try to be complete; its main goal is to show what interfaces were removed, changed or added to give some impression and orientation of what you have to do to port your application to the KDE Frameworks 5 KTextEditor interfaces.

Introduction

The KTextEditor interfaces changes in KDE Frameworks 5 are neither binary nor source compatible to the KTextEditor interfaces included in KDE 4, so programs written/compiled for the KDE 4 KTextEditor interfaces will not compile (nor run) under Frameworks 5.

The Frameworks 5 KTextEditor interfaces undergone a heavy cleanup, i.e. obsolete functions were removed, interfaces were merged and extended. All interface changes like for example parameter changes of a function are not mentioned in detail in this page, look into the particular class API documentation.

Removed/Merged Interfaces and Classes

Entirely removed interfaces and classes are:

• KTextEditor::Factory
  Just use KTextEditor::Editor::instance() to get the editor instance. This pointer is always valid.
• KTextEditor::EditorChooser
  Instead, just use KTextEditor::Editor::instance();
• SmartInterface (removed since KDE 4.5)
• SmartCursor, SmartRange, SmartCursorNotifier, SmartCursorWatcher, SmartRangeNotifier, SmartRangeWatcher (already unsupported since KDE 4.5)
• LoadSaveFilterCheckPlugin was removed, since it was unused.
• KTextEditor::VariableInterface
  This interface was not used by other applications and therefore got removed. If required, it can be added again.
• KTextEditor::SearchInterface
  This interface was removed. The function searchText() was added to KTextEditor::Document.
• KTextEditor::ConfigPageInterface
  This interface was removed. The functions configPages() and configPage() were both added to the KTextEditor::Editor and the KTextEditor::Plugin interface.
• KTextEditor::ParameterizedSessionConfigInterface
  This interface was removed. The functions are now available directly in the Document and the View as follows:
  • KTextEditor::Document::readSessionConfig() and KTextEditor::Document::writeSessionConfig()
  • KTextEditor::View::readSessionConfig() and KTextEditor::View::writeSessionConfig()
• CoordinatesToCursorInterface was merged into the KTextEditor::View.
• CodeCompletionModelControllerInterface2, CodeCompletionModelControllerInterface3 and CodeCompletionModelControllerInterface4 were merged into the KTextEditor::CodeCompletionModelControllerInterface.
• KTextEditor::CommandInterface
  This interface was merged into the KTextEditor::Editor.
• KTextEditor::Command
  This class now inherits QObject. Further, a Command now automatically registers and unregisters itself. Hence, CommandInterface::registerCommand() and CommandInterface::unregisterCommand() were removed.
• KTextEditor::CommandExtension
  This interface was merged into KTextEditor::Command. KTextEditor::CommandExtension::flagCompletions() was removed since it was never implemented and therefore unused.
• KTextEditor::RangeCommand
  This interface was merged into KTextEditor::Command. The function KTextEditor::Command::exec() now takes an optional Range as 3rd parameter.
• KTextEditor::HighlightInterface
  The default styles are now in the namespace KTextEditor::DefaultStyle. The rest of this interface was merged into the KTextEditor::Document and KTextEditor::View, see:
  • KTextEditor::Document::defaultStyleAt()
  • KTextEditor::View::defaultStyleAttribute()
  • KTextEditor::View::lineAttributes()
• KTextEditor::HighlightInterface::AttributeBlock moved to KTextEditor::AttributeBlock.
• KTextEditor::RecoveryInterface
  This interface was merged into the KTextEditor::Document, see
  • KTextEditor::Document::isDataRecoveryAvailable()
  • KTextEditor::Document::recoverData()
  • KTextEditor::Document::discardDataRecovery()

Interface Changes

The following interfaces were changed:

• KTextEditor::Editor::setSimpleMode() was removed.
• KTextEditor::Editor::readConfig() and KTextEditor::Editor::writeConfig()
  Both functions were removed. The Editor configuration is automatically saved to katepartrc now and shared among all applications that use the KTextEditor framework.
• KTextEditor::View::setSelection(const Cursor &position, int length, bool wrap) was removed in favor of the Range based KTextEditor::View::setSelection()
• KTextEditor::Document::activeView()
  The active view was removed in favor of KTextEditor::MainWindow::activeView().
• KTextEditor::Document::checksum() returns the sha1 checksum (same as git) of the file on disk.
• KTextEditor::Document::wordRangeAt() returns the Range of the word under the given cursor.
• KTextEditor::Document::wordAt() returns the word under the given cursor.
• KTextEditor::Document::character() was renamed to KTextEditor::Document::characterAt()
• KTextEditor::Document::isLineModified(), KTextEditor::Document::isLineSaved(), and KTextEditor::Document::isLineTouched() are new.
• KTextEditor::Document::readWriteChanged()
  This signal is emitted whenever the read-only state of the document changes.
• KTextEditor::Document::startEditing() and KTextEditor::Document::endEditing() were removed in favour of the RAII class KTextEditor::Document::EditingTransaction. Further, KTextEditor::Document::isEditingTransactionRunning() was added.
• KTextEditor::Document::exclusiveEditStart() was renamed to KTextEditor::Document::editingStarted().
• KTextEditor::Document::exclusiveEditEnd() was renamed to KTextEditor::Document::editingFinished().
• New KTextEditor::Document gained new editing signals:
  
  • KTextEditor::Document::lineWrapped() and KTextEditor::Document::lineUnwrapped()
  • KTextEditor::Document::textInserted() and KTextEditor::Document::textRemoved()
  • KTextEditor::Document::textChanged() These signals are emitted only between the signals KTextEditor::Document::editingStarted() and before KTextEditor::Document::editingFinished(). Note, that you should never modify the document between these two signals.
• KTextEditor::Document::cursorInText() was unused and removed in favor of KTextEditor::Document::isValidTextPosition().
• KTextEditor::View now has a status bar by default. It can be controlled by View::setStatusBarEnabled() and View::isStatusBarEnabled(). Whenever the visibility of the statusbar changes, the signal View::statusBarEnabledChanged() is emitted.
• KTextEditor::View::informationMessage() was removed in favor of KTextEditor::Document::postMessage().
• KTextEditor::View::viewModeChanged() gained an additional parameter with the current view edit mode.
• New enums KTextEditor::View::InputMode and KTextEditor::View::ViewMode.
• KTextEditor::View::viewEditModeChanged() was renamed to KTextEditor::View::viewInputModeChanged().
• New functions KTextEditor::View::viewModeHuman and KTextEditor::View::viewInputModeHuman().
• KTextEditor::SessionConfigInterface
  This interface is an extension only for a KTextEditor::Plugin and the Plugin view's returned by KTextEditor::Plugin::createView().
• KTextEditor::CodeCompletionModel
KTextEditor::CodeCompletionModel::hasGroups() now returns false (KF5) instead of true (KDE4).

New Interfaces

The following interfaces are new:

• KTextEditor::Application (since KDE 5.0)
  The Application is an interface that is implemented by the host application. It provides information about the documents managed by the application as well as convenience functions for instance to open or close documents.
• KTextEditor::MainWindow (since KDE 5.0)
  A MainWindow usually represents a toplevel window of the application. It manages the views and also provides an accessor to the MainWindow's active view through MainWindow::activeView(). The provides signals that indicate that the active view has changed, or that a view has been created. Other than that, it for instance allows to create tool views and similar convenience functions to show view bars.
• KTextEditor::Message (since KDE 4.11)
  Class providing notifications to the user in a KTextEditor::View.

Significantly Enhanced Classes

The following classes have been significantly enhanced:

• KTextEditor::Cursor
  The Cursor now is a tuple of two ints, namely the line and column. It has no virtual destructor so that you cannot derive from Cursor. Since a Cursor uses 8 Bytes, it is even ok to pass a Cursor as copy in parameters instead of a reference. Further, the Cursor has been marked as Q_MOVABLE, making it behave like a Plain Old Data (POD) type.
• KTextEditor::Range
  The Range now is a tuple of two Cursors, namely the Range::startCursor() and the Range::endCursor(). It has no virtual destructor so that you cannot derive from Range. Further, the Range has been marked as Q_MOVABLE, making it behave like a Plain Old Data (POD) type.
• KTextEditor::TextHintInterface
  This interface now requires you to call registerTextHintProvider() and unregisterTextHintProvider() with a corresponding object that implements KTextEditor::TextHintProvider.
• KTextEditor::Attribute
  This class was extended by several attributes that were internal to Kate Part before, including the name, spell checking, and the default style.

New Classes

The following classes are either new, or were added late in the KDE 4 release cycle:

• KTextEditor::DocumentCursor
  The DocumentCursor is a cursor associated to a KTextEditor::Document. It provides convenience functions such as for text navigation. However, it does not automatically maintain its position when the document's contents changes.
• KTextEditor::MovingCursor (since KDE 4.5)
  The MovingCursor was introduced in KDE 4.5 as replacement to the SmartCursor. A MovingCursor is bound to a specific Document and maintains its position.
• KTextEditor::MovingRange
  The MovingRange was introduced in KDE 4.5 as replacement to the SmartRange. A MovingRange is bound to a specific Document and maintains its position.
• KTextEditor::MovingRangeFeedback (since KDE 4.5)
  Class providing notifications of changes to a KTextEditor::MovingRange.

Plugin Architecture Changes

The KTextEditor::Plugin system was heavily extended to support 'application plugins'. That is, a plugin can now create tool views in a KTextEditor::MainWindows and access the Application's document list. So the plugins are now shared between all applications using the KTextEditor interfaces (e.g. Kate, KDevelop, and Kile).

See also

KTextEditor::Plugin

Author

Dominik Haumann <dhaum.nosp@m.ann@.nosp@m.kde.o.nosp@m.rg>