ui/base/ime/text_input_client.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_BASE_IME_TEXT_INPUT_CLIENT_H_
   6 #define UI_BASE_IME_TEXT_INPUT_CLIENT_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/i18n/rtl.h"
  10 #include "base/strings/string16.h"
  11 #include "ui/base/ime/composition_text.h"
  12 #include "ui/base/ime/text_input_mode.h"
  13 #include "ui/base/ime/text_input_type.h"
  14 #include "ui/base/ime/ui_base_ime_export.h"
  15 #include "ui/gfx/native_widget_types.h"
  16 #include "ui/gfx/range/range.h"
  17
  18 namespace gfx {
  19 class Rect;
  20 }
  21
  22 namespace ui {
  23
  24 // An interface implemented by a View that needs text input support.
  25 class UI_BASE_IME_EXPORT TextInputClient {
  26  public:
  27   virtual ~TextInputClient();
  28
  29   // Input method result -------------------------------------------------------
  30
  31   // Sets composition text and attributes. If there is composition text already,
  32   // it'll be replaced by the new one. Otherwise, current selection will be
  33   // replaced. If there is no selection, the composition text will be inserted
  34   // at the insertion point.
  35   virtual void SetCompositionText(const ui::CompositionText& composition) = 0;
  36
  37   // Converts current composition text into final content.
  38   virtual void ConfirmCompositionText() = 0;
  39
  40   // Removes current composition text.
  41   virtual void ClearCompositionText() = 0;
  42
  43   // Inserts a given text at the insertion point. Current composition text or
  44   // selection will be removed. This method should never be called when the
  45   // current text input type is TEXT_INPUT_TYPE_NONE.
  46   virtual void InsertText(const base::string16& text) = 0;
  47
  48   // Inserts a single char at the insertion point. Unlike above InsertText()
  49   // method, this method has an extra |flags| parameter indicating the modifier
  50   // key states when the character is generated. This method should only be
  51   // called when a key press is not handled by the input method but still
  52   // generates a character (eg. by the keyboard driver). In another word, the
  53   // preceding key press event should not be a VKEY_PROCESSKEY.
  54   // This method will be called whenever a char is generated by the keyboard,
  55   // even if the current text input type is TEXT_INPUT_TYPE_NONE.
  56   virtual void InsertChar(base::char16 ch, int flags) = 0;
  57
  58   // Input context information -------------------------------------------------
  59
  60   // Returns native window to which input context is bound.
  61   virtual gfx::NativeWindow GetAttachedWindow() const = 0;
  62
  63   // Returns current text input type. It could be changed and even becomes
  64   // TEXT_INPUT_TYPE_NONE at runtime.
  65   virtual ui::TextInputType GetTextInputType() const = 0;
  66
  67   // Returns current text input mode. It could be changed and even becomes
  68   // TEXT_INPUT_MODE_DEFAULT at runtime.
  69   virtual ui::TextInputMode GetTextInputMode() const = 0;
  70
  71   // Returns the current text input flags, which is a bit map of
  72   // WebTextInputType defined in blink. This is valid only for web input fileds;
  73   // it will return TEXT_INPUT_FLAG_NONE for native input fields.
  74   virtual int GetTextInputFlags() const = 0;
  75
  76   // Returns if the client supports inline composition currently.
  77   virtual bool CanComposeInline() const = 0;
  78
  79   // Returns current caret (insertion point) bounds in the universal screen
  80   // coordinates. If there is selection, then the selection bounds will be
  81   // returned.
  82   // Note: On Windows, the returned value is supposed to be DIP (Density
  83   // Independent Pixel).
  84   // TODO(ime): Have a clear spec whether the returned value is DIP or not.
  85   // http://crbug.com/360334
  86   virtual gfx::Rect GetCaretBounds() const = 0;
  87
  88   // Retrieves the composition character boundary rectangle in the universal
  89   // screen coordinates. The |index| is zero-based index of character position
  90   // in composition text.
  91   // Returns false if there is no composition text or |index| is out of range.
  92   // The |rect| is not touched in the case of failure.
  93   // Note: On Windows, the returned value is supposed to be DIP
  94   // (Density Independent Pixel).
  95   // TODO(ime): Have a clear spec whether the returned value is DIP or not.
  96   // http://crbug.com/360334
  97   virtual bool GetCompositionCharacterBounds(uint32 index,
  98                                              gfx::Rect* rect) const = 0;
  99
 100   // Returns true if there is composition text.
 101   virtual bool HasCompositionText() const = 0;
 102
 103   // Document content operations ----------------------------------------------
 104
 105   // Retrieves the UTF-16 based character range containing accessibled text in
 106   // the View. It must cover the composition and selection range.
 107   // Returns false if the information cannot be retrieved right now.
 108   virtual bool GetTextRange(gfx::Range* range) const = 0;
 109
 110   // Retrieves the UTF-16 based character range of current composition text.
 111   // Returns false if the information cannot be retrieved right now.
 112   virtual bool GetCompositionTextRange(gfx::Range* range) const = 0;
 113
 114   // Retrieves the UTF-16 based character range of current selection.
 115   // Returns false if the information cannot be retrieved right now.
 116   virtual bool GetSelectionRange(gfx::Range* range) const = 0;
 117
 118   // Selects the given UTF-16 based character range. Current composition text
 119   // will be confirmed before selecting the range.
 120   // Returns false if the operation is not supported.
 121   virtual bool SetSelectionRange(const gfx::Range& range) = 0;
 122
 123   // Deletes contents in the given UTF-16 based character range. Current
 124   // composition text will be confirmed before deleting the range.
 125   // The input caret will be moved to the place where the range gets deleted.
 126   // ExtendSelectionAndDelete should be used instead as far as you are deleting
 127   // characters around current caret. This function with the range based on
 128   // GetSelectionRange has a race condition due to asynchronous IPCs between
 129   // browser and renderer.
 130   // Returns false if the operation is not supported.
 131   virtual bool DeleteRange(const gfx::Range& range) = 0;
 132
 133   // Retrieves the text content in a given UTF-16 based character range.
 134   // The result will be stored into |*text|.
 135   // Returns false if the operation is not supported or the specified range
 136   // is out of the text range returned by GetTextRange().
 137   virtual bool GetTextFromRange(const gfx::Range& range,
 138                                 base::string16* text) const = 0;
 139
 140   // Miscellaneous ------------------------------------------------------------
 141
 142   // Called whenever current keyboard layout or input method is changed,
 143   // especially the change of input locale and text direction.
 144   virtual void OnInputMethodChanged() = 0;
 145
 146   // Called whenever the user requests to change the text direction and layout
 147   // alignment of the current text box. It's for supporting ctrl-shift on
 148   // Windows.
 149   // Returns false if the operation is not supported.
 150   virtual bool ChangeTextDirectionAndLayoutAlignment(
 151       base::i18n::TextDirection direction) = 0;
 152
 153   // Deletes the current selection plus the specified number of characters
 154   // before and after the selection or caret. This function should be used
 155   // instead of calling DeleteRange with GetSelectionRange, because
 156   // GetSelectionRange may not be the latest value due to asynchronous of IPC
 157   // between browser and renderer.
 158   virtual void ExtendSelectionAndDelete(size_t before, size_t after) = 0;
 159
 160   // Ensure the caret is within |rect|.  |rect| is in screen coordinates and
 161   // may extend beyond the bounds of this TextInputClient.
 162   // Note: On Windows, the returned value is supposed to be DIP (Density
 163   // Independent Pixel).
 164   // TODO(ime): Have a clear spec whether the returned value is DIP or not.
 165   // http://crbug.com/360334
 166   virtual void EnsureCaretInRect(const gfx::Rect& rect) = 0;
 167
 168   // Called when IME shows a candidate window.
 169   virtual void OnCandidateWindowShown() = 0;
 170   // Called when IME updates any appearance of the current candidate window.
 171   virtual void OnCandidateWindowUpdated() = 0;
 172   // Called when IME hides the candidate window.
 173   virtual void OnCandidateWindowHidden() = 0;
 174
 175   // Returns true if |command_id| is currently allowed to be executed.
 176   virtual bool IsEditCommandEnabled(int command_id) = 0;
 177
 178   // Execute the command specified by |command_id| on the next key event.
 179   // This allows a TextInputClient to be informed of a platform-independent edit
 180   // command that has been derived from the key event currently being dispatched
 181   // (but not yet sent to the TextInputClient). The edit command will take into
 182   // account any OS-specific, or user-specified, keybindings that may be set up.
 183   virtual void SetEditCommandForNextKeyEvent(int command_id) = 0;
 184 };
 185
 186 }  // namespace ui
 187
 188 #endif  // UI_BASE_IME_TEXT_INPUT_CLIENT_H_