Declarations for Pepper IME API.

ppapi/api/ppb_input_event.idl

 /* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 /**
  * This file defines the Input Event interfaces.
  */
 
 label Chrome {
   M13 = 1.0,
-  M14 = 1.1
+  M14 = 1.1,
+  M15 = 1.1,
+  M16 = 1.2
 };
 
 /**
  * This enumeration contains the types of input events.
  */
 [assert_size(4)]
 enum PP_InputEvent_Type {
   PP_INPUTEVENT_TYPE_UNDEFINED   = -1,
 
   /**
@@ skipping 70 matching lines @@
    *
    * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
    */
   PP_INPUTEVENT_TYPE_CHAR        = 9,
 
   /**
    * TODO(brettw) when is this used?
    *
    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
    */
-  PP_INPUTEVENT_TYPE_CONTEXTMENU = 10
+  PP_INPUTEVENT_TYPE_CONTEXTMENU = 10,
+
+  /**
+   * Notification that an input method composition process has just started.
+   *
+   * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
+   */
+  PP_INPUTEVENT_TYPE_COMPOSITION_START = 11,
+
+  /**
+   * Notification that the input method composition string is updated.
+   *
+   * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
+   */
+  PP_INPUTEVENT_TYPE_COMPOSITION_UPDATE = 12,
+
+  /**
+   * Notification that an input method composition process has completed.
+   *
+   * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
+   */
+  PP_INPUTEVENT_TYPE_COMPOSITION_END = 13,
+
+  /**
+   * Notification that an input method committed a string.
+   *
+   * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
+   */
+  PP_INPUTEVENT_TYPE_IME_TEXT = 14
 };
 
 /**
  * This enumeration contains event modifier constants. Each modifier is one
  * bit. Retrieve the modifiers from an input event using the GetEventModifiers
  * function on PPB_InputEvent.
  */
 [assert_size(4)]
 enum PP_InputEvent_Modifier {
   PP_INPUTEVENT_MODIFIER_SHIFTKEY         = 1 << 0,
@@ skipping 580 matching lines @@
    * @param[in] character_event A <code>PP_Resource</code> corresponding to a
    * keyboard event.
    *
    * @return A string var representing a single typed character for character
    * input events. For non-character input events the return value will be an
    * undefined var.
    */
   PP_Var GetCharacterText([in] PP_Resource character_event);
 };
 
+
+/**
+ * The <code>PPB_CompositionInputEvent</code> interface contains pointers to
+ * several functions related to composition input events.
+ */
+[version=1.2, macro="PPB_COMPOSITION_INPUT_EVENT_INTERFACE"]
+interface PPB_CompositionInputEvent {

[yzshen1, 2011/09/13 06:28:34]

It seems to me that the naming convention is:
PP_INPUTEVENT_CLASS_<some_class> <--> PPB_<some_class>InputEvent.
(For example, PP_INPUTEVENT_CLASS_MOUSE <--> PPB_MouseInputEvent.)
It might be good to follow this convention. 

[kinaba, 2011/09/13 09:29:01]

Done. Changed the class name to PP_INPUTEVENT_CLASS_COMPOSITION.

+  /**
+   * IsCompositionInputEvent() determines if a resource is a composition event.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
+   *
+   * @return <code>PP_TRUE</code> if the given resource is a valid input event.
+   */
+  PP_Bool IsCompositionInputEvent([in] PP_Resource resource);
+
+  /**
+   * GetText() returns the composition text as a UTF-8 string for the given
+   * composition event.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @return A string var representing the composition text. For non-composition
+   * input events the return value will be an undefined var.
+   */
+  PP_Var GetText([in] PP_Resource composition_event);
+
+  /**
+   * GetSegments() returns the segmentation information by a list of indices of
+   * a UTF-8 string returned by GetText. Each segment is numbered from 0 to
+   * size-1, and the ith segment begins from segments[2*i] and ends with
+   * segments[2*i+1]. For events other than COMPOSITION_UPDATE, the function

[yzshen1, 2011/09/13 06:28:34]

It might be good to add more comments about the segments array. According to the
design doc, it satisfies "startx < endx, and startx < startx+1, and all startx
and endx are between 0 and length of composition text. "

[kinaba, 2011/09/13 09:29:01]

Done.

+   * returns an empty array.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @param[out] segments A pointer to an array containing segment information.

[yzshen1, 2011/09/13 06:28:34]

If we decide to use a void* memory block like this, it is good to add comments
about : who is responsible for releasing the memory/how to release it, what is
the type of each element in the memory block (is it uint32_t?).

Moreover, it is probably more common to use void** instead of void* as an out
parameter for pointers.

To me, it seems better to have two methods instead of this GetSegments:
uint32_t GetSegmentNumber();
and
PP_Bool GetSegmentAt([in] uint32_t index, [out] uint32_t start, [out] uint32_t
end);

All these calls will be handled within the plugin process, so there won't be
much overhead.

[kinaba, 2011/09/13 09:29:01]

Done. Thanks, it looks much better!

+   *
+   * @param[out] size The number of segments.
+   */
+  void GetSegments([in] PP_Resource composition_event,
+                   [out] mem_t segments,
+                   [out] uint32_t size);
+
+  /**
+   * GetTargetSegment() returns the number of the current target segment of

[yzshen1, 2011/09/13 06:28:34]

Minor issue: number -> index?

[kinaba, 2011/09/13 09:29:01]

Done.

+   * composition.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @return An integer indicating the index of the target segment. When there
+   * is no active target segment, or the event is not COMPOSITION_UPDATE,
+   * returns -1.
+   */
+  int32_t GetTargetSegment([in] PP_Resource composition_event);
+  
+  /**
+   * GetSelection() returns the caret position in the current composition text.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @param[out] start Start index.
+   *
+   * @param[out] end End index.
+   */
+  void GetSelection([in] PP_Resource composition_event,
+                    [out] uint32_t start,
+                    [out] uint32_t end);
+};