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.
5 #ifndef UI_BASE_IME_TEXT_INPUT_CLIENT_H_
6 #define UI_BASE_IME_TEXT_INPUT_CLIENT_H_
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"
24 // An interface implemented by a View that needs text input support.
25 class UI_BASE_EXPORT TextInputClient {
27 virtual ~TextInputClient();
29 // Input method result -------------------------------------------------------
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;
37 // Converts current composition text into final content.
38 virtual void ConfirmCompositionText() = 0;
40 // Removes current composition text.
41 virtual void ClearCompositionText() = 0;
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;
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;
58 // Input context information -------------------------------------------------
60 // Returns native window to which input context is bound.
61 virtual gfx::NativeWindow GetAttachedWindow() const = 0;
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;
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;
71 // Returns if the client supports inline composition currently.
72 virtual bool CanComposeInline() const = 0;
74 // Returns current caret (insertion point) bounds relative to the screen
75 // coordinates. If there is selection, then the selection bounds will be
77 virtual gfx::Rect GetCaretBounds() const = 0;
79 // Retrieves the composition character boundary rectangle relative to the
80 // screen coordinates. The |index| is zero-based index of character position
81 // in composition text.
82 // Returns false if there is no composition text or |index| is out of range.
83 // The |rect| is not touched in the case of failure.
84 virtual bool GetCompositionCharacterBounds(uint32 index,
85 gfx::Rect* rect) const = 0;
87 // Returns true if there is composition text.
88 virtual bool HasCompositionText() const = 0;
90 // Document content operations ----------------------------------------------
92 // Retrieves the UTF-16 based character range containing accessibled text in
93 // the View. It must cover the composition and selection range.
94 // Returns false if the information cannot be retrieved right now.
95 virtual bool GetTextRange(gfx::Range* range) const = 0;
97 // Retrieves the UTF-16 based character range of current composition text.
98 // Returns false if the information cannot be retrieved right now.
99 virtual bool GetCompositionTextRange(gfx::Range* range) const = 0;
101 // Retrieves the UTF-16 based character range of current selection.
102 // Returns false if the information cannot be retrieved right now.
103 virtual bool GetSelectionRange(gfx::Range* range) const = 0;
105 // Selects the given UTF-16 based character range. Current composition text
106 // will be confirmed before selecting the range.
107 // Returns false if the operation is not supported.
108 virtual bool SetSelectionRange(const gfx::Range& range) = 0;
110 // Deletes contents in the given UTF-16 based character range. Current
111 // composition text will be confirmed before deleting the range.
112 // The input caret will be moved to the place where the range gets deleted.
113 // ExtendSelectionAndDelete should be used instead as far as you are deleting
114 // characters around current caret. This function with the range based on
115 // GetSelectionRange has a race condition due to asynchronous IPCs between
116 // browser and renderer.
117 // Returns false if the operation is not supported.
118 virtual bool DeleteRange(const gfx::Range& range) = 0;
120 // Retrieves the text content in a given UTF-16 based character range.
121 // The result will be stored into |*text|.
122 // Returns false if the operation is not supported or the specified range
123 // is out of the text range returned by GetTextRange().
124 virtual bool GetTextFromRange(const gfx::Range& range,
125 base::string16* text) const = 0;
127 // Miscellaneous ------------------------------------------------------------
129 // Called whenever current keyboard layout or input method is changed,
130 // especially the change of input locale and text direction.
131 virtual void OnInputMethodChanged() = 0;
133 // Called whenever the user requests to change the text direction and layout
134 // alignment of the current text box. It's for supporting ctrl-shift on
136 // Returns false if the operation is not supported.
137 virtual bool ChangeTextDirectionAndLayoutAlignment(
138 base::i18n::TextDirection direction) = 0;
140 // Deletes the current selection plus the specified number of characters
141 // before and after the selection or caret. This function should be used
142 // instead of calling DeleteRange with GetSelectionRange, because
143 // GetSelectionRange may not be the latest value due to asynchronous of IPC
144 // between browser and renderer.
145 virtual void ExtendSelectionAndDelete(size_t before, size_t after) = 0;
147 // Ensure the caret is within |rect|. |rect| is in screen coordinates and
148 // may extend beyond the bounds of this TextInputClient.
149 virtual void EnsureCaretInRect(const gfx::Rect& rect) = 0;
151 // Called when IME shows a candidate window.
152 virtual void OnCandidateWindowShown() = 0;
153 // Called when IME updates any appearance of the current candidate window.
154 virtual void OnCandidateWindowUpdated() = 0;
155 // Called when IME hides the candidate window.
156 virtual void OnCandidateWindowHidden() = 0;
161 #endif // UI_BASE_IME_TEXT_INPUT_CLIENT_H_