65 Following is the basic input framework program flow:

    65 \bold The input framework program flow

    66 

    66 

    67 1. An editor gains input focus.

    67 1. An editor gains input focus.<BR>

    68 2  Input mode cache resolves correct mode handler and activates it.

    68 2. Editor sets requestSoftwareInputPanel event to active input context.<BR>

    69 3. A virtual function HbInputMethod::focusReceived is called. At this point the input method

    69 3. The input framework creates input state based on editor attributes and the input mode cache <BR>

    70    initializes whatever it needs to initialize in order to start the input operation (for example,

    70    resolves correct mode handler and activates it.<BR>

    71    opens the virtual keyboard by using HbVkbHost API) and waits for user actions.

    71 4. A virtual function HbInputMethod::focusReceived is called. At this point the input method<BR>

    72 4. Text is written. The input method delivers results to the editor buffer by using HbInputFocusObject API.

    72    initializes whatever it needs to initialize in order to start the input operation (for example,<BR>

    73    It can access editor attributes via HbEditorInterface API.

    73    opens the virtual keyboard by using HbVkbHost API) and waits for user actions.<BR>

    74 5. The active editor loses focus. At this point the input method receives a call to virtual function

    74 5. Text is written. The input method delivers results to the editor buffer by using HbInputFocusObject API.<BR>

    75    HbInputMethod::focusLost and is expected to conclude any ongoing input operations and shut down active

    75    It can access editor attributes via HbEditorInterface API.<BR>

    76    UI elements (such as the virtual keyboard).

    76 6. The active editor loses focus. At this point the input method receives a call to virtual function<BR>

    77 6. The input method waits for next focusReceived() call.

    77    HbInputMethod::focusLost and is expected to conclude any ongoing input operations and shut down active<BR>

    78    UI elements (such as the virtual keyboard).<BR>

    79 7. The input method waits for next focusReceived() call. <BR>

    80 

    81 \bold Input method resolving

    82 

    83 The input framework resolves correct input state handler based on three attributes: input mode,

    84 keyboard type and input language.

    85 

    86 The framework recognizes three different input modes: default, numeric and custom.

    87 Default and numeric input modes are something that the framework resolves for active

    88 input language and keyboard type. Custom input mode is something that the framework never

    89 activates automatically, but it is activated from UI or directly from application

    90 (or input method) code.

    91 

    92 Numeric input mode is something that can handle those editors that are configured to only accept

    93 numeric data (for example those that have Qt::ImhDigitsOnly hints on).

    94 

    95 Language attribute is matched either as a direct match or as a language range. Language range

    96 means the input method is capable of handling all the languages that

    97 HbKeymapFactory::availableLanguages() returns. Direct match always wins so it is possible

    98 to override language range for specific languages.

    99 

   100 The keyboard attribute is always matched directly. Note that event though the constant

   101 has term "keyboard" in it, it covers all input devices such as hand writing recognition widgets

   102 that don't utilize traditional keys. it is up the the input method what that constant

   103 really means.

   104 

   105 The input method resolving parameters are part of input plugin meta data and they are returned

   106 by QInputContextPlugin::languages() method. A single entry in the returned string list

   107 is formed by packing resolving parameters into HbInputModeProperties structure and calling

   108 HbInputModeProperties::asString() method.

   109 

   110 Following code snippet shows how the input context plugin returns resolving parameters

   111 

   112 \snippet{unittest_hbinputmethod/unittest_hbinputmethod.cpp,1}

   113 

   114 \bold Input method resolving example

   115 

   116 Say that we have implemented touch input methods for 12 key portrait mode and qwerty landscape mode.

   117 Then we have Chinese touch input method for both portrait and landscape orientations and also

   118 Chinese handwriting recognition input mode for portrait mode.

   119 

   120 Touch input methods resolve to language range, which means that they will be handle all

   121 the other languages, except Chinese, which has its own designated input method.

   122 

   123 Touch input methods also implement support for numeric mode. Because Chinese language uses

   124 same numeric system as "latin" based languages, we only want to implement numeric mode

   125 handling in one input method and arrange resolving parameters so that the numeric mode

   126 is handled by default touch input method even when the global input language is Chinese.

   127 

   128 Chinese handwriting input method is something that is a custom mode, and will be activated

   129 from UI.

   130 

   131 Following example shows how the resolving attributes are set up to achieve above configuration.

   132 

   133 Portait touch input method returns following attributes

   134 

   135 \snippet{unittest_hbinputmethod/unittest_hbinputmethod.cpp,2}

   136 

   137 Landscape touch input method returns following attributes

   138 

   139 \snippet{unittest_hbinputmethod/unittest_hbinputmethod.cpp,3}

   140 

   141 Chinese portrait input method returns following attributes

   142 

   143 \snippet{unittest_hbinputmethod/unittest_hbinputmethod.cpp,4}

   144 

   145 Chinese landscape input method returns following attributes

   146 

   147 \snippet{unittest_hbinputmethod/unittest_hbinputmethod.cpp,5}

   148 

   149 Chinese handwriting recognition input method returns following attributes

   150 (note use of HbInputModeCustom, in this example HWR is something that we

   151 want to active from UI separately).

   152 

   153 \snippet{unittest_hbinputmethod/unittest_hbinputmethod.cpp,6}

   123     QInputContext* proxy = master->d_ptr->newProxy();

   199     QInputContext* proxy = master->d_ptr->proxy();    

   124     app.setInputContext(proxy);

   200     // A check required so that Qt does not delete inputcontext

   201     // which we are passing.

   202     if (proxy != app.inputContext())

   203         app.setInputContext(proxy);

   166 Activates given input method. Input context is

   245 Activates given input method. Returns false if input method was not found

   167 switched to custom method. Returns false if input method was not found

   174     if (!inputMethod.isEmpty()) {

   252     if (!inputMethod.isEmpty()) {       

   175         HbInputSettingProxy::instance()->setActiveCustomInputMethod(inputMethod);

   176 

   182             if (customMethod) {

   258             if (customMethod) {              

   183                 d->contextSwitch(customMethod);

   259                d->contextSwitch(customMethod);

   304 

   380     

   306         return;

   382 	    return;

   307     }

   383 	}

   308 

   384 		

   309     QInputContext::setFocusWidget(widget);

   385     // attach focuswidget to prxoy inputcontext as proxy is 

   310 

   386     // the only inputcotext known to qt framework.

   387     d->proxy()->QInputContext::setFocusWidget(widget);

   388     

   779 

   857 	d->hideMainWindow();