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_COMPOSITION 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_COMPOSITION 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_COMPOSITION class.
+   */
+  PP_INPUTEVENT_TYPE_COMPOSITION_END = 13,
+
+  /**
+   * Notification that an input method committed a string.
+   *
+   * Register for this event using the PP_INPUTEVENT_CLASS_COMPOSITION 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 71 matching lines @@
   /**
    * Identifies touch input events.
    *
    * Request touch events only if you intend to handle them. If the browser
    * knows you do not need to handle touch events, it can handle them at a
    * higher level and achieve higher performance.
    */
   PP_INPUTEVENT_CLASS_TOUCH = 1 << 3,
 
   /**
-   * Identifies IME composition input events.
+   * Identifies composition input events.

[brettw, 2011/09/13 22:36:04]

Is IME not appropriate here? Sorry if I don't totally understand all the terms
here. I just want to be sure that things are named so that if a developer knyows
he doesn't care about IME, he knows to skip these things.

[kochi, 2011/09/14 02:07:05]

I thinks this is in response to Yuzhu's comment about
naming convention (CLASS_* <=> *InputEvent)

I think IME is fine here, so what about changing the
event interface name to have 'IME' prefix?  This still
breaks the convention, but slightly better than not following
the convention at all.

On 2011/09/13 22:36:04, brettw wrote:

[kinaba, 2011/09/14 08:54:04]

I see. I turned the names to _CLASS_IME and IMEInputEvent.

    *
-   * Request this input event class if you allow on-the-spot IME input.
+   * Request this input event class if you allow on-the-spot composition.
    */
-  PP_INPUTEVENT_CLASS_IME = 1 << 4
+  PP_INPUTEVENT_CLASS_COMPOSITION = 1 << 4
 };
 
 /**
  * The <code>PPB_InputEvent</code> interface contains pointers to several
  * functions related to generic input events on the browser.
  */
 [version=1.0, macro="PPB_INPUT_EVENT_INTERFACE"]
 interface PPB_InputEvent {
   /**
    * RequestInputEvent() requests that input events corresponding to the given
@@ skipping 484 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 {

[brettw, 2011/09/13 22:36:04]

Can we put the APIs in the Dev directory (and name them accordingly) to start
off with? I imagine we'll be tweaking them a lot and it would be nice to not
have to worry about backwards compat as much.

You can keep the input event types in the enum above, I think.

[kinaba, 2011/09/14 08:54:04]

Done.

+  /**
+   * 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);
+
+  /**
+   * GetSegmentNumber() returns the number of segments in the composition text.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @return The number of segments. For events other than COMPOSITION_UPDATE,
+   * returns 0.
+   */
+  uint32_t GetSegmentNumber([in] PP_Resource composition_event);
+
+  /**
+   * GetSegmentAt() returns the start and the end position of the index-th
+   * segment in the composition text. The positions are given by byte-indices of
+   * the string GetText(). They always satisfy 0 <= start < end <= (Length of
+   * GetText()) and start[index] < start[index+1]. When the event is not
+   * COMPOSITION_UPDATE or index >= GetSegmentNumber(), nothing happens.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @param[in] index An integer indicating a segment.
+   *
+   * @param[out] start The start position of the index-th segment.
+   *
+   * @param[out] end The end position of the index-th segment.
+   */
+  void GetSegmentAt([in] PP_Resource composition_event,
+                    [in] uint32_t index,
+                    [out] uint32_t start,
+                    [out] uint32_t end);
+
+  /**
+   * GetTargetSegment() returns the index of the current target segment of
+   * 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 range selected by caret in the composition text.
+   *
+   * @param[in] composition_event A <code>PP_Resource</code> corresponding to a
+   * composition event.
+   *
+   * @param[out] start The start position of the current selection.
+   *
+   * @param[out] end The end position of the current selection.
+   */
+  void GetSelection([in] PP_Resource composition_event,
+                    [out] uint32_t start,
+                    [out] uint32_t end);
+};