/** \page kte_port_to_5 Porting to KDE Frameworks 5

<p><b>
\ref index "Overview" |
\ref kte_design "Design" |
\ref kte_guidelines "Coding Guidelines" |
Porting to %KDE Frameworks 5
</b></p>

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.

\section kte_port_intro 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.

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

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

\section kte_port_new New Interfaces
The following interfaces are new:
 - \p KTextEditor::Application (since KDE 5.0) \n
   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.
 - \p KTextEditor::MainWindow (since KDE 5.0) \n
   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.
 - \p KTextEditor::Message (since KDE 4.11) \n
   Class providing notifications to the user in a KTextEditor::View.

\section kte_port_enhanced_classes Significantly Enhanced Classes
The following classes have been significantly enhanced:
 - \p KTextEditor::Cursor \n
   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.
 - \p KTextEditor::Range \n
   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.
 - \p KTextEditor::TextHintInterface \n
   This interface now requires you to call registerTextHintProvider() and
   unregisterTextHintProvider() with a corresponding object that implements
   \p KTextEditor::TextHintProvider.
 - \p KTextEditor::Attribute \n
   This class was extended by several attributes that were internal to Kate Part
   before, including the name, spell checking, and the default style.

\section kte_port_new_classes New Classes
The following classes are either new, or were added late in the KDE 4 release cycle:
 - \p KTextEditor::DocumentCursor \n
   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.
 - \p KTextEditor::MovingCursor (since KDE 4.5) \n
   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.
 - \p KTextEditor::MovingRange \n
   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.
 - \p KTextEditor::MovingRangeFeedback (since KDE 4.5) \n
   Class providing notifications of changes to a KTextEditor::MovingRange.

\section kte_port_plugins 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::MainWindow%s 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 KTextEditor::Plugin

\author Dominik Haumann \<dhaumann@kde.org\>
*/