Declarations for Pepper IME API.

ppapi/api/dev/ppb_text_input_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_TextInput_Dev</code> interface.
+ */
+
+label Chrome {
+  M16 = 0.1
+};
+
+/**
+ * PP_TextInput_Type is used to indicate the status of a plugin in regard to
+ * text input. Intentionally kept in sync with WebKit::WebTextInputType in:

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

We shouldn't be talking about the sync with webkit here. Once we publish this
API, we can't change it, and WebKit could diverge, so we can't stay up-to-date.

Instead, I just wouldn't comment here, and then in the webkit/plugins/ppapi
implementation, have a conversion function with compiler asserts that they're
the same values. Then if they diverge, we have one place to change to keep the
conversion up-to-date. See the webkit/plugins/ppapi/webkit_forwarding_impl.cc

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

Done. In fact, the static asserts are already set up in my implementation and
hence simply removed the comment here.

+ * third_party/WebKit/Source/WebKit/chromium/public/WebTextInputType.h
+ */
+[assert_size(4)]
+enum PP_TextInput_Type {
+  /**
+   * Input caret is not in an editable node, no input method shall be used.
+   */
+  PP_TEXTINPUT_TYPE_NONE = 0,
+  /**
+   * Input caret is in a normal editable node, any input method can be used.
+   */
+  PP_TEXTINPUT_TYPE_TEXT = 1,
+  /**
+   * Input caret is in a password box, an input method may be used only if
+   * it's suitable for password input.
+   */
+  PP_TEXTINPUT_TYPE_PASSWORD = 2,
+  PP_TEXTINPUT_TYPE_SEARCH = 3,
+  PP_TEXTINPUT_TYPE_EMAIL = 4,
+  PP_TEXTINPUT_TYPE_NUMBER = 5,
+  PP_TEXTINPUT_TYPE_TELEPHONE = 6,
+  PP_TEXTINPUT_TYPE_URL = 7
+};
+
+interface PPB_TextInput_Dev {

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

I'm worried the very generic name "TextInput" might be confusing. This wold only
be used for IME, right? I can imagine seeing this and being confused that I need
to implement this for all types of text input.

Does it make sense to have "IME" in the name, like "IMETextInput"?

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

IME generally accepted as CJK input methods, but e.g.
setting text field type is beyond the scope of IME, hence
we use TextInput as prefix for this.

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

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

It is not limited to IME. For instance, touch UI relies on the text input type
and caret position to decide virtual keyboard pop-up. As opposed to the
IMEInputEvent that can somehow be ignored, "TextInput" is recommendable (though
not mandatory) for all types of text inputs.

I added several comments to make the purpose of this interface clearer so as not
to bring confusion...

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

Is it true that Confirm/CancelCompositionText are IME-specific and supposed to
work with PP_INPUTEVENT_CLASS_IME; while other functions can be used by other
text inputs such as touch UI?

On 2011/09/14 08:54:04, kinaba wrote:

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

Yes--they are IME-specific and very closely related to
PP_INPUTEVENT_CLASS_IME--but, no, they can be used without registering
PP_INPUTEVENT_CLASS_IME. A hypothetical example is a plugin that doesn't want to
bother managing composition text by itself (and hence don't register for
PP_INPUTEVENT_CLASS_IME), but wants to make sure the composition is reset at the
timing of, say, focus-change.
True.

+  /**
+   * Informs the browser about the current text input mode of the plugin.
+   */
+  void SetTextInputType([in] PP_Instance instance,
+                        [in] PP_TextInput_Type type);
+
+  /**
+   * Informs the browser about the coordinates of the text input caret, and the
+   * bounding box of the text input area. The browser uses the information to
+   * locate the composition candidate window, etc.
+   */
+  void UpdateCaretPosition([in] PP_Instance instance,
+                           [in] PP_Rect caret,
+                           [in] PP_Rect bounding_box);
+  /**
+   * Forces to commit the current composition text (if any).
+   */
+  void ConfirmCompositionText([in] PP_Instance instance);
+
+  /**
+   * Cancels the current composition (if any).
+   */
+  void CancelCompositionText([in] PP_Instance instance);
+};