views/ime/input_method.h

   1 // Copyright (c) 2011 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 VIEWS_IME_INPUT_METHOD_H_
   6 #define VIEWS_IME_INPUT_METHOD_H_
   7 #pragma once
   8
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/i18n/rtl.h"
  13 #include "ui/base/ime/text_input_type.h"
  14 #include "views/views_export.h"
  15
  16 namespace views {
  17
  18 namespace internal {
  19 class InputMethodDelegate;
  20 }  // namespace internal
  21
  22 class KeyEvent;
  23 class TextInputClient;
  24 class View;
  25 class Widget;
  26
  27 // An interface implemented by an object that encapsulates a native input method
  28 // service provided by the underlying operation system.
  29 // Because on most systems, the system input method service is bound to
  30 // individual native window. On Windows, its HWND, on Linux/Gtk, its GdkWindow.
  31 // And in Views control system, only the top-level NativeWidget has a native
  32 // window that can get keyboard focus. So this API is designed to be bound to
  33 // the top-level NativeWidget.
  34 class VIEWS_EXPORT InputMethod {
  35  public:
  36   virtual ~InputMethod() {}
  37
  38   // Sets the delegate used by this InputMethod instance. It should only be
  39   // called by the internal NativeWidget or testing code.
  40   virtual void set_delegate(internal::InputMethodDelegate* delegate) = 0;
  41
  42   // Initialize the InputMethod object and attach it to the given |widget|.
  43   // The |widget| must already be initialized.
  44   virtual void Init(Widget* widget) = 0;
  45
  46   // Called when the top-level NativeWidget gets keyboard focus. It should only
  47   // be called by the top-level NativeWidget which owns this InputMethod
  48   // instance.
  49   virtual void OnFocus() = 0;
  50
  51   // Called when the top-level NativeWidget loses keyboard focus. It should only
  52   // be called by the top-level NativeWidget which owns this InputMethod
  53   // instance.
  54   virtual void OnBlur() = 0;
  55
  56   // Dispatch a key event to the input method. The key event will be dispatched
  57   // back to the caller via InputMethodDelegate::DispatchKeyEventPostIME(), once
  58   // it's processed by the input method. It should only be called by the
  59   // top-level NativeWidget which owns this InputMethod instance, or other
  60   // related platform dependent code, such as a message dispatcher.
  61   virtual void DispatchKeyEvent(const KeyEvent& key) = 0;
  62
  63   // Called by the focused |view| whenever its text input type is changed.
  64   // Before calling this method, the focused |view| must confirm or clear
  65   // existing composition text and call InputMethod::CancelComposition() when
  66   // necessary. Otherwise unexpected behavior may happen. This method has no
  67   // effect if the |view| is not focused.
  68   virtual void OnTextInputTypeChanged(View* view) = 0;
  69
  70   // Called by the focused |view| whenever its caret bounds is changed.
  71   // This method has no effect if the |view| is not focused.
  72   virtual void OnCaretBoundsChanged(View* view) = 0;
  73
  74   // Called by the focused |view| to ask the input method cancel the ongoing
  75   // composition session. This method has no effect if the |view| is not
  76   // focused.
  77   virtual void CancelComposition(View* view) = 0;
  78
  79   // Returns the locale of current keyboard layout or input method, as a BCP-47
  80   // tag, or an empty string if the input method cannot provide it.
  81   virtual std::string GetInputLocale() = 0;
  82
  83   // Returns the text direction of current keyboard layout or input method, or
  84   // base::i18n::UNKNOWN_DIRECTION if the input method cannot provide it.
  85   virtual base::i18n::TextDirection GetInputTextDirection() = 0;
  86
  87   // Checks if the input method is active, i.e. if it's ready for processing
  88   // keyboard event and generate composition or text result.
  89   // If the input method is inactive, then it's not necessary to inform it the
  90   // changes of caret bounds and text input type.
  91   // Note: character results may still be generated and sent to the text input
  92   // client by calling TextInputClient::InsertChar(), even if the input method
  93   // is not active.
  94   virtual bool IsActive() = 0;
  95
  96   // Gets the focused text input client. Returns NULL if the Widget is not
  97   // focused, or there is no focused View or the focused View doesn't support
  98   // text input.
  99   virtual TextInputClient* GetTextInputClient() const = 0;
 100
 101   // Gets the text input type of the focused text input client. Returns
 102   // ui::TEXT_INPUT_TYPE_NONE if there is no focused text input client.
 103   virtual ui::TextInputType GetTextInputType() const = 0;
 104
 105   // Returns true if the input method is a mock and not real.
 106   virtual bool IsMock() const = 0;
 107
 108   // TODO(suzhe): Support mouse/touch event.
 109 };
 110
 111 }  // namespace views
 112
 113 #endif  // VIEWS_IME_INPUT_METHOD_H_