ppapi/c/dev/ppb_text_input_dev.h

   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 /* From dev/ppb_text_input_dev.idl modified Tue Aug  6 10:37:25 2013. */
   7
   8 #ifndef PPAPI_C_DEV_PPB_TEXT_INPUT_DEV_H_
   9 #define PPAPI_C_DEV_PPB_TEXT_INPUT_DEV_H_
  10
  11 #include "ppapi/c/pp_instance.h"
  12 #include "ppapi/c/pp_macros.h"
  13 #include "ppapi/c/pp_point.h"
  14 #include "ppapi/c/pp_rect.h"
  15 #include "ppapi/c/pp_size.h"
  16 #include "ppapi/c/pp_stdint.h"
  17
  18 #define PPB_TEXTINPUT_DEV_INTERFACE_0_1 "PPB_TextInput(Dev);0.1"
  19 #define PPB_TEXTINPUT_DEV_INTERFACE_0_2 "PPB_TextInput(Dev);0.2"
  20 #define PPB_TEXTINPUT_DEV_INTERFACE PPB_TEXTINPUT_DEV_INTERFACE_0_2
  21
  22 /**
  23  * @file
  24  * This file defines the <code>PPB_TextInput_Dev</code> interface.
  25  */
  26
  27
  28 /**
  29  * @addtogroup Enums
  30  * @{
  31  */
  32 /**
  33  * PP_TextInput_Type is used to indicate the status of a plugin in regard to
  34  * text input.
  35  */
  36 typedef enum {
  37   /**
  38    * Input caret is not in an editable mode, no input method shall be used.
  39    */
  40   PP_TEXTINPUT_TYPE_DEV_NONE = 0,
  41   /**
  42    * Input caret is in a normal editable mode, any input method can be used.
  43    */
  44   PP_TEXTINPUT_TYPE_DEV_TEXT = 1,
  45   /**
  46    * Input caret is in a password box, an input method may be used only if
  47    * it's suitable for password input.
  48    */
  49   PP_TEXTINPUT_TYPE_DEV_PASSWORD = 2,
  50   PP_TEXTINPUT_TYPE_DEV_SEARCH = 3,
  51   PP_TEXTINPUT_TYPE_DEV_EMAIL = 4,
  52   PP_TEXTINPUT_TYPE_DEV_NUMBER = 5,
  53   PP_TEXTINPUT_TYPE_DEV_TELEPHONE = 6,
  54   PP_TEXTINPUT_TYPE_DEV_URL = 7
  55 } PP_TextInput_Type_Dev;
  56 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TextInput_Type_Dev, 4);
  57 /**
  58  * @}
  59  */
  60
  61 /**
  62  * @addtogroup Interfaces
  63  * @{
  64  */
  65 /**
  66  * <code>PPB_TextInput_Dev</code> provides a set of functions for giving hints
  67  * to the browser about the text input status of plugins, and functions for
  68  * controlling input method editors (IMEs).
  69  */
  70 struct PPB_TextInput_Dev_0_2 {
  71   /**
  72    * Informs the browser about the current text input mode of the plugin.
  73    * Typical use of this information in the browser is to properly
  74    * display/suppress tools for supporting text inputs (such as virtual
  75    * keyboards in touch screen based devices, or input method editors often
  76    * used for composing East Asian characters).
  77    */
  78   void (*SetTextInputType)(PP_Instance instance, PP_TextInput_Type_Dev type);
  79   /**
  80    * Informs the browser about the coordinates of the text input caret and the
  81    * bounding box of the text input area. Typical use of this information in
  82    * the browser is to layout IME windows etc.
  83    */
  84   void (*UpdateCaretPosition)(PP_Instance instance,
  85                               const struct PP_Rect* caret,
  86                               const struct PP_Rect* bounding_box);
  87   /**
  88    * Cancels the current composition in IME.
  89    */
  90   void (*CancelCompositionText)(PP_Instance instance);
  91   /**
  92    * In response to the <code>PPP_TextInput_Dev::RequestSurroundingText</code>
  93    * call, informs the browser about the current text selection and surrounding
  94    * text. <code>text</code> is a UTF-8 string that contains the current range
  95    * of text selection in the plugin. <code>caret</code> is the byte-index of
  96    * the caret position within <code>text</code>. <code>anchor</code> is the
  97    * byte-index of the anchor position (i.e., if a range of text is selected,
  98    * it is the other edge of selection different from <code>caret</code>. If
  99    * there are no selection, <code>anchor</code> is equal to <code>caret</code>.
 100    *
 101    * Typical use of this information in the browser is to enable "reconversion"
 102    * features of IME that puts back the already committed text into the
 103    * pre-commit composition state. Another use is to improve the precision
 104    * of suggestion of IME by taking the context into account (e.g., if the caret
 105    * looks to be on the beginning of a sentence, suggest capital letters in a
 106    * virtual keyboard).
 107    *
 108    * When the focus is not on text, call this function setting <code>text</code>
 109    * to an empty string and <code>caret</code> and <code>anchor</code> to zero.
 110    * Also, the plugin should send the empty text when it does not want to reveal
 111    * the selection to IME (e.g., when the surrounding text is containing
 112    * password text).
 113    */
 114   void (*UpdateSurroundingText)(PP_Instance instance,
 115                                 const char* text,
 116                                 uint32_t caret,
 117                                 uint32_t anchor);
 118   /**
 119    * Informs the browser when a range of text selection is changed in a plugin.
 120    * When the browser needs to know the content of the updated selection, it
 121    * pings back by <code>PPP_TextInput_Dev::RequestSurroundingText</code>. The
 122    * plugin then should send the information with
 123    * <code>UpdateSurroundingText</code>.
 124    */
 125   void (*SelectionChanged)(PP_Instance instance);
 126 };
 127
 128 typedef struct PPB_TextInput_Dev_0_2 PPB_TextInput_Dev;
 129
 130 struct PPB_TextInput_Dev_0_1 {
 131   void (*SetTextInputType)(PP_Instance instance, PP_TextInput_Type_Dev type);
 132   void (*UpdateCaretPosition)(PP_Instance instance,
 133                               const struct PP_Rect* caret,
 134                               const struct PP_Rect* bounding_box);
 135   void (*CancelCompositionText)(PP_Instance instance);
 136 };
 137 /**
 138  * @}
 139  */
 140
 141 #endif  /* PPAPI_C_DEV_PPB_TEXT_INPUT_DEV_H_ */
 142