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
10label Chrome {
11  M16 = 0.1,
12  M21 = 0.2
13};
14
15[macro="PPB_IME_INPUT_EVENT_DEV_INTERFACE"]
16interface 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};
144