ppapi/api/dev/ppb_ime_input_event_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_IMEInputEvent_Dev</code> interface.
   8  */
   9
  10 label Chrome {
  11   M16 = 0.1,
  12   M21 = 0.2
  13 };
  14
  15 [macro="PPB_IME_INPUT_EVENT_DEV_INTERFACE"]
  16 interface PPB_IMEInputEvent_Dev {
  17   /**
  18    * Create() creates an IME input event with the given parameters. Normally
  19    * you will get an IME event passed through the <code>HandleInputEvent</code>
  20    * and will not need to create them, but some applications may want to create
  21    * their own for internal use.
  22    *
  23    * @param[in] instance The instance for which this event occurred.
  24    *
  25    * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
  26    * input event. The type must be one of the IME event types.
  27    *
  28    * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
  29    * when the event occurred.
  30    *
  31    * @param[in] text The string returned by <code>GetText</code>.
  32    *
  33    * @param[in] segment_number The number returned by
  34    * <code>GetSegmentNumber</code>.
  35    *
  36    * @param[in] segment_offsets The array of numbers returned by
  37    * <code>GetSegmentOffset</code>. If <code>segment_number</code> is zero,
  38    * the number of elements of the array should be zero. If
  39    * <code>segment_number</code> is non-zero, the length of the array must be
  40    * <code>segment_number</code> + 1.
  41    *
  42    * @param[in] target_segment The number returned by
  43    * <code>GetTargetSegment</code>.
  44    *
  45    * @param[in] selection_start The start index returned by
  46    * <code>GetSelection</code>.
  47    *
  48    * @param[in] selection_end The end index returned by
  49    * <code>GetSelection</code>.
  50    *
  51    * @return A <code>PP_Resource</code> containing the new IME input event.
  52    */
  53   [version=0.2]
  54   PP_Resource Create([in] PP_Instance instance,
  55                      [in] PP_InputEvent_Type type,
  56                      [in] PP_TimeTicks time_stamp,
  57                      [in] PP_Var text,
  58                      [in] uint32_t segment_number,
  59                      [in] uint32_t[] segment_offsets,
  60                      [in] int32_t target_segment,
  61                      [in] uint32_t selection_start,
  62                      [in] uint32_t selection_end);
  63
  64   /**
  65    * IsIMEInputEvent() determines if a resource is an IME event.
  66    *
  67    * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
  68    *
  69    * @return <code>PP_TRUE</code> if the given resource is a valid input event.
  70    */
  71   PP_Bool IsIMEInputEvent([in] PP_Resource resource);
  72
  73   /**
  74    * GetText() returns the composition text as a UTF-8 string for the given IME
  75    * event.
  76    *
  77    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
  78    * event.
  79    *
  80    * @return A string var representing the composition text. For non-IME input
  81    * events the return value will be an undefined var.
  82    */
  83   PP_Var GetText([in] PP_Resource ime_event);
  84
  85   /**
  86    * GetSegmentNumber() returns the number of segments in the composition text.
  87    *
  88    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
  89    * event.
  90    *
  91    * @return The number of segments. For events other than COMPOSITION_UPDATE,
  92    * returns 0.
  93    */
  94   uint32_t GetSegmentNumber([in] PP_Resource ime_event);
  95
  96   /**
  97    * GetSegmentOffset() returns the position of the index-th segmentation point
  98    * in the composition text. The position is given by a byte-offset (not a
  99    * character-offset) of the string returned by GetText(). It always satisfies
 100    * 0=GetSegmentOffset(0) < ... < GetSegmentOffset(i) < GetSegmentOffset(i+1)
 101    * < ... < GetSegmentOffset(GetSegmentNumber())=(byte-length of GetText()).
 102    * Note that [GetSegmentOffset(i), GetSegmentOffset(i+1)) represents the range
 103    * of the i-th segment, and hence GetSegmentNumber() can be a valid argument
 104    * to this function instead of an off-by-1 error.
 105    *
 106    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
 107    * event.
 108    *
 109    * @param[in] index An integer indicating a segment.
 110    *
 111    * @return The byte-offset of the segmentation point. If the event is not
 112    * COMPOSITION_UPDATE or index is out of range, returns 0.
 113    */
 114   uint32_t GetSegmentOffset([in] PP_Resource ime_event,
 115                             [in] uint32_t index);
 116
 117   /**
 118    * GetTargetSegment() returns the index of the current target segment of
 119    * composition.
 120    *
 121    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
 122    * event.
 123    *
 124    * @return An integer indicating the index of the target segment. When there
 125    * is no active target segment, or the event is not COMPOSITION_UPDATE,
 126    * returns -1.
 127    */
 128   int32_t GetTargetSegment([in] PP_Resource ime_event);
 129
 130   /**
 131    * GetSelection() returns the range selected by caret in the composition text.
 132    *
 133    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
 134    * event.
 135    *
 136    * @param[out] start The start position of the current selection.
 137    *
 138    * @param[out] end The end position of the current selection.
 139    */
 140   void GetSelection([in] PP_Resource ime_event,
 141                     [out] uint32_t start,
 142                     [out] uint32_t end);
 143 };