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 18 namespace gfx { 19 class Rect; 20 } 21 22 namespace ui { 23 24 // An interface implemented by a View that needs text input support. 25 class 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