Click or drag to resize
ChromiumWebBrowser Class

[This is preliminary documentation and is subject to change.]

Windows Forms webbrowser control based on ChromiumFX.
Inheritance Hierarchy
SystemObject
  SystemMarshalByRefObject
    System.ComponentModelComponent
      System.Windows.FormsControl
        Chromium.WebBrowserChromiumWebBrowser

Namespace: Chromium.WebBrowser
Assembly: ChromiumWebBrowser (in ChromiumWebBrowser.dll)
Syntax
public class ChromiumWebBrowser : Control

The ChromiumWebBrowser type exposes the following members.

Constructors
  NameDescription
Public methodChromiumWebBrowser
Creates a ChromiumWebBrowser object with about:blank as initial URL. The underlying CfxBrowser is created immediately with the default CfxRequestContext.
Public methodChromiumWebBrowser(Boolean)
Creates a ChromiumWebBrowser object with about:blank as initial URL. If createImmediately is true, then the underlying CfxBrowser is created immediately with the default CfxRequestContext.
Public methodChromiumWebBrowser(String)
Creates a ChromiumWebBrowser object with the given initial URL. The underlying CfxBrowser is created immediately with the default CfxRequestContext.
Public methodChromiumWebBrowser(String, Boolean)
Creates a ChromiumWebBrowser object with the given initial URL. If createImmediately is true, then the underlying CfxBrowser is created immediately with the default CfxRequestContext.
Top
Properties
  NameDescription
Public propertyBrowser
Returns the CfxBrowser object for this ChromiumWebBrowser. Might be null if the browser has not yet been created. Wait for the BrowserCreated event before accessing this property.
Public propertyBrowserHost
Returns the CfxBrowserHost object for this ChromiumWebBrowser. Might be null if the browser has not yet been created. Wait for the BrowserCreated event before accessing this property.
Public propertyStatic memberBrowserProcessHandler
The CfxBrowserProcessHandler for this browser process. Do not access this property before calling ChromiumWebBrowser.Initialize()
Public propertyCanGoBack
Returns true if the browser can navigate backwards.
Public propertyCanGoForward
Returns true if the browser can navigate forwards.
Public propertyContextMenuHandler
Returns the context menu handler for this browser. If this is never accessed the default implementation will be used.
Public propertyStatic memberDefaultBrowserSettings
The CfxBrowserSettings applied for new instances of ChromiumWebBrowser. Any changes to these settings will only apply to new browsers, leaving already created browsers unaffected.
Public propertyDialogHandler
Returns the dialog handler for this browser. If this is never accessed the default implementation will be used.
Public propertyDisplayHandler
Returns the display handler for this browser.
Public propertyDownloadHandler
Returns the download handler for this browser. If this is never accessed downloads will not be allowed.
Public propertyDragHandler
Returns the drag handler for this browser.
Public propertyFindHandler
Returns the find handler for this browser.
Public propertyFindToolbar
Get the find toolbar of this browser window.
Public propertyFocusHandler
Returns the focus handler for this browser.
Public propertyGeolocationHandler
Returns the geolocation handler for this browser. If this is never accessed geolocation access will be denied by default.
Public propertyGlobalObject
Represents the main frame's global javascript object (window). Any changes to the global object's properties will be available after the next time a V8 context is created in the render process for the main frame of this browser.
Public propertyIsLoading
Returns true if the browser is currently loading.
Public propertyJsDialogHandler
Returns the js dialog handler for this browser. If this is never accessed the default implementation will be used.
Public propertyKeyboardHandler
Returns the keyboard handler for this browser.
Public propertyLifeSpanHandler
Returns the life span handler for this browser.
Public propertyLoadHandler
Returns the load handler for this browser.
Public propertyRemoteCallbackInvokeMode
The invoke mode for this browser. See also JSInvokeMode. Changes to the invoke mode will be effective after the next time the browser creates a V8 context. If this is set to "Inherit", then "Invoke" will be assumed. The invoke mode also applies to VisitDom and EvaluateJavascript.
Public propertyRemoteCallbacksWillInvoke
Indicates whether render process callbacks on this browser will be executed on the thread that owns the browser's underlying window handle. Depends on the invoke mode. If the invoke mode is set to "Inherit", then "Invoke" will be assumed.
Public propertyRequestHandler
Returns the request handler for this browser. Do not set the return value in the GetResourceHandler event for URLs with associated WebResources (see also SetWebResource).
Public propertyUrl
Returns the URL currently loaded in the main frame.
Top
Methods
  NameDescription
