Add GetCharacter() and GetUnmodifiedCharacter() methods to views::Event.

views/events/event.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 VIEWS_EVENTS_EVENT_H_
 #define VIEWS_EVENTS_EVENT_H_
 #pragma once
 
 #include "base/basictypes.h"
 #include "base/time.h"
@@ skipping 271 matching lines @@
 //
 ////////////////////////////////////////////////////////////////////////////////
 class KeyEvent : public Event {
  public:
   explicit KeyEvent(NativeEvent native_event);
   KeyEvent(NativeEvent2 native_event_2, FromNativeEvent2 from_native);
 
   // Creates a new KeyEvent synthetically (i.e. not in response to an input
   // event from the host environment). This is typically only used in testing as
   // some metadata obtainable from the underlying native event is not present.
-  // TODO(beng): see if we can kill this.
+  // It's also used by input methods to fabricate keyboard events.
   KeyEvent(ui::EventType type,
            ui::KeyboardCode key_code,
            int event_flags);
 
   ui::KeyboardCode key_code() const { return key_code_; }
 
+  // Gets the character generated by this key event. It only supports Unicode
+  // BMP characters.
+  uint16 GetCharacter() const;
+
+  // Gets the character generated by this key event ignoring concurrently-held
+  // modifiers (except shift).
+  uint16 GetUnmodifiedCharacter() const;
+
  private:
+  // A helper function to get the character generated by a key event in a
+  // platform independent way. It supports control characters as well.
+  // It assumes a US keyboard layout is used, so it may only be used when there
+  // is no native event or no better way to get the character.
+  // For example, if a virtual keyboard implementation can only generate key
+  // events with key_code and flags information, then there is no way for us to
+  // determine the actual character that should be generate by the key. Because
+  // a key_code only represents a physical key on the keyboard, it has nothing
+  // to do with the actual character printed on that key. In such case, the only
+  // thing we can do is to assume that we are using a US keyboard and get the
+  // character according to US keyboard layout definition.
+  // If a virtual keyboard implementation wants to support other keyboard
+  // layouts, that may generate different text for a certain key than on a US
+  // keyboard, a special native event object should be introduced to carry extra
+  // information to help determine the correct character.
+  // Take XKeyEvent as an example, it contains not only keycode and modifier
+  // flags but also group and other extra XKB information to help determine the
+  // correct character. That's why we can use XLookupString() function to get
+  // the correct text generated by a X key event (See how is GetCharacter()
+  // implemented in event_x.cc).
+  static uint16 GetCharacterFromKeyCode(ui::KeyboardCode key_code, int flags);
+
   ui::KeyboardCode key_code_;
 
   DISALLOW_COPY_AND_ASSIGN(KeyEvent);
 };
 
 ////////////////////////////////////////////////////////////////////////////////
 //
 // MouseWheelEvent class
 //
 // A MouseWheelEvent is used to propagate mouse wheel user events.
@@ skipping 52 matching lines @@
 
   // Bitmask of supported ui::DragDropTypes::DragOperation by the source.
   int source_operations_;
 
   DISALLOW_COPY_AND_ASSIGN(DropTargetEvent);
 };
 
 }  // namespace views
 
 #endif  // VIEWS_EVENTS_EVENT_H_