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_VIEWS_IME_INPUT_METHOD_H_
6#define UI_VIEWS_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/views/views_export.h"
15
16namespace ui {
17class KeyEvent;
18class TextInputClient;
19}  // namespace ui
20
21namespace views {
22
23namespace internal {
24class InputMethodDelegate;
25}  // namespace internal
26
27class View;
28class Widget;
29
30// An interface implemented by an object that encapsulates a native input method
31// service provided by the underlying operation system. Input method services
32// are typically bound to individual native windows (HWND, aura::Window, etc.).
33// In Views, only the top-level Widgets get keyboard focus, so this API is
34// designed to be bound to top-level Widgets.
35class VIEWS_EXPORT InputMethod {
36 public:
37  // TODO(yukawa): Move these typedef into ime_constants.h or somewhere.
38#if defined(OS_WIN)
39  typedef LRESULT NativeEventResult;
40#else
41  typedef int32 NativeEventResult;
42#endif
43
44  virtual ~InputMethod() {}
45
46  // Sets the delegate used by this InputMethod instance.
47  // This should only be called by the owner Widget or testing code.
48  virtual void SetDelegate(internal::InputMethodDelegate* delegate) = 0;
49
50  // Initialize the InputMethod object and attach it to the given |widget|.
51  // The |widget| must already be initialized.
52  virtual void Init(Widget* widget) = 0;
53
54  // Called when the top-level Widget gains or loses keyboard focus.
55  // These should only be called by the Widget that owns this InputMethod.
56  virtual void OnFocus() = 0;
57  virtual void OnBlur() = 0;
58
59  // Called when the focused window receives native IME messages that are not
60  // translated into other predefined event callbacks. Currently this method is
61  // used only for IME functionalities specific to Windows.
62  // TODO(ime): Break down these messages into platform-neutral methods.
63  virtual bool OnUntranslatedIMEMessage(const base::NativeEvent& event,
64                                        NativeEventResult* result) = 0;
65
66  // Dispatch a key event to the input method. The key event will be dispatched
67  // back to the caller via InputMethodDelegate::DispatchKeyEventPostIME(), once
68  // it has been processed by the input method. It should only be called by the
69  // top-level Widget that owns this InputMethod instance, or other related
70  // platform-specific code, such as a message dispatcher.
71  virtual void DispatchKeyEvent(const ui::KeyEvent& key) = 0;
72
73  // Called by the focused |view| whenever its text input type has changed.
74  // Before calling this method, the focused |view| must confirm or clear any
75  // existing composition text and call InputMethod::CancelComposition() when
76  // necessary. This method has no effect if |view| is not focused.
77  virtual void OnTextInputTypeChanged(View* view) = 0;
78
79  // Called by the focused |view| whenever its caret bounds have changed.
80  // This method has no effect if |view| is not focused.
81  virtual void OnCaretBoundsChanged(View* view) = 0;
82
83  // Called by the focused |view| to cancel the ongoing composition session.
84  // This method has no effect if |view| is not focused.
85  virtual void CancelComposition(View* view) = 0;
86
87  // Called by the focused client whenever its input locale is changed.
88  // This method is currently used only on Windows.
89  // This method does not take a parameter of View for historical reasons.
90  // TODO(ime): Consider to take a parameter of View.
91  virtual void OnInputLocaleChanged() = 0;
92
93  // Returns the locale of current keyboard layout or input method, as a BCP-47
94  // tag, or an empty string if the input method cannot provide it.
95  virtual std::string GetInputLocale() = 0;
96
97  // Returns the text direction of current keyboard layout or input method, or
98  // base::i18n::UNKNOWN_DIRECTION if the input method cannot provide it.
99  virtual base::i18n::TextDirection GetInputTextDirection() = 0;
100
101  // Returns true if the input method is ready to process keyboard events and
102  // generate composition or text results. It is not necessary to notify
103  // inactive input methods of caret bounds or text input type changes.
104  // Note: TextInputClient::InsertChar() may be called to send input to the text
105  // input client even if the input method is not active.
106  virtual bool IsActive() = 0;
107
108  // Returns the focused text input client, or NULL if the Widget is not active,
109  // has no focused View, or if the focused View does not support text input.
110  virtual ui::TextInputClient* GetTextInputClient() const = 0;
111
112  // Gets the text input type of the focused text input client. Returns
113  // ui::TEXT_INPUT_TYPE_NONE if there is no focused text input client.
114  virtual ui::TextInputType GetTextInputType() const = 0;
115
116  // Returns true if we know for sure that a candidate window (or IME suggest,
117  // etc.) is open.  Returns false if no popup window is open or the detection
118  // of IME popups is not supported.
119  virtual bool IsCandidatePopupOpen() const = 0;
120
121  // Returns true if the input method is a mock instance used for testing.
122  virtual bool IsMock() const = 0;
123
124  // TODO(suzhe): Support mouse/touch event.
125};
126
127}  // namespace views
128
129#endif  // UI_VIEWS_IME_INPUT_METHOD_H_
130