Public methodCreateBrowser
Creates the underlying CfxBrowser with the default CfxRequestContext. This method should only be called if this ChromiumWebBrowser was instanciated with createImmediately == false.
Public methodCreateBrowser(String)
Creates the underlying CfxBrowser with the default CfxRequestContext and the given initial URL. This method should only be called if this ChromiumWebBrowser was instanciated with createImmediately == false.
Public methodCreateBrowser(CfxRequestContext)
Creates the underlying CfxBrowser with the given CfxRequestContext. This method should only be called if this ChromiumWebBrowser was instanciated with createImmediately == false.
Public methodCreateBrowser(String, CfxRequestContext)
Creates the underlying CfxBrowser with the given CfxRequestContext and initial URL. This method should only be called if this ChromiumWebBrowser was instanciated with createImmediately == false.
Public methodEvaluateJavascript(String, ActionCfrV8Value, CfrV8Exception)
Evaluate a string of javascript code in the browser's main frame. Evaluation is done asynchronously in the render process. Returns false if the remote browser is currently unavailable. If this function returns false, then |callback| will not be called. Otherwise, |callback| will be called asynchronously in the context of the render thread and, if RemoteCallbackInvokeMode is set to Invoke, on the thread that owns the browser's underlying window handle. Use with care: The callback may never be called if the render process gets killed prematurely. On success the CfrV8Value argument of the callback will be set to the return value of the evaluated script, if any. On failure the CfrV8Exception argument of the callback will be set to the exception thrown by the evaluated script, if any. Do not block the callback since it blocks the render thread. *** WARNING *** In CEF 3.2623 and higher, the return value of the evaluation seems to be broken in some cases (see also issue #65).
Public methodEvaluateJavascript(String, JSInvokeMode, ActionCfrV8Value, CfrV8Exception)
Evaluate a string of javascript code in the browser's main frame. Evaluation is done asynchronously in the render process. Returns false if the remote browser is currently unavailable. If this function returns false, then |callback| will not be called. Otherwise, |callback| will be called asynchronously in the context of the render thread. If |invokeMode| is set to Invoke, |callback| will be called on the thread that owns the browser's underlying window handle. If |invokeMode| is set to Inherit, |callback| will be called according to RemoteCallbackInvokeMode. Use with care: The callback may never be called if the render process gets killed prematurely. On success the CfrV8Value argument of the callback will be set to the return value of the evaluated script, if any. On failure the CfrV8Exception argument of the callback will be set to the exception thrown by the evaluated script, if any. Do not block the callback since it blocks the render thread. *** WARNING *** In CEF 3.2623 and higher, the return value of the evaluation seems to be broken in some cases (see also issue #65).
Public methodExecuteJavascript(String)
Execute a string of javascript code in the browser's main frame. Execution is asynchronous, this function returns immediately. Returns false if the browser has not yet been created.
Public methodExecuteJavascript(String, String, Int32)
Execute a string of javascript code in the browser's main frame. The |scriptUrl| parameter is the URL where the script in question can be found, if any. The renderer may request this URL to show the developer the source of the error. The |startLine| parameter is the base line number to use for error reporting. Execution is asynchronous, this function returns immediately. Returns false if the browser has not yet been created.
Public methodFind(String)
Search for |searchText|. The search will be forward and case-insensitive. Returns the identifier for this find operation (see also CfxFindHandler), or -1 if the browser has not yet been created.
Public methodFind(String, Boolean)
Search for |searchText|. |forward| indicates whether to search forward or backward within the page. The search will be case-insensitive. Returns the identifier for this find operation (see also CfxFindHandler), or -1 if the browser has not yet been created.
Public methodFind(String, Boolean, Boolean)
Search for |searchText|. |forward| indicates whether to search forward or backward within the page. |matchCase| indicates whether the search should be case-sensitive. Returns the identifier for this find operation (see also CfxFindHandler), or -1 if the browser has not yet been created.
Public methodGlobalObjectForFrame
Represents a named frame's global javascript object (window). Any changes to the global object's properties will be available after the next time a V8 context is created in the render process of this browser for a frame with this name.
Public methodGoBack
Navigate backwards.
Public methodGoForward
Navigate forwards.
Public methodStatic memberInitialize
Initialize the ChromiumWebBrowser and ChromiumFX libraries. The application can change initialization settings by handling the OnBeforeCfxInitialize event.
Public methodLoadString(String)
Load the contents of |stringVal| with dummy url about:blank.
Public methodLoadString(String, String)
Load the contents of |stringVal| with the specified dummy |url|. |url| should have a standard scheme (for example, http scheme) or behaviors like link clicks and web security restrictions may not behave as expected.
Public methodLoadUrl
Load the specified |url| into the main frame.
Protected methodOnGotFocus (Overrides ControlOnGotFocus(EventArgs).)
Protected methodOnResize (Overrides ControlOnResize(EventArgs).)
Protected methodOnVisibleChanged (Overrides ControlOnVisibleChanged(EventArgs).)
Public methodRemoveWebResource
Remove a resource previously set for the specified URL.
Public methodRenderThreadInvoke(MethodInvoker)
Special Invoke for framework callbacks from the render process. Maintains the thread within the context of the calling remote thread. Use this instead of invoke when the following conditions are meat: 1) The current thread is executing in the scope of a framework callback event from the render process (ex. CfrTask.Execute). 2) You need to Invoke on the webbrowser control and 3) The invoked code needs to call into the render process.
Public methodRenderThreadInvoke(Delegate, Object)
Special Invoke for framework callbacks from the render process. Maintains the thread in the context of the calling remote thread. Use this instead of invoke when the following conditions are meat: 1) The current thread is executing in the scope of a framework callback event from the render process (ex. CfrTask.Execute). 2) You need to Invoke on the webbrowser control and 3) The invoked code needs to call into the render process.
Public methodSetWebResource
Set a resource to be used for the specified URL. Note that these resources are kept in the memory. If you need to handle a lot of custom web resources, subscribing to RequestHandler.GetResourceHandler and loading from disk on demand might be a better choice.
Public methodStatic memberShutdown
This function should be called on the main application thread to shut down the CEF browser process before the application exits.
Public methodVisitDom
Visit the DOM in the remote browser's main frame. Returns false if the remote browser is currently unavailable. If this function returns false, then |callback| will not be called. Otherwise, |callback| will be called according to the InvokeMode setting. The document object passed to the callback represents a snapshot of the DOM at the time the callback is executed. DOM objects are only valid for the scope of the callback. Do not keep references to or attempt to access any DOM objects outside the scope of the callback. Use with care: The callback may never be called if the render process gets killed prematurely. Do not keep a reference to the remote DOM or remote browser object after returning from the callback. Do not block the callback since it blocks the renderer thread. Explicitly Dispose() all CfrDomNode objects, otherwise the render process may become unstable and crash.
Top
Events
  NameDescription
