ppapi/api/ppb_text_input_controller.idl

   1 /* Copyright 2013 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_TextInputController</code> interface.
   8  */
   9
  10 label Chrome {
  11   M30 = 1.0
  12 };
  13
  14 /**
  15  * PP_TextInput_Type is used to indicate the status of a plugin in regard to
  16  * text input.
  17  */
  18 [assert_size(4)]
  19 enum PP_TextInput_Type {
  20   /**
  21    * Input caret is not in an editable mode, no input method shall be used.
  22    */
  23   PP_TEXTINPUT_TYPE_NONE = 0,
  24   /**
  25    * Input caret is in a normal editable mode, any input method can be used.
  26    */
  27   PP_TEXTINPUT_TYPE_TEXT = 1,
  28   /**
  29    * Input caret is in a password box, an input method may be used only if
  30    * it's suitable for password input.
  31    */
  32   PP_TEXTINPUT_TYPE_PASSWORD = 2,
  33   PP_TEXTINPUT_TYPE_SEARCH = 3,
  34   PP_TEXTINPUT_TYPE_EMAIL = 4,
  35   PP_TEXTINPUT_TYPE_NUMBER = 5,
  36   PP_TEXTINPUT_TYPE_TELEPHONE = 6,
  37   PP_TEXTINPUT_TYPE_URL = 7
  38 };
  39
  40 /**
  41  * <code>PPB_TextInputController</code> provides a set of functions for giving
  42  * hints to the browser about the text input status of plugins, and functions
  43  * for controlling input method editors (IMEs).
  44  */
  45 interface PPB_TextInputController {
  46   /**
  47    * Informs the browser about the current text input mode of the plugin.
  48    * Typical use of this information in the browser is to properly
  49    * display/suppress tools for supporting text inputs (such as virtual
  50    * keyboards in touch screen based devices, or input method editors often
  51    * used for composing East Asian characters).
  52    */
  53   void SetTextInputType([in] PP_Instance instance,
  54                         [in] PP_TextInput_Type type);
  55
  56   /**
  57    * Informs the browser about the coordinates of the text input caret area.
  58    * Typical use of this information in the browser is to layout IME windows
  59    * etc.
  60    */
  61   void UpdateCaretPosition([in] PP_Instance instance,
  62                            [in] PP_Rect caret);
  63
  64   /**
  65    * Cancels the current composition in IME.
  66    */
  67   void CancelCompositionText([in] PP_Instance instance);
  68
  69   /**
  70    * Informs the browser about the current text selection and surrounding
  71    * text. <code>text</code> is a UTF-8 string that contains the current range
  72    * of text selection in the plugin. <code>caret</code> is the byte-index of
  73    * the caret position within <code>text</code>. <code>anchor</code> is the
  74    * byte-index of the anchor position (i.e., if a range of text is selected,
  75    * it is the other edge of selection different from <code>caret</code>. If
  76    * there are no selection, <code>anchor</code> is equal to <code>caret</code>.
  77    *
  78    * Typical use of this information in the browser is to enable "reconversion"
  79    * features of IME that puts back the already committed text into the
  80    * pre-commit composition state. Another use is to improve the precision
  81    * of suggestion of IME by taking the context into account (e.g., if the caret
  82    * looks to be on the beginning of a sentence, suggest capital letters in a
  83    * virtual keyboard).
  84    *
  85    * When the focus is not on text, call this function setting <code>text</code>
  86    * to an empty string and <code>caret</code> and <code>anchor</code> to zero.
  87    * Also, the plugin should send the empty text when it does not want to reveal
  88    * the selection to IME (e.g., when the surrounding text is containing
  89    * password text).
  90    */
  91   void UpdateSurroundingText([in] PP_Instance instance,
  92                              [in] PP_Var text,
  93                              [in] uint32_t caret,
  94                              [in] uint32_t anchor);
  95 };