/* Copyright (c) 2012 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,
  M19 = 0.2
};

/**
 * PP_TextInput_Type is used to indicate the status of a plugin in regard to
 * text input.
 */
[assert_size(4)]
enum PP_TextInput_Type_Dev {
  /**
   * Input caret is not in an editable mode, no input method shall be used.
   */
  PP_TEXTINPUT_TYPE_DEV_NONE = 0,
  /**
   * Input caret is in a normal editable mode, any input method can be used.
   */
  PP_TEXTINPUT_TYPE_DEV_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_DEV_PASSWORD = 2,
  PP_TEXTINPUT_TYPE_DEV_SEARCH = 3,
  PP_TEXTINPUT_TYPE_DEV_EMAIL = 4,
  PP_TEXTINPUT_TYPE_DEV_NUMBER = 5,
  PP_TEXTINPUT_TYPE_DEV_TELEPHONE = 6,
  PP_TEXTINPUT_TYPE_DEV_URL = 7
};

/**
 * <code>PPB_TextInput_Dev</code> provides a set of functions for giving hints
 * to the browser about the text input status of plugins, and functions for
 * controlling input method editors (IMEs).
 */
interface PPB_TextInput_Dev {
  /**
   * Informs the browser about the current text input mode of the plugin.
   * Typical use of this information in the browser is to properly
   * display/suppress tools for supporting text inputs (such as virtual
   * keyboards in touch screen based devices, or input method editors often
   * used for composing East Asian characters).
   */
  void SetTextInputType([in] PP_Instance instance,
                        [in] PP_TextInput_Type_Dev type);

  /**
   * Informs the browser about the coordinates of the text input caret and the
   * bounding box of the text input area. Typical use of this information in
   * the browser is to layout IME windows etc.
   */
  void UpdateCaretPosition([in] PP_Instance instance,
                           [in] PP_Rect caret,
                           [in] PP_Rect bounding_box);

  /**
   * Cancels the current composition in IME.
   */
  void CancelCompositionText([in] PP_Instance instance);

  /**
   * In response to the <code>PPP_TextInput_Dev::RequestSurroundingText</code>
   * call, informs the browser about the current text selection and surrounding
   * text. <code>text</code> is a UTF-8 string that contains the current range
   * of text selection in the plugin. <code>caret</code> is the byte-index of
   * the caret position within <code>text</code>. <code>anchor</code> is the
   * byte-index of the anchor position (i.e., if a range of text is selected,
   * it is the other edge of selection different from <code>caret</code>. If
   * there are no selection, <code>anchor</code> is equal to <code>caret</code>.
   *
   * Typical use of this information in the browser is to enable "reconversion"
   * features of IME that puts back the already committed text into the
   * pre-commit composition state. Another use is to improve the precision
   * of suggestion of IME by taking the context into account (e.g., if the caret
   * looks to be on the beginning of a sentence, suggest capital letters in a
   * virtual keyboard).
   *
   * When the focus is not on text, call this function setting <code>text</code>
   * to an empty string and <code>caret</code> and <code>anchor</code> to zero.
   * Also, the plugin should send the empty text when it does not want to reveal
   * the selection to IME (e.g., when the surrounding text is containing
   * password text).
   */
  [version=0.2]
  void UpdateSurroundingText([in] PP_Instance instance,
                             [in] str_t text,
                             [in] uint32_t caret,
                             [in] uint32_t anchor);

  /**
   * Informs the browser when a range of text selection is changed in a plugin.
   * When the browser needs to know the content of the updated selection, it
   * pings back by <code>PPP_TextInput_Dev::RequestSurroundingText</code>. The
   * plugin then should send the information with
   * <code>UpdateSurroundingText</code>.
   */
  [version=0.2]
  void SelectionChanged([in] PP_Instance instance);
};