[immodule-qt] Completing comments and documents

[YamaKen]

Hi all,

I've written following important comments in the source. Please
review it. The comments are design decisions about key
filtering.

Index: src/kernel/qapplication_x11.cpp
===================================================================
--- src/kernel/qapplication_x11.cpp	(revision 16)
+++ src/kernel/qapplication_x11.cpp	(revision 17)
@@ -3152,6 +3152,14 @@
     }
 
 #ifndef QT_NO_IM
+    // Filtering input events by the input context. It has to be taken
+    // place before any other key event consumers such as eventfilters
+    // and accelerators because some input methods require quite
+    // various key combination and sequences. It often conflicts with
+    // accelerators and so on, so we must give the input context the
+    // filtering opportunity first to ensure all input methods work
+    // properly regardless of application design.
+
     if( keywidget && keywidget->isEnabled() && keywidget->isInputMethodEnabled() ) {
 	if( ( event->type==XKeyPress || event->type==XKeyRelease ) &&
 	    sm_blockUserInput ) // block user interaction during session management
@@ -3180,6 +3188,8 @@
 						  state, ascii, code, type,
 						  FALSE, FALSE );
 
+	    // both key press/release is required for some complex
+	    // input methods. don't eliminate anything.
 	    QKeyEvent keyevent( type, code, ascii, state, text, FALSE, count );
 
 	    if( qic && qic->filterEvent( &keyevent ) )
@@ -5293,9 +5303,25 @@
     // compress keys
     if ( !text.isEmpty() && testWState(WState_CompressKeys) &&
 #ifndef QT_NO_IM
-	 // input methods need discrete key events
-         // UPDATED COMMENT REQUIRED -- 2004-07-08 YamaKen
-	 // describe design decision
+	 // Ordinary input methods require discrete key events to work
+	 // properly, so key compression has to be disabled when input
+	 // context exists.
+	 //
+	 // And further consideration, some complex input method
+	 // require all key press/release events discretely even if
+	 // the input method awares of key compression and compressed
+	 // keys are ordinary alphabets. For example, the uim project
+	 // is planning to implement "combinational shift" feature for
+	 // a Japanese input method, uim-skk. It will work as follows.
+	 //
+	 // 1. press "r"
+	 // 2. press "u"
+	 // 3. release both "r" and "u" in arbitrary order
+	 // 4. above key sequence generates "Ru"
+	 //
+	 // Of course further consideration about other participants
+	 // such as key repeat mechanism is required to implement such
+	 // feature.
 	 ! qic &&
 #endif // QT_NO_IM
 	 // do not compress keys if the key event we just got above matches

-------------------------------
YamaKen  yamaken at bp.iij4u.or.jp