QWSInputMethod Class Reference
^{[QtGui module]}

Detailed Description

The QWSInputMethod class provides international input methods in Qtopia Core.

Note that this class is still subject to change.

An input method consists of a keyboard filter and optionally a graphical interface. Derive from this class to implement custom input methods, and use the QWSServer::setCurrentInputMethod() function to install it.

To intercept key events from physical or virtual keyboards, reimplement the filter() function and use the setInputResolution() function to control the number of bits shifted when going from pointer resolution to screen resolution in the process of filtering mouse events (the current settings can be retrieved using the inputResolutionShift() function). To handle mouse events within a preedit text, reimplement the virtual mouseHandler() function.

Internally, preedit texts are passed encapsulated by an IMEvent generated by the sendPreeditString() function which is a convenience function for sendEvent(). The sendEvent() function sends a QInputMethodEvent object to the focus widget. QWSInputMethod also provides the sendCommitString() convenience function which sends a QInputMethodEvent object encapsulating given commit string to the focus widget, and the sendMouseEvent() function which creates (and sends) a QWSEvent of the QWSEvent::Mouse type from the given parameters.

The reset() function allows subclasses of QWSInputMethod to reset the state of the input method. The default implementation calls sendEvent() with empty preedit and commit strings, if the input method is in compose mode, i.e. the input method is actively composing a preedit string.

The QWSInputMethod class also provides the sendQuery() function for sending input method queries. When deriving from QWSInputMethod, the virtual queryResponse() function must be reimplemented to receive responses to such queries.

Finally, QWSInputMethod provides the updateHandler() function handling update events, including resets and focus changes. The UpdateType enum describes the various types of update events recognized by the input method.

See also QWSEvent, QWSServer, and Qtopia Core.

Member Type Documentation

enum QWSInputMethod::UpdateType

This enum describes the various types of update events recognized by the input method.

See also updateHandler().

Member Function Documentation

QWSInputMethod::QWSInputMethod ()

Constructs a new input method.

QWSInputMethod::~QWSInputMethod ()   [virtual]

Destructs this input method, uninstalling it if it is installed.

bool QWSInputMethod::filter ( int unicode, int keycode, int modifiers, bool isPress, bool autoRepeat )   [virtual]

This virtual function allows subclasses of QWSInputMethod to handle key input from physical or virtual keyboards.

To block the event from further processing, return true when reimplementing this function; the default implementation returns false.

The key input is identified by its unicode, keycode (a Qt::Key value), modifiers (an OR combination of Qt::KeyboardModifiers), isPress telling whether the input is a key press or key release, and autoRepeat determining if the input is auto repeated.

See also QWSKeyboardHandler and Character Input.

bool QWSInputMethod::filter ( const QPoint & position, int state, int wheel )   [virtual]

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QWSInputMethod to handle mouse input from physical or virtual pointer devices.

To block the event from further processing, return true when reimplementing this function; the default implementation returns false. The mouse event is specified by the given position, state and wheel parameters.

See also setInputResolution(), QWSMouseHandler, and Pointer Handling.

uint QWSInputMethod::inputResolutionShift () const   [protected]

Returns the number of bits shifted to go from pointer resolution to screen resolution when filtering mouse events using the filter() function.

See also setInputResolution().

void QWSInputMethod::mouseHandler ( int offset, int state )   [virtual]

This virtual function allows subclasses of QWSInputMethod to handle mouse events within the preedit text.

The offset parameter specifies the position of the mouse event within the string, and state the type of the mouse event as described by the QWSServer::IMMouse enum. If state is less than 0, the mouse event is inside the associated widget, but outside the preedit text. When clicking in a different widget, the state is QWSServer::MouseOutside.

The default implementation resets the input method on all mouse presses.

See also sendPreeditString() and reset().

void QWSInputMethod::queryResponse ( int property, const QVariant & result )   [virtual]

This virtual function allows subclasses of QWSInputMethod to receive replies to an input method query.

Internally, an input method query is passed encapsulated by an IMQuery event generated by the sendQuery() function. The queried property and the result is passed in the property and result parameters.

See also sendQuery() and QWSServer::sendIMQuery().

void QWSInputMethod::reset ()   [virtual]

This virtual function allows subclasses of QWSInputMethod to reset the state of the input method.

The default implementation calls sendEvent() with empty preedit and commit strings, if the input method is in compose mode, i.e. the input method is actively composing a preedit string.

See also sendEvent().

void QWSInputMethod::sendCommitString ( const QString & commitString, int replaceFromPosition = 0, int replaceLength = 0 )   [protected]

Sends a QInputMethodEvent object encapsulating the given commitString, to the focus widget. This is a convenience function for the sendEvent() function.

If the specified replaceLength is greater than 0, the commit string will replace the given number of characters of the receiving widget's previous text, starting at the given replaceFromPosition relative to the start of the current preedit string.

This will cause the input method to leave compose mode, i.e. the input method will no longer be actively composing the preedit string.

See also sendEvent() and sendPreeditString().

void QWSInputMethod::sendEvent ( const QInputMethodEvent * )   [protected]

Sends a QInputMethodEvent object to the focus widget. a

See also sendPreeditString(), sendCommitString(), and reset().

void QWSInputMethod::sendMouseEvent ( const QPoint & position, int state, int wheel )   [protected]

Sends a mouse event specified by the given position, state and wheel parameters.

The given position will be transformed if the screen coordinates do not match the pointer device coordinates.

Note that the event will be not be tested by the active input method, but calling the QWSServer::sendMouseEvent() function will make the current input method filter the event.

See also mouseHandler() and sendEvent().

void QWSInputMethod::sendPreeditString ( const QString & preeditString, int cursorPosition, int selectionLength = 0 )   [protected]

Sends a QInputMethodEvent object encapsulating the given preeditString, to the focus widget. This is a convenience function for the sendEvent() function.

The specified selectionLength is the number of characters to be marked as selected (starting at the given cursorPosition). If selectionLength is negative, the text before cursorPosition is marked.

The preedit string is marked with QInputContext::PreeditFormat, and the selected part is marked with QInputContext::SelectionFormat.

Sending an input method event with a non-empty preedit string will cause the input method to enter compose mode. Sending an input method event with an empty preedit string will cause the input method to leave compose mode, i.e. the input method will no longer be actively composing the preedit string.

See also sendEvent() and sendCommitString().

void QWSInputMethod::sendQuery ( int property )   [protected]

Sends an input method query (internally encapsulated by a QWSEvent of the IMQuery type) for the specified property.

To receive responses to input method queries, reimplement the virtual queryResponse() function.

See also queryResponse() and QWSServer::sendIMQuery().

uint QWSInputMethod::setInputResolution ( bool isHigh )   [protected]

Sets and returns the number of bits shifted to go from pointer resolution to screen resolution when filtering mouse events using the filter() function.

If isHigh is true and the device has a pointer device resolution twice or more of the screen resolution, the positions passed to the filter() function will be presented at the higher resolution; otherwise the resolution will be equal to that of the screen resolution.

See also filter() and inputResolutionShift().

void QWSInputMethod::updateHandler ( int type )   [virtual]

Handles update events including resets and focus changes.

The update events are specified by the given type which is one of the UpdateType enum values. Note that reimplementations of this function must call the base implementation for all cases that it does not handle itself.

See also UpdateType.