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_INTERFACE"]
+interface PPB_IMEInputEvent_Dev {
+  /**
+   * 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-indices of

[yzshen1, 2011/09/14 17:32:56]

byte -> char?

[brettw, 2011/09/14 23:00:06]

We should be careful how this is defined. Is it Unicode characters or bytes?
Either way there should probably be some extra comment here explaining that it's
not the "other one."

[kinaba, 2011/09/15 08:53:50]

It is bytes, not Unicode characters. Improved the comment for clarification.
Thank you for good suggestion.

+   * the string GetText(). They always satisfy 0 <= start < end <= (Length of

[yzshen1, 2011/09/14 17:32:56]

Just to double check: according to "end <= (Length of GetText())", the segment
is defined as [start, end) instead of [start, end], right?
It is better to comment about that explicitly.

I am not sure usually what the segments look like, but according to the
definition, overlapping is allowed:
[0, 3), [1, 3)
However, overlapping with the same starting position is not allowed:
Not allowed: [0, 2) [0, 3)
Is this intended?

[kochi, 2011/09/15 07:27:19]

I just discussed this with Kazuhiro and removed the
'startx < startx+1' constraint from the doc.

The background is that information from IME is not
guaranteed and some IME may send
{ [2, 3), [0, 3), [1, 3), [1, 2) }
for example.

The browser may filter out such overlapping case, but
some IME *might* invent useful usage of overlapping
segments and we cannot prevent from it to happen.

So we defer the validation of the data to plugins.


On 2011/09/14 17:32:56, yzshen1 wrote:

[kinaba, 2011/09/15 08:53:50]

Added a comment saying that [start, end) is the one, instead of [start, end]. As
explained in Takayoshi's reply, we've dropped further constraints.

+   * GetText()) and start[index] < start[index+1]. When the event is not
+   * COMPOSITION_UPDATE or index >= GetSegmentNumber(), nothing happens.

[yzshen1, 2011/09/14 17:32:56]

Is it better to return a PP_Bool?

[kinaba, 2011/09/15 08:53:50]

Done.

+   *
+   * @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.
+   */
+  void GetSegmentAt([in] PP_Resource ime_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] 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);
+};