ktexteditor/docs/design.dox

0001 /** \page kte_design Overview of the Core Interface Design
0002
0003 <p><b>
0004 \ref index "Overview" |
0005 Design |
0006 \ref kte_guidelines "Coding Guidelines" |
0007 \ref kte_port_to_5 "Porting to KDE Frameworks 5"
0008 </b></p>
0009
0010 The core of the KTextEditor interfaces consists of three main interfaces:
0011 - KTextEditor::Editor (singleton) \n
0012   The Editor is a singleton accessed through KTextEditor::Editor::instance().
0013   This singleton allows to create documents, get a document list, and a be
0014   informed when a new document is created.
0015 - KTextEditor::Document \n
0016   The Document interface represents a single document and enables the creation of
0017   views, access to and manipulation of document contents, and access to document
0018   extension interfaces.
0019 - KTextEditor::View \n
0020   The View provides a widget that displays the contents of a Document, and its
0021   interface allows for manipulation of text selection, position of the cursor and mouse,
0022   text selections, and behavior of the view.  Additionally it provides access to
0023   the view extension interfaces.
0024
0025 The hierarchy can be illustrated as follows:
0026 \image html ktexteditorhierarchy.png "Basic KTextEditor Hierarchy"
0027
0028 \section kte_design_user Notes for KTextEditor Users
0029 To use the KTextEditor framework you first have to get the KTextEditor::Editor
0030 singleton through KTextEditor::Editor::instance(). Using this obejct, documents
0031 can be created and deleted.
0032
0033 \section kte_design_part Using KTextEditor as KPart
0034 If linking to KF5::TextEditor is not an option, you can also access the
0035 KTextEditor framework as follows
0036 \code
0037   KService::Ptr service = KService::serviceByDesktopPath("katepart");
0038   if (service) {
0039       m_part = service->createInstance<KParts::ReadWritePart>(0);
0040   }
0041 \endcode
0042
0043 \section kte_design_developer Notes for KTextEditor Developers
0044 The KTextEditor::Editor has a list of all opened documents and can create new
0045 documents. A Document's content is visualized by a KTextEditor::View. A Document
0046 can have any number of views (or none). When the content of the document is
0047 changed, the change is reflected in all views.
0048
0049 \see KTextEditor::Editor, KTextEditor::Document, KTextEditor::View
0050
0051 \author Dominik Haumann \<dhaumann@kde.org\>
0052 */