IME (input method editor) support for Aura, part 3 of 3: Use ui::InputMethod in ash.

ui/base/ime/input_method.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef UI_BASE_IME_INPUT_METHOD_H_
+#define UI_BASE_IME_INPUT_METHOD_H_
+#pragma once
+
+#include <string>
+
+#include "base/basictypes.h"
+#include "base/event_types.h"
+#include "base/i18n/rtl.h"
+#include "ui/base/ime/text_input_type.h"
+#include "ui/base/keycodes/keyboard_codes.h"
+#include "ui/gfx/native_widget_types.h"
+#include "ui/base/ui_export.h"
+
+namespace ui {
+
+namespace internal {
+class InputMethodDelegate;
+}  // namespace internal
+
+class TextInputClient;
+
+// An interface implemented by an object that encapsulates a native input method
+// service provided by the underlying operating system, and acts as a "system
+// wide" input method for all Chrome windows. A class that implements this
+// interface should behave as follows:
+// - Receives a keyboard event directly from a message dispatcher for the
+//   system through the InputMethod::DispatchKeyEvent API, and forwards it to
+//   an underlying input method for the OS.
+// - The input method should handle the key event either of the following ways:
+//   1) Send the original key down event to the focused window, which is e.g.
+//      a NativeWidgetAura (NWA) or a RenderWidgetHostViewAura (RWHVA), using
+//      internal::InputMethodDelegate::DispatchKeyEventPostIME API, then send
+//      a Char event using TextInputClient::InsertChar API to a text input
+//      client, which is, again, e.g. NWA or RWHVA, and then send the original
+//      key up event to the same window.
+//   2) Send VKEY_PROCESSKEY event to the window using the DispatchKeyEvent API,
+//      then update IME status (e.g. composition text) using TextInputClient,
+//      and then send the original key up event to the window.
+// - Keeps track of the active top-level gfx::NativeWindow to see which window
+//   can call APIs, OnTextInputTypeChanged, OnCaretBoundsChanged, and
+//   CancelComposition, that change the state of the input method.
+// In Aura environment, aura::DesktopHost creates an instance of ui::InputMethod
+// and owns it.
+class UI_EXPORT InputMethod {
+ public:
+  virtual ~InputMethod();
+
+  // Sets the delegate used by this InputMethod instance. It should only be
+  // called by an object which manages the whole UI (e.g. aura::DesktopHost).
+  virtual void set_delegate(internal::InputMethodDelegate* delegate) = 0;
+
+  // Sets the text input client which receives text input events such as
+  // SetCompositionText(). |client| can be NULL. A gfx::NativeWindow which
+  // implementes TextInputClient interface, e.g. NWA and RWHVA, should register
+  // itself by calling the method when it is focused, and unregister itself by
+  // calling the metho with NULL when it is unfocused.
+  virtual void set_text_input_client(TextInputClient* client) = 0;

[James Su, 2011/11/21 08:23:36]

How about rename it to SetFocusedTextInputClient() to emphasize that we are
tracing the input focus per TextInputClient basis. The actual ui::InputMethod
implementation may toggle the system input method state in this method.

In additional we may still need something similar than
views::InputMethod::OnFocus()/OnBlur() to know if the toplevel native(system)
window, where the ui::InputMethod object is attached to, is focused or not.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Gets the current text input client. Returns NULL when no client is set.
+  virtual TextInputClient* text_input_client() const = 0;

[James Su, 2011/11/21 08:23:36]

We may rename it to GetTextInputClient() as well.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Initializes the InputMethod object.
+  virtual void Init() = 0;

[James Su, 2011/11/21 08:23:36]

This method should have a parameter to tell this ui::InputMethod object which
native(system) window should be attached to. But we can't use gfx::NativeWindow,
as it's typedefed to aura::Window when USE_AURA is defined, which is not what we
want.

Perhaps we may introduce a new header file similar than base/event_types.h for
this purpose.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Dispatches a key event to the input method. The key event will be
+  // dispatched back to the caller via
+  // ui::InputMethodDelegate::DispatchKeyEventPostIME(), once it's processed by
+  // the input method. It should only be called by a message dispatcher.
+  virtual void DispatchKeyEvent(gfx::NativeEvent native_key_event) = 0;

[James Su, 2011/11/21 08:23:36]

It's better to use the real system event type (base/event_types.h) to avoid
depending on aura code.
And it's better to use const reference here.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Called by the focused |window| whenever its text input type is changed.
+  // Before calling this method, the focused |window| must confirm or clear
+  // existing composition text and call InputMethod::CancelComposition() when
+  // necessary. Otherwise unexpected behavior may happen. This method has no
+  // effect if the |window| is not inside the active window.
+  virtual void OnTextInputTypeChanged(gfx::NativeWindow window) = 0;

[James Su, 2011/11/21 08:23:36]

Using |window| as parameter makes no sense here. We can remove the parameter,
indicating it's change of the currently focused TextInputClient. Or maybe we can
use ui::TextInputClient* focused_client instead, so that we can make sure it's
called by the correct TextInputClient object.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Called by the focused |window| whenever its caret bounds is changed.
+  // This method has no effect if the |window| is not inside the active window.
+  virtual void OnCaretBoundsChanged(gfx::NativeWindow window) = 0;

[James Su, 2011/11/21 08:23:36]

Same as above method.
The only problem is how to translate the caret bounds to desired coordinates we
want(usually it can be the native window we are attached to, then we can
translate it to the whole screen when necessary).

One possible solution is to let the TextInputClient object's GetCaretBounds()
method return the translated caret bounds for us. But then the definition of
TextInputClient::GetCaretBounds method may be different for views::InputMethod
and ui::InputMethod, though I don't think it's a big deal.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Called by the focused |window| to ask the input method cancel the ongoing
+  // composition session. This method has no effect if the |window| is not
+  // inside the active window.
+  virtual void CancelComposition(gfx::NativeWindow window) = 0;

[James Su, 2011/11/21 08:23:36]

ditto.

[Yusuke Sato, 2011/11/22 11:09:30]

Done.

+
+  // Returns the locale of current keyboard layout or input method, as a BCP-47
+  // tag, or an empty string if the input method cannot provide it.
+  virtual std::string GetInputLocale() = 0;
+
+  // Returns the text direction of current keyboard layout or input method, or
+  // base::i18n::UNKNOWN_DIRECTION if the input method cannot provide it.
+  virtual base::i18n::TextDirection GetInputTextDirection() = 0;
+
+  // Checks if the input method is active, i.e. if it's ready for processing
+  // keyboard event and generate composition or text result.
+  // If the input method is inactive, then it's not necessary to inform it the
+  // changes of caret bounds and text input type.
+  // Note: character results may still be generated and sent to the text input
+  // client by calling TextInputClient::InsertChar(), even if the input method
+  // is not active.
+  virtual bool IsActive() = 0;
+
+  // Gets the text input type of the focused text input client. Returns
+  // ui::TEXT_INPUT_TYPE_NONE if there is no focused client.
+  virtual TextInputType GetTextInputType() const = 0;
+
+  // We emulate Windows' WM_KEYDOWN and WM_CHAR messages. WM_CHAR events are
+  // only generated for certain keys; see
+  // http://msdn.microsoft.com/en-us/library/windows/desktop/ms646268.aspx.
+  static bool ShouldSendCharEventForKeyboardCode(KeyboardCode keycode);

[James Su, 2011/11/21 08:23:36]

I'm wondering why we need this method. On Linux, if a key press event
corresponds to a valid character, then we always need to send the character.

btw, can you help rename ui::DefaultSymbolFromXEvent() defined in
ui/base/keycodes/keyboard_code_conversion_x.h to something more reasonable? e.g.
ui::GetCharacterFromXEvent().

[Yusuke Sato, 2011/11/22 11:09:30]

Removed.
 
Added TODO.

+};
+
+}  // namespace ui
+
+#endif  // UI_BASE_IME_INPUT_METHOD_H_