plugintutorial.dox

/*! @page plugintutorial Plugin Tutorial 

@section intro Introduction

This page is a short tutorial about creating your own input method plugin.
MeeGo Touch Input Method provides a framework which developers can extend the functionality 
of the input method by providing a new input method user interface. The new input method is implemented as 
a plugin.

This page shows some excerpts from MeeGo Keyboard source code.

@section skeleton Skeleton
There are two important parts in the plugin making: the user interface of the input method, which is the part that user interact with while inputting text; and the settings, which is the part that enables user to set preferences on the input method.


@subsection ui User interface
The UI is loaded and controlled by a MAbstractInputMethod class. 
@code
class MKeyboardHost: public MAbstractInputMethod
{
    Q_OBJECT

    public:
        MKeyboardHost(MAbstractInputMethodHost *host, QWidget *mainWindow);
        virtual ~MKeyboardHost();
    .....
@endcode

The MAbstractInputMethod itself needs to be loaded by the plugin class, which is a MInputMethodPlugin class. For the plugin system to work, class must declare proper interface using Q_INTERFACES (in the header file) and export the plugin with Q_EXPORT_PLUGIN2 (in the .cpp file):

@code
// The header file:
class MKeyboardPlugin : public QObject, public MInputMethodPlugin
{
    Q_OBJECT
    Q_INTERFACES(MInputMethodPlugin)

public:
    MKeyboardPlugin();
    virtual ~MKeyboardPlugin();
    .....
@endcode
@code
// At the end of the .cpp file:
Q_EXPORT_PLUGIN2(meego-keyboard, MKeyboardPlugin)
@endcode

The UI class is created in the createInputMethod method:

@code
MAbstractInputMethod *
MKeyboardPlugin::createInputMethod(MAbstractInputMethodHost *host, QWidget *mainWindow)
{
    MAbstractInputMethod *inputMethod = new MKeyboardHost(host, mainWindow);
    return inputMethod;
}
@endcode

The plugin is given a main window that should be used as a parent widget for plugin visualization.
Plugin is then free to create a QWidget or QGraphicsView or similar. 

The interaction between the UI and the application is done by employing functions provided by MAbstractInputMethod and MAbstractInputMethodHost.

@subsection settings Settings
Settings is basically a QGraphicsWidget which holds items to provide user to set some preferences or behaviour of the input method. It is displayed in the control panel of the system.

The settings is created by subclassing MAbstractInputMethodSettings.
@code
/*!
 * \brief MKeyboardSettings is the implemetation of meego-keyboard setting.
 * MKeyboardSettings implement MAbstractInputMethodSettings and create the meego-keyboard
 * setting. It provides below functionalities: get/set error corretion, get/set word
 * completion, get/set installed (selected) keyboards.
 */
class MKeyboardSettings: public QObject, public MAbstractInputMethodSettings
{
    Q_OBJECT

public:
    MKeyboardSettings();
    .....
@endcode

The actual widget shown is created in MKeyboardSettings::createContentWidget:
@code
QGraphicsWidget *MKeyboardSettings::createContentWidget(QGraphicsWidget *parent)
{
    // the pointer of returned QGraphicsWidget is owned by the caller,
    // so we just always create a new containerWidget.
    return new MKeyboardSettingsWidget(this, parent);
}
@endcode

@section compilation Compilation
To use the framework you need to add @c plugin and @c meegoimframework to @c CONFIG variable in your project file.
@code
CONFIG += plugin meegoimframework
@endcode

@section installation Installation
The plugin is installed to @c /usr/lib/meego-im-plugins directory. Depending on the user interface type, the plugin can be activated programmaticaly by setting the handler GConf key to the name of the plugin. The GConf parent key is @c /meegotouch/inputmethods/plugins/handler.

During runtime the plugin can be selected from control panel on the system.

*/