Public eventBrowserCreated
Raised after the CfxBrowser object for this WebBrowser has been created. The event is executed on the thread that owns this browser control's underlying window handle.
Public eventStatic memberOnBeforeCfxInitialize
Provides an opportunity to change initialization settings and subscribe to browser process handler events.
Public eventStatic memberOnBeforeCommandLineProcessing
Provides an opportunity to view and/or modify command-line arguments before processing by CEF and Chromium. The |ProcessType| value will be NULL for the browser process. Do not keep a reference to the CfxCommandLine object passed to this function. The CfxSettings.CommandLineArgsDisabled value can be used to start with an NULL command-line object. Any values specified in CfxSettings that equate to command-line arguments will be set before this function is called. Be cautious when using this function to modify command-line arguments for non-browser processes as this may result in undefined behavior including crashes.
Public eventOnBeforeContextMenu Obsolete.
Public eventOnContextMenuCommand Obsolete.
Public eventOnLoadingStateChange Obsolete.
Public eventStatic memberOnRegisterCustomSchemes
Provides an opportunity to register custom schemes. Do not keep a reference to the |Registrar| object. This function is called on the main thread for each process and the registered schemes should be the same across all processes.
Public eventStatic memberOnRemoteContextCreated Obsolete.
Public eventOnV8ContextCreated
Called immediately after the V8 context for a frame has been created. To retrieve the JavaScript 'window' object use the CfrV8Context.GetGlobal() function. V8 handles can only be accessed from the thread on which they are created. A task runner for posting tasks on the associated thread can be retrieved via the CfrV8Context.GetTaskRunner() function. All javascript properties/functions defined through GlobalObject or GlobalObjectForFrame are made available before this event is executed. If RemoteCallbackInvokeMode is set to Invoke, then this event is executed on the thread that owns the browser's underlying window handle.
Public eventRemoteBrowserCreated
Called after a remote browser has been created. When browsing cross-origin a new browser will be created before the old browser is destroyed. Applications may keep a reference to the CfrBrowser object outside the scope of this event, but you have to be aware that those objects become invalid as soon as the framework swaps render processes and/or recreates browsers.
Public eventStatic memberRemoteProcessCreated
For each new render process created, provides an opportunity to subscribe to CfrRenderProcessHandler remote callback events.
Top
See Also