Porting to KDE 4

Overview | Design | Coding Guidelines | Porting to KDE 4 | Using

This document describes porting applications using the KTextEditor interfaces from KDE 3 to KDE 4. 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 4 KTextEditor interfaces.

Introduction

The KTextEditor interfaces changes in KDE 4 are neither binary nor source compatible to the KTextEditor interfaces included in KDE 3, so programs written/compiled for the KDE 3 KTextEditor interfaces will not compile (nor run) under KDE 4. There are no plans to provide a compatibility layer.

The KDE 4 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. As already mentioned in the mainpage, all line/column tuples were replaced with a KTextEditor::Cursor, and all Cursor/Cursor tuples with a KTextEditor::Range.

A KTextEditor::Factory class was introduced to access a specific Editor implementation, read Overview of the Core Interface Design for detailed information.

Removed Interfaces

Some interfaces were removed mainly because they described user actions which implementation and support is up to the KTextEditor part itself, like printing, copy & paste and word wrapping. Entirely removed interfaces are, in order:

• all DCOP interfaces
• ClipboardInterface
• CursorInterface
• DynWordWrapInterface
• PrintInterface
• SelectionExtDCOPInterface
• UndoInterface
• ViewStatusMsgInterface
• WordWrapInterface

Merged Interfaces

The following interfaces were merged, in order:

• BlockSelectionInterface, SelectionInterface and SelectionInterfaceExt were merged into the KTextEditor::View, so that a KTextEditor::Document itself does not provide any selection methods anymore.
• ConfigInterface was partly merged into the KTextEditor::Editor and now only contains very basic functions to set/get properties. Session related config options can be configured in a new interface called KTextEditor::SessionConfigInterface
• DocumentInfoInterface was merged into the KTextEditor::Document
• EditInterface was merged into the KTextEditor::Document
• EditInterfaceExt was merged into the KTextEditor::Document
• EncodingInterface was merged into the KTextEditor::Document
• HighlightingInterface was merged into the KTextEditor::Document
• MarkInterfaceExtension was merged into the KTextEditor::MarkInterface
• PluginViewInterface was merged into the KTextEditor::Plugin
• PopupMenuInterface was merged into the KTextEditor::View
• ViewCursorInterface was merged into the KTextEditor::View

Interface Changes

The following interfaces were renamed:

• KTextEditor::CodeCompletionInterface was changed to support several clients at once. A client registers a so-called KTextEditor::CompletionProvider that provides its own completion and argument hint da.
• CompletionEntry was renamed to KTextEditor::CompletionItem
• signal modifiedOnDisc() was renamed to KTextEditor::ModificationInterface::modifiedOnDisk()

New Interfaces

The following interfaces are new:

• KTextEditor::CommandInterface, support for command-line commands
• KTextEditor::ModificationInterface, support for handling external modified files
• KTextEditor::SessionConfigInterface, support for session specific settings
• KTextEditor::SmartInterface, support for smart cursors + ranges, plus their uses such as arbitrary highlighting and action association

Significantly Enhanced Classes

The following classes have been significantly enhanced:

• KTextEditor::Cursor
  Has been upgraded for greatly increased convenience, and now forms a cornerstone of the KTextEditor interfaces.

New Classes

The following classes are new:

• KTextEditor::SmartCursor
  A cursor which is bound to a specific KTextEditor::Document, and maintains its position.
• KTextEditor::SmartCursorWatcher and KTextEditor::SmartCursorNotifier
  Classes for providing notifications of changes to a SmartCursor.
• KTextEditor::Range
  A tuple of start + end cursors with many convenience methods
• KTextEditor::SmartRange
  A KTextEditor::Range which is bound to a specific Document, and maintains its position.
• KTextEditor::SmartRangeWatcher and KTextEditor::SmartRangeNotifier
  Classes for providing notifications of changes to a SmartRange.

Plugin Architecture Changes

The KTextEditor::Plugin interface changed to support more than only one KTextEditor::Document at a time. A plugin in a KDE 4 KTextEditor implementation no longer is bound to a single document (i.e. for every document a single instance of the plugin existed). Now, a plugin can handle several documents and views. Also a plugin now is able to load and save session related config settings if desired.

See also

KTextEditor::Plugin

Author

Dominik Haumann <dhdev.nosp@m.@gmx.nosp@m..de>

Hamish Rodda <rodda.nosp@m.@kde.nosp@m..org>