ui/views/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_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
  16 namespace ui {
  17 class KeyEvent;
  18 class TextInputClient;
  19 }  // namespace ui
  20
  21 namespace views {
  22
  23 namespace internal {
  24 class InputMethodDelegate;
  25 }  // namespace internal
  26
  27 class View;
  28 class 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.
  35 class VIEWS_EXPORT InputMethod {
  36  public:
  37
  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 true if the input method is ready to process keyboard events and
  98   // generate composition or text results. It is not necessary to notify
  99   // inactive input methods of caret bounds or text input type changes.
 100   // Note: TextInputClient::InsertChar() may be called to send input to the text
 101   // input client even if the input method is not active.
 102   virtual bool IsActive() = 0;
 103
 104   // Returns the focused text input client, or NULL if the Widget is not active,
 105   // has no focused View, or if the focused View does not support text input.
 106   virtual ui::TextInputClient* GetTextInputClient() const = 0;
 107
 108   // Gets the text input type of the focused text input client. Returns
 109   // ui::TEXT_INPUT_TYPE_NONE if there is no focused text input client.
 110   virtual ui::TextInputType GetTextInputType() const = 0;
 111
 112   // Returns true if we know for sure that a candidate window (or IME suggest,
 113   // etc.) is open.  Returns false if no popup window is open or the detection
 114   // of IME popups is not supported.
 115   virtual bool IsCandidatePopupOpen() const = 0;
 116
 117   // Displays an on screen keyboard if enabled.
 118   virtual void ShowImeIfNeeded() = 0;
 119
 120   // Returns true if the input method is a mock instance used for testing.
 121   virtual bool IsMock() const = 0;
 122
 123   // TODO(suzhe): Support mouse/touch event.
 124 };
 125
 126 }  // namespace views
 127
 128 #endif  // UI_VIEWS_IME_INPUT_METHOD_H_