NPAPI:CocoaEventModel: Difference between revisions

NPAPI:CocoaEventModel (view source)

Revision as of 23:56, 20 January 2011

2,313 bytes added , 20 January 2011

→‎Text Input

Josh

Confirmed users, Bureaucrats and Sysops emeriti

1,680

edits

@@ Line 207: / Line 207: @@
 == Text Input ==
-Plugin-ins can return 2 (kNPEventStartIME) from NPP_HandleEvent for NPCocoaEventKeyDown events when they want the browser to have an input method process the event.
+(Note: Due to an [[NPAPI:CocoaCompositionClarification|amended specification]] and inconsistency in original implementations the variable <code>NPNVsupportsUpdatedCocoaTextInputBool</code> (NPNVariable = 3002) will indicate whether a browser supports this updated specification or not. If this is undefined or is false then text input behavior will vary between browsers.)
-The input method may open an out-of-line input window where complex text can be composed. When the user confirms the text and dismisses the window, an NPCocoaEventTextInput event is sent with the relevant unicode string.
+Plugin-ins can return 2, (<code>kNPEventStartIME</code>) from <code>NPP_HandleEvent</code> for <code>NPCocoaEventKeyDown</code> events when they want the browser to have an input method process the event.
-No <code>NPCocoaEventKeyDown</code> or <code>NPCocoaEventKeyUp</code> events will be sent to the plugin during composition. <code>NPCocoaEventFlagsChanged</code> events will still be sent. Browser implementers should be mindful of the edge case where a key down ends composition (for example, the return key when an input window is in use) - the subsequent key up event is considered to be associated with the composition and should not be sent to the plugin.
+The input method may open an out-of-line input window where complex text can be composed. When the user confirms the text and dismisses the window, an <code>NPCocoaEventTextInput</code> event is sent with the relevant unicode string.
-Due to an [[NPAPI:CocoaCompositionClarification|amended specification]] and inconsistency in original implementations the variable <code>NPNVsupportsUpdatedCocoaTextInputBool</code> (NPNVariable = 3002) will indicate whether a browser supports this updated specification or not. If this is not defined and true then text input behavior will vary between browsers.
+Composition is considered to have started once a plugin returns <code>kNPEventStartIME</code> for a <code>NPCocoaEventKeyDown</code> event. Once a composition is started, plugins will not receive <code>NPCocoaEventKeyDown</code> or <code>NPCocoaEventKeyUp</code> events associated with compositions regardless of whether the composition results in a <code>NPCocoaEventTextInput</code> event or not (it may be canceled or the key press may not result in a meaningful composition).
+<code>NPCocoaEventFlagsChanged</code> events will be sent at all times, even during composition.
+* Example 1
+** User presses the "a" key in an en-us context.
+** Plugin gets a <code>NPCocoaEventKeyDown</code> event and returns <code>kNPEventStartIME</code>.
+** Plugin gets <code>NPCocoaEventTextInput</code> event for string "a".
+** Plugin does not get <code>NPCocoaEventKeyUp</code> event for "a" key.
+* Example 2
+** User presses "enter" in an out-of-line composition window to commit a complex text composition that started with the plugin returning <code>kNPEventStartIME</code> for a <code>NPCocoaEventKeyDown</code> event.
+** Plugin does not receive an <code>NPCocoaEventKeyDown</code> event for the "enter" key. It is considered to belong to the composition.
+** Plugin receives <code>NPCocoaEventTextInput</code> event containing composed string.
+** Plugin does not receive a <code>NPCocoaEventKeyUp</code> event for the "enter" key. It is considered to belong to the composition.
+* Example 3
+** User presses "option-e" in an en-us context.
+** Plugin receives a <code>NPCocoaEventKeyDown</code> event for "option-e" and returns <code>kNPEventStartIME</code>.
+** Plugin does not receive a <code>NPCocoaEventKeyUp</code> event for the "option-e" key. It is considered to belong to the composition.
+** User presses "e" to complete a composition of the string "é".
+** Plugin does not receive a <code>NPCocoaEventKeyDown</code> event for the "e" key. It is considered to belong to the composition.
+** Plugin receives <code>NPCocoaEventTextInput</code> event containing composed string "é".
+** Plugin does not receive a <code>NPCocoaEventKeyUp</code> event for the "e" key. It is considered to belong to the composition.
+* Example 4
+** User presses "F3" key in an en-us context.
+** Plugin receives a <code>NPCocoaEventKeyDown</code> event for the "F3" key and returns <code>kNPEventStartIME</code>.
+** Plugin does not receive a <code>NPCocoaEventTextInput</code> event because F3 is a dead key as far as composition is concerned. Composition is considered to be canceled.
+** Plugin does not receive a <code>NPCocoaEventKeyUp</code> event for the "F3" key. It is considered to belong to the composition which is now canceled.
 == Notes ==