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