Standardize IME callbacks for off-screen rendering (issue #1675)

include/capi/cef_browser_capi.h

@@ -618,24 +618,62 @@ typedef struct _cef_browser_host_t {
       struct _cef_browser_host_t* self, int frame_rate);
 
   ///
-  // Get the NSTextInputContext implementation for enabling IME on Mac when
-  // window rendering is disabled.
+  // Begins a new composition or updates the existing composition. Blink has a
+  // special node (a composition node) that allows the input function to change
+  // text without affecting other DOM nodes. |text| is the optional text that
+  // will be inserted into the composition node. |underlines| is an optional set
+  // of ranges that will be underlined in the resulting text.
+  // |replacement_range| is an optional range of the existing text that will be
+  // replaced. |selection_range| is an optional range of the resulting text that
+  // will be selected after insertion or replacement. The |replacement_range|
+  // value is only used on OS X.
+  //
+  // This function may be called multiple times as the composition changes. When
+  // the client is done making changes the composition should either be canceled
+  // or completed. To cancel the composition call ImeCancelComposition. To
+  // complete the composition call either ImeCommitText or
+  // ImeFinishComposingText. Completion is usually signaled when:
+  //   A. The client receives a WM_IME_COMPOSITION message with a GCS_RESULTSTR
+  //      flag (on Windows), or;
+  //   B. The client receives a "commit" signal of GtkIMContext (on Linux), or;
+  //   C. insertText of NSTextInput is called (on Mac).
+  //
+  // This function is only used when window rendering is disabled.
   ///
-  cef_text_input_context_t (CEF_CALLBACK *get_nstext_input_context)(
-      struct _cef_browser_host_t* self);
+  void (CEF_CALLBACK *ime_set_composition)(struct _cef_browser_host_t* self,
+      const cef_string_t* text, size_t underlinesCount,
+      cef_composition_underline_t const* underlines,
+      const cef_range_t* replacement_range,
+      const cef_range_t* selection_range);
 
   ///
-  // Handles a keyDown event prior to passing it through the NSTextInputClient
-  // machinery.
+  // Completes the existing composition by optionally inserting the specified
+  // |text| into the composition node. |replacement_range| is an optional range
+  // of the existing text that will be replaced. |relative_cursor_pos| is where
+  // the cursor will be positioned relative to the current cursor position. See
+  // comments on ImeSetComposition for usage. The |replacement_range| and
+  // |relative_cursor_pos| values are only used on OS X. This function is only
+  // used when window rendering is disabled.
   ///
-  void (CEF_CALLBACK *handle_key_event_before_text_input_client)(
-      struct _cef_browser_host_t* self, cef_event_handle_t keyEvent);
+  void (CEF_CALLBACK *ime_commit_text)(struct _cef_browser_host_t* self,
+      const cef_string_t* text, const cef_range_t* replacement_range,
+      int relative_cursor_pos);
 
   ///
-  // Performs any additional actions after NSTextInputClient handles the event.
+  // Completes the existing composition by applying the current composition node
+  // contents. If |keep_selection| is false (0) the current selection, if any,
+  // will be discarded. See comments on ImeSetComposition for usage. This
+  // function is only used when window rendering is disabled.
   ///
-  void (CEF_CALLBACK *handle_key_event_after_text_input_client)(
-      struct _cef_browser_host_t* self, cef_event_handle_t keyEvent);
+  void (CEF_CALLBACK *ime_finish_composing_text)(
+      struct _cef_browser_host_t* self, int keep_selection);
+
+  ///
+  // Cancels the existing composition and discards the composition node contents
+  // without applying them. See comments on ImeSetComposition for usage. This
+  // function is only used when window rendering is disabled.
+  ///
+  void (CEF_CALLBACK *ime_cancel_composition)(struct _cef_browser_host_t* self);
 
   ///
   // Call this function when the user drags the mouse into the web view (before

include/capi/cef_render_handler_capi.h

@@ -161,6 +161,16 @@ typedef struct _cef_render_handler_t {
   void (CEF_CALLBACK *on_scroll_offset_changed)(
       struct _cef_render_handler_t* self, struct _cef_browser_t* browser,
       double x, double y);
+
+  ///
+  // Called when the IME composition range has changed. |selected_range| is the
+  // range of characters that have been selected. |character_bounds| is the
+  // bounds of each character in view coordinates.
+  ///
+  void (CEF_CALLBACK *on_ime_composition_range_changed)(
+      struct _cef_render_handler_t* self, struct _cef_browser_t* browser,
+      const cef_range_t* selected_range, size_t character_boundsCount,
+      cef_rect_t const* character_bounds);
 } cef_render_handler_t;
 
 

include/cef_browser.h

@@ -669,24 +669,66 @@ class CefBrowserHost : public virtual CefBase {
   virtual void SetWindowlessFrameRate(int frame_rate) =0;
 
   ///
-  // Get the NSTextInputContext implementation for enabling IME on Mac when
-  // window rendering is disabled.
+  // Begins a new composition or updates the existing composition. Blink has a
+  // special node (a composition node) that allows the input method to change
+  // text without affecting other DOM nodes. |text| is the optional text that
+  // will be inserted into the composition node. |underlines| is an optional set
+  // of ranges that will be underlined in the resulting text.
+  // |replacement_range| is an optional range of the existing text that will be
+  // replaced. |selection_range| is an optional range of the resulting text that
+  // will be selected after insertion or replacement. The |replacement_range|
+  // value is only used on OS X.
+  //
+  // This method may be called multiple times as the composition changes. When
+  // the client is done making changes the composition should either be canceled
+  // or completed. To cancel the composition call ImeCancelComposition. To
+  // complete the composition call either ImeCommitText or
+  // ImeFinishComposingText. Completion is usually signaled when:
+  //   A. The client receives a WM_IME_COMPOSITION message with a GCS_RESULTSTR
+  //      flag (on Windows), or;
+  //   B. The client receives a "commit" signal of GtkIMContext (on Linux), or;
+  //   C. insertText of NSTextInput is called (on Mac).
+  //
+  // This method is only used when window rendering is disabled.
   ///
-  /*--cef(default_retval=NULL)--*/
-  virtual CefTextInputContext GetNSTextInputContext() =0;
+  /*--cef(optional_param=text, optional_param=underlines)--*/
+  virtual void ImeSetComposition(
+      const CefString& text,
+      const std::vector<CefCompositionUnderline>& underlines,
+      const CefRange& replacement_range,
+      const CefRange& selection_range) =0;
 
   ///
-  // Handles a keyDown event prior to passing it through the NSTextInputClient
-  // machinery.
+  // Completes the existing composition by optionally inserting the specified
+  // |text| into the composition node. |replacement_range| is an optional range
+  // of the existing text that will be replaced. |relative_cursor_pos| is where
+  // the cursor will be positioned relative to the current cursor position. See
+  // comments on ImeSetComposition for usage. The |replacement_range| and
+  // |relative_cursor_pos| values are only used on OS X.
+  // This method is only used when window rendering is disabled.
   ///
-  /*--cef()--*/
-  virtual void HandleKeyEventBeforeTextInputClient(CefEventHandle keyEvent) =0;
+  /*--cef(optional_param=text)--*/
+  virtual void ImeCommitText(const CefString& text,
+                             const CefRange& replacement_range,
+                             int relative_cursor_pos) =0;
 
   ///
-  // Performs any additional actions after NSTextInputClient handles the event.
+  // Completes the existing composition by applying the current composition node
+  // contents. If |keep_selection| is false the current selection, if any, will
+  // be discarded. See comments on ImeSetComposition for usage.
+  // This method is only used when window rendering is disabled.
   ///
   /*--cef()--*/
-  virtual void HandleKeyEventAfterTextInputClient(CefEventHandle keyEvent) =0;
+  virtual void ImeFinishComposingText(bool keep_selection) =0;
+
+  ///
+  // Cancels the existing composition and discards the composition node
+  // contents without applying them. See comments on ImeSetComposition for
+  // usage.
+  // This method is only used when window rendering is disabled.
+  ///
+  /*--cef()--*/
+  virtual void ImeCancelComposition() =0;
 
   ///
   // Call this method when the user drags the mouse into the web view (before

include/cef_render_handler.h

@@ -176,6 +176,16 @@ class CefRenderHandler : public virtual CefBase {
   virtual void OnScrollOffsetChanged(CefRefPtr<CefBrowser> browser,
                                      double x,
                                      double y) {}
+
+  ///
+  // Called when the IME composition range has changed. |selected_range| is the
+  // range of characters that have been selected. |character_bounds| is the
+  // bounds of each character in view coordinates.
+  ///
+  /*--cef()--*/
+  virtual void OnImeCompositionRangeChanged(CefRefPtr<CefBrowser> browser,
+                                            const CefRange& selected_range,
+                                            const RectList& character_bounds) {}
 };
 
 #endif  // CEF_INCLUDE_CEF_RENDER_HANDLER_H_

include/internal/cef_linux.h

@@ -39,7 +39,6 @@
 #define CefCursorHandle cef_cursor_handle_t
 #define CefEventHandle cef_event_handle_t
 #define CefWindowHandle cef_window_handle_t
-#define CefTextInputContext cef_text_input_context_t
 
 struct CefMainArgsTraits {
   typedef cef_main_args_t struct_type;

include/internal/cef_mac.h

@@ -39,7 +39,6 @@
 #define CefCursorHandle cef_cursor_handle_t
 #define CefEventHandle cef_event_handle_t
 #define CefWindowHandle cef_window_handle_t
-#define CefTextInputContext cef_text_input_context_t
 
 struct CefMainArgsTraits {
   typedef cef_main_args_t struct_type;

include/internal/cef_types.h

@@ -2682,6 +2682,33 @@ typedef enum {
   CEF_CDM_REGISTRATION_ERROR_NOT_SUPPORTED,
 } cef_cdm_registration_error_t;
 
+///
+// Structure representing IME composition underline information. This is a thin
+// wrapper around Blink's WebCompositionUnderline class and should be kept in
+// sync with that.
+///
+typedef struct _cef_composition_underline_t {
+  ///
+  // Underline character range.
+  ///
+  cef_range_t range;
+
+  ///
+  // Text color.
+  ///
+  cef_color_t color;
+
+  ///
+  // Background color.
+  ///
+  cef_color_t background_color;
+
+  ///
+  // Set to true (1) for thick underline.
+  ///
+  int thick;
+} cef_composition_underline_t;
+
 #ifdef __cplusplus
 }
 #endif

include/internal/cef_types_linux.h

@@ -60,7 +60,6 @@ extern "C" {
 // thread-safe and must only be accessed on the browser process UI thread.
 ///
 CEF_EXPORT XDisplay* cef_get_xdisplay();
-#define cef_text_input_context_t void*
 
 ///
 // Structure representing CefExecuteProcess arguments.

include/internal/cef_types_mac.h

@@ -43,22 +43,18 @@
 @class NSCursor;
 @class NSEvent;
 @class NSView;
-@class NSTextInputContext;
 #else
 class NSCursor;
 class NSEvent;
 struct NSView;
-class NSTextInputContext;
 #endif
 #define cef_cursor_handle_t NSCursor*
 #define cef_event_handle_t NSEvent*
 #define cef_window_handle_t NSView*
-#define cef_text_input_context_t NSTextInputContext*
 #else
 #define cef_cursor_handle_t void*
 #define cef_event_handle_t void*
 #define cef_window_handle_t void*
-#define cef_text_input_context_t void*
 #endif
 
 #define kNullCursorHandle NULL

include/internal/cef_types_win.h

@@ -42,7 +42,6 @@
 #define cef_cursor_handle_t HCURSOR
 #define cef_event_handle_t MSG*
 #define cef_window_handle_t HWND
-#define cef_text_input_context_t void*
 
 #define kNullCursorHandle NULL
 #define kNullEventHandle NULL

include/internal/cef_types_wrappers.h

@@ -975,4 +975,31 @@ struct CefBoxLayoutSettingsTraits {
 ///
 typedef CefStructBase<CefBoxLayoutSettingsTraits> CefBoxLayoutSettings;
 
+struct CefCompositionUnderlineTraits {
+  typedef cef_composition_underline_t struct_type;
+
+  static inline void init(struct_type* s) {
+    s->range = {0, 0};
+    s->color = 0;
+    s->background_color = 0;
+    s->thick = 0;
+  }
+
+  static inline void clear(struct_type* s) {
+  }
+
+  static inline void set(const struct_type* src, struct_type* target,
+                         bool copy) {
+    target->range = src->range;
+    target->color = src->color;
+    target->background_color = src->background_color;
+    target->thick = src->thick;
+  }
+};
+
+///
+// Class representing IME composition underline.
+///
+typedef CefStructBase<CefCompositionUnderlineTraits> CefCompositionUnderline;
+
 #endif  // CEF_INCLUDE_INTERNAL_CEF_TYPES_WRAPPERS_H_

include/internal/cef_win.h

@@ -41,7 +41,6 @@
 #define CefCursorHandle cef_cursor_handle_t
 #define CefEventHandle cef_event_handle_t
 #define CefWindowHandle cef_window_handle_t
-#define CefTextInputContext cef_text_input_context_t
 
 struct CefMainArgsTraits {
   typedef cef_main_args_t struct_type;