src/chrome/browser/chromeos/input_method/input_method_engine.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 CHROME_BROWSER_CHROMEOS_INPUT_METHOD_INPUT_METHOD_ENGINE_H_
   6 #define CHROME_BROWSER_CHROMEOS_INPUT_METHOD_INPUT_METHOD_ENGINE_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 class GURL;
  12
  13 namespace chromeos {
  14
  15 namespace input_method {
  16 struct KeyEventHandle;
  17 }  // namespace input_method
  18
  19 // InputMethodEngine is used to translate from the Chrome IME API to the native
  20 // API.
  21 class InputMethodEngine {
  22  public:
  23   struct KeyboardEvent {
  24     KeyboardEvent();
  25     virtual ~KeyboardEvent();
  26
  27     std::string type;
  28     std::string key;
  29     std::string code;
  30     bool alt_key;
  31     bool ctrl_key;
  32     bool shift_key;
  33     bool caps_lock;
  34   };
  35
  36   enum {
  37     MENU_ITEM_MODIFIED_LABEL        = 0x0001,
  38     MENU_ITEM_MODIFIED_STYLE        = 0x0002,
  39     MENU_ITEM_MODIFIED_VISIBLE      = 0x0004,
  40     MENU_ITEM_MODIFIED_ENABLED      = 0x0008,
  41     MENU_ITEM_MODIFIED_CHECKED      = 0x0010,
  42     MENU_ITEM_MODIFIED_ICON         = 0x0020,
  43   };
  44
  45   enum MenuItemStyle {
  46     MENU_ITEM_STYLE_NONE,
  47     MENU_ITEM_STYLE_CHECK,
  48     MENU_ITEM_STYLE_RADIO,
  49     MENU_ITEM_STYLE_SEPARATOR,
  50   };
  51
  52   enum MouseButtonEvent {
  53     MOUSE_BUTTON_LEFT,
  54     MOUSE_BUTTON_RIGHT,
  55     MOUSE_BUTTON_MIDDLE,
  56   };
  57
  58   enum SegmentStyle {
  59     SEGMENT_STYLE_UNDERLINE,
  60     SEGMENT_STYLE_DOUBLE_UNDERLINE,
  61   };
  62
  63   enum CandidateWindowPosition {
  64     WINDOW_POS_CURSOR,
  65     WINDOW_POS_COMPOSITTION,
  66   };
  67
  68   struct MenuItem {
  69     MenuItem();
  70     virtual ~MenuItem();
  71
  72     std::string id;
  73     std::string label;
  74     MenuItemStyle style;
  75     bool visible;
  76     bool enabled;
  77     bool checked;
  78
  79     unsigned int modified;
  80     std::vector<MenuItem> children;
  81   };
  82
  83   struct InputContext {
  84     int id;
  85     std::string type;
  86   };
  87
  88   struct UsageEntry {
  89     std::string title;
  90     std::string body;
  91   };
  92
  93   struct Candidate {
  94     Candidate();
  95     virtual ~Candidate();
  96
  97     std::string value;
  98     int id;
  99     std::string label;
 100     std::string annotation;
 101     UsageEntry usage;
 102     std::vector<Candidate> candidates;
 103   };
 104
 105   struct CandidateWindowProperty {
 106     CandidateWindowProperty();
 107     virtual ~CandidateWindowProperty();
 108     int page_size;
 109     bool is_cursor_visible;
 110     bool is_vertical;
 111     bool show_window_at_composition;
 112   };
 113
 114   struct SegmentInfo {
 115     int start;
 116     int end;
 117     SegmentStyle style;
 118   };
 119
 120   class Observer {
 121    public:
 122     virtual ~Observer();
 123
 124     // Called when the IME becomes the active IME.
 125     virtual void OnActivate(const std::string& engine_id) = 0;
 126
 127     // Called when the IME is no longer active.
 128     virtual void OnDeactivated(const std::string& engine_id) = 0;
 129
 130     // Called when a text field gains focus, and will be sending key events.
 131     virtual void OnFocus(const InputContext& context) = 0;
 132
 133     // Called when a text field loses focus, and will no longer generate events.
 134     virtual void OnBlur(int context_id) = 0;
 135
 136     // Called when an InputContext's properties change while it is focused.
 137     virtual void OnInputContextUpdate(const InputContext& context) = 0;
 138
 139     // Called when the user pressed a key with a text field focused.
 140     virtual void OnKeyEvent(const std::string& engine_id,
 141                             const KeyboardEvent& event,
 142                             input_method::KeyEventHandle* key_data) = 0;
 143
 144     // Called when the user clicks on an item in the candidate list.
 145     virtual void OnCandidateClicked(const std::string& engine_id,
 146                                     int candidate_id,
 147                                     MouseButtonEvent button) = 0;
 148
 149     // Called when a menu item for this IME is interacted with.
 150     virtual void OnMenuItemActivated(const std::string& engine_id,
 151                                      const std::string& menu_id) = 0;
 152
 153     // Called when a surrounding text is changed.
 154     virtual void OnSurroundingTextChanged(const std::string& engine_id,
 155                                           const std::string& text,
 156                                           int cursor_pos,
 157                                           int anchor_pos) = 0;
 158
 159     // Called when Chrome terminates on-going text input session.
 160     virtual void OnReset(const std::string& engine_id) = 0;
 161   };
 162
 163   virtual ~InputMethodEngine() {}
 164
 165   // Called when the input metho initialization is done.
 166   // This function is called from private API.
 167   // TODO(nona): Remove this function.
 168   virtual void StartIme() = 0;
 169
 170   // Set the current composition and associated properties.
 171   virtual bool SetComposition(int context_id,
 172                               const char* text,
 173                               int selection_start,
 174                               int selection_end,
 175                               int cursor,
 176                               const std::vector<SegmentInfo>& segments,
 177                               std::string* error) = 0;
 178
 179   // Clear the current composition.
 180   virtual bool ClearComposition(int context_id, std::string* error) = 0;
 181
 182   // Commit the specified text to the specified context.  Fails if the context
 183   // is not focused.
 184   virtual bool CommitText(int context_id, const char* text,
 185                           std::string* error) = 0;
 186
 187   // This function returns the current property of the candidate window.
 188   // The caller can use the returned value as the default property and
 189   // modify some of specified items.
 190   virtual const CandidateWindowProperty&
 191     GetCandidateWindowProperty() const = 0;
 192
 193   // Change the property of the candidate window and repaint the candidate
 194   // window widget.
 195   virtual void SetCandidateWindowProperty(
 196       const CandidateWindowProperty& property) = 0;
 197
 198   // Show or hide the candidate window.
 199   virtual bool SetCandidateWindowVisible(bool visible, std::string* error) = 0;
 200
 201   // Set the text that appears as a label in the candidate window.
 202   virtual void SetCandidateWindowAuxText(const char* text) = 0;
 203
 204   // Show or hide the extra text in the candidate window.
 205   virtual void SetCandidateWindowAuxTextVisible(bool visible) = 0;
 206
 207   // Set the list of entries displayed in the candidate window.
 208   virtual bool SetCandidates(int context_id,
 209                              const std::vector<Candidate>& candidates,
 210                              std::string* error) = 0;
 211
 212   // Set the position of the cursor in the candidate window.
 213   virtual bool SetCursorPosition(int context_id, int candidate_id,
 214                                  std::string* error) = 0;
 215
 216   // Set the list of items that appears in the language menu when this IME is
 217   // active.
 218   virtual bool SetMenuItems(const std::vector<MenuItem>& items) = 0;
 219
 220   // Update the state of the menu items.
 221   virtual bool UpdateMenuItems(const std::vector<MenuItem>& items) = 0;
 222
 223   // Returns true if this IME is active, false if not.
 224   virtual bool IsActive() const = 0;
 225
 226   // Inform the engine that a key event has been processed.
 227   virtual void KeyEventDone(input_method::KeyEventHandle* key_data,
 228                             bool handled) = 0;
 229
 230   // Deletes |number_of_chars| unicode characters as the basis of |offset| from
 231   // the surrounding text. The |offset| is relative position based on current
 232   // caret.
 233   // NOTE: Currently we are falling back to backspace forwarding workaround,
 234   // because delete_surrounding_text is not supported in Chrome. So this
 235   // function is restricted for only preceding text.
 236   // TODO(nona): Support full spec delete surrounding text.
 237   virtual bool DeleteSurroundingText(int context_id,
 238                                      int offset,
 239                                      size_t number_of_chars,
 240                                      std::string* error) = 0;
 241
 242   // Create an IME engine.
 243   static InputMethodEngine* CreateEngine(
 244       InputMethodEngine::Observer* observer,
 245       const char* engine_name,
 246       const char* extension_id,
 247       const char* engine_id,
 248       const char* description,
 249       const std::vector<std::string>& language,
 250       const std::vector<std::string>& layouts,
 251       const GURL& options_page,
 252       std::string* error);
 253 };
 254
 255 }  // namespace chromeos
 256
 257 #endif  // CHROME_BROWSER_CHROMEOS_INPUT_METHOD_INPUT_METHOD_ENGINE_H_