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 UI_BASE_IME_TEXT_INPUT_CLIENT_H_
6#define UI_BASE_IME_TEXT_INPUT_CLIENT_H_
7
8#include "base/basictypes.h"
9#include "base/i18n/rtl.h"
10#include "base/strings/string16.h"
11#include "ui/base/ime/composition_text.h"
12#include "ui/base/ime/text_input_mode.h"
13#include "ui/base/ime/text_input_type.h"
14#include "ui/base/ui_base_export.h"
15#include "ui/gfx/native_widget_types.h"
16#include "ui/gfx/range/range.h"
17
18namespace gfx {
19class Rect;
20}
21
22namespace ui {
23
24// An interface implemented by a View that needs text input support.
25class UI_BASE_EXPORT TextInputClient {
26 public:
27  virtual ~TextInputClient();
28
29  // Input method result -------------------------------------------------------
30
31  // Sets composition text and attributes. If there is composition text already,
32  // it'll be replaced by the new one. Otherwise, current selection will be
33  // replaced. If there is no selection, the composition text will be inserted
34  // at the insertion point.
35  virtual void SetCompositionText(const ui::CompositionText& composition) = 0;
36
37  // Converts current composition text into final content.
38  virtual void ConfirmCompositionText() = 0;
39
40  // Removes current composition text.
41  virtual void ClearCompositionText() = 0;
42
43  // Inserts a given text at the insertion point. Current composition text or
44  // selection will be removed. This method should never be called when the
45  // current text input type is TEXT_INPUT_TYPE_NONE.
46  virtual void InsertText(const base::string16& text) = 0;
47
48  // Inserts a single char at the insertion point. Unlike above InsertText()
49  // method, this method has an extra |flags| parameter indicating the modifier
50  // key states when the character is generated. This method should only be
51  // called when a key press is not handled by the input method but still
52  // generates a character (eg. by the keyboard driver). In another word, the
53  // preceding key press event should not be a VKEY_PROCESSKEY.
54  // This method will be called whenever a char is generated by the keyboard,
55  // even if the current text input type is TEXT_INPUT_TYPE_NONE.
56  virtual void InsertChar(base::char16 ch, int flags) = 0;
57
58  // Input context information -------------------------------------------------
59
60  // Returns native window to which input context is bound.
61  virtual gfx::NativeWindow GetAttachedWindow() const = 0;
62
63  // Returns current text input type. It could be changed and even becomes
64  // TEXT_INPUT_TYPE_NONE at runtime.
65  virtual ui::TextInputType GetTextInputType() const = 0;
66
67  // Returns current text input mode. It could be changed and even becomes
68  // TEXT_INPUT_MODE_DEFAULT at runtime.
69  virtual ui::TextInputMode GetTextInputMode() const = 0;
70
71  // Returns if the client supports inline composition currently.
72  virtual bool CanComposeInline() const = 0;
73
74  // Returns current caret (insertion point) bounds in the universal screen
75  // coordinates. If there is selection, then the selection bounds will be
76  // returned.
77  // Note: On Windows, the returned value is supposed to be DIP (Density
78  // Independent Pixel).
79  // TODO(ime): Have a clear spec whether the returned value is DIP or not.
80  // http://crbug.com/360334
81  virtual gfx::Rect GetCaretBounds() const = 0;
82
83  // Retrieves the composition character boundary rectangle in the universal
84  // screen coordinates. The |index| is zero-based index of character position
85  // in composition text.
86  // Returns false if there is no composition text or |index| is out of range.
87  // The |rect| is not touched in the case of failure.
88  // Note: On Windows, the returned value is supposed to be DIP
89  // (Density Independent Pixel).
90  // TODO(ime): Have a clear spec whether the returned value is DIP or not.
91  // http://crbug.com/360334
92  virtual bool GetCompositionCharacterBounds(uint32 index,
93                                             gfx::Rect* rect) const = 0;
94
95  // Returns true if there is composition text.
96  virtual bool HasCompositionText() const = 0;
97
98  // Document content operations ----------------------------------------------
99
100  // Retrieves the UTF-16 based character range containing accessibled text in
101  // the View. It must cover the composition and selection range.
102  // Returns false if the information cannot be retrieved right now.
103  virtual bool GetTextRange(gfx::Range* range) const = 0;
104
105  // Retrieves the UTF-16 based character range of current composition text.
106  // Returns false if the information cannot be retrieved right now.
107  virtual bool GetCompositionTextRange(gfx::Range* range) const = 0;
108
109  // Retrieves the UTF-16 based character range of current selection.
110  // Returns false if the information cannot be retrieved right now.
111  virtual bool GetSelectionRange(gfx::Range* range) const = 0;
112
113  // Selects the given UTF-16 based character range. Current composition text
114  // will be confirmed before selecting the range.
115  // Returns false if the operation is not supported.
116  virtual bool SetSelectionRange(const gfx::Range& range) = 0;
117
118  // Deletes contents in the given UTF-16 based character range. Current
119  // composition text will be confirmed before deleting the range.
120  // The input caret will be moved to the place where the range gets deleted.
121  // ExtendSelectionAndDelete should be used instead as far as you are deleting
122  // characters around current caret. This function with the range based on
123  // GetSelectionRange has a race condition due to asynchronous IPCs between
124  // browser and renderer.
125  // Returns false if the operation is not supported.
126  virtual bool DeleteRange(const gfx::Range& range) = 0;
127
128  // Retrieves the text content in a given UTF-16 based character range.
129  // The result will be stored into |*text|.
130  // Returns false if the operation is not supported or the specified range
131  // is out of the text range returned by GetTextRange().
132  virtual bool GetTextFromRange(const gfx::Range& range,
133                                base::string16* text) const = 0;
134
135  // Miscellaneous ------------------------------------------------------------
136
137  // Called whenever current keyboard layout or input method is changed,
138  // especially the change of input locale and text direction.
139  virtual void OnInputMethodChanged() = 0;
140
141  // Called whenever the user requests to change the text direction and layout
142  // alignment of the current text box. It's for supporting ctrl-shift on
143  // Windows.
144  // Returns false if the operation is not supported.
145  virtual bool ChangeTextDirectionAndLayoutAlignment(
146      base::i18n::TextDirection direction) = 0;
147
148  // Deletes the current selection plus the specified number of characters
149  // before and after the selection or caret. This function should be used
150  // instead of calling DeleteRange with GetSelectionRange, because
151  // GetSelectionRange may not be the latest value due to asynchronous of IPC
152  // between browser and renderer.
153  virtual void ExtendSelectionAndDelete(size_t before, size_t after) = 0;
154
155  // Ensure the caret is within |rect|.  |rect| is in screen coordinates and
156  // may extend beyond the bounds of this TextInputClient.
157  // Note: On Windows, the returned value is supposed to be DIP (Density
158  // Independent Pixel).
159  // TODO(ime): Have a clear spec whether the returned value is DIP or not.
160  // http://crbug.com/360334
161  virtual void EnsureCaretInRect(const gfx::Rect& rect) = 0;
162
163  // Called when IME shows a candidate window.
164  virtual void OnCandidateWindowShown() = 0;
165  // Called when IME updates any appearance of the current candidate window.
166  virtual void OnCandidateWindowUpdated() = 0;
167  // Called when IME hides the candidate window.
168  virtual void OnCandidateWindowHidden() = 0;
169
170  // Returns true if |command_id| is currently allowed to be executed.
171  virtual bool IsEditingCommandEnabled(int command_id) = 0;
172  // Execute the command specified by |command_id|.
173  virtual void ExecuteEditingCommand(int command_id) = 0;
174};
175
176}  // namespace ui
177
178#endif  // UI_BASE_IME_TEXT_INPUT_CLIENT_H_
179