ppapi/cpp/dev/ime_input_event_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 #ifndef PPAPI_CPP_DEV_IME_INPUT_EVENT_DEV_H_
   6 #define PPAPI_CPP_DEV_IME_INPUT_EVENT_DEV_H_
   7
   8 #include <utility>
   9 #include <vector>
  10
  11 #include "ppapi/c/dev/ppb_ime_input_event_dev.h"
  12 #include "ppapi/cpp/input_event.h"
  13
  14 /// @file
  15 /// This file defines the API used to handle IME input events.
  16
  17 namespace pp {
  18
  19 class Var;
  20
  21 class IMEInputEvent_Dev : public InputEvent {
  22  public:
  23   /// Constructs an is_null() IME input event object.
  24   IMEInputEvent_Dev();
  25
  26   /// Constructs an IME input event object from the provided generic input
  27   /// event. If the given event is itself is_null() or is not an IME input
  28   /// event, the object will be is_null().
  29   ///
  30   /// @param[in] event A generic input event.
  31   explicit IMEInputEvent_Dev(const InputEvent& event);
  32
  33   /// This constructor manually constructs an IME event from the provided
  34   /// parameters.
  35   ///
  36   /// @param[in] instance The instance for which this event occurred.
  37   ///
  38   /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
  39   /// input event. The type must be one of the ime event types.
  40   ///
  41   /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
  42   /// when the event occurred.
  43   ///
  44   /// @param[in] text The string returned by <code>GetText</code>.
  45   ///
  46   /// @param[in] segment_offsets The array of numbers returned by
  47   /// <code>GetSegmentOffset</code>.
  48   ///
  49   /// @param[in] target_segment The number returned by
  50   /// <code>GetTargetSegment</code>.
  51   ///
  52   /// @param[in] selection The range returned by <code>GetSelection</code>.
  53   IMEInputEvent_Dev(const InstanceHandle& instance,
  54                     PP_InputEvent_Type type,
  55                     PP_TimeTicks time_stamp,
  56                     const Var& text,
  57                     const std::vector<uint32_t>& segment_offsets,
  58                     int32_t target_segment,
  59                     const std::pair<uint32_t, uint32_t>& selection);
  60
  61   /// Returns the composition text as a UTF-8 string for the given IME event.
  62   ///
  63   /// @return A string var representing the composition text. For non-IME
  64   /// input events the return value will be an undefined var.
  65   Var GetText() const;
  66
  67   /// Returns the number of segments in the composition text.
  68   ///
  69   /// @return The number of segments. For events other than COMPOSITION_UPDATE,
  70   /// returns 0.
  71   uint32_t GetSegmentNumber() const;
  72
  73   /// Returns the position of the index-th segmentation point in the composition
  74   /// text. The position is given by a byte-offset (not a character-offset) of
  75   /// the string returned by GetText(). It always satisfies
  76   /// 0=GetSegmentOffset(0) < ... < GetSegmentOffset(i) < GetSegmentOffset(i+1)
  77   /// < ... < GetSegmentOffset(GetSegmentNumber())=(byte-length of GetText()).
  78   /// Note that [GetSegmentOffset(i), GetSegmentOffset(i+1)) represents the
  79   /// range of the i-th segment, and hence GetSegmentNumber() can be a valid
  80   /// argument to this function instead of an off-by-1 error.
  81   ///
  82   /// @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
  83   /// event.
  84   ///
  85   /// @param[in] index An integer indicating a segment.
  86   ///
  87   /// @return The byte-offset of the segmentation point. If the event is not
  88   /// COMPOSITION_UPDATE or index is out of range, returns 0.
  89   uint32_t GetSegmentOffset(uint32_t index) const;
  90
  91   /// Returns the index of the current target segment of composition.
  92   ///
  93   /// @return An integer indicating the index of the target segment. When there
  94   /// is no active target segment, or the event is not COMPOSITION_UPDATE,
  95   /// returns -1.
  96   int32_t GetTargetSegment() const;
  97
  98   /// Returns the range selected by caret in the composition text.
  99   ///
 100   /// @return A pair of integers indicating the selection range.
 101   std::pair<uint32_t, uint32_t> GetSelection() const;
 102 };
 103
 104 }  // namespace pp
 105
 106 #endif  // PPAPI_CPP_DEV_IME_INPUT_EVENT_DEV_H_