ui/base/ime/input_method.h

   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   // Called when the top-level system window gets keyboard focus.
  63   virtual void OnFocus() = 0;
  64
  65   // Called when the top-level system window loses keyboard focus.
  66   virtual void OnBlur() = 0;
  67
  68   // Called when the focused window receives native IME messages that are not
  69   // translated into other predefined event callbacks. Currently this method is
  70   // used only for IME functionalities specific to Windows.
  71   // TODO(ime): Break down these messages into platform-neutral methods.
  72   virtual bool OnUntranslatedIMEMessage(const base::NativeEvent& event,
  73                                         NativeEventResult* result) = 0;
  74
  75   // Sets the text input client which receives text input events such as
  76   // SetCompositionText(). |client| can be NULL. A gfx::NativeWindow which
  77   // implementes TextInputClient interface, e.g. NWA and RWHVA, should register
  78   // itself by calling the method when it is focused, and unregister itself by
  79   // calling the method with NULL when it is unfocused.
  80   virtual void SetFocusedTextInputClient(TextInputClient* client) = 0;
  81
  82   // Detaches and forgets the |client| regardless of whether it has the focus or
  83   // not.  This method is meant to be called when the |client| is going to be
  84   // destroyed.
  85   virtual void DetachTextInputClient(TextInputClient* client) = 0;
  86
  87   // Gets the current text input client. Returns NULL when no client is set.
  88   virtual TextInputClient* GetTextInputClient() const = 0;
  89
  90   // Dispatches a key event to the input method. The key event will be
  91   // dispatched back to the caller via
  92   // ui::InputMethodDelegate::DispatchKeyEventPostIME(), once it's processed by
  93   // the input method. It should only be called by a message dispatcher.
  94   // Returns true if the event was processed.
  95   virtual bool DispatchKeyEvent(const ui::KeyEvent& event) = 0;
  96
  97   // Called by the focused client whenever its text input type is changed.
  98   // Before calling this method, the focused client must confirm or clear
  99   // existing composition text and call InputMethod::CancelComposition() when
 100   // necessary. Otherwise unexpected behavior may happen. This method has no
 101   // effect if the client is not the focused client.
 102   virtual void OnTextInputTypeChanged(const TextInputClient* client) = 0;
 103
 104   // Called by the focused client whenever its caret bounds is changed.
 105   // This method has no effect if the client is not the focused client.
 106   virtual void OnCaretBoundsChanged(const TextInputClient* client) = 0;
 107
 108   // Called by the focused client to ask the input method cancel the ongoing
 109   // composition session. This method has no effect if the client is not the
 110   // focused client.
 111   virtual void CancelComposition(const TextInputClient* client) = 0;
 112
 113   // Called by the focused client whenever its input locale is changed.
 114   // This method is currently used only on Windows.
 115   // This method does not take a parameter of TextInputClient for historical
 116   // reasons.
 117   // TODO(ime): Consider to take a parameter of TextInputClient.
 118   virtual void OnInputLocaleChanged() = 0;
 119
 120   // Returns the locale of current keyboard layout or input method, as a BCP-47
 121   // tag, or an empty string if the input method cannot provide it.
 122   virtual std::string GetInputLocale() = 0;
 123
 124   // TODO(yoichio): Following 3 methods(GetTextInputType, GetTextInputMode and
 125   // CanComposeInline) calls client's same method and returns its value. It is
 126   // not InputMethod itself's infomation. So rename these to
 127   // GetClientTextInputType and so on.
 128   // Gets the text input type of the focused text input client. Returns
 129   // ui::TEXT_INPUT_TYPE_NONE if there is no focused client.
 130   virtual TextInputType GetTextInputType() const = 0;
 131
 132   // Gets the text input mode of the focused text input client. Returns
 133   // ui::TEXT_INPUT_TYPE_DEFAULT if there is no focused client.
 134   virtual TextInputMode GetTextInputMode() const = 0;
 135
 136   // Gets the text input flags of the focused text input client. Returns
 137   // 0 if there is no focused client.
 138   virtual int GetTextInputFlags() const = 0;
 139
 140   // Checks if the focused text input client supports inline composition.
 141   virtual bool CanComposeInline() const = 0;
 142
 143   // Returns true if we know for sure that a candidate window (or IME suggest,
 144   // etc.) is open.  Returns false if no popup window is open or the detection
 145   // of IME popups is not supported.
 146   virtual bool IsCandidatePopupOpen() const = 0;
 147
 148   // Displays an on screen keyboard if enabled.
 149   virtual void ShowImeIfNeeded() = 0;
 150
 151   // Management of the observer list.
 152   virtual void AddObserver(InputMethodObserver* observer) = 0;
 153   virtual void RemoveObserver(InputMethodObserver* observer) = 0;
 154 };
 155
 156 }  // namespace ui
 157
 158 #endif  // UI_BASE_IME_INPUT_METHOD_H_