summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristoph Cullmann <cullmann@kde.org>2014-01-20 16:58:12 (GMT)
committerChristoph Cullmann <cullmann@kde.org>2014-01-20 16:58:12 (GMT)
commite4ca13be334ef2111ee9e953d72573d9da1adec0 (patch)
tree9c77281730af390063dbff293e48ae2ea5f881c5
parentd7ffeb43c9cf1255a2eb8925a4d0dbf896b36733 (diff)
move up the real main dox file
-rw-r--r--Mainpage.dox603
-rw-r--r--src/include/ktexteditor/Mainpage.dox599
2 files changed, 583 insertions, 619 deletions
diff --git a/Mainpage.dox b/Mainpage.dox
index 1382936..955eb40 100644
--- a/Mainpage.dox
+++ b/Mainpage.dox
@@ -1,36 +1,599 @@
-/** @mainpage Kate Editor Component
+/*
+This file is part of the KDE project
-The Kate Editor Component (also called Kate Part) implements the
-KTextEditor interfaces. Thus, all Kate Part classes are internal
-and never appear in public interfaces.
+Copyright (c) 2005-2013 by Dominik Haumann <dhdev@gmx.de>
+Copyright (c) 2005 by Christoph Cullmann <cullmann@kde.org>
-If you wish to have a text editor component in your application,
-use the KTextEditor interfaces.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2
+or any later version published by the Free Software Foundation;
+*/
+
+/** \mainpage KTextEditor
+
+<p><b>
+Overview |
+\ref kte_design "Design" |
+\ref kte_guidelines "Coding Guidelines" |
+\ref kte_port_to_5 "Porting to Frameworks 5" |
+\ref kte_howto "Using"
+</b></p>
+
+\section kte_intro Introduction
+The KTextEditor interfaces - also called KTE interfaces - are a set of
+well-defined interfaces which an application or library can implement to provide
+advanced plain text editing services. Applications which utilise this interface
+can thus allow the user to choose which implementation of the editor component
+to use. The only implementation right now is the Kate Editor Component
+(Kate Part).
+
+\section kte_general General
+ - \ref kte_design
+ - \ref kte_howto
+ - \ref kte_port_to_5
+ - <a href="http://www.kate-editor.org/support">Contact/Mailing Lists</a>
+
+
+\section kte_notes Implementation Notes
+ - \ref kte_guidelines
+
+\section kte_extensions Extension Interfaces
+ - \ref kte_group_doc_extensions
+ - \ref kte_group_view_extensions
+ - \ref kte_group_editor_extensions
+ - \ref kte_group_plugin_extensions
+ - \ref kte_group_command_extensions
+ - \ref kte_group_ccmodel_extensions
+
+\section kte_apiref API Reference
+ - <a href="classes.html">All Classes</a>
+ - <a href="annotated.html">Annotated Classes</a>
+ - <a href="hierarchy.html">Inheritance Hierarchy</a>
+<!-- grouped classes -> TODO Grouping -->
@authors
+Dominik Haumann \<dhdev@gmx.de\><br>
Christoph Cullmann \<cullmann@kde.org\><br>
-Joseph Wenninger \<jowenn@kde.org\><br>
-Anders Lund \<anders@alweb.dk\><br>
Hamish Rodda \<rodda@kde.org\><br>
-Waldo Bastian \<bastian@kde.org\><br>
-Charles Samuels \<charles@kde.org\><br>
-Michael Bartl \<michael.bartl1@chello.at\><br>
-Matt Newell \<newellm@proaxis.com\><br>
-Michael McCallum \<gholam@xtra.co.nz\><br>
-John Firebaugh \<jfirebaugh@kde.org\><br>
-Nadeem Hasan \<nhasan@nadmm.com\><br>
+Joseph Wenninger \<jowenn@kde.org\><br>
Jochen Wilhelmy \<digisnap@cs.tu-berlin.de\><br>
-Glen Parker \<glenebob@nwlink.com\><br>
-Michael Koch \<koch@kde.org\><br>
-Dominik Haumann \<dhdev@gmx.de\>
+Anders Lund \<anders@alweb.dk\><br>
+Matt Broadstone \<mbroadst@gmail.com\>
@maintainers
-Christoph Cullmann \<cullmann@kde.org\>
+Dominik Haumann \<dhdev@gmx.de\><br>
+Christoph Cullmann \<cullmann@kde.org\><br>
+Hamish Rodda \<rodda@kde.org\>
@licenses
@lgpl
*/
-// DOXYGEN_REFERENCES = kdecore kio kdeui kparts
+
+
+
+
+
+/** \page kte_design Overview of the Core Interface Design
+
+<p><b>
+\ref index "Overview" |
+Design |
+\ref kte_guidelines "Coding Guidelines" |
+\ref kte_port_to_5 "Porting to KDE Frameworks 5" |
+\ref kte_howto "Using"
+</b></p>
+
+The core of the KTextEditor interfaces consists of several main interfaces:
+- KTextEditor::Factory \n
+ The Factory provides access to the editor object.
+- KTextEditor::Editor \n
+ The Editor interface allows you to create documents, get a document list,
+ and a be informed when a new document is created.
+- KTextEditor::Document \n
+ The Document interface represents a single document and enables the creation of
+ views, access to and manipulation of document contents, and access to document
+ extension interfaces.
+- KTextEditor::View \n
+ The View provides a widget that displays the contents of a Document, and its
+ interface allows for manipulation of text selection, position of the cursor and mouse,
+ text selections, and behaviour of the view. Additionally it provides access to
+ the view extension interfaces.
+
+The hierarchy can be illustrated as follows:
+\image html ktexteditorhierarchy.png "Basic KTextEditor Hierarchy"
+
+\section kte_design_user Notes for KTextEditor Users
+To use a KTextEditor implementation you first have to get the
+KTextEditor::Editor object. This can be done in several ways and is described
+in detail in the following documentation:
+ - KTextEditor::Factory
+
+\section kte_design_developer Notes for KTextEditor Developers
+The KTextEditor::Factory provides access to its KTextEditor::Editor. The
+Editor has a list of all opened documents and can create new documents. A
+Document's content is visualized by a View. A Document can have any number of
+views (or none). When the contents of the document are changed, the change
+is reflected in all views.
+
+The Factory \e should always return the same Editor object, as
+it does not make sense to load the same editor implementation several times.
+Further notes about the Editor implementation can be found in the
+\ref editor_notes.
+
+\see KTextEditor::Factory, KTextEditor::Editor, KTextEditor::Document,
+ KTextEditor::View
+
+\author Dominik Haumann \<dhdev@gmx.de\>
+*/
+
+
+
+
+
+/** \page kte_guidelines Coding Guidelines and API Conventions
+
+<p><b>
+\ref index "Overview" |
+\ref kte_design "Design" |
+Coding Guidelines |
+\ref kte_port_to_5 "Porting to Frameworks 5" |
+\ref kte_howto "Using"
+</b></p>
+
+All KTextEditor interfaces have a consistent design.
+- naming follows Qt style. Avoid Java style getters like getSomeData()
+ for example,
+- core interfaces (see \ref kte_design) which inherit QObject declare all
+ signals as real signals,
+- all other interfaces, which do not subclass QObject, must declare their
+ signals as virtual private member functions. An implementation must
+ reimplement this virtual member function as a real signal.
+- all signals have the sender object as first parameter, for example
+ all document signals have to look like this:
+ \code
+ void signalFromDocument (KTextEditor::Document *doc, ...);
+ \endcode
+ This allows easy and consistent query which object did send the signal,
+ which is important for most applications, as they listen to multiple
+ documents/views/editors/...
+- all interface functions should be virtual, to allow subclasses to
+ overwrite them, most members should even be pure virtual, beside
+ additional convenience/helper functions.
+
+The interface KTextEditor::Cursor represents a cursor position, i.e. a
+line/column tuple. The same holds for KTextEditor::Range. As both of this
+concepts are much cleaner than tuples, please keep the following guidelines:
+- never use line/column tuples in parameter lists, use KTextEditor::Cursor
+ instead,
+- never use Cursor/Cursor tuples for ranges, use KTextEditor::Range
+ instead of two Cursors.
+
+\author Christoph Cullmann \<cullmann@kde.org\>
+\author Dominik Haumann \<dhdev@gmx.de\>
+*/
+
+
+
+
+
+/** \defgroup kte_group_doc_extensions Document Extension Interfaces
+A KTextEditor implementation may implement a Document extension interface, but
+it does not \e need to. So as a KTextEditor user you have to cast the Document
+to the desired interface and then check, whether the cast returns NULL or the
+valid interface.
+
+Use qobject_cast to cast a Document \e doc into the
+\e DesiredExtensionInterface, example:
+\code
+ // doc is of type KTextEditor::Document*
+ KTextEditor::DesiredExtensionInterface *iface =
+ qobject_cast<KTextEditor::DesiredExtensionInterface*>( doc );
+
+ if( iface ) {
+ // the implementation supports the interface
+ // do stuff
+ }
+ else
+ {
+ // the implementation does not support the interface
+ }
+\endcode
+
+\see KTextEditor::Document
+
+The following classes are a list of all available Document extension interfaces.
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+
+
+/** \defgroup kte_group_moving_classes MovingCursors and MovingRanges
+\ingroup kte_group_doc_extensions
+
+If the KTextEditor implementation supports the KTextEditor::MovingInterface,
+there are several \e moving classes available.
+
+Instances of the \e moving classes are bound to a specific Document, and
+maintain their position in that document regardless of changes to the text.
+Changes to KTextEditor::MovingRange%s can be caught by using the class
+KTextEditor::MovingRangeFeedback.
+
+The following is a list of all classes that are available when the document
+supports the KTextEditor::MovingInterface:
+
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+
+
+/** \defgroup kte_group_view_extensions View Extension Interfaces
+A KTextEditor implementation may implement a View extension interface, but
+it does not \e need to. So as a KTextEditor user you have to cast the View
+to the desired interface and then check, whether the cast returns NULL or the
+valid interface.
+
+Use qobject_cast to cast a View \e view into the
+\e DesiredExtensionInterface, example:
+\code
+ // view is of type KTextEditor::View*
+ KTextEditor::DesiredExtensionInterface *iface =
+ qobject_cast<KTextEditor::DesiredExtensionInterface*>( view );
+
+ if( iface ) {
+ // the implementation supports the interface
+ // do stuff
+ }
+ else
+ {
+ // the implementation does not support the interface
+ }
+\endcode
+
+\see KTextEditor::View
+
+The following classes are a list of all available View extension interfaces.
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+
+
+/** \defgroup kte_group_editor_extensions Editor Extension Interfaces
+A KTextEditor implementation may implement an Editor extension interface, but
+it does not \e need to. So as a KTextEditor user you have to cast the Editor
+to the desired interface and then check, whether the cast returns NULL or the
+valid interface.
+
+Use qobject_cast to cast a Editor \e editor into the
+\e DesiredExtensionInterface, example:
+\code
+ // editor is of type KTextEditor::Editor*
+ KTextEditor::DesiredExtensionInterface *iface =
+ qobject_cast<KTextEditor::DesiredExtensionInterface*>( view );
+
+ if( iface ) {
+ // the implementation supports the interface
+ // do stuff
+ }
+ else
+ {
+ // the implementation does not support the interface
+ }
+\endcode
+
+\see KTextEditor::Editor
+
+The following classes are a list of all available Editor extension interfaces.
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+
+
+/** \defgroup kte_group_plugin_extensions Plugin Extension Interfaces
+A KTextEditor Plugin can use extension interfaces, but it does not \e need
+to. So as a KTextEditor implementator you have to cast the Plugin to the desired
+interface and then check, whether the cast returns NULL or the valid interface.
+
+Use qobject_cast to cast a Plugin \e plugin into the
+\e DesiredExtensionInterface, example:
+\code
+ // plugin is of type KTextEditor::Plugin*
+ KTextEditor::DesiredExtensionInterface *iface =
+ qobject_cast<KTextEditor::DesiredExtensionInterface*>( plugin );
+
+ if( iface ) {
+ // the implementation supports the interface
+ // do stuff
+ }
+ else
+ {
+ // the implementation does not support the interface
+ }
+\endcode
+
+\see KTextEditor::Plugin
+
+The following classes are a list of all available Plugin extension interfaces.
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+
+
+/** \defgroup kte_group_command_extensions Command Extension Interfaces
+A KTextEditor command-line Command can use extension interfaces, but it does not
+\e need to. So as a KTextEditor implementator you have to cast the Command to
+the desired interface and then check, whether the cast returns NULL or the valid
+interface.
+
+Use qobject_cast to cast a Command \e cmd into the
+\e DesiredExtensionInterface, example:
+\code
+ // cmd is of type KTextEditor::Command*
+ KTextEditor::DesiredExtensionInterface *iface =
+ qobject_cast<KTextEditor::DesiredExtensionInterface*>( cmd );
+
+ if( iface ) {
+ // the implementation supports the interface
+ // do stuff
+ }
+ else
+ {
+ // the implementation does not support the interface
+ }
+\endcode
+
+\see KTextEditor::Command
+
+The following classes are a list of all available Command extension interfaces.
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+/** \defgroup kte_group_ccmodel_extensions CodeCompletionModel Extension Interfaces
+A CodeCompletionModel implementation may implement a CodeCompletionModel
+extension interface, but it does not \e need to.
+
+\see KTextEditor::CodeCompletionModel
+
+The following classes are a list of all available CodeCompletionModel
+extension interfaces.
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+/** \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 |
+\ref kte_howto "Using"
+</b></p>
+
+This document describes porting applications using the KTextEditor interfaces
+from KDE 4 to KDE Frameworks 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 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. There are no plans to provide a compatibility layer.
+
+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.
+
+A KTextEditor::Factory class was introduced to access a specific Editor
+implementation, read \ref kte_design for detailed information.
+
+\section kte_port_remove Removed Interfaces and Removed Classes
+Entirely removed interfaces and classes are, in order:
+ - \p KTextEditor::EditorChooser \n
+ Instead, just use \p KTextEditor::editor();
+ - \p SmartInterface (removed since KDE 4.5)
+ - \p SmartCursor, \p SmartRange, \p SmartCursorNotifier, \p SmartCursorWatcher,
+ \p SmartRangeNotifier, \p SmartRangeWatcher (already unspoorted since KDE 4.5)
+ - \p LoadSaveFilterCheckPlugin was removed, since it was unused.
+
+\section kte_port_merge Merged Interfaces
+The following interfaces were merged, in order:
+ - \p CoordinatesToCursorInterface was merged into the KTextEditor::View.
+ - \p CodeCompletionModelControllerInterface2,
+ \p CodeCompletionModelControllerInterface3 and
+ \p CodeCompletionModelControllerInterface4
+ were merged into the \p KTextEditor::CodeCompletionModelControllerInterface.
+
+\section kte_port_rename Interface Changes
+The following interfaces were changed:
+ - \p KTextEditor::Editor::setSimpleMode() was removed.
+ - \p KTextEditor::View::setSelection(const Cursor &position, int length, bool wrap)
+ was removed in favour of the Range based KTextEditor::View::setSelection()
+ - \p KTextEditor::Document::wordRangeAt(const Cursor &position)
+ returns the Range of the word under \p position.
+ - \p KTextEditor::Document::wordAt(const Cursor &position)
+ returns the word under \p position.
+ - \p KTextEditor::Document::character() was renamed to
+ \p KTextEditor::Document::characterAt()
+ - \p KTextEditor::Document::readWriteChanged() \n
+ This signal is emitted whenever the read-only state of the document changes.
+ - \p KTextEditor::TextHintInterfacePrivate::needTextHint() now takes a View
+ as first parameter
+
+\section kte_port_new New Interfaces
+The following interfaces are new:
+ - none, yet.
+
+\section kte_port_enhanced_classes Significantly Enhanced Classes
+The following classes have been significantly enhanced:
+ - 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.
+ - KTextEditor::Range \n
+ The Range now is a tuple of two Cursors, namely the startCursor and the
+ 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.
+
+\section kte_port_new_classes New Classes
+The following classes are either new, or were added late in the KDE 4 release
+horizon:
+ - 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.
+ - 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.
+ - 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.
+ - KTextEditor::MovingRangeFeedback (since KDE 4.5) \n
+ Class providing notifications of changes to a KTextEditor::MovingRange.
+ - KTextEditor::MessageInterface (since KDE 4.11) \n
+ Class providing notifications to the user in a KTextEditor::View.
+
+\section kte_port_plugins 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 \e 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 KTextEditor::Plugin
+
+\author Dominik Haumann \<dhdev@gmx.de\>
+\author Hamish Rodda \<rodda@kde.org\>
+*/
+
+
+
+
+
+/** \page kte_howto How to use the KTextEditor Interfaces
+
+<p><b>
+\ref index "Overview" |
+\ref kte_design "Design" |
+\ref kte_guidelines "Coding Guidelines" |
+\ref kte_port_to_5 "Porting to KDE 4" |
+Using
+</b></p>
+
+This HOWTO will explain step by step how to load a KTextEditor component and
+plug a single View into a KMainWindow.
+
+Tobics:
+ - \ref kte_howto_header
+ - \ref kte_howto_source
+ - \ref kte_howto_notes
+
+\section kte_howto_header The Header File
+
+The following class only contains two pointers to a Document and its View.
+
+\code
+ #include <kxmlguiwindow.h>
+
+ namespace KTextEditor
+ {
+ class Document;
+ class View;
+ }
+
+ class MainWindow : public KXmlGuiWindow
+ {
+ Q_OBJECT
+
+ public:
+ MainWindow();
+ ~MainWindow();
+
+ private:
+ KTextEditor::View *m_view;
+ KTextEditor::Document *m_document;
+ };
+\endcode
+
+\section kte_howto_source The Mainwindow Implementation
+
+The following source code queries for a Editor part.
+If the returned Editor is invalid, we simply quit, otherwise we create a new
+document and a view and plug it into the mainwindow.
+
+\code
+ #include "mainwindow.h"
+ #include <ktexteditor/document.h>
+ #include <ktexteditor/view.h>
+ #include <ktexteditor/editor.h>
+
+ #include <kxmlguifactory.h>
+ #include <kmessagebox.h>
+
+ MainWindow::MainWindow ()
+ : KXmlGuiWindow(),
+ m_view(0),
+ m_document(0)
+ {
+ KTextEditor::Editor *editor = KTextEditor::editor();
+
+ if (!editor) {
+ KMessageBox::error(this, i18n("A KDE text-editor component could not be found;\n"
+ "please check your KDE installation."));
+ kapp->exit(1);
+ }
+
+ m_document = editor->createDocument(0);
+ m_view = m_document->createView(this);
+
+ setCentralWidget(m_view);
+
+ setXMLFile("mainwindowui.rc");
+ guiFactory()->addClient(m_view);
+
+ show ();
+ }
+
+ MainWindow::~MainWindow()
+ {
+ if (m_document) {
+ guiFactory()->removeClient(m_view);
+
+ // the document deletes its views itself
+ delete m_document;
+ }
+ }
+\endcode
+
+\section kte_howto_notes Notes
+In order to compile link against the following libraries:
+ - ktexteditor
+ - kdeui
+
+\author Dominik Haumann \<dhdev@gmx.de\>
+*/
+
+// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
// DOXYGEN_SET_PROJECT_NAME = KTextEditor
// vim:ts=4:sw=4:expandtab:filetype=doxygen
diff --git a/src/include/ktexteditor/Mainpage.dox b/src/include/ktexteditor/Mainpage.dox
deleted file mode 100644
index 955eb40..0000000
--- a/src/include/ktexteditor/Mainpage.dox
+++ /dev/null
@@ -1,599 +0,0 @@
-/*
-This file is part of the KDE project
-
-Copyright (c) 2005-2013 by Dominik Haumann <dhdev@gmx.de>
-Copyright (c) 2005 by Christoph Cullmann <cullmann@kde.org>
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2
-or any later version published by the Free Software Foundation;
-*/
-
-/** \mainpage KTextEditor
-
-<p><b>
-Overview |
-\ref kte_design "Design" |
-\ref kte_guidelines "Coding Guidelines" |
-\ref kte_port_to_5 "Porting to Frameworks 5" |
-\ref kte_howto "Using"
-</b></p>
-
-\section kte_intro Introduction
-The KTextEditor interfaces - also called KTE interfaces - are a set of
-well-defined interfaces which an application or library can implement to provide
-advanced plain text editing services. Applications which utilise this interface
-can thus allow the user to choose which implementation of the editor component
-to use. The only implementation right now is the Kate Editor Component
-(Kate Part).
-
-\section kte_general General
- - \ref kte_design
- - \ref kte_howto
- - \ref kte_port_to_5
- - <a href="http://www.kate-editor.org/support">Contact/Mailing Lists</a>
-
-
-\section kte_notes Implementation Notes
- - \ref kte_guidelines
-
-\section kte_extensions Extension Interfaces
- - \ref kte_group_doc_extensions
- - \ref kte_group_view_extensions
- - \ref kte_group_editor_extensions
- - \ref kte_group_plugin_extensions
- - \ref kte_group_command_extensions
- - \ref kte_group_ccmodel_extensions
-
-\section kte_apiref API Reference
- - <a href="classes.html">All Classes</a>
- - <a href="annotated.html">Annotated Classes</a>
- - <a href="hierarchy.html">Inheritance Hierarchy</a>
-<!-- grouped classes -> TODO Grouping -->
-
-@authors
-Dominik Haumann \<dhdev@gmx.de\><br>
-Christoph Cullmann \<cullmann@kde.org\><br>
-Hamish Rodda \<rodda@kde.org\><br>
-Joseph Wenninger \<jowenn@kde.org\><br>
-Jochen Wilhelmy \<digisnap@cs.tu-berlin.de\><br>
-Anders Lund \<anders@alweb.dk\><br>
-Matt Broadstone \<mbroadst@gmail.com\>
-
-@maintainers
-Dominik Haumann \<dhdev@gmx.de\><br>
-Christoph Cullmann \<cullmann@kde.org\><br>
-Hamish Rodda \<rodda@kde.org\>
-
-@licenses
-@lgpl
-
-*/
-
-
-
-
-
-/** \page kte_design Overview of the Core Interface Design
-
-<p><b>
-\ref index "Overview" |
-Design |
-\ref kte_guidelines "Coding Guidelines" |
-\ref kte_port_to_5 "Porting to KDE Frameworks 5" |
-\ref kte_howto "Using"
-</b></p>
-
-The core of the KTextEditor interfaces consists of several main interfaces:
-- KTextEditor::Factory \n
- The Factory provides access to the editor object.
-- KTextEditor::Editor \n
- The Editor interface allows you to create documents, get a document list,
- and a be informed when a new document is created.
-- KTextEditor::Document \n
- The Document interface represents a single document and enables the creation of
- views, access to and manipulation of document contents, and access to document
- extension interfaces.
-- KTextEditor::View \n
- The View provides a widget that displays the contents of a Document, and its
- interface allows for manipulation of text selection, position of the cursor and mouse,
- text selections, and behaviour of the view. Additionally it provides access to
- the view extension interfaces.
-
-The hierarchy can be illustrated as follows:
-\image html ktexteditorhierarchy.png "Basic KTextEditor Hierarchy"
-
-\section kte_design_user Notes for KTextEditor Users
-To use a KTextEditor implementation you first have to get the
-KTextEditor::Editor object. This can be done in several ways and is described
-in detail in the following documentation:
- - KTextEditor::Factory
-
-\section kte_design_developer Notes for KTextEditor Developers
-The KTextEditor::Factory provides access to its KTextEditor::Editor. The
-Editor has a list of all opened documents and can create new documents. A
-Document's content is visualized by a View. A Document can have any number of
-views (or none). When the contents of the document are changed, the change
-is reflected in all views.
-
-The Factory \e should always return the same Editor object, as
-it does not make sense to load the same editor implementation several times.
-Further notes about the Editor implementation can be found in the
-\ref editor_notes.
-
-\see KTextEditor::Factory, KTextEditor::Editor, KTextEditor::Document,
- KTextEditor::View
-
-\author Dominik Haumann \<dhdev@gmx.de\>
-*/
-
-
-
-
-
-/** \page kte_guidelines Coding Guidelines and API Conventions
-
-<p><b>
-\ref index "Overview" |
-\ref kte_design "Design" |
-Coding Guidelines |
-\ref kte_port_to_5 "Porting to Frameworks 5" |
-\ref kte_howto "Using"
-</b></p>
-
-All KTextEditor interfaces have a consistent design.
-- naming follows Qt style. Avoid Java style getters like getSomeData()
- for example,
-- core interfaces (see \ref kte_design) which inherit QObject declare all
- signals as real signals,
-- all other interfaces, which do not subclass QObject, must declare their
- signals as virtual private member functions. An implementation must
- reimplement this virtual member function as a real signal.
-- all signals have the sender object as first parameter, for example
- all document signals have to look like this:
- \code
- void signalFromDocument (KTextEditor::Document *doc, ...);
- \endcode
- This allows easy and consistent query which object did send the signal,
- which is important for most applications, as they listen to multiple
- documents/views/editors/...
-- all interface functions should be virtual, to allow subclasses to
- overwrite them, most members should even be pure virtual, beside
- additional convenience/helper functions.
-
-The interface KTextEditor::Cursor represents a cursor position, i.e. a
-line/column tuple. The same holds for KTextEditor::Range. As both of this
-concepts are much cleaner than tuples, please keep the following guidelines:
-- never use line/column tuples in parameter lists, use KTextEditor::Cursor
- instead,
-- never use Cursor/Cursor tuples for ranges, use KTextEditor::Range
- instead of two Cursors.
-
-\author Christoph Cullmann \<cullmann@kde.org\>
-\author Dominik Haumann \<dhdev@gmx.de\>
-*/
-
-
-
-
-
-/** \defgroup kte_group_doc_extensions Document Extension Interfaces
-A KTextEditor implementation may implement a Document extension interface, but
-it does not \e need to. So as a KTextEditor user you have to cast the Document
-to the desired interface and then check, whether the cast returns NULL or the
-valid interface.
-
-Use qobject_cast to cast a Document \e doc into the
-\e DesiredExtensionInterface, example:
-\code
- // doc is of type KTextEditor::Document*
- KTextEditor::DesiredExtensionInterface *iface =
- qobject_cast<KTextEditor::DesiredExtensionInterface*>( doc );
-
- if( iface ) {
- // the implementation supports the interface
- // do stuff
- }
- else
- {
- // the implementation does not support the interface
- }
-\endcode
-
-\see KTextEditor::Document
-
-The following classes are a list of all available Document extension interfaces.
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-
-
-/** \defgroup kte_group_moving_classes MovingCursors and MovingRanges
-\ingroup kte_group_doc_extensions
-
-If the KTextEditor implementation supports the KTextEditor::MovingInterface,
-there are several \e moving classes available.
-
-Instances of the \e moving classes are bound to a specific Document, and
-maintain their position in that document regardless of changes to the text.
-Changes to KTextEditor::MovingRange%s can be caught by using the class
-KTextEditor::MovingRangeFeedback.
-
-The following is a list of all classes that are available when the document
-supports the KTextEditor::MovingInterface:
-
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-
-
-/** \defgroup kte_group_view_extensions View Extension Interfaces
-A KTextEditor implementation may implement a View extension interface, but
-it does not \e need to. So as a KTextEditor user you have to cast the View
-to the desired interface and then check, whether the cast returns NULL or the
-valid interface.
-
-Use qobject_cast to cast a View \e view into the
-\e DesiredExtensionInterface, example:
-\code
- // view is of type KTextEditor::View*
- KTextEditor::DesiredExtensionInterface *iface =
- qobject_cast<KTextEditor::DesiredExtensionInterface*>( view );
-
- if( iface ) {
- // the implementation supports the interface
- // do stuff
- }
- else
- {
- // the implementation does not support the interface
- }
-\endcode
-
-\see KTextEditor::View
-
-The following classes are a list of all available View extension interfaces.
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-
-
-/** \defgroup kte_group_editor_extensions Editor Extension Interfaces
-A KTextEditor implementation may implement an Editor extension interface, but
-it does not \e need to. So as a KTextEditor user you have to cast the Editor
-to the desired interface and then check, whether the cast returns NULL or the
-valid interface.
-
-Use qobject_cast to cast a Editor \e editor into the
-\e DesiredExtensionInterface, example:
-\code
- // editor is of type KTextEditor::Editor*
- KTextEditor::DesiredExtensionInterface *iface =
- qobject_cast<KTextEditor::DesiredExtensionInterface*>( view );
-
- if( iface ) {
- // the implementation supports the interface
- // do stuff
- }
- else
- {
- // the implementation does not support the interface
- }
-\endcode
-
-\see KTextEditor::Editor
-
-The following classes are a list of all available Editor extension interfaces.
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-
-
-/** \defgroup kte_group_plugin_extensions Plugin Extension Interfaces
-A KTextEditor Plugin can use extension interfaces, but it does not \e need
-to. So as a KTextEditor implementator you have to cast the Plugin to the desired
-interface and then check, whether the cast returns NULL or the valid interface.
-
-Use qobject_cast to cast a Plugin \e plugin into the
-\e DesiredExtensionInterface, example:
-\code
- // plugin is of type KTextEditor::Plugin*
- KTextEditor::DesiredExtensionInterface *iface =
- qobject_cast<KTextEditor::DesiredExtensionInterface*>( plugin );
-
- if( iface ) {
- // the implementation supports the interface
- // do stuff
- }
- else
- {
- // the implementation does not support the interface
- }
-\endcode
-
-\see KTextEditor::Plugin
-
-The following classes are a list of all available Plugin extension interfaces.
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-
-
-/** \defgroup kte_group_command_extensions Command Extension Interfaces
-A KTextEditor command-line Command can use extension interfaces, but it does not
-\e need to. So as a KTextEditor implementator you have to cast the Command to
-the desired interface and then check, whether the cast returns NULL or the valid
-interface.
-
-Use qobject_cast to cast a Command \e cmd into the
-\e DesiredExtensionInterface, example:
-\code
- // cmd is of type KTextEditor::Command*
- KTextEditor::DesiredExtensionInterface *iface =
- qobject_cast<KTextEditor::DesiredExtensionInterface*>( cmd );
-
- if( iface ) {
- // the implementation supports the interface
- // do stuff
- }
- else
- {
- // the implementation does not support the interface
- }
-\endcode
-
-\see KTextEditor::Command
-
-The following classes are a list of all available Command extension interfaces.
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-/** \defgroup kte_group_ccmodel_extensions CodeCompletionModel Extension Interfaces
-A CodeCompletionModel implementation may implement a CodeCompletionModel
-extension interface, but it does not \e need to.
-
-\see KTextEditor::CodeCompletionModel
-
-The following classes are a list of all available CodeCompletionModel
-extension interfaces.
-<!-- The classes are defined by the \ingroup doxygen command -->
-*/
-
-
-
-/** \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 |
-\ref kte_howto "Using"
-</b></p>
-
-This document describes porting applications using the KTextEditor interfaces
-from KDE 4 to KDE Frameworks 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 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. There are no plans to provide a compatibility layer.
-
-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.
-
-A KTextEditor::Factory class was introduced to access a specific Editor
-implementation, read \ref kte_design for detailed information.
-
-\section kte_port_remove Removed Interfaces and Removed Classes
-Entirely removed interfaces and classes are, in order:
- - \p KTextEditor::EditorChooser \n
- Instead, just use \p KTextEditor::editor();
- - \p SmartInterface (removed since KDE 4.5)
- - \p SmartCursor, \p SmartRange, \p SmartCursorNotifier, \p SmartCursorWatcher,
- \p SmartRangeNotifier, \p SmartRangeWatcher (already unspoorted since KDE 4.5)
- - \p LoadSaveFilterCheckPlugin was removed, since it was unused.
-
-\section kte_port_merge Merged Interfaces
-The following interfaces were merged, in order:
- - \p CoordinatesToCursorInterface was merged into the KTextEditor::View.
- - \p CodeCompletionModelControllerInterface2,
- \p CodeCompletionModelControllerInterface3 and
- \p CodeCompletionModelControllerInterface4
- were merged into the \p KTextEditor::CodeCompletionModelControllerInterface.
-
-\section kte_port_rename Interface Changes
-The following interfaces were changed:
- - \p KTextEditor::Editor::setSimpleMode() was removed.
- - \p KTextEditor::View::setSelection(const Cursor &position, int length, bool wrap)
- was removed in favour of the Range based KTextEditor::View::setSelection()
- - \p KTextEditor::Document::wordRangeAt(const Cursor &position)
- returns the Range of the word under \p position.
- - \p KTextEditor::Document::wordAt(const Cursor &position)
- returns the word under \p position.
- - \p KTextEditor::Document::character() was renamed to
- \p KTextEditor::Document::characterAt()
- - \p KTextEditor::Document::readWriteChanged() \n
- This signal is emitted whenever the read-only state of the document changes.
- - \p KTextEditor::TextHintInterfacePrivate::needTextHint() now takes a View
- as first parameter
-
-\section kte_port_new New Interfaces
-The following interfaces are new:
- - none, yet.
-
-\section kte_port_enhanced_classes Significantly Enhanced Classes
-The following classes have been significantly enhanced:
- - 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.
- - KTextEditor::Range \n
- The Range now is a tuple of two Cursors, namely the startCursor and the
- 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.
-
-\section kte_port_new_classes New Classes
-The following classes are either new, or were added late in the KDE 4 release
-horizon:
- - 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.
- - 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.
- - 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.
- - KTextEditor::MovingRangeFeedback (since KDE 4.5) \n
- Class providing notifications of changes to a KTextEditor::MovingRange.
- - KTextEditor::MessageInterface (since KDE 4.11) \n
- Class providing notifications to the user in a KTextEditor::View.
-
-\section kte_port_plugins 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 \e 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 KTextEditor::Plugin
-
-\author Dominik Haumann \<dhdev@gmx.de\>
-\author Hamish Rodda \<rodda@kde.org\>
-*/
-
-
-
-
-
-/** \page kte_howto How to use the KTextEditor Interfaces
-
-<p><b>
-\ref index "Overview" |
-\ref kte_design "Design" |
-\ref kte_guidelines "Coding Guidelines" |
-\ref kte_port_to_5 "Porting to KDE 4" |
-Using
-</b></p>
-
-This HOWTO will explain step by step how to load a KTextEditor component and
-plug a single View into a KMainWindow.
-
-Tobics:
- - \ref kte_howto_header
- - \ref kte_howto_source
- - \ref kte_howto_notes
-
-\section kte_howto_header The Header File
-
-The following class only contains two pointers to a Document and its View.
-
-\code
- #include <kxmlguiwindow.h>
-
- namespace KTextEditor
- {
- class Document;
- class View;
- }
-
- class MainWindow : public KXmlGuiWindow
- {
- Q_OBJECT
-
- public:
- MainWindow();
- ~MainWindow();
-
- private:
- KTextEditor::View *m_view;
- KTextEditor::Document *m_document;
- };
-\endcode
-
-\section kte_howto_source The Mainwindow Implementation
-
-The following source code queries for a Editor part.
-If the returned Editor is invalid, we simply quit, otherwise we create a new
-document and a view and plug it into the mainwindow.
-
-\code
- #include "mainwindow.h"
- #include <ktexteditor/document.h>
- #include <ktexteditor/view.h>
- #include <ktexteditor/editor.h>
-
- #include <kxmlguifactory.h>
- #include <kmessagebox.h>
-
- MainWindow::MainWindow ()
- : KXmlGuiWindow(),
- m_view(0),
- m_document(0)
- {
- KTextEditor::Editor *editor = KTextEditor::editor();
-
- if (!editor) {
- KMessageBox::error(this, i18n("A KDE text-editor component could not be found;\n"
- "please check your KDE installation."));
- kapp->exit(1);
- }
-
- m_document = editor->createDocument(0);
- m_view = m_document->createView(this);
-
- setCentralWidget(m_view);
-
- setXMLFile("mainwindowui.rc");
- guiFactory()->addClient(m_view);
-
- show ();
- }
-
- MainWindow::~MainWindow()
- {
- if (m_document) {
- guiFactory()->removeClient(m_view);
-
- // the document deletes its views itself
- delete m_document;
- }
- }
-\endcode
-
-\section kte_howto_notes Notes
-In order to compile link against the following libraries:
- - ktexteditor
- - kdeui
-
-\author Dominik Haumann \<dhdev@gmx.de\>
-*/
-
-// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
-// DOXYGEN_SET_PROJECT_NAME = KTextEditor
-// vim:ts=4:sw=4:expandtab:filetype=doxygen