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