New InputMethod api for Views.

views/ime/input_method.h

Index: views/ime/input_method.h
diff --git a/views/ime/input_method.h b/views/ime/input_method.h
new file mode 100644
index 0000000000000000000000000000000000000000..4ce052a4d534867d8e9182e986e06d74bfc49b3d
--- /dev/null
+++ b/views/ime/input_method.h
@@ -0,0 +1,106 @@
+// 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 VIEWS_IME_INPUT_METHOD_H_
+#define VIEWS_IME_INPUT_METHOD_H_
+#pragma once
+
+#include <string>
+
+#include "base/basictypes.h"
+#include "base/i18n/rtl.h"
+#include "ui/base/ime/text_input_type.h"
+
+namespace views {
+
+namespace internal {
+class InputMethodDelegate;
+}  // namespace internal
+
+class KeyEvent;
+class TextInputClient;
+class View;
+class Widget;
+
+// An interface implemented by an object that encapsulates a native input method
+// service provided by the underlying operation system.
+// Because on most systems, the system input method service is bound to
+// individual native window. On Windows, its HWND, on Linux/Gtk, its GdkWindow.
+// And in Views control system, only the top-level NativeWidget has a native
+// window that can get keyboard focus. So this API is designed to be bound to
+// the top-level NativeWidget.
+class InputMethod {
+ public:
+  virtual ~InputMethod() {}
+
+  // Sets the delegate used by this InputMethod instance. It should only be
+  // called by the internal NativeWidget or testing code.
+  virtual void set_delegate(internal::InputMethodDelegate* delegate) = 0;
+
+  // Initialize the InputMethod object and attach it to the given |widget|.
+  // The |widget| must already be initialized.
+  virtual void Init(Widget* widget) = 0;
+
+  // Called when the top-level NativeWidget gets keyboard focus. It should only
+  // be called by the top-level NativeWidget which owns this InputMethod
+  // instance.
+  virtual void OnFocusIn() = 0;

[Peng, 2011/03/30 18:41:35]

Maybe rename to OnFocus() and OnBlur(). I changed them to OnFocus() and OnBlur()
in my origin design by someone's review comments.

[James Su, 2011/03/30 19:44:22]

Done.

+
+  // Called when the top-level NativeWidget loses keyboard focus. It should only
+  // be called by the top-level NativeWidget which owns this InputMethod
+  // instance.
+  virtual void OnFocusOut() = 0;

[Peng, 2011/03/30 18:41:35]

I think it leaks some functions for tracing focus of input client. I think that
is necessary for some InputMethod implementations to get notification when input
client is changed.

for example:

virtual void OnInputClientFocusIn(TextInputClient *client) and virtual void
OnInputClientFocusOut(TextInputClient *client);
or
virtual void SetInputClient(TextInputClient *client)

[James Su, 2011/03/30 19:44:22]

TextInputClient and View are 1:1 mapping, so they share the same focus state, so
we don't need another set of methods for TextInputClient's focus state.

[Peng, 2011/03/30 21:32:37]

IC. The functions is for tracing view too. I did not find any virtual functions
for geting notify when focused view (or TextInputClient) is changed.

On 2011/03/30 19:44:22, James Su wrote:

[James Su, 2011/03/30 21:44:00]

That's the purpose of FocusChangeListener provided by FocusManager.

[Peng, 2011/03/30 23:56:33]

I think that is not convenient. I don't think it is good idea to let InputMethod
implementation to do it by self. Especially InputMethodBase has similar code,
but it can not be used by Child classes.

I think widget should know changes of focus and it also own an instance of
InputMethod . And let widget call InputMethod::OnInputClientFocus{In,Out}, it
could be simpler.

On 2011/03/30 21:44:00, James Su wrote:

[James Su, 2011/03/31 00:08:08]

No. Otherwise why we need FocusChangeListener at all? Widget won't know the
focus change event without implementing FocusChangeListener and hooking into
FocusManager.
This is the only way for monitoring focus change.

+
+  // Dispatch a key event to the input method. The key event will be dispatched
+  // back to the caller via InputMethodDelegate::DispatchKeyEventPostIME(), once
+  // it's processed by the input method. It should only be called by the
+  // top-level NativeWidget which owns this InputMethod instance, or other
+  // related platform dependent code, such as a message dispatcher.
+  virtual void DispatchKeyEvent(const KeyEvent& key) = 0;
+
+  // Called by the focused |view| whenever its text input type is changed.
+  // Before calling this method, the focused |view| must confirm or clear
+  // existing composition text and call InputMethod::CancelComposition() when
+  // necessary. Otherwise unexpected behavior may happen.
+  virtual void OnTextInputTypeChanged(View* view) = 0;

[Peng, 2011/03/30 18:41:35]

You defined TextInputClient in the design. It should be used for communicating
with InputMethod. So maybe you should replace View* to TextInputClient * here?
And for other functions.

[James Su, 2011/03/30 19:44:22]

View* is used here intentionally, because we allow a View to return NULL
TextInputClient* to indicate that it doesn't support text input at all. Note
that NULL TextInputClient* and ui::TEXT_INPUT_TYPE_NONE is different, a non-NULL
TextInputClient* will always receive character events through InsertChar()
regardless of its text input type.

[Peng, 2011/03/30 21:32:37]

It is OK. But this design is weird.

On 2011/03/30 19:44:22, James Su wrote:

[James Su, 2011/03/30 21:44:00]

It's pretty normal. Think in this way: the InputMethod object provide text input
service to View objects through (optional)TextInputClient interface. So the
major bodies in this relationship are InputMethod and View.

+
+  // Called by the focused |view| whenever its caret bounds is changed.
+  virtual void OnCaretBoundsChanged(View* view) = 0;
+
+  // Called by the focused |view| to ask the input method cancel the ongoing
+  // composition session.
+  virtual void CancelComposition(View* view) = 0;
+
+  // 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 focused text input client. Returns NULL if the Widget is not
+  // focused, or there is no focused View or the focused View doesn't support
+  // text input.
+  virtual TextInputClient* GetTextInputClient() const = 0;
+
+  // Gets the text input type of the focused text input client. Returns
+  // ui::TEXT_INPUT_TYPE_NONE if there is no focused text input client.
+  virtual ui::TextInputType GetTextInputType() const = 0;
+
+  // TODO(suzhe): Support mouse/touch event.
+};
+
+}  // namespace views
+
+#endif  // VIEWS_IME_INPUT_METHOD_H_