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