render_widget_host.h revision effb81e5f8246d0db0270817048dc992db66e9fb
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 CONTENT_PUBLIC_BROWSER_RENDER_WIDGET_HOST_H_ 6#define CONTENT_PUBLIC_BROWSER_RENDER_WIDGET_HOST_H_ 7 8#include "base/callback.h" 9#include "content/common/content_export.h" 10#include "content/public/browser/native_web_keyboard_event.h" 11#include "ipc/ipc_channel.h" 12#include "ipc/ipc_sender.h" 13#include "third_party/WebKit/public/web/WebInputEvent.h" 14#include "third_party/WebKit/public/web/WebTextDirection.h" 15#include "third_party/skia/include/core/SkBitmap.h" 16#include "ui/gfx/size.h" 17#include "ui/surface/transport_dib.h" 18 19#if defined(TOOLKIT_GTK) 20#include "ui/base/x/x11_util.h" 21#elif defined(OS_MACOSX) 22#include "skia/ext/platform_device.h" 23#endif 24 25class SkBitmap; 26 27namespace gfx { 28class Rect; 29} 30 31namespace blink { 32class WebMouseEvent; 33struct WebScreenInfo; 34} 35 36namespace content { 37 38class RenderProcessHost; 39class RenderWidgetHostImpl; 40class RenderWidgetHostIterator; 41class RenderWidgetHostView; 42 43// A RenderWidgetHost manages the browser side of a browser<->renderer 44// HWND connection. The HWND lives in the browser process, and 45// windows events are sent over IPC to the corresponding object in the 46// renderer. The renderer paints into shared memory, which we 47// transfer to a backing store and blit to the screen when Windows 48// sends us a WM_PAINT message. 49// 50// How Shutdown Works 51// 52// There are two situations in which this object, a RenderWidgetHost, can be 53// instantiated: 54// 55// 1. By a WebContents as the communication conduit for a rendered web page. 56// The WebContents instantiates a derived class: RenderViewHost. 57// 2. By a WebContents as the communication conduit for a select widget. The 58// WebContents instantiates the RenderWidgetHost directly. 59// 60// For every WebContents there are several objects in play that need to be 61// properly destroyed or cleaned up when certain events occur. 62// 63// - WebContents - the WebContents itself, and its associated HWND. 64// - RenderViewHost - representing the communication conduit with the child 65// process. 66// - RenderWidgetHostView - the view of the web page content, message handler, 67// and plugin root. 68// 69// Normally, the WebContents contains a child RenderWidgetHostView that renders 70// the contents of the loaded page. It has a WS_CLIPCHILDREN style so that it 71// does no painting of its own. 72// 73// The lifetime of the RenderWidgetHostView is tied to the render process. If 74// the render process dies, the RenderWidgetHostView goes away and all 75// references to it must become NULL. 76// 77// RenderViewHost (a RenderWidgetHost subclass) is the conduit used to 78// communicate with the RenderView and is owned by the WebContents. If the 79// render process crashes, the RenderViewHost remains and restarts the render 80// process if needed to continue navigation. 81// 82// Some examples of how shutdown works: 83// 84// For a WebContents, its Destroy method tells the RenderViewHost to 85// shut down the render process and die. 86// 87// When the render process is destroyed it destroys the View: the 88// RenderWidgetHostView, which destroys its HWND and deletes that object. 89// 90// For select popups, the situation is a little different. The RenderWidgetHost 91// associated with the select popup owns the view and itself (is responsible 92// for destroying itself when the view is closed). The WebContents's only 93// responsibility is to select popups is to create them when it is told to. When 94// the View is destroyed via an IPC message (for when WebCore destroys the 95// popup, e.g. if the user selects one of the options), or because 96// WM_CANCELMODE is received by the view, the View schedules the destruction of 97// the render process. However in this case since there's no WebContents 98// container, when the render process is destroyed, the RenderWidgetHost just 99// deletes itself, which is safe because no one else should have any references 100// to it (the WebContents does not). 101// 102// It should be noted that the RenderViewHost, not the RenderWidgetHost, 103// handles IPC messages relating to the render process going away, since the 104// way a RenderViewHost (WebContents) handles the process dying is different to 105// the way a select popup does. As such the RenderWidgetHostView handles these 106// messages for select popups. This placement is more out of convenience than 107// anything else. When the view is live, these messages are forwarded to it by 108// the RenderWidgetHost's IPC message map. 109class CONTENT_EXPORT RenderWidgetHost : public IPC::Sender { 110 public: 111 // Returns the size of all the backing stores used for rendering 112 static size_t BackingStoreMemorySize(); 113 114 // Returns the RenderWidgetHost given its ID and the ID of its render process. 115 // Returns NULL if the IDs do not correspond to a live RenderWidgetHost. 116 static RenderWidgetHost* FromID(int32 process_id, int32 routing_id); 117 118 // Returns an iterator to iterate over the global list of active render widget 119 // hosts. 120 static scoped_ptr<RenderWidgetHostIterator> GetRenderWidgetHosts(); 121 122 virtual ~RenderWidgetHost() {} 123 124 // Update the text direction of the focused input element and notify it to a 125 // renderer process. 126 // These functions have two usage scenarios: changing the text direction 127 // from a menu (as Safari does), and; changing the text direction when a user 128 // presses a set of keys (as IE and Firefox do). 129 // 1. Change the text direction from a menu. 130 // In this scenario, we receive a menu event only once and we should update 131 // the text direction immediately when a user chooses a menu item. So, we 132 // should call both functions at once as listed in the following snippet. 133 // void RenderViewHost::SetTextDirection(WebTextDirection direction) { 134 // UpdateTextDirection(direction); 135 // NotifyTextDirection(); 136 // } 137 // 2. Change the text direction when pressing a set of keys. 138 // Because of auto-repeat, we may receive the same key-press event many 139 // times while we presses the keys and it is nonsense to send the same IPC 140 // message every time when we receive a key-press event. 141 // To suppress the number of IPC messages, we just update the text direction 142 // when receiving a key-press event and send an IPC message when we release 143 // the keys as listed in the following snippet. 144 // if (key_event.type == WebKeyboardEvent::KEY_DOWN) { 145 // if (key_event.windows_key_code == 'A' && 146 // key_event.modifiers == WebKeyboardEvent::CTRL_KEY) { 147 // UpdateTextDirection(dir); 148 // } else { 149 // CancelUpdateTextDirection(); 150 // } 151 // } else if (key_event.type == WebKeyboardEvent::KEY_UP) { 152 // NotifyTextDirection(); 153 // } 154 // Once we cancel updating the text direction, we have to ignore all 155 // succeeding UpdateTextDirection() requests until calling 156 // NotifyTextDirection(). (We may receive keydown events even after we 157 // canceled updating the text direction because of auto-repeat.) 158 // Note: we cannot undo this change for compatibility with Firefox and IE. 159 virtual void UpdateTextDirection(blink::WebTextDirection direction) = 0; 160 virtual void NotifyTextDirection() = 0; 161 162 virtual void Focus() = 0; 163 virtual void Blur() = 0; 164 165 // Sets whether the renderer should show controls in an active state. On all 166 // platforms except mac, that's the same as focused. On mac, the frontmost 167 // window will show active controls even if the focus is not in the web 168 // contents, but e.g. in the omnibox. 169 virtual void SetActive(bool active) = 0; 170 171 // Copies the given subset of the backing store, and passes the result as a 172 // bitmap to a callback. 173 // 174 // If |src_rect| is empty, the whole contents is copied. If non empty 175 // |accelerated_dst_size| is given and accelerated compositing is active, the 176 // content is shrunk so that it fits in |accelerated_dst_size|. If 177 // |accelerated_dst_size| is larger than the content size, the content is not 178 // resized. If |accelerated_dst_size| is empty, the size copied from the 179 // source contents is used. |callback| is invoked with true on success, false 180 // otherwise, along with a SkBitmap containing the copied pixel data. 181 // 182 // NOTE: |callback| is called synchronously if the backing store is available. 183 // When accelerated compositing is active, |callback| may be called 184 // asynchronously. 185 virtual void CopyFromBackingStore( 186 const gfx::Rect& src_rect, 187 const gfx::Size& accelerated_dst_size, 188 const base::Callback<void(bool, const SkBitmap&)>& callback, 189 const SkBitmap::Config& bitmap_config) = 0; 190 // Ensures that the view does not drop the backing store even when hidden. 191 virtual bool CanCopyFromBackingStore() = 0; 192#if defined(OS_ANDROID) 193 virtual void LockBackingStore() = 0; 194 virtual void UnlockBackingStore() = 0; 195#endif 196#if defined(TOOLKIT_GTK) 197 // Paint the backing store into the target's |dest_rect|. 198 virtual bool CopyFromBackingStoreToGtkWindow(const gfx::Rect& dest_rect, 199 GdkWindow* target) = 0; 200#elif defined(OS_MACOSX) 201 virtual gfx::Size GetBackingStoreSize() = 0; 202 virtual bool CopyFromBackingStoreToCGContext(const CGRect& dest_rect, 203 CGContextRef target) = 0; 204#endif 205 206 // Send a command to the renderer to turn on full accessibility. 207 virtual void EnableFullAccessibilityMode() = 0; 208 209 // Check whether this RenderWidget has full accessibility mode. 210 virtual bool IsFullAccessibilityModeForTesting() = 0; 211 212 // Send a command to the renderer to turn on tree only accessibility. 213 virtual void EnableTreeOnlyAccessibilityMode() = 0; 214 215 // Check whether this RenderWidget has tree-only accessibility mode. 216 virtual bool IsTreeOnlyAccessibilityModeForTesting() = 0; 217 218 // Forwards the given message to the renderer. These are called by 219 // the view when it has received a message. 220 virtual void ForwardMouseEvent( 221 const blink::WebMouseEvent& mouse_event) = 0; 222 virtual void ForwardWheelEvent( 223 const blink::WebMouseWheelEvent& wheel_event) = 0; 224 virtual void ForwardKeyboardEvent( 225 const NativeWebKeyboardEvent& key_event) = 0; 226 227 virtual const gfx::Vector2d& GetLastScrollOffset() const = 0; 228 229 virtual RenderProcessHost* GetProcess() const = 0; 230 231 virtual int GetRoutingID() const = 0; 232 233 // Gets the View of this RenderWidgetHost. Can be NULL, e.g. if the 234 // RenderWidget is being destroyed or the render process crashed. You should 235 // never cache this pointer since it can become NULL if the renderer crashes, 236 // instead you should always ask for it using the accessor. 237 virtual RenderWidgetHostView* GetView() const = 0; 238 239 // Returns true if the renderer is loading, false if not. 240 virtual bool IsLoading() const = 0; 241 242 // Returns true if this is a RenderViewHost, false if not. 243 virtual bool IsRenderView() const = 0; 244 245 // Makes an IPC call to tell webkit to replace the currently selected word 246 // or a word around the cursor. 247 virtual void Replace(const base::string16& word) = 0; 248 249 // Makes an IPC call to tell webkit to replace the misspelling in the current 250 // selection. 251 virtual void ReplaceMisspelling(const base::string16& word) = 0; 252 253 // Called to notify the RenderWidget that the resize rect has changed without 254 // the size of the RenderWidget itself changing. 255 virtual void ResizeRectChanged(const gfx::Rect& new_rect) = 0; 256 257 // Restart the active hang monitor timeout. Clears all existing timeouts and 258 // starts with a new one. This can be because the renderer has become 259 // active, the tab is being hidden, or the user has chosen to wait some more 260 // to give the tab a chance to become active and we don't want to display a 261 // warning too soon. 262 virtual void RestartHangMonitorTimeout() = 0; 263 264 virtual void SetIgnoreInputEvents(bool ignore_input_events) = 0; 265 266 // Stops loading the page. 267 virtual void Stop() = 0; 268 269 // Called to notify the RenderWidget that it has been resized. 270 virtual void WasResized() = 0; 271 272 // Access to the implementation's IPC::Listener::OnMessageReceived. Intended 273 // only for test code. 274 275 // Add/remove a callback that can handle key presses without requiring focus. 276 typedef base::Callback<bool(const NativeWebKeyboardEvent&)> 277 KeyPressEventCallback; 278 virtual void AddKeyPressEventCallback( 279 const KeyPressEventCallback& callback) = 0; 280 virtual void RemoveKeyPressEventCallback( 281 const KeyPressEventCallback& callback) = 0; 282 283 // Add/remove a callback that can handle all kinds of mouse events. 284 typedef base::Callback<bool(const blink::WebMouseEvent&)> MouseEventCallback; 285 virtual void AddMouseEventCallback(const MouseEventCallback& callback) = 0; 286 virtual void RemoveMouseEventCallback(const MouseEventCallback& callback) = 0; 287 288 // Get the screen info corresponding to this render widget. 289 virtual void GetWebScreenInfo(blink::WebScreenInfo* result) = 0; 290 291 // Grabs snapshot from renderer side and returns the bitmap to a callback. 292 // If |src_rect| is empty, the whole contents is copied. This is an expensive 293 // operation due to the IPC, but it can be used as a fallback method when 294 // CopyFromBackingStore fails due to the backing store not being available or, 295 // in composited mode, when the accelerated surface is not available to the 296 // browser side. 297 virtual void GetSnapshotFromRenderer( 298 const gfx::Rect& src_subrect, 299 const base::Callback<void(bool, const SkBitmap&)>& callback) = 0; 300 301 virtual SkBitmap::Config PreferredReadbackFormat() = 0; 302 303 protected: 304 friend class RenderWidgetHostImpl; 305 306 // Retrieves the implementation class. Intended only for code 307 // within content/. This method is necessary because 308 // RenderWidgetHost is the root of a diamond inheritance pattern, so 309 // subclasses inherit it virtually, which removes our ability to 310 // static_cast to the subclass. 311 virtual RenderWidgetHostImpl* AsRenderWidgetHostImpl() = 0; 312}; 313 314} // namespace content 315 316#endif // CONTENT_PUBLIC_BROWSER_RENDER_WIDGET_HOST_H_ 317