| Classes | Functions | DevRef | Qt API | Qtopia Documentation |

## Input Methods

Input methods must supply a QWidget that will be shown above the task bar and emit a signal when a key is pressed:

    #include <qwidget.h>

    class SimpleInputMethod : public QWidget
    {
        Q_OBJECT
    public:
        SimpleInputMethod( QWidget *parent, const char *name, WFlags f );

    signals:
        void keyPress( ushort unicode, ushort keycode, ushort modifiers, bool press, bool repeat )
    };

The parameters of the keyPress signal are:

Parameter | Notes
--- | ---
unicode | The unicode value of the character, or 0xFFFF if it is a non-printing key.
keycode | The key code as specified in `qnamespace.h`
modifiers | A combination of zero or more of the following OR'ed together: Qt::ShiftButton, Qt::ControlButton and Qt::AltButton
press | TRUE for a key press, FALSE for a key release.
repeat | TRUE if this is a repeating keypress.

Input methods may be added to Qtopia via plugins. In order to write an input method plugin you must create an interface to your input method by deriving from the InputMethodInterface class and implementing the pure virtual functions.

To make an input method plugin the following implementation is required:

    #include <qpe/inputmethodinterface.h>

    class SimpleInputMethodImpl : public InputMethodInterface
    {
    public:
        SimpleInputMethodImpl();
        virtual ~SimpleInputMethodImpl();

    #ifndef QT_NO_COMPONENT
        QRESULT queryInterface( const QUuid&, QUnknownInterface** );
        Q_REFCOUNT
    #endif

        virtual QWidget *inputMethod( QWidget *parent, Qt::WFlags f );
        virtual void resetState();
        virtual QPixmap *icon();
        virtual QString name();
        virtual void onKeyPress( QObject *receiver, const char *slot );

    private:
        SimpleInputMethod *input;
        QPixmap *icn;
        ulong ref;
    };

The constructor and destructor are very simple:

    SimpleInputMethodImpl::SimpleInputMethodImpl()
        : input(0), icn(0), ref(0)
    {
    }

    SimpleInputMethodImpl::~SimpleInputMethodImpl()
    {
        delete input;
        delete icn;
    }

The queryInterface() function can be implemented using the following boilerplate code:

    QRESULT SimpleInputMethodImpl::queryInterface( const QUuid &uuid, QUnknownInterface **iface )
    {
        *iface = 0;
        if ( uuid == IID_QUnknown )
            *iface = this;
        else if ( uuid == IID_InputMethod )
            *iface = this;

        if ( *iface )
            (*iface)->addRef();
        return QS_OK;
    }

The inputMethod() function returns the input method widget. This widget will be display just above the task bar when the user needs to input text. You should always return the same widget if this function is called multiple times.

    QWidget *SimpleInputMethodImpl::inputMethod( QWidget *parent, Qt::WFlags f )
    {
        if ( !input )
            input = new SimpleInputMethod( parent, "SimpleInput", f );
        return input;
    }

The resetState() function should return the input method to its default state.

The name() function returns the name of the input method. This will be displayed in the popup list of available input methods.

    QString SimpleInputMethodImpl::name()
    {
        return qApp->translate( "InputMethods", "SimpleInput" );
    }

The name() function returns the icon for the input method. This will be displayed in the taskbar when the input method is selected.

    QPixmap *SimpleInputMethodImpl::icon()
    {
        if ( !icn )
            icn = new QPixmap( your pixmap );
        return icn;
    }

The onKeyPress() function must connect the supplied slot to the signal that is emitted when a key press is generated.

The following code will connect the signal to the supplied slot:

    void SimpleInputMethodImpl::onKeyPress( QObject *receiver, const char *slot )
    {
        if ( input )
            QObject::connect( input, SIGNAL(keyPress(ushort,ushort,ushort,bool,bool)), receiver, slot );
    }

You must also create an instance of the input method plugin using the following boilerplate code:

    Q_EXPORT_INTERFACE()
    {
        Q_CREATE_INSTANCE( SimpleInputMethodImpl )
    }

The plugin must be compiled as a shared library and placed in the `$QPEDIR/plugins/imputmethods` directory. The following `tmake` project file will create a suitable Makefile:

    TEMPLATE     = lib
    CONFIG      += qt warn_on release
    HEADERS      = simpleinputmethod.h \
                   simpleinputmethodimpl.h
    SOURCES      = simpleinputmethod.cpp \
                   simpleinputmethodimpl.cpp
    TARGET       = simpleinputmethod
    DESTDIR      = $(QPEDIR)/plugins/inputmethods
    INCLUDEPATH += $(QPEDIR)/include
    LIBS        += -lqpe
    VERSION      = 1.0.0

Examples of Qtopia input methods can be found in the `inputmethods/` directory of the Qtopia source code.