Warning, /frameworks/ktexteditor/docs/porting.dox is written in an unsupported language. File is not indexed.

0001 /** \page kte_port_to_5 Porting to KDE Frameworks 5
0002 
0003 <p><b>
0004 \ref index "Overview" |
0005 \ref kte_design "Design" |
0006 \ref kte_guidelines "Coding Guidelines" |
0007 Porting to %KDE Frameworks 5
0008 </b></p>
0009 
0010 This document describes porting applications using the KTextEditor interfaces
0011 from KDE 4 to KDE Frameworks 5. This page does not try to be complete; its main
0012 goal is to show what interfaces were removed, changed or added to give some
0013 impression and orientation of what you have to do to port your application to
0014 the KDE Frameworks 5 KTextEditor interfaces.
0015 
0016 \section kte_port_intro Introduction
0017 The KTextEditor interfaces changes in KDE Frameworks 5 are neither binary nor
0018 source compatible to the KTextEditor interfaces included in KDE 4, so programs
0019 written/compiled for the KDE 4 KTextEditor interfaces will not compile
0020 (nor run) under Frameworks 5.
0021 
0022 The Frameworks 5 KTextEditor interfaces undergone a heavy cleanup, i.e. obsolete
0023 functions were removed, interfaces were merged and extended. All interface
0024 changes like for example parameter changes of a function are not mentioned in
0025 detail in this page, look into the particular class API documentation.
0026 
0027 \section kte_port_remove Removed/Merged Interfaces and Classes
0028 Entirely removed interfaces and classes are:
0029  - \p KTextEditor::Factory \n
0030    Just use KTextEditor::Editor::instance() to get the editor instance.
0031    This pointer is \e always valid.
0032  - \p KTextEditor::EditorChooser \n
0033    Instead, just use \p KTextEditor::Editor::instance();
0034  - \p SmartInterface (removed since KDE 4.5)
0035  - \p SmartCursor, \p SmartRange, \p SmartCursorNotifier, \p SmartCursorWatcher,
0036    \p SmartRangeNotifier, \p SmartRangeWatcher (already unsupported since KDE 4.5)
0037  - \p LoadSaveFilterCheckPlugin was removed, since it was unused.
0038  - \p KTextEditor::VariableInterface \n
0039    This interface was not used by other applications and therefore got removed.
0040    If required, it can be added again.
0041  - \p KTextEditor::SearchInterface \n
0042    This interface was removed. The function \p searchText() was added to
0043    \p KTextEditor::Document.
0044  - \p KTextEditor::ConfigPageInterface \n
0045    This interface was removed. The functions \p configPages() and \p configPage()
0046    were both added to the \p KTextEditor::Editor and the \p KTextEditor::Plugin interface.
0047  - \p KTextEditor::ParameterizedSessionConfigInterface \n
0048    This interface was removed. The functions are now available directly in the
0049    Document and the View as follows:
0050    - \p KTextEditor::Document::readSessionConfig() and \p KTextEditor::Document::writeSessionConfig()
0051    - \p KTextEditor::View::readSessionConfig() and \p KTextEditor::View::writeSessionConfig()
0052  - \p CoordinatesToCursorInterface was merged into the \p KTextEditor::View.
0053  - \p CodeCompletionModelControllerInterface2,
0054    \p CodeCompletionModelControllerInterface3 and
0055    \p CodeCompletionModelControllerInterface4
0056    were merged into the \p KTextEditor::CodeCompletionModelControllerInterface.
0057  - \p KTextEditor::CommandInterface \n
0058    This interface was merged into the \p KTextEditor::Editor.
0059  - \p KTextEditor::Command \n
0060    This class now inherits QObject. Further, a Command now automatically
0061    registers and unregisters itself. Hence, \p CommandInterface::registerCommand()
0062    and \p CommandInterface::unregisterCommand() were removed.
0063  - \p KTextEditor::CommandExtension \n
0064    This interface was merged into \p KTextEditor::Command.
0065    KTextEditor::CommandExtension::flagCompletions() was removed since it was
0066    never implemented and therefore unused.
0067  - \p KTextEditor::RangeCommand \n
0068    This interface was merged into \p KTextEditor::Command. The function
0069    \p KTextEditor::Command::exec() now takes an optional Range as 3rd parameter.
0070  - \p KTextEditor::HighlightInterface \n
0071    The default styles are now in the namespace \p KTextEditor::DefaultStyle.
0072    The rest of this interface was merged into the \p KTextEditor::Document and \p KTextEditor::View, see:
0073    - \p KTextEditor::Document::defaultStyleAt()
0074    - \p KTextEditor::View::defaultStyleAttribute()
0075    - \p KTextEditor::View::lineAttributes()
0076  - \p KTextEditor::HighlightInterface::AttributeBlock moved to \p KTextEditor::AttributeBlock.
0077  - \p KTextEditor::RecoveryInterface \n
0078    This interface was merged into the \p KTextEditor::Document, see
0079    - \p KTextEditor::Document::isDataRecoveryAvailable()
0080    - \p KTextEditor::Document::recoverData()
0081    - \p KTextEditor::Document::discardDataRecovery()
0082 
0083 \section kte_port_rename Interface Changes
0084 The following interfaces were changed:
0085  - \p KTextEditor::Editor::setSimpleMode() was removed.
0086  - \p KTextEditor::Editor::readConfig() and \p KTextEditor::Editor::writeConfig() \n
0087    Both functions were removed. The Editor configuration is automatically saved
0088    to \e katepartrc now and shared among all applications that use the KTextEditor framework.
0089  - \p KTextEditor::View::setSelection(const Cursor &position, int length, bool wrap)
0090    was removed in favor of the Range based KTextEditor::View::setSelection()
0091  - \p KTextEditor::Document::activeView() \n
0092    The active view was removed in favor of KTextEditor::MainWindow::activeView().
0093  - \p KTextEditor::Document::checksum() returns the sha1 checksum (same as git) of the file on disk.
0094  - \p KTextEditor::Document::wordRangeAt() returns the Range of the word under the given cursor.
0095  - \p KTextEditor::Document::wordAt() returns the word under the given cursor.
0096  - \p KTextEditor::Document::character() was renamed to \p KTextEditor::Document::characterAt()
0097  - \p KTextEditor::Document::isLineModified(), \p KTextEditor::Document::isLineSaved(),
0098    and \p KTextEditor::Document::isLineTouched() are new.
0099  - \p KTextEditor::Document::readWriteChanged() \n
0100    This signal is emitted whenever the read-only state of the document changes.
0101  - \p KTextEditor::Document::startEditing() and \p KTextEditor::Document::endEditing()
0102    were removed in favour of the RAII class \p KTextEditor::Document::EditingTransaction.
0103    Further, \p KTextEditor::Document::isEditingTransactionRunning() was added.
0104  - \p KTextEditor::Document::exclusiveEditStart() was renamed to \p KTextEditor::Document::editingStarted().
0105  - \p KTextEditor::Document::exclusiveEditEnd() was renamed to \p KTextEditor::Document::editingFinished().
0106  - New \p KTextEditor::Document gained new editing signals: \n
0107    - \p KTextEditor::Document::lineWrapped() and \p KTextEditor::Document::lineUnwrapped()
0108    - \p KTextEditor::Document::textInserted() and \p KTextEditor::Document::textRemoved()
0109    - \p KTextEditor::Document::textChanged()
0110    These signals are emitted only between the signals \p KTextEditor::Document::editingStarted()
0111    and before \p KTextEditor::Document::editingFinished(). Note, that you should
0112    \e never modify the document between these two signals.
0113  - \p KTextEditor::Document::cursorInText() was unused and removed in favor of
0114    \p KTextEditor::Document::isValidTextPosition().
0115  - \p KTextEditor::View now has a status bar by default. It can be controlled
0116    by \p View::setStatusBarEnabled() and \p View::isStatusBarEnabled(). Whenever the visibility
0117    of the statusbar changes, the signal \p View::statusBarEnabledChanged() is emitted.
0118  - \p KTextEditor::View::informationMessage() was removed in favor of \p KTextEditor::Document::postMessage().
0119  - \p KTextEditor::View::viewModeChanged() gained an additional parameter with the current view edit mode.
0120  - New enums \p KTextEditor::View::InputMode and \p KTextEditor::View::ViewMode.
0121  - \p KTextEditor::View::viewEditModeChanged() was renamed to \p KTextEditor::View::viewInputModeChanged().
0122  - New functions \p KTextEditor::View::viewModeHuman and \p KTextEditor::View::viewInputModeHuman().
0123  - \p KTextEditor::SessionConfigInterface \n
0124    This interface is an extension only for a \p KTextEditor::Plugin and the Plugin
0125    view's returned by \p KTextEditor::Plugin::createView().
0126  - \p KTextEditor::CodeCompletionModel \n
0127    \p KTextEditor::CodeCompletionModel::hasGroups() now returns \e false (KF5)
0128    instead of \e true (KDE4).
0129 
0130 \section kte_port_new New Interfaces
0131 The following interfaces are new:
0132  - \p KTextEditor::Application (since KDE 5.0) \n
0133    The Application is an interface that is implemented by the host application.
0134    It provides information about the documents managed by the application as well
0135    as convenience functions for instance to open or close documents.
0136  - \p KTextEditor::MainWindow (since KDE 5.0) \n
0137    A MainWindow usually represents a toplevel window of the application.
0138    It manages the views and also provides an accessor to the MainWindow's active
0139    view through MainWindow::activeView(). The provides signals that indicate that
0140    the active view has changed, or that a view has been created. Other than that,
0141    it for instance allows to create tool views and similar convenience functions
0142    to show view bars.
0143  - \p KTextEditor::Message (since KDE 4.11) \n
0144    Class providing notifications to the user in a KTextEditor::View.
0145 
0146 \section kte_port_enhanced_classes Significantly Enhanced Classes
0147 The following classes have been significantly enhanced:
0148  - \p KTextEditor::Cursor \n
0149    The Cursor now is a tuple of two ints, namely the line and column. It has no
0150    virtual destructor so that you cannot derive from Cursor. Since a Cursor
0151    uses 8 Bytes, it is even ok to pass a Cursor as copy in parameters instead
0152    of a reference.
0153    Further, the Cursor has been marked as Q_MOVABLE, making it behave like a
0154    Plain Old Data (POD) type.
0155  - \p KTextEditor::Range \n
0156    The Range now is a tuple of two Cursors, namely the Range::startCursor() and the
0157    Range::endCursor(). It has no virtual destructor so that you cannot derive from Range.
0158    Further, the Range has been marked as Q_MOVABLE, making it behave like a
0159    Plain Old Data (POD) type.
0160  - \p KTextEditor::TextHintInterface \n
0161    This interface now requires you to call registerTextHintProvider() and
0162    unregisterTextHintProvider() with a corresponding object that implements
0163    \p KTextEditor::TextHintProvider.
0164  - \p KTextEditor::Attribute \n
0165    This class was extended by several attributes that were internal to Kate Part
0166    before, including the name, spell checking, and the default style.
0167 
0168 \section kte_port_new_classes New Classes
0169 The following classes are either new, or were added late in the KDE 4 release cycle:
0170  - \p KTextEditor::DocumentCursor \n
0171    The DocumentCursor is a cursor associated to a KTextEditor::Document. It
0172    provides convenience functions such as for text navigation. However, it does
0173    not automatically maintain its position when the document's contents changes.
0174  - \p KTextEditor::MovingCursor (since KDE 4.5) \n
0175    The MovingCursor was introduced in KDE 4.5 as replacement to the SmartCursor.
0176    A MovingCursor is bound to a specific Document and maintains its position.
0177  - \p KTextEditor::MovingRange \n
0178    The MovingRange was introduced in KDE 4.5 as replacement to the SmartRange.
0179    A MovingRange is bound to a specific Document and maintains its position.
0180  - \p KTextEditor::MovingRangeFeedback (since KDE 4.5) \n
0181    Class providing notifications of changes to a KTextEditor::MovingRange.
0182 
0183 \section kte_port_plugins Plugin Architecture Changes
0184 The KTextEditor::Plugin system was heavily extended to support 'application
0185 plugins'. That is, a plugin can now create tool views in a KTextEditor::MainWindow%s and
0186 access the Application's document list. So the plugins are now shared
0187 between all applications using the KTextEditor interfaces (e.g. Kate, KDevelop,
0188 and Kile).
0189 
0190 \see KTextEditor::Plugin
0191 
0192 \author Dominik Haumann \<dhaumann@kde.org\>
0193 */