Kate

© 2005 by Dominik Haumann

If you need a more powerful text editor part than a simple KTextEdit the way to go is to embed a katepart into your application. This HOWTO assumes you already have a working KDE application based on a KMainWindow. You can achieve this for example with KDevelop templates.

Basics

The sourcecode of the KatePart can be found in the KDE module kdelibs in kdelibs/kate/part. However this is mainly internal code, and as a user you do not really have to look into it. More important is the interface defined by the KatePart. The KatePart implements the KTextEditor interface, but we assume here, that you want to support the KatePart only - and not all editor components that implement the KTextEditor interface, which means we directly query for a KatePart and not for a general text editor component. So the much more important interface files (header files) can be found in kdelibs/kate/interfaces. This files are installed into the folder $KDEDIR/include/kate/, and can be included by using for example

#include <kate/document.h>
#include <kate/view.h>

The class Kate::Document is derived from many KTextEditor classes, which means all the interfaces are implemented. The following code snippet is copied from kate/document.h file:

class Document :
    public KTextEditor::Document,
    public KTextEditor::EditInterface,
    public KTextEditor::UndoInterface,
    public KTextEditor::CursorInterface,
    public KTextEditor::SelectionInterface,
    public KTextEditor::SearchInterface,
    public KTextEditor::HighlightingInterface,
    public KTextEditor::BlockSelectionInterface,
    public KTextEditor::ConfigInterface,
    public KTextEditor::MarkInterface,
    public KTextEditor::PrintInterface,
    public KTextEditor::WordWrapInterface,
    public KTextEditor::MarkInterfaceExtension,
    public KTextEditor::SelectionInterfaceExt
{ ... };

Same goes for the Kate::View

class View :
    public KTextEditor::View,
    public KTextEditor::ClipboardInterface,
    public KTextEditor::PopupMenuInterface,
    public KTextEditor::ViewCursorInterface,
    public KTextEditor::CodeCompletionInterface,
    public KTextEditor::DynWordWrapInterface
{ ... };

Look into the files in the folder $KDEDIR/include/ktexteditor to see what functions are available then.

Embedding a KatePart

As the KatePart is a library you have to load it by using KDE’s library factory. If the library does exist, a new part can be created. To do this, we first start with our own MainWindow implementation.

The Constructor

The MainWindow could look like this

#include "mainwindow.h"     // own mainwindow, derived from KMainWindow

#include <kmainwindow.h>    // KMainWindow
#include <kparts/factory.h> // KPart Factory
#include <klibloader.h>     // LibLoader, contains factories
#include <kate/document.h>  // Katepart document
#include <kate/view.h>      // Katepart view

MainWindow::MainWindow()
    : KMainWindow( 0, "MainWindow" )
{
    // set the XMLGUI ui resource file
    setXMLFile( "mainwindowui.rc" );

    // create the document and view
    // Assuming, Kate::View* m_view; is a member of the MainWindow
    m_view = createKatePart();

    // set the view as mainwindow
    setCentralWidget( m_view );

    // add the view's XML GUI Client
    guiFactory()->addClient( m_view );
}

Creating a KatePart

In general that is what initializes the mainwindow including a menu. Still missing is the creation of a KatePart, this can be done as follows:

Kate::View* MainWindow::createKatePart()
{
    // Get KPart factory for the katepart library.
    // This returns 0, if the library can not be found
    KParts::Factory* factory = (KParts::Factory *)
        KLibLoader::self()->factory ("libkatepart");

    if (factory)
    {
        // The library was found, so create the Kate::Document
        KTextEditor::Document *doc = (KTextEditor::Document *)
            factory->createPart( 0, "", this, "", "KTextEditor::Document" );

        // The document only represents the document, to view
        // the document's content
        // we have to create a view for the document.
        Kate::View *view = (Kate::View *) doc->createView( this, 0L );

        // all went well, so return the view
        return view;
    }
    else
    {
        // The library was not found
        return 0L;
    }
}

If you now compile, you already should see an embedded KatePart. If you have linker problems, make sure you link against -lkparts and -lkdeui.

Further Signals

It’s up to you now to connect further signals to slots, for example if you have a status bar, you can connect the following signals to a slot:

view->getDoc(), SIGNAL( nameChanged(Kate::Document *) )
view,           SIGNAL( cursorPositionChanged() )
view,           SIGNAL( newStatus() )
view->getDoc(), SIGNAL( undoChanged() )

To provide a nice popup menu you have to install one yourself, like view->installPopup ((QPopupMenu*)(mainWindow()->factory() ->container(“ktexteditor_popup”, mainWindow())) );

There are much more signals, look into the files kate/view.h and kate/document.h to see what is available!

The Destructor

Still missing is a clean application exit, where the view and document are destroyed. We will implement this in the MainWindow’s destructor:

MainWindow::~MainWindow()
{
    if ( m_view )
    {
        // remove the view's XML GUI client
        guiFactory()->removeClient( m_view );

        // remove the view, then the doc
        Kate::Document *doc = m_view->getDoc();
        delete m_view;
        delete doc;
    }
}

How the Kate Application does all this

The Kate application has more advanced features. Because you can edit multiple files at once Kate is a MDI application. Therefore Kate has a document manager, that contains a list of all opened documents. As a document can have one or more views Kate has a powerful viewspace manager, that allows for example window splitting.