Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QInputContext Class Reference

The QInputContext class abstracts the input method dependent data and composing state. More...

    #include <QInputContext>

- List of all members, including inherited members

### Public Functions

- QInputContext ( QWidget * )
- ~QInputContext ()
- int lookupString ( XKeyEvent * , QByteArray & , KeySym * , Status * ) const
- void reset ()
- void setComposeArea ( int , int , int , int )
- void setComposePosition ( int , int )
- void setFocus ()
- void setXFontSet ( const QFont & )

### Static Public Members

- QWidget * microFocusWidget ()
- void notifyWidgetDeletion ( QWidget * )
- void reset ( QWidget * focusW = 0 )
- void setMicroFocusWidget ( QWidget * )
- void translateIMEvent ( QWSIMEvent * , QWidget * )

## Detailed Description

The QInputContext class abstracts the input method dependent data and composing state.

An input method is responsible to input complex text that cannot be inputted via simple keymap. It converts a sequence of input events (typically key events) into a text string through the input method specific converting process. The class of the processes are widely ranging from simple finite state machine to complex text translator that pools a whole paragraph of a text with text editing capability to perform grammar and semantic analysis.

To abstract such different input method specific intermediate information, Qt offers the QInputContext as base class. The concept is well known as 'input context' in the input method domain. an input context is created for a text widget in response to a demand. It is ensured that an input context is prepared for an input method before input to a text widget.

Multiple input contexts that is belonging to a single input method may concurrently coexist. Suppose multi-window text editor. Each text widget of window A and B holds different QInputContext instance which contains different state information such as partially composed text.

### Groups of functions:

Context | Functions
--- | ---
Receiving information | x11FilterEvent(), filterEvent(), setMicroFocus(), mouseHandler()
Sending back composed text | sendIMEvent(),
State change notification | setFocus(), unsetFocus(), reset()
Context information | identifierName(), language(), font(), isComposing(),

### Sharing input context between text widgets

Any input context can be shared between several text widgets to reduce resource consumption. In ideal case, each text widgets should be allocated dedicated input context. But some complex input contexts require slightly heavy resource such as 100 kilobytes of memory. It prevents quite many text widgets from being used concurrently.

To resolve such problem, we can share an input context. There is one 'input context holder widget' per text widgets that shares identical input context. In this model, the holder widget owns the shared input context. Other text widgets access the input context via QApplication::locateICHolderWidget(). But the access convention is transparently hidden into QWidget, so developers are not required to aware of it.

What developer should know is only the mapping function QApplication::locateICHolderWidget(). It accepts a widget as argument and returns its holder widget. Default implementation returns the top-level widget of the widget as reasonable assumption. But some applications should reimplement the function to fit application specific usability. See QApplication::locateICHolderWidget() for further information.

### Preedit preservation

As described above, input contexts have wide variety of amount of the state information in accordance with belonging input method. It is ranging from 2-3 keystrokes of sequence in deterministic input methods to hundreds of keystrokes with semantic text refinement in complex input methods such as ordinary Japanese input method. The difference requires the different reset policies in losing input focus.

The former simple input method case, users will prefer resetting the context to back to the neutral state when something happened. Suppose a web browsing. The user scroll the page by scrollbar after he or she has typed a half of the valid key sequence into a text widget. In the case, the input context should be reset in losing focus when he or she has dragged the scrollbar. He or she will be confused if the input context is still preserved until focused back to the text widget because he or she will restart typing with first key of the sequence as a habitual operation.

On the other hand, we should choose completely different policy for the latter complex input method case. Suppose same situation as above but he or she is using a complex input method. In the case, he or she will be angry if the input context has been lost when he or she has dragged the scrollbar because the input context contained a valuably composed text made up by considerable input cost. So we should not reset the input context in the case. And the input context should be preserved until focused back to the text widget. This behavior is named as 'preedit preservation'.

The two policies can be switched by calling or not calling reset() in unsetFocus(). Default implementation of unsetFocus() calls reset() to fit the simple input methods. The implementation is expressed as 'preedit preservation is disabled'.

### Preedit relocation

Although the most case of the preedit preservation problem for complex input methods is resolved as described above, there is a special case. Suppose the case that matches all of the following conditions.

- a input focus has been moved from a text widget to another text widget directly
- the input context is shared between the two text widgets
- preedit preservation is enabled for the input context

In the case, there are the following two requirements that contradicts each other. The input context sharing causes it.

- the input context has to be reset to prepare to input to the newly focused text widget
- the input context has to be preserved until focused back to the previous text widget

A intrinsic feature named 'preedit relocation' is available to compromise the requirements. If the feature is enabled for the input context, it is simply moved to the new text widget with the preedit string. The user continues the input on the new text widget, or relocate it to another text widget. The preedit of previous text widget is automatically cleared to back to the neutral state of the widget.

This strange behavior is just a compromise. As described in previous section, complex input method user should not be exposed to the risk losing the input context because it contains valuable long text made up with considerable input cost. The user will immediately focus back to the previous text widget to continue the input in the correct text widget if the preedit relocation occurred. The feature is mainly existing as safety.

The feature properly works even if the focus is moved as following. Input method developers are not required to be aware of the relocation protocol since QInputContext transparently handles it.

a text widget -> a non-text widget -> another text widget

To enable the preedit relocation feature, the input context class have to reimplement isPreeditRelocationEnabled() as returns true. The implementation requires that the preedit preservation is also enabled since preedit relocation is a special case of the preedit preservation. If the preedit relocation is disabled, the input context is simply reset in the relocation case.

### Input context instanciation

### Input method switching

### Text widget implementor's guide

Add following code fragment into createPopupMenu() to add input method dependent submenus.

        #ifndef QT_NO_IM
            QInputContext *qic = getInputContext();
            if (qic)
                qic->addActionsTo(popup);
        #endif

See also QInputContextPlugin, QInputContextFactory, QApplication::locateICHolderWidget(), and QApplication::defaultInputMethod().

## Member Function Documentation

### QInputContext::QInputContext ( QWidget * )

### QInputContext::~QInputContext ()

Destroys the input context.

### int QInputContext::lookupString ( XKeyEvent * , QByteArray & , KeySym * , Status * ) const

### QWidget * QInputContext::microFocusWidget () `[static]`

### void QInputContext::notifyWidgetDeletion ( QWidget * ) `[static]`

### void QInputContext::reset ()

This function can be reimplemented in a subclass to reset the state of the input method.

This function is called by several widgets to reset input state. For example, a text widget call this function before inserting a text to make widget ready to accept a text.

Default implementation is sufficient for simple input method. You can override this function to reset external input method engines in complex input method. In the case, call QInputContext::reset() to ensure proper termination of inputting.

You must not send any QInputMethodEvent except empty InputMethodEnd event using QInputContext::reset() at reimplemented reset(). It will break input state consistency.

### void QInputContext::reset ( QWidget * focusW = 0 ) `[static]`

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

### void QInputContext::setComposeArea ( int , int , int , int )

### void QInputContext::setComposePosition ( int , int )

### void QInputContext::setFocus ()

### void QInputContext::setMicroFocusWidget ( QWidget * ) `[static]`

### void QInputContext::setXFontSet ( const QFont & )

### void QInputContext::translateIMEvent ( QWSIMEvent * , QWidget * ) `[static]`