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 \<email@example.com\> 0193 */