ppapi/api/dev/ppb_text_input_dev.idl

   1 /* Copyright (c) 2012 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_TextInput_Dev</code> interface.
   8  */
   9
  10 label Chrome {
  11   M16 = 0.1,
  12   M19 = 0.2
  13 };
  14
  15 /**
  16  * PP_TextInput_Type is used to indicate the status of a plugin in regard to
  17  * text input.
  18  */
  19 [assert_size(4)]
  20 enum PP_TextInput_Type_Dev {
  21   /**
  22    * Input caret is not in an editable mode, no input method shall be used.
  23    */
  24   PP_TEXTINPUT_TYPE_DEV_NONE = 0,
  25   /**
  26    * Input caret is in a normal editable mode, any input method can be used.
  27    */
  28   PP_TEXTINPUT_TYPE_DEV_TEXT = 1,
  29   /**
  30    * Input caret is in a password box, an input method may be used only if
  31    * it's suitable for password input.
  32    */
  33   PP_TEXTINPUT_TYPE_DEV_PASSWORD = 2,
  34   PP_TEXTINPUT_TYPE_DEV_SEARCH = 3,
  35   PP_TEXTINPUT_TYPE_DEV_EMAIL = 4,
  36   PP_TEXTINPUT_TYPE_DEV_NUMBER = 5,
  37   PP_TEXTINPUT_TYPE_DEV_TELEPHONE = 6,
  38   PP_TEXTINPUT_TYPE_DEV_URL = 7
  39 };
  40
  41 /**
  42  * <code>PPB_TextInput_Dev</code> provides a set of functions for giving hints
  43  * to the browser about the text input status of plugins, and functions for
  44  * controlling input method editors (IMEs).
  45  */
  46 interface PPB_TextInput_Dev {
  47   /**
  48    * Informs the browser about the current text input mode of the plugin.
  49    * Typical use of this information in the browser is to properly
  50    * display/suppress tools for supporting text inputs (such as virtual
  51    * keyboards in touch screen based devices, or input method editors often
  52    * used for composing East Asian characters).
  53    */
  54   void SetTextInputType([in] PP_Instance instance,
  55                         [in] PP_TextInput_Type_Dev type);
  56
  57   /**
  58    * Informs the browser about the coordinates of the text input caret and the
  59    * bounding box of the text input area. Typical use of this information in
  60    * the browser is to layout IME windows etc.
  61    */
  62   void UpdateCaretPosition([in] PP_Instance instance,
  63                            [in] PP_Rect caret,
  64                            [in] PP_Rect bounding_box);
  65
  66   /**
  67    * Cancels the current composition in IME.
  68    */
  69   void CancelCompositionText([in] PP_Instance instance);
  70
  71   /**
  72    * In response to the <code>PPP_TextInput_Dev::RequestSurroundingText</code>
  73    * call, informs the browser about the current text selection and surrounding
  74    * text. <code>text</code> is a UTF-8 string that contains the current range
  75    * of text selection in the plugin. <code>caret</code> is the byte-index of
  76    * the caret position within <code>text</code>. <code>anchor</code> is the
  77    * byte-index of the anchor position (i.e., if a range of text is selected,
  78    * it is the other edge of selection different from <code>caret</code>. If
  79    * there are no selection, <code>anchor</code> is equal to <code>caret</code>.
  80    *
  81    * Typical use of this information in the browser is to enable "reconversion"
  82    * features of IME that puts back the already committed text into the
  83    * pre-commit composition state. Another use is to improve the precision
  84    * of suggestion of IME by taking the context into account (e.g., if the caret
  85    * looks to be on the beginning of a sentence, suggest capital letters in a
  86    * virtual keyboard).
  87    *
  88    * When the focus is not on text, call this function setting <code>text</code>
  89    * to an empty string and <code>caret</code> and <code>anchor</code> to zero.
  90    * Also, the plugin should send the empty text when it does not want to reveal
  91    * the selection to IME (e.g., when the surrounding text is containing
  92    * password text).
  93    */
  94   [version=0.2]
  95   void UpdateSurroundingText([in] PP_Instance instance,
  96                              [in] str_t text,
  97                              [in] uint32_t caret,
  98                              [in] uint32_t anchor);
  99
 100   /**
 101    * Informs the browser when a range of text selection is changed in a plugin.
 102    * When the browser needs to know the content of the updated selection, it
 103    * pings back by <code>PPP_TextInput_Dev::RequestSurroundingText</code>. The
 104    * plugin then should send the information with
 105    * <code>UpdateSurroundingText</code>.
 106    */
 107   [version=0.2]
 108   void SelectionChanged([in] PP_Instance instance);
 109 };