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_INPUT_METHOD_H_
6 #define UI_BASE_IME_INPUT_METHOD_H_
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"
18 class InputMethodDelegate
;
19 } // namespace internal
21 class InputMethodObserver
;
23 class TextInputClient
;
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.
51 typedef LRESULT NativeEventResult
;
53 typedef int32 NativeEventResult
;
56 virtual ~InputMethod() {}
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;
62 // Initializes the InputMethod object. Pass true if the system toplevel window
63 // already has keyboard focus.
64 virtual void Init(bool focused
) = 0;
66 // Called when the top-level system window gets keyboard focus.
67 virtual void OnFocus() = 0;
69 // Called when the top-level system window loses keyboard focus.
70 virtual void OnBlur() = 0;
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;
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;
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
89 virtual void DetachTextInputClient(TextInputClient
* client
) = 0;
91 // Gets the current text input client. Returns NULL when no client is set.
92 virtual TextInputClient
* GetTextInputClient() const = 0;
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;
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;
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;
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
115 virtual void CancelComposition(const TextInputClient
* client
) = 0;
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
121 // TODO(ime): Consider to take a parameter of TextInputClient.
122 virtual void OnInputLocaleChanged() = 0;
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;
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
135 virtual bool IsActive() = 0;
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;
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;
149 // Gets the text input flags of the focused text input client. Returns
150 // 0 if there is no focused client.
151 virtual int GetTextInputFlags() const = 0;
153 // Checks if the focused text input client supports inline composition.
154 virtual bool CanComposeInline() const = 0;
156 // Returns true if we know for sure that a candidate window (or IME suggest,
157 // etc.) is open. Returns false if no popup window is open or the detection
158 // of IME popups is not supported.
159 virtual bool IsCandidatePopupOpen() const = 0;
161 // Displays an on screen keyboard if enabled.
162 virtual void ShowImeIfNeeded() = 0;
164 // Management of the observer list.
165 virtual void AddObserver(InputMethodObserver
* observer
) = 0;
166 virtual void RemoveObserver(InputMethodObserver
* observer
) = 0;
171 #endif // UI_BASE_IME_INPUT_METHOD_H_