summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlex Merry <kde@randomguy3.me.uk>2014-01-21 02:25:07 (GMT)
committerAlex Merry <kde@randomguy3.me.uk>2014-01-23 16:58:24 (GMT)
commit49f259c728fe1930c38bb940c6f7a9306d879642 (patch)
tree4f8504c9430ca4aece2d63956bb24b2b6bf5eeb3
parent18c71aae37f8404a1e8ab25134e1bf78b0a6dad7 (diff)
Split Mainpage.dox up
The front page content goes in README.md. Other pages are now in separate files under docs/. It would be nice to convert some or all of the documentation pages to markdown, so they can be easily read without running them through doxygen first.
-rw-r--r--Mainpage.dox592
-rw-r--r--README.md11
-rw-r--r--docs/apidocs-groups.dox193
-rw-r--r--docs/coding-guidelines.dox41
-rw-r--r--docs/design.dox51
-rw-r--r--docs/howto.dox156
-rw-r--r--docs/porting.dox122
7 files changed, 572 insertions, 594 deletions
diff --git a/Mainpage.dox b/Mainpage.dox
deleted file mode 100644
index 515d78a..0000000
--- a/Mainpage.dox
+++ /dev/null
@@ -1,592 +0,0 @@
-/** \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 (short: KTE) framework provides a set of well-defined
-interfaces that provide a full fledged text editor. Well-known applications
-that use the KTextEditor framework are Kate, KDevelop or Kile.
-
-\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 \<dhaumann@kde.org\><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 \<dhaumann@kde.org\><br>
-Christoph Cullmann \<cullmann@kde.org\><br>
-
-@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 three main interfaces:
-- KTextEditor::Editor (singleton) \n
- The Editor is a singleton accessed through KTextEditor::Editor::instance().
- This singleton allows 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 behavior 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 \<dhaumann@kde.org\>
-*/
-
-
-
-
-
-/** \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 \<dhaumann@kde.org\>
-*/
-
-
-
-
-
-/** \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 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 Interfaces and Removed 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();
- - \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 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::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:
- - 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.
- - 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.
- - KTextEditor::MessageInterface (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:
- - 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 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.
-
-\section kte_port_new_classes New Classes
-The following classes are either new, or were added late in the KDE 4 release cycle:
- - 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.
-
-\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 MainWindow%s and
-access the Application's document list. So the applications 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\>
-*/
-
-
-
-
-
-/** \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.
-
-Topics:
- - \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 \<dhaumann@kde.org\>
-*/
-
-// DOXYGEN_REFERENCES = kdecore kdeui kio kparts
-// DOXYGEN_SET_PROJECT_NAME = KTextEditor
-// vim:ts=4:sw=4:expandtab:filetype=doxygen
diff --git a/README.md b/README.md
index 82de5a2..226476c 100644
--- a/README.md
+++ b/README.md
@@ -33,8 +33,8 @@ If you are using CMake, you need to have
find_package(KF5TextEditor NO_MODULE)
-(or similar) in your CMakeLists.txt file, and you need to link any target that
-uses KTextEditor against KF5::TextEditor.
+(or similar) in your CMakeLists.txt file, and you need to link to
+KF5::TextEditor.
After that, you can use KTextEditor::Editor to create an editor instance, and
use that to manage KTextEditor::Document instances.
@@ -55,6 +55,13 @@ See the documentation for these classes for more information.
Contributions to KTextEditor shall be licensed under LGPLv2+.
+## Further Documentation
+
+- @ref kte_design
+- @ref kte_howto
+- @ref kte_port_to_5
+- @ref kte_guidelines
+
## Links
- Home page: <https://projects.kde.org/projects/frameworks/ktexteditor>
diff --git a/docs/apidocs-groups.dox b/docs/apidocs-groups.dox
new file mode 100644
index 0000000..d4fc054
--- /dev/null
+++ b/docs/apidocs-groups.dox
@@ -0,0 +1,193 @@
+/** \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 -->
+*/
diff --git a/docs/coding-guidelines.dox b/docs/coding-guidelines.dox
new file mode 100644
index 0000000..6983562
--- /dev/null
+++ b/docs/coding-guidelines.dox
@@ -0,0 +1,41 @@
+/** \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 \<dhaumann@kde.org\>
+*/
diff --git a/docs/design.dox b/docs/design.dox
new file mode 100644
index 0000000..703bd8b
--- /dev/null
+++ b/docs/design.dox
@@ -0,0 +1,51 @@
+/** \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 three main interfaces:
+- KTextEditor::Editor (singleton) \n
+ The Editor is a singleton accessed through KTextEditor::Editor::instance().
+ This singleton allows 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 behavior 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 \<dhaumann@kde.org\>
+*/
diff --git a/docs/howto.dox b/docs/howto.dox
new file mode 100644
index 0000000..09cd846
--- /dev/null
+++ b/docs/howto.dox
@@ -0,0 +1,156 @@
+/** \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 \<dhaumann@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.
+
+Topics:
+ - \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 \<dhaumann@kde.org\>
+*/
diff --git a/docs/porting.dox b/docs/porting.dox
new file mode 100644
index 0000000..918a1ca
--- /dev/null
+++ b/docs/porting.dox
@@ -0,0 +1,122 @@
+/** \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 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 Interfaces and Removed 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();
+ - \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 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::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:
+ - 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.
+ - 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.
+ - KTextEditor::MessageInterface (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:
+ - 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 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.
+
+\section kte_port_new_classes New Classes
+The following classes are either new, or were added late in the KDE 4 release cycle:
+ - 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.
+
+\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 MainWindow%s and
+access the Application's document list. So the applications 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\>
+*/