Declarations for Pepper IME API.

ppapi/api/dev/ppb_ime_input_event_dev.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 <code>PPB_IMEInputEvent_Dev</code> interface.
+ */
+
+label Chrome {
+  M16 = 0.1
+};
+
+[version=0.1, macro="PPB_IME_INPUT_EVENT_DEV_INTERFACE"]
+interface PPB_IMEInputEvent_Dev {

[James Su, 2011/09/16 06:39:53]

Is this event only for composition text or for both composition text and result
text?
If it's only for composition text, I'd suggest to have term Composition in the
name. Maybe IMECompositionEvent (if you'd prefer to keep term IME).

HTML DOM event specification has different events for composition and result
text, so it's probably good for us to  have different events as well.

+  /**
+   * IsIMEInputEvent() determines if a resource is an IME 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 IsIMEInputEvent([in] PP_Resource resource);
+
+  /**
+   * GetText() returns the composition text as a UTF-8 string for the given IME
+   * event.
+   *
+   * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
+   * event.
+   *
+   * @return A string var representing the composition text. For non-IME input
+   * events the return value will be an undefined var.
+   */
+  PP_Var GetText([in] PP_Resource ime_event);
+
+  /**
+   * GetSegmentNumber() returns the number of segments in the composition text.
+   *
+   * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
+   * event.
+   *
+   * @return The number of segments. For events other than COMPOSITION_UPDATE,
+   * returns 0.
+   */
+  uint32_t GetSegmentNumber([in] PP_Resource ime_event);
+
+  /**
+   * GetSegmentAt() returns the start and the end position of the index-th
+   * segment in the composition text. The positions are given by byte-offsets
+   * (not character-offsets) of the string returned by GetText(). The range of
+   * the segment extends from start (inclusive) to end (exclusive). They satisfy
+   * 0 <= start < end <= (byte-length of GetText()). When the event is not
+   * COMPOSITION_UPDATE or index >= GetSegmentNumber(), the function returns
+   * PP_FALSE and nothing else happens.
+   *
+   * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
+   * 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.
+   *
+   * @return PP_TRUE when the start and the end position is successfully
+   * obtained, and PP_FALSE otherwise.
+   */
+  PP_Bool GetSegmentAt([in] PP_Resource ime_event,
+                       [in] uint32_t index,
+                       [out] uint32_t start,
+                       [out] uint32_t end);

[James Su, 2011/09/16 06:39:53]

The segmentation information should only have a set of indexes, indicating the
segmentation boundary in the text. And the first and the last index should be 0
and text length.
Both windows and mac define segmentation information in this way.

Using [start,end) pairs is ok for underline information, but  semantically, it's
not suitable for describing segmentation information.

+
+  /**
+   * GetTargetSegment() returns the index of the current target segment of
+   * composition.
+   *
+   * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
+   * 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 ime_event);
+
+  /**
+   * GetSelection() returns the range selected by caret in the composition text.
+   *
+   * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
+   * 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 ime_event,
+                    [out] uint32_t start,
+                    [out] uint32_t end);
+};