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