input_method_engine.h revision 4e180b6a0b4720a9b8e9e959a882386f690f08ff 
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
11class GURL;
12
13namespace chromeos {
14
15namespace input_method {
16struct KeyEventHandle;
17}  // namespace input_method
18
19// InputMethodEngine is used to translate from the Chrome IME API to the native
20// API.
21class 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_
258