1 // Copyright (c) 2012 Marshall A. Greenblatt. All rights reserved. 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are 5 // met: 6 // 7 // * Redistributions of source code must retain the above copyright 8 // notice, this list of conditions and the following disclaimer. 9 // * Redistributions in binary form must reproduce the above 10 // copyright notice, this list of conditions and the following disclaimer 11 // in the documentation and/or other materials provided with the 12 // distribution. 13 // * Neither the name of Google Inc. nor the name Chromium Embedded 14 // Framework nor the names of its contributors may be used to endorse 15 // or promote products derived from this software without specific prior 16 // written permission. 17 // 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 // 30 // --------------------------------------------------------------------------- 31 // 32 // The contents of this file must follow a specific format in order to 33 // support the CEF translator tool. See the translator.README.txt file in the 34 // tools directory for more information. 35 // 36 37 #ifndef CEF_INCLUDE_CEF_BROWSER_H_ 38 #define CEF_INCLUDE_CEF_BROWSER_H_ 39 #pragma once 40 41 #include <vector> 42 #include "include/cef_base.h" 43 #include "include/cef_devtools_message_observer.h" 44 #include "include/cef_drag_data.h" 45 #include "include/cef_frame.h" 46 #include "include/cef_image.h" 47 #include "include/cef_navigation_entry.h" 48 #include "include/cef_registration.h" 49 #include "include/cef_request_context.h" 50 51 class CefBrowserHost; 52 class CefClient; 53 54 /// 55 // Class used to represent a browser window. When used in the browser process 56 // the methods of this class may be called on any thread unless otherwise 57 // indicated in the comments. When used in the render process the methods of 58 // this class may only be called on the main thread. 59 /// 60 /*--cef(source=library)--*/ 61 class CefBrowser : public virtual CefBaseRefCounted { 62 public: 63 /// 64 // Returns the browser host object. This method can only be called in the 65 // browser process. 66 /// 67 /*--cef()--*/ 68 virtual CefRefPtr<CefBrowserHost> GetHost() = 0; 69 70 /// 71 // Returns true if the browser can navigate backwards. 72 /// 73 /*--cef()--*/ 74 virtual bool CanGoBack() = 0; 75 76 /// 77 // Navigate backwards. 78 /// 79 /*--cef()--*/ 80 virtual void GoBack() = 0; 81 82 /// 83 // Returns true if the browser can navigate forwards. 84 /// 85 /*--cef()--*/ 86 virtual bool CanGoForward() = 0; 87 88 /// 89 // Navigate forwards. 90 /// 91 /*--cef()--*/ 92 virtual void GoForward() = 0; 93 94 /// 95 // Returns true if the browser is currently loading. 96 /// 97 /*--cef()--*/ 98 virtual bool IsLoading() = 0; 99 100 /// 101 // Reload the current page. 102 /// 103 /*--cef()--*/ 104 virtual void Reload() = 0; 105 106 /// 107 // Reload the current page ignoring any cached data. 108 /// 109 /*--cef()--*/ 110 virtual void ReloadIgnoreCache() = 0; 111 112 /// 113 // Stop loading the page. 114 /// 115 /*--cef()--*/ 116 virtual void StopLoad() = 0; 117 118 /// 119 // Returns the globally unique identifier for this browser. This value is also 120 // used as the tabId for extension APIs. 121 /// 122 /*--cef()--*/ 123 virtual int GetIdentifier() = 0; 124 125 /// 126 // Returns true if this object is pointing to the same handle as |that| 127 // object. 128 /// 129 /*--cef()--*/ 130 virtual bool IsSame(CefRefPtr<CefBrowser> that) = 0; 131 132 /// 133 // Returns true if the window is a popup window. 134 /// 135 /*--cef()--*/ 136 virtual bool IsPopup() = 0; 137 138 /// 139 // Returns true if a document has been loaded in the browser. 140 /// 141 /*--cef()--*/ 142 virtual bool HasDocument() = 0; 143 144 /// 145 // Returns the main (top-level) frame for the browser window. In the browser 146 // process this will return a valid object until after 147 // CefLifeSpanHandler::OnBeforeClose is called. In the renderer process this 148 // will return NULL if the main frame is hosted in a different renderer 149 // process (e.g. for cross-origin sub-frames). 150 /// 151 /*--cef()--*/ 152 virtual CefRefPtr<CefFrame> GetMainFrame() = 0; 153 154 /// 155 // Returns the focused frame for the browser window. 156 /// 157 /*--cef()--*/ 158 virtual CefRefPtr<CefFrame> GetFocusedFrame() = 0; 159 160 /// 161 // Returns the frame with the specified identifier, or NULL if not found. 162 /// 163 /*--cef(capi_name=get_frame_byident)--*/ 164 virtual CefRefPtr<CefFrame> GetFrame(int64 identifier) = 0; 165 166 /// 167 // Returns the frame with the specified name, or NULL if not found. 168 /// 169 /*--cef(optional_param=name)--*/ 170 virtual CefRefPtr<CefFrame> GetFrame(const CefString& name) = 0; 171 172 /// 173 // Returns the number of frames that currently exist. 174 /// 175 /*--cef()--*/ 176 virtual size_t GetFrameCount() = 0; 177 178 /// 179 // Returns the identifiers of all existing frames. 180 /// 181 /*--cef(count_func=identifiers:GetFrameCount)--*/ 182 virtual void GetFrameIdentifiers(std::vector<int64>& identifiers) = 0; 183 184 /// 185 // Returns the names of all existing frames. 186 /// 187 /*--cef()--*/ 188 virtual void GetFrameNames(std::vector<CefString>& names) = 0; 189 }; 190 191 /// 192 // Callback interface for CefBrowserHost::RunFileDialog. The methods of this 193 // class will be called on the browser process UI thread. 194 /// 195 /*--cef(source=client)--*/ 196 class CefRunFileDialogCallback : public virtual CefBaseRefCounted { 197 public: 198 /// 199 // Called asynchronously after the file dialog is dismissed. 200 // |selected_accept_filter| is the 0-based index of the value selected from 201 // the accept filters array passed to CefBrowserHost::RunFileDialog. 202 // |file_paths| will be a single value or a list of values depending on the 203 // dialog mode. If the selection was cancelled |file_paths| will be empty. 204 /// 205 /*--cef(index_param=selected_accept_filter,optional_param=file_paths)--*/ 206 virtual void OnFileDialogDismissed( 207 int selected_accept_filter, 208 const std::vector<CefString>& file_paths) = 0; 209 }; 210 211 /// 212 // Callback interface for CefBrowserHost::GetNavigationEntries. The methods of 213 // this class will be called on the browser process UI thread. 214 /// 215 /*--cef(source=client)--*/ 216 class CefNavigationEntryVisitor : public virtual CefBaseRefCounted { 217 public: 218 /// 219 // Method that will be executed. Do not keep a reference to |entry| outside of 220 // this callback. Return true to continue visiting entries or false to stop. 221 // |current| is true if this entry is the currently loaded navigation entry. 222 // |index| is the 0-based index of this entry and |total| is the total number 223 // of entries. 224 /// 225 /*--cef()--*/ 226 virtual bool Visit(CefRefPtr<CefNavigationEntry> entry, 227 bool current, 228 int index, 229 int total) = 0; 230 }; 231 232 /// 233 // Callback interface for CefBrowserHost::PrintToPDF. The methods of this class 234 // will be called on the browser process UI thread. 235 /// 236 /*--cef(source=client)--*/ 237 class CefPdfPrintCallback : public virtual CefBaseRefCounted { 238 public: 239 /// 240 // Method that will be executed when the PDF printing has completed. |path| 241 // is the output path. |ok| will be true if the printing completed 242 // successfully or false otherwise. 243 /// 244 /*--cef()--*/ 245 virtual void OnPdfPrintFinished(const CefString& path, bool ok) = 0; 246 }; 247 248 /// 249 // Callback interface for CefBrowserHost::DownloadImage. The methods of this 250 // class will be called on the browser process UI thread. 251 /// 252 /*--cef(source=client)--*/ 253 class CefDownloadImageCallback : public virtual CefBaseRefCounted { 254 public: 255 /// 256 // Method that will be executed when the image download has completed. 257 // |image_url| is the URL that was downloaded and |http_status_code| is the 258 // resulting HTTP status code. |image| is the resulting image, possibly at 259 // multiple scale factors, or empty if the download failed. 260 /// 261 /*--cef(optional_param=image)--*/ 262 virtual void OnDownloadImageFinished(const CefString& image_url, 263 int http_status_code, 264 CefRefPtr<CefImage> image) = 0; 265 }; 266 267 /// 268 // Class used to represent the browser process aspects of a browser window. The 269 // methods of this class can only be called in the browser process. They may be 270 // called on any thread in that process unless otherwise indicated in the 271 // comments. 272 /// 273 /*--cef(source=library)--*/ 274 class CefBrowserHost : public virtual CefBaseRefCounted { 275 public: 276 typedef cef_drag_operations_mask_t DragOperationsMask; 277 typedef cef_file_dialog_mode_t FileDialogMode; 278 typedef cef_mouse_button_type_t MouseButtonType; 279 typedef cef_paint_element_type_t PaintElementType; 280 281 /// 282 // Create a new browser window using the window parameters specified by 283 // |windowInfo|. All values will be copied internally and the actual window 284 // will be created on the UI thread. If |request_context| is empty the 285 // global request context will be used. This method can be called on any 286 // browser process thread and will not block. The optional |extra_info| 287 // parameter provides an opportunity to specify extra information specific 288 // to the created browser that will be passed to 289 // CefRenderProcessHandler::OnBrowserCreated() in the render process. 290 /// 291 /*--cef(optional_param=client,optional_param=url, 292 optional_param=request_context,optional_param=extra_info)--*/ 293 static bool CreateBrowser(const CefWindowInfo& windowInfo, 294 CefRefPtr<CefClient> client, 295 const CefString& url, 296 const CefBrowserSettings& settings, 297 CefRefPtr<CefDictionaryValue> extra_info, 298 CefRefPtr<CefRequestContext> request_context); 299 300 /// 301 // Create a new browser window using the window parameters specified by 302 // |windowInfo|. If |request_context| is empty the global request context 303 // will be used. This method can only be called on the browser process UI 304 // thread. The optional |extra_info| parameter provides an opportunity to 305 // specify extra information specific to the created browser that will be 306 // passed to CefRenderProcessHandler::OnBrowserCreated() in the render 307 // process. 308 /// 309 /*--cef(optional_param=client,optional_param=url, 310 optional_param=request_context,optional_param=extra_info)--*/ 311 static CefRefPtr<CefBrowser> CreateBrowserSync( 312 const CefWindowInfo& windowInfo, 313 CefRefPtr<CefClient> client, 314 const CefString& url, 315 const CefBrowserSettings& settings, 316 CefRefPtr<CefDictionaryValue> extra_info, 317 CefRefPtr<CefRequestContext> request_context); 318 319 /// 320 // Returns the hosted browser object. 321 /// 322 /*--cef()--*/ 323 virtual CefRefPtr<CefBrowser> GetBrowser() = 0; 324 325 /// 326 // Request that the browser close. The JavaScript 'onbeforeunload' event will 327 // be fired. If |force_close| is false the event handler, if any, will be 328 // allowed to prompt the user and the user can optionally cancel the close. 329 // If |force_close| is true the prompt will not be displayed and the close 330 // will proceed. Results in a call to CefLifeSpanHandler::DoClose() if the 331 // event handler allows the close or if |force_close| is true. See 332 // CefLifeSpanHandler::DoClose() documentation for additional usage 333 // information. 334 /// 335 /*--cef()--*/ 336 virtual void CloseBrowser(bool force_close) = 0; 337 338 /// 339 // Helper for closing a browser. Call this method from the top-level window 340 // close handler. Internally this calls CloseBrowser(false) if the close has 341 // not yet been initiated. This method returns false while the close is 342 // pending and true after the close has completed. See CloseBrowser() and 343 // CefLifeSpanHandler::DoClose() documentation for additional usage 344 // information. This method must be called on the browser process UI thread. 345 /// 346 /*--cef()--*/ 347 virtual bool TryCloseBrowser() = 0; 348 349 /// 350 // Set whether the browser is focused. 351 /// 352 /*--cef()--*/ 353 virtual void SetFocus(bool focus) = 0; 354 355 /// 356 // Retrieve the window handle for this browser. If this browser is wrapped in 357 // a CefBrowserView this method should be called on the browser process UI 358 // thread and it will return the handle for the top-level native window. 359 /// 360 /*--cef()--*/ 361 virtual CefWindowHandle GetWindowHandle() = 0; 362 363 /// 364 // Retrieve the window handle of the browser that opened this browser. Will 365 // return NULL for non-popup windows or if this browser is wrapped in a 366 // CefBrowserView. This method can be used in combination with custom handling 367 // of modal windows. 368 /// 369 /*--cef()--*/ 370 virtual CefWindowHandle GetOpenerWindowHandle() = 0; 371 372 /// 373 // Returns true if this browser is wrapped in a CefBrowserView. 374 /// 375 /*--cef()--*/ 376 virtual bool HasView() = 0; 377 378 /// 379 // Returns the client for this browser. 380 /// 381 /*--cef()--*/ 382 virtual CefRefPtr<CefClient> GetClient() = 0; 383 384 /// 385 // Returns the request context for this browser. 386 /// 387 /*--cef()--*/ 388 virtual CefRefPtr<CefRequestContext> GetRequestContext() = 0; 389 390 /// 391 // Get the current zoom level. The default zoom level is 0.0. This method can 392 // only be called on the UI thread. 393 /// 394 /*--cef()--*/ 395 virtual double GetZoomLevel() = 0; 396 397 /// 398 // Change the zoom level to the specified value. Specify 0.0 to reset the 399 // zoom level. If called on the UI thread the change will be applied 400 // immediately. Otherwise, the change will be applied asynchronously on the 401 // UI thread. 402 /// 403 /*--cef()--*/ 404 virtual void SetZoomLevel(double zoomLevel) = 0; 405 406 /// 407 // Call to run a file chooser dialog. Only a single file chooser dialog may be 408 // pending at any given time. |mode| represents the type of dialog to display. 409 // |title| to the title to be used for the dialog and may be empty to show the 410 // default title ("Open" or "Save" depending on the mode). |default_file_path| 411 // is the path with optional directory and/or file name component that will be 412 // initially selected in the dialog. |accept_filters| are used to restrict the 413 // selectable file types and may any combination of (a) valid lower-cased MIME 414 // types (e.g. "text/*" or "image/*"), (b) individual file extensions (e.g. 415 // ".txt" or ".png"), or (c) combined description and file extension delimited 416 // using "|" and ";" (e.g. "Image Types|.png;.gif;.jpg"). 417 // |selected_accept_filter| is the 0-based index of the filter that will be 418 // selected by default. |callback| will be executed after the dialog is 419 // dismissed or immediately if another dialog is already pending. The dialog 420 // will be initiated asynchronously on the UI thread. 421 /// 422 /*--cef(optional_param=title,optional_param=default_file_path, 423 optional_param=accept_filters,index_param=selected_accept_filter)--*/ 424 virtual void RunFileDialog(FileDialogMode mode, 425 const CefString& title, 426 const CefString& default_file_path, 427 const std::vector<CefString>& accept_filters, 428 int selected_accept_filter, 429 CefRefPtr<CefRunFileDialogCallback> callback) = 0; 430 431 /// 432 // Download the file at |url| using CefDownloadHandler. 433 /// 434 /*--cef()--*/ 435 virtual void StartDownload(const CefString& url) = 0; 436 437 /// 438 // Download |image_url| and execute |callback| on completion with the images 439 // received from the renderer. If |is_favicon| is true then cookies are not 440 // sent and not accepted during download. Images with density independent 441 // pixel (DIP) sizes larger than |max_image_size| are filtered out from the 442 // image results. Versions of the image at different scale factors may be 443 // downloaded up to the maximum scale factor supported by the system. If there 444 // are no image results <= |max_image_size| then the smallest image is resized 445 // to |max_image_size| and is the only result. A |max_image_size| of 0 means 446 // unlimited. If |bypass_cache| is true then |image_url| is requested from the 447 // server even if it is present in the browser cache. 448 /// 449 /*--cef()--*/ 450 virtual void DownloadImage(const CefString& image_url, 451 bool is_favicon, 452 uint32 max_image_size, 453 bool bypass_cache, 454 CefRefPtr<CefDownloadImageCallback> callback) = 0; 455 456 /// 457 // Print the current browser contents. 458 /// 459 /*--cef()--*/ 460 virtual void Print() = 0; 461 462 /// 463 // Print the current browser contents to the PDF file specified by |path| and 464 // execute |callback| on completion. The caller is responsible for deleting 465 // |path| when done. For PDF printing to work on Linux you must implement the 466 // CefPrintHandler::GetPdfPaperSize method. 467 /// 468 /*--cef(optional_param=callback)--*/ 469 virtual void PrintToPDF(const CefString& path, 470 const CefPdfPrintSettings& settings, 471 CefRefPtr<CefPdfPrintCallback> callback) = 0; 472 473 /// 474 // Search for |searchText|. |identifier| must be a unique ID and these IDs 475 // must strictly increase so that newer requests always have greater IDs than 476 // older requests. If |identifier| is zero or less than the previous ID value 477 // then it will be automatically assigned a new valid ID. |forward| indicates 478 // whether to search forward or backward within the page. |matchCase| 479 // indicates whether the search should be case-sensitive. |findNext| indicates 480 // whether this is the first request or a follow-up. The CefFindHandler 481 // instance, if any, returned via CefClient::GetFindHandler will be called to 482 // report find results. 483 /// 484 /*--cef()--*/ 485 virtual void Find(int identifier, 486 const CefString& searchText, 487 bool forward, 488 bool matchCase, 489 bool findNext) = 0; 490 491 /// 492 // Cancel all searches that are currently going on. 493 /// 494 /*--cef()--*/ 495 virtual void StopFinding(bool clearSelection) = 0; 496 497 /// 498 // Open developer tools (DevTools) in its own browser. The DevTools browser 499 // will remain associated with this browser. If the DevTools browser is 500 // already open then it will be focused, in which case the |windowInfo|, 501 // |client| and |settings| parameters will be ignored. If |inspect_element_at| 502 // is non-empty then the element at the specified (x,y) location will be 503 // inspected. The |windowInfo| parameter will be ignored if this browser is 504 // wrapped in a CefBrowserView. 505 /// 506 /*--cef(optional_param=windowInfo,optional_param=client, 507 optional_param=settings,optional_param=inspect_element_at)--*/ 508 virtual void ShowDevTools(const CefWindowInfo& windowInfo, 509 CefRefPtr<CefClient> client, 510 const CefBrowserSettings& settings, 511 const CefPoint& inspect_element_at) = 0; 512 513 /// 514 // Explicitly close the associated DevTools browser, if any. 515 /// 516 /*--cef()--*/ 517 virtual void CloseDevTools() = 0; 518 519 /// 520 // Returns true if this browser currently has an associated DevTools browser. 521 // Must be called on the browser process UI thread. 522 /// 523 /*--cef()--*/ 524 virtual bool HasDevTools() = 0; 525 526 /// 527 // Send a method call message over the DevTools protocol. |message| must be a 528 // UTF8-encoded JSON dictionary that contains "id" (int), "method" (string) 529 // and "params" (dictionary, optional) values. See the DevTools protocol 530 // documentation at https://chromedevtools.github.io/devtools-protocol/ for 531 // details of supported methods and the expected "params" dictionary contents. 532 // |message| will be copied if necessary. This method will return true if 533 // called on the UI thread and the message was successfully submitted for 534 // validation, otherwise false. Validation will be applied asynchronously and 535 // any messages that fail due to formatting errors or missing parameters may 536 // be discarded without notification. Prefer ExecuteDevToolsMethod if a more 537 // structured approach to message formatting is desired. 538 // 539 // Every valid method call will result in an asynchronous method result or 540 // error message that references the sent message "id". Event messages are 541 // received while notifications are enabled (for example, between method calls 542 // for "Page.enable" and "Page.disable"). All received messages will be 543 // delivered to the observer(s) registered with AddDevToolsMessageObserver. 544 // See CefDevToolsMessageObserver::OnDevToolsMessage documentation for details 545 // of received message contents. 546 // 547 // Usage of the SendDevToolsMessage, ExecuteDevToolsMethod and 548 // AddDevToolsMessageObserver methods does not require an active DevTools 549 // front-end or remote-debugging session. Other active DevTools sessions will 550 // continue to function independently. However, any modification of global 551 // browser state by one session may not be reflected in the UI of other 552 // sessions. 553 // 554 // Communication with the DevTools front-end (when displayed) can be logged 555 // for development purposes by passing the 556 // `--devtools-protocol-log-file=<path>` command-line flag. 557 /// 558 /*--cef()--*/ 559 virtual bool SendDevToolsMessage(const void* message, 560 size_t message_size) = 0; 561 562 /// 563 // Execute a method call over the DevTools protocol. This is a more structured 564 // version of SendDevToolsMessage. |message_id| is an incremental number that 565 // uniquely identifies the message (pass 0 to have the next number assigned 566 // automatically based on previous values). |method| is the method name. 567 // |params| are the method parameters, which may be empty. See the DevTools 568 // protocol documentation (linked above) for details of supported methods and 569 // the expected |params| dictionary contents. This method will return the 570 // assigned message ID if called on the UI thread and the message was 571 // successfully submitted for validation, otherwise 0. See the 572 // SendDevToolsMessage documentation for additional usage information. 573 /// 574 /*--cef(optional_param=params)--*/ 575 virtual int ExecuteDevToolsMethod(int message_id, 576 const CefString& method, 577 CefRefPtr<CefDictionaryValue> params) = 0; 578 579 /// 580 // Add an observer for DevTools protocol messages (method results and events). 581 // The observer will remain registered until the returned Registration object 582 // is destroyed. See the SendDevToolsMessage documentation for additional 583 // usage information. 584 /// 585 /*--cef()--*/ 586 virtual CefRefPtr<CefRegistration> AddDevToolsMessageObserver( 587 CefRefPtr<CefDevToolsMessageObserver> observer) = 0; 588 589 /// 590 // Retrieve a snapshot of current navigation entries as values sent to the 591 // specified visitor. If |current_only| is true only the current navigation 592 // entry will be sent, otherwise all navigation entries will be sent. 593 /// 594 /*--cef()--*/ 595 virtual void GetNavigationEntries( 596 CefRefPtr<CefNavigationEntryVisitor> visitor, 597 bool current_only) = 0; 598 599 /// 600 // If a misspelled word is currently selected in an editable node calling 601 // this method will replace it with the specified |word|. 602 /// 603 /*--cef()--*/ 604 virtual void ReplaceMisspelling(const CefString& word) = 0; 605 606 /// 607 // Add the specified |word| to the spelling dictionary. 608 /// 609 /*--cef()--*/ 610 virtual void AddWordToDictionary(const CefString& word) = 0; 611 612 /// 613 // Returns true if window rendering is disabled. 614 /// 615 /*--cef()--*/ 616 virtual bool IsWindowRenderingDisabled() = 0; 617 618 /// 619 // Notify the browser that the widget has been resized. The browser will first 620 // call CefRenderHandler::GetViewRect to get the new size and then call 621 // CefRenderHandler::OnPaint asynchronously with the updated regions. This 622 // method is only used when window rendering is disabled. 623 /// 624 /*--cef()--*/ 625 virtual void WasResized() = 0; 626 627 /// 628 // Notify the browser that it has been hidden or shown. Layouting and 629 // CefRenderHandler::OnPaint notification will stop when the browser is 630 // hidden. This method is only used when window rendering is disabled. 631 /// 632 /*--cef()--*/ 633 virtual void WasHidden(bool hidden) = 0; 634 635 /// 636 // Send a notification to the browser that the screen info has changed. The 637 // browser will then call CefRenderHandler::GetScreenInfo to update the 638 // screen information with the new values. This simulates moving the webview 639 // window from one display to another, or changing the properties of the 640 // current display. This method is only used when window rendering is 641 // disabled. 642 /// 643 /*--cef()--*/ 644 virtual void NotifyScreenInfoChanged() = 0; 645 646 /// 647 // Invalidate the view. The browser will call CefRenderHandler::OnPaint 648 // asynchronously. This method is only used when window rendering is 649 // disabled. 650 /// 651 /*--cef()--*/ 652 virtual void Invalidate(PaintElementType type) = 0; 653 654 /// 655 // Issue a BeginFrame request to Chromium. Only valid when 656 // CefWindowInfo::external_begin_frame_enabled is set to true. 657 /// 658 /*--cef()--*/ 659 virtual void SendExternalBeginFrame() = 0; 660 661 /// 662 // Send a key event to the browser. 663 /// 664 /*--cef()--*/ 665 virtual void SendKeyEvent(const CefKeyEvent& event) = 0; 666 667 /// 668 // Send a mouse click event to the browser. The |x| and |y| coordinates are 669 // relative to the upper-left corner of the view. 670 /// 671 /*--cef()--*/ 672 virtual void SendMouseClickEvent(const CefMouseEvent& event, 673 MouseButtonType type, 674 bool mouseUp, 675 int clickCount) = 0; 676 677 /// 678 // Send a mouse move event to the browser. The |x| and |y| coordinates are 679 // relative to the upper-left corner of the view. 680 /// 681 /*--cef()--*/ 682 virtual void SendMouseMoveEvent(const CefMouseEvent& event, 683 bool mouseLeave) = 0; 684 685 /// 686 // Send a mouse wheel event to the browser. The |x| and |y| coordinates are 687 // relative to the upper-left corner of the view. The |deltaX| and |deltaY| 688 // values represent the movement delta in the X and Y directions respectively. 689 // In order to scroll inside select popups with window rendering disabled 690 // CefRenderHandler::GetScreenPoint should be implemented properly. 691 /// 692 /*--cef()--*/ 693 virtual void SendMouseWheelEvent(const CefMouseEvent& event, 694 int deltaX, 695 int deltaY) = 0; 696 697 /// 698 // Send a touch event to the browser for a windowless browser. 699 /// 700 /*--cef()--*/ 701 virtual void SendTouchEvent(const CefTouchEvent& event) = 0; 702 703 /// 704 // Send a focus event to the browser. 705 /// 706 /*--cef()--*/ 707 virtual void SendFocusEvent(bool setFocus) = 0; 708 709 /// 710 // Send a capture lost event to the browser. 711 /// 712 /*--cef()--*/ 713 virtual void SendCaptureLostEvent() = 0; 714 715 /// 716 // Notify the browser that the window hosting it is about to be moved or 717 // resized. This method is only used on Windows and Linux. 718 /// 719 /*--cef()--*/ 720 virtual void NotifyMoveOrResizeStarted() = 0; 721 722 /// 723 // Returns the maximum rate in frames per second (fps) that CefRenderHandler:: 724 // OnPaint will be called for a windowless browser. The actual fps may be 725 // lower if the browser cannot generate frames at the requested rate. The 726 // minimum value is 1 and the maximum value is 60 (default 30). This method 727 // can only be called on the UI thread. 728 /// 729 /*--cef()--*/ 730 virtual int GetWindowlessFrameRate() = 0; 731 732 /// 733 // Set the maximum rate in frames per second (fps) that CefRenderHandler:: 734 // OnPaint will be called for a windowless browser. The actual fps may be 735 // lower if the browser cannot generate frames at the requested rate. The 736 // minimum value is 1 and the maximum value is 60 (default 30). Can also be 737 // set at browser creation via CefBrowserSettings.windowless_frame_rate. 738 /// 739 /*--cef()--*/ 740 virtual void SetWindowlessFrameRate(int frame_rate) = 0; 741 742 /// 743 // Begins a new composition or updates the existing composition. Blink has a 744 // special node (a composition node) that allows the input method to change 745 // text without affecting other DOM nodes. |text| is the optional text that 746 // will be inserted into the composition node. |underlines| is an optional set 747 // of ranges that will be underlined in the resulting text. 748 // |replacement_range| is an optional range of the existing text that will be 749 // replaced. |selection_range| is an optional range of the resulting text that 750 // will be selected after insertion or replacement. The |replacement_range| 751 // value is only used on OS X. 752 // 753 // This method may be called multiple times as the composition changes. When 754 // the client is done making changes the composition should either be canceled 755 // or completed. To cancel the composition call ImeCancelComposition. To 756 // complete the composition call either ImeCommitText or 757 // ImeFinishComposingText. Completion is usually signaled when: 758 // A. The client receives a WM_IME_COMPOSITION message with a GCS_RESULTSTR 759 // flag (on Windows), or; 760 // B. The client receives a "commit" signal of GtkIMContext (on Linux), or; 761 // C. insertText of NSTextInput is called (on Mac). 762 // 763 // This method is only used when window rendering is disabled. 764 /// 765 /*--cef(optional_param=text, optional_param=underlines)--*/ 766 virtual void ImeSetComposition( 767 const CefString& text, 768 const std::vector<CefCompositionUnderline>& underlines, 769 const CefRange& replacement_range, 770 const CefRange& selection_range) = 0; 771 772 /// 773 // Completes the existing composition by optionally inserting the specified 774 // |text| into the composition node. |replacement_range| is an optional range 775 // of the existing text that will be replaced. |relative_cursor_pos| is where 776 // the cursor will be positioned relative to the current cursor position. See 777 // comments on ImeSetComposition for usage. The |replacement_range| and 778 // |relative_cursor_pos| values are only used on OS X. 779 // This method is only used when window rendering is disabled. 780 /// 781 /*--cef(optional_param=text)--*/ 782 virtual void ImeCommitText(const CefString& text, 783 const CefRange& replacement_range, 784 int relative_cursor_pos) = 0; 785 786 /// 787 // Completes the existing composition by applying the current composition node 788 // contents. If |keep_selection| is false the current selection, if any, will 789 // be discarded. See comments on ImeSetComposition for usage. 790 // This method is only used when window rendering is disabled. 791 /// 792 /*--cef()--*/ 793 virtual void ImeFinishComposingText(bool keep_selection) = 0; 794 795 /// 796 // Cancels the existing composition and discards the composition node 797 // contents without applying them. See comments on ImeSetComposition for 798 // usage. 799 // This method is only used when window rendering is disabled. 800 /// 801 /*--cef()--*/ 802 virtual void ImeCancelComposition() = 0; 803 804 /// 805 // Call this method when the user drags the mouse into the web view (before 806 // calling DragTargetDragOver/DragTargetLeave/DragTargetDrop). 807 // |drag_data| should not contain file contents as this type of data is not 808 // allowed to be dragged into the web view. File contents can be removed using 809 // CefDragData::ResetFileContents (for example, if |drag_data| comes from 810 // CefRenderHandler::StartDragging). 811 // This method is only used when window rendering is disabled. 812 /// 813 /*--cef()--*/ 814 virtual void DragTargetDragEnter(CefRefPtr<CefDragData> drag_data, 815 const CefMouseEvent& event, 816 DragOperationsMask allowed_ops) = 0; 817 818 /// 819 // Call this method each time the mouse is moved across the web view during 820 // a drag operation (after calling DragTargetDragEnter and before calling 821 // DragTargetDragLeave/DragTargetDrop). 822 // This method is only used when window rendering is disabled. 823 /// 824 /*--cef()--*/ 825 virtual void DragTargetDragOver(const CefMouseEvent& event, 826 DragOperationsMask allowed_ops) = 0; 827 828 /// 829 // Call this method when the user drags the mouse out of the web view (after 830 // calling DragTargetDragEnter). 831 // This method is only used when window rendering is disabled. 832 /// 833 /*--cef()--*/ 834 virtual void DragTargetDragLeave() = 0; 835 836 /// 837 // Call this method when the user completes the drag operation by dropping 838 // the object onto the web view (after calling DragTargetDragEnter). 839 // The object being dropped is |drag_data|, given as an argument to 840 // the previous DragTargetDragEnter call. 841 // This method is only used when window rendering is disabled. 842 /// 843 /*--cef()--*/ 844 virtual void DragTargetDrop(const CefMouseEvent& event) = 0; 845 846 /// 847 // Call this method when the drag operation started by a 848 // CefRenderHandler::StartDragging call has ended either in a drop or 849 // by being cancelled. |x| and |y| are mouse coordinates relative to the 850 // upper-left corner of the view. If the web view is both the drag source 851 // and the drag target then all DragTarget* methods should be called before 852 // DragSource* mthods. 853 // This method is only used when window rendering is disabled. 854 /// 855 /*--cef()--*/ 856 virtual void DragSourceEndedAt(int x, int y, DragOperationsMask op) = 0; 857 858 /// 859 // Call this method when the drag operation started by a 860 // CefRenderHandler::StartDragging call has completed. This method may be 861 // called immediately without first calling DragSourceEndedAt to cancel a 862 // drag operation. If the web view is both the drag source and the drag 863 // target then all DragTarget* methods should be called before DragSource* 864 // mthods. 865 // This method is only used when window rendering is disabled. 866 /// 867 /*--cef()--*/ 868 virtual void DragSourceSystemDragEnded() = 0; 869 870 /// 871 // Returns the current visible navigation entry for this browser. This method 872 // can only be called on the UI thread. 873 /// 874 /*--cef()--*/ 875 virtual CefRefPtr<CefNavigationEntry> GetVisibleNavigationEntry() = 0; 876 877 /// 878 // Set accessibility state for all frames. |accessibility_state| may be 879 // default, enabled or disabled. If |accessibility_state| is STATE_DEFAULT 880 // then accessibility will be disabled by default and the state may be further 881 // controlled with the "force-renderer-accessibility" and 882 // "disable-renderer-accessibility" command-line switches. If 883 // |accessibility_state| is STATE_ENABLED then accessibility will be enabled. 884 // If |accessibility_state| is STATE_DISABLED then accessibility will be 885 // completely disabled. 886 // 887 // For windowed browsers accessibility will be enabled in Complete mode (which 888 // corresponds to kAccessibilityModeComplete in Chromium). In this mode all 889 // platform accessibility objects will be created and managed by Chromium's 890 // internal implementation. The client needs only to detect the screen reader 891 // and call this method appropriately. For example, on macOS the client can 892 // handle the @"AXEnhancedUserInterface" accessibility attribute to detect 893 // VoiceOver state changes and on Windows the client can handle WM_GETOBJECT 894 // with OBJID_CLIENT to detect accessibility readers. 895 // 896 // For windowless browsers accessibility will be enabled in TreeOnly mode 897 // (which corresponds to kAccessibilityModeWebContentsOnly in Chromium). In 898 // this mode renderer accessibility is enabled, the full tree is computed, and 899 // events are passed to CefAccessibiltyHandler, but platform accessibility 900 // objects are not created. The client may implement platform accessibility 901 // objects using CefAccessibiltyHandler callbacks if desired. 902 /// 903 /*--cef()--*/ 904 virtual void SetAccessibilityState(cef_state_t accessibility_state) = 0; 905 906 /// 907 // Enable notifications of auto resize via CefDisplayHandler::OnAutoResize. 908 // Notifications are disabled by default. |min_size| and |max_size| define the 909 // range of allowed sizes. 910 /// 911 /*--cef()--*/ 912 virtual void SetAutoResizeEnabled(bool enabled, 913 const CefSize& min_size, 914 const CefSize& max_size) = 0; 915 916 /// 917 // Returns the extension hosted in this browser or NULL if no extension is 918 // hosted. See CefRequestContext::LoadExtension for details. 919 /// 920 /*--cef()--*/ 921 virtual CefRefPtr<CefExtension> GetExtension() = 0; 922 923 /// 924 // Returns true if this browser is hosting an extension background script. 925 // Background hosts do not have a window and are not displayable. See 926 // CefRequestContext::LoadExtension for details. 927 /// 928 /*--cef()--*/ 929 virtual bool IsBackgroundHost() = 0; 930 931 /// 932 // Set whether the browser's audio is muted. 933 /// 934 /*--cef()--*/ 935 virtual void SetAudioMuted(bool mute) = 0; 936 937 /// 938 // Returns true if the browser's audio is muted. This method can only be 939 // called on the UI thread. 940 /// 941 /*--cef()--*/ 942 virtual bool IsAudioMuted() = 0; 943 }; 944 945 #endif // CEF_INCLUDE_CEF_BROWSER_H_ 946