/*
This file is part of the KDE project

Copyright (c) 2005-2006 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_kde4 "Porting to KDE 4" |
\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_kde4
 - <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_kde4 "Porting to KDE 4" |
\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
 - KTextEditor::EditorChooser

\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.

As applications can load different editor implementations via different
factories (for example the kate-part and the yzis-part) the signal
KTextEditor::Editor::documentCreated() contains the responsible Editor as
first argument.

\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_kde4 "Porting to KDE 4" |
\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 cursorposition, 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_smart_classes Smart Cursors and Ranges
\ingroup kte_group_doc_extensions

If the KTextEditor implementation supports the KTextEditor::SmartInterface,
there are several \e smart classes available.

In general, instances of the \e smart classes are bound to a specific document, and maintain their
position in that document regardless of changes to the text.  They also provide:
- feedback on changes to their position and changes to text related to their position,
- support for the other \e smart interfaces, such as arbitrary highlighting, action binding, etc.

The following is a list of all classes that are available when the document
supports the KTextEditor::SmartInterface:

\warning All Smart interfaces were deprecated and not implemented anymore in
KDE >= 4.6. They were replaced by the \ref kte_group_moving_classes

<!-- 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 MovingRange%s can be caught by using the class 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_kde4 Porting to KDE 4

<p><b>
\ref index "Overview" |
\ref kte_design "Design" |
\ref kte_guidelines "Coding Guidelines" |
Porting to %KDE 4 |
\ref kte_howto "Using"
</b></p>

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.

\section kte_port_intro 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 \ref kte_design for detailed information.

\section kte_port_remove 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
 - \p ClipboardInterface
 - \p CursorInterface
 - \p DynWordWrapInterface
 - \p PrintInterface
 - \p SelectionExtDCOPInterface
 - \p UndoInterface
 - \p ViewStatusMsgInterface
 - \p WordWrapInterface

\section kte_port_merge Merged Interfaces
The following interfaces were merged, in order:
 - \p BlockSelectionInterface, \p SelectionInterface and
   \p SelectionInterfaceExt were merged into the KTextEditor::View, so that a
   KTextEditor::Document itself does not provide any selection methods anymore.
 - \p 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
 - \p DocumentInfoInterface was merged into the KTextEditor::Document
 - \p EditInterface was merged into the KTextEditor::Document
 - \p EditInterfaceExt was merged into the KTextEditor::Document
 - \p EncodingInterface was merged into the KTextEditor::Document
 - \p HighlightingInterface was merged into the KTextEditor::Document
 - \p MarkInterfaceExtension was merged into the KTextEditor::MarkInterface
 - \p PluginViewInterface was merged into the KTextEditor::Plugin
 - \p PopupMenuInterface was merged into the KTextEditor::View
 - \p ViewCursorInterface was merged into the KTextEditor::View

\section kte_port_rename Interface Changes
The following interfaces were renamed:
 - \p 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.
 - \p CompletionEntry was renamed to KTextEditor::CompletionItem
 - signal \p modifiedOnDisc() was renamed to
   KTextEditor::ModificationInterface::modifiedOnDisk()

\section kte_port_new 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

\section kte_port_enhanced_classes Significantly Enhanced Classes
The following classes have been significantly enhanced:
 - KTextEditor::Cursor \n
   Has been upgraded for greatly increased convenience, and now forms a
   cornerstone of the KTextEditor interfaces.

\section kte_port_new_classes New Classes
The following classes are new:
 - KTextEditor::SmartCursor \n
   A cursor which is bound to a specific KTextEditor::Document, and maintains
   its position.
 - KTextEditor::SmartCursorWatcher and KTextEditor::SmartCursorNotifier \n
   Classes for providing notifications of changes to a SmartCursor.
 - KTextEditor::Range \n
   A tuple of start + end cursors with many convenience methods
 - KTextEditor::SmartRange \n
   A KTextEditor::Range which is bound to a specific Document, and maintains its
   position.
 - KTextEditor::SmartRangeWatcher and KTextEditor::SmartRangeNotifier \n
   Classes for providing notifications of changes to a SmartRange.

\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_kde4 "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 by using the EditorChooser.
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 <ktexteditor/editorchooser.h>

  #include <kxmlguifactory.h>
  #include <kmessagebox.h>

  MainWindow::MainWindow ()
    : KXmlGuiWindow(),
      m_view(0),
      m_document(0)
  {
    KTextEditor::Editor *editor = KTextEditor::EditorChooser::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