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_INPUT_METHOD_H_ 6 #define UI_BASE_IME_INPUT_METHOD_H_ 7 8 #include <string> 9 10 #include "base/basictypes.h" 11 #include "base/event_types.h" 12 #include "base/i18n/rtl.h" 13 #include "ui/base/ime/text_input_type.h" 14 #include "ui/base/keycodes/keyboard_codes.h" 15 #include "ui/base/ui_export.h" 16 17 namespace ui { 18 19 namespace internal { 20 class InputMethodDelegate; 21 } // namespace internal 22 23 class InputMethodObserver; 24 class KeyEvent; 25 class TextInputClient; 26 27 // An interface implemented by an object that encapsulates a native input method 28 // service provided by the underlying operating system, and acts as a "system 29 // wide" input method for all Chrome windows. A class that implements this 30 // interface should behave as follows: 31 // - Receives a keyboard event directly from a message dispatcher for the 32 // system through the InputMethod::DispatchKeyEvent API, and forwards it to 33 // an underlying input method for the OS. 34 // - The input method should handle the key event either of the following ways: 35 // 1) Send the original key down event to the focused window, which is e.g. 36 // a NativeWidgetAura (NWA) or a RenderWidgetHostViewAura (RWHVA), using 37 // internal::InputMethodDelegate::DispatchKeyEventPostIME API, then send 38 // a Char event using TextInputClient::InsertChar API to a text input 39 // client, which is, again, e.g. NWA or RWHVA, and then send the original 40 // key up event to the same window. 41 // 2) Send VKEY_PROCESSKEY event to the window using the DispatchKeyEvent API, 42 // then update IME status (e.g. composition text) using TextInputClient, 43 // and then send the original key up event to the window. 44 // - Keeps track of the focused TextInputClient to see which client can call 45 // APIs, OnTextInputTypeChanged, OnCaretBoundsChanged, and CancelComposition, 46 // that change the state of the input method. 47 // In Aura environment, aura::RootWindowHost creates an instance of 48 // ui::InputMethod and owns it. 49 class InputMethod { 50 public: 51 // TODO(yukawa): Move these typedef into ime_constants.h or somewhere. 52 #if defined(OS_WIN) 53 typedef LRESULT NativeEventResult; 54 #else 55 typedef int32 NativeEventResult; 56 #endif 57 58 virtual ~InputMethod() {} 59 60 // Sets the delegate used by this InputMethod instance. It should only be 61 // called by an object which manages the whole UI. 62 virtual void SetDelegate(internal::InputMethodDelegate* delegate) = 0; 63 64 // Initializes the InputMethod object. Pass true if the system toplevel window 65 // already has keyboard focus. 66 virtual void Init(bool focused) = 0; 67 68 // Called when the top-level system window gets keyboard focus. 69 virtual void OnFocus() = 0; 70 71 // Called when the top-level system window loses keyboard focus. 72 virtual void OnBlur() = 0; 73 74 // Called when the focused window receives native IME messages that are not 75 // translated into other predefined event callbacks. Currently this method is 76 // used only for IME functionalities specific to Windows. 77 // TODO(ime): Break down these messages into platform-neutral methods. 78 virtual bool OnUntranslatedIMEMessage(const base::NativeEvent& event, 79 NativeEventResult* result) = 0; 80 81 // Sets the text input client which receives text input events such as 82 // SetCompositionText(). |client| can be NULL. A gfx::NativeWindow which 83 // implementes TextInputClient interface, e.g. NWA and RWHVA, should register 84 // itself by calling the method when it is focused, and unregister itself by 85 // calling the metho with NULL when it is unfocused. 86 virtual void SetFocusedTextInputClient(TextInputClient* client) = 0; 87 88 // Gets the current text input client. Returns NULL when no client is set. 89 virtual TextInputClient* GetTextInputClient() const = 0; 90 91 // Dispatches a key event to the input method. The key event will be 92 // dispatched back to the caller via 93 // ui::InputMethodDelegate::DispatchKeyEventPostIME(), once it's processed by 94 // the input method. It should only be called by a message dispatcher. 95 // Returns true if the event was processed. 96 virtual bool DispatchKeyEvent(const base::NativeEvent& native_key_event) = 0; 97 98 // TODO(yusukes): Add DispatchFabricatedKeyEvent to support virtual keyboards. 99 // TODO(yusukes): both win and ibus override to do nothing. Is this needed? 100 // Returns true if the event was processed. 101 virtual bool DispatchFabricatedKeyEvent(const ui::KeyEvent& event) = 0; 102 103 // Called by the focused client whenever its text input type is changed. 104 // Before calling this method, the focused client must confirm or clear 105 // existing composition text and call InputMethod::CancelComposition() when 106 // necessary. Otherwise unexpected behavior may happen. This method has no 107 // effect if the client is not the focused client. 108 virtual void OnTextInputTypeChanged(const TextInputClient* client) = 0; 109 110 // Called by the focused client whenever its caret bounds is changed. 111 // This method has no effect if the client is not the focused client. 112 virtual void OnCaretBoundsChanged(const TextInputClient* client) = 0; 113 114 // Called by the focused client to ask the input method cancel the ongoing 115 // composition session. This method has no effect if the client is not the 116 // focused client. 117 virtual void CancelComposition(const TextInputClient* client) = 0; 118 119 // Called by the focused client whenever its input locale is changed. 120 // This method is currently used only on Windows. 121 // This method does not take a parameter of TextInputClient for historical 122 // reasons. 123 // TODO(ime): Consider to take a parameter of TextInputClient. 124 virtual void OnInputLocaleChanged() = 0; 125 126 // Returns the locale of current keyboard layout or input method, as a BCP-47 127 // tag, or an empty string if the input method cannot provide it. 128 virtual std::string GetInputLocale() = 0; 129 130 // Returns the text direction of current keyboard layout or input method, or 131 // base::i18n::UNKNOWN_DIRECTION if the input method cannot provide it. 132 virtual base::i18n::TextDirection GetInputTextDirection() = 0; 133 134 // Checks if the input method is active, i.e. if it's ready for processing 135 // keyboard event and generate composition or text result. 136 // If the input method is inactive, then it's not necessary to inform it the 137 // changes of caret bounds and text input type. 138 // Note: character results may still be generated and sent to the text input 139 // client by calling TextInputClient::InsertChar(), even if the input method 140 // is not active. 141 virtual bool IsActive() = 0; 142 143 // Gets the text input type of the focused text input client. Returns 144 // ui::TEXT_INPUT_TYPE_NONE if there is no focused client. 145 virtual TextInputType GetTextInputType() const = 0; 146 147 // Checks if the focused text input client supports inline composition. 148 virtual bool CanComposeInline() const = 0; 149 150 // Returns true if we know for sure that a candidate window (or IME suggest, 151 // etc.) is open. Returns false if no popup window is open or the detection 152 // of IME popups is not supported. 153 virtual bool IsCandidatePopupOpen() const = 0; 154 155 // Management of the observer list. 156 virtual void AddObserver(InputMethodObserver* observer) = 0; 157 virtual void RemoveObserver(InputMethodObserver* observer) = 0; 158 }; 159 160 } // namespace ui 161 162 #endif // UI_BASE_IME_INPUT_METHOD_H_ 163
