CefSharp.WinForms

ChromiumWebBrowser is the WinForms web browser control

Used as workaround for issue https://github.com/cefsharp/CefSharp/issues/3021

The browser initialized - boolean represented as 0 (false) and 1(true) as we use Interlocker to increment/reset

A flag that indicates if you can execute javascript in the main frame. Flag is set to true in IRenderProcessMessageHandler.OnContextCreated. and false in IRenderProcessMessageHandler.OnContextReleased

Implement and assign to handle dialog events.

The dialog handler.

Implement and assign to handle events related to JavaScript Dialogs.

The js dialog handler.

Implement and assign to handle events related to key press.

The keyboard handler.

Implement and assign to handle events related to browser requests.

The request handler.

Implement and assign to handle events related to downloading files.

The download handler.

Implement and assign to handle events related to browser load status.

The load handler.

Implement and assign to handle events related to popups.

The life span handler.

Implement and assign to handle events related to browser display state.

The display handler.

Implement and assign to handle events related to the browser context menu

The menu handler.

Implement and assign to handle messages from the render process.

The render process message handler.

Implement to handle events related to find results.

The find handler.

Implement to handle audio events.

The for this ChromiumWebBrowser.

The focus handler. If you need customized focus handling behavior for WinForms, the suggested best practice would be to inherit from DefaultFocusHandler and try to avoid needing to override the logic in OnGotFocus. The implementation in DefaultFocusHandler relies on very detailed behavior of how WinForms and Windows interact during window activation.

Implement and assign to handle events related to dragging.

The drag handler.

Implement and control the loading of resources

The resource handler factory.

Event handler that will get called when the resource load for a navigation fails or is canceled. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

Event handler that will get called when the browser begins loading a frame. Multiple frames may be loading at the same time. Sub-frames may start or continue loading after the main frame load has ended. This method may not be called for a particular frame if the load request for that frame fails. For notification of overall browser load status use OnLoadingStateChange instead. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

Whilst this may seem like a logical place to execute js, it's called before the DOM has been loaded, implement as it's called when the underlying V8Context is created

Event handler that will get called when the browser is done loading a frame. Multiple frames may be loading at the same time. Sub-frames may start or continue loading after the main frame load has ended. This method will always be called for all frames irrespective of whether the request completes successfully. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

Event handler that will get called when the Loading state has changed. This event will be fired twice. Once when loading is initiated either programmatically or by user action, and once when loading is terminated due to completion, cancellation of failure. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

Event handler for receiving Javascript console messages being sent from web pages. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).

Event handler for changes to the status message. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).

Event handler that will get called when the message that originates from CefSharp.PostMessage

A flag that indicates whether the WebBrowser is initialized (true) or not (false).

true if this instance is browser initialized; otherwise, false.

Handles the event.

The instance containing the event data.

Handles the event.

The instance containing the event data.

Handles the event.

The instance containing the event data.

Handles the event.

The instance containing the event data.

Handles the event.

The instance containing the event data.

Gets or sets a value indicating whether this instance has parent.

true if this instance has parent; otherwise, false.

Gets the browser adapter.

The browser adapter.

Sets the handler references to null. Where required also calls Dispose().

Check is browser is initialized

true if browser is initialized

Throw exception if browser not initialized.

Thrown when an exception error condition occurs.

Throw exception if disposed.

Thrown when a supplied object has been disposed.

The managed cef browser adapter

The parent form message interceptor

The browser

A flag that indicates whether or not the designer is active NOTE: DesignMode becomes false by the time we get to the destructor/dispose so it gets stored here

A flag that indicates whether or not has been called.

Has the underlying Cef Browser been created (slightly different to initialized in that the browser is initialized in an async fashion)

A flag indicating if the was used when calling CreateBrowser If false and contains a non empty string Load will be called on the main frame

If true the the WS_EX_NOACTIVATE style will be removed so that future mouse clicks inside the browser correctly activate and focus the window.

Browser initialization settings

The request context (we deliberately use a private variable so we can throw an exception if user attempts to set after browser created)

The value for disposal, if it's 1 (one) then this instance is either disposed or in the process of getting disposed

Parking control used to temporarily host the CefBrowser instance when is true.

This flag is set when the browser gets focus before the underlying CEF browser has been initialized.

Gets a value indicating whether this instance is disposed.

if this instance is disposed; otherwise, .

Gets or sets the browser settings.

The browser settings.

Activates browser upon creation, the default value is false. Prior to version 73 the default behaviour was to activate browser on creation (Equivalent of setting this property to true). To restore this behaviour set this value to true immediately after you create the instance. https://bitbucket.org/chromiumembedded/cef/issues/1856/branch-2526-cef-activates-browser-window

Gets or sets the request context.

The request context.

A flag that indicates whether the control is currently loading one or more web pages (true) or not (false).

true if this instance is loading; otherwise, false. In the WPF control, this property is implemented as a Dependency Property and fully supports data binding.

The text that will be displayed as a ToolTip

The tooltip text.

The address (URL) which the browser control is currently displaying. Will automatically be updated as the user navigates to another page (e.g. by clicking on a link).

The address. In the WPF control, this property is implemented as a Dependency Property and fully supports data binding.

Occurs when the browser address changed. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

Occurs when the browser title changed. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

Event called after the underlying CEF browser instance has been created. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.

A flag that indicates whether the state of the control currently supports the GoForward action (true) or not (false).

true if this instance can go forward; otherwise, false. In the WPF control, this property is implemented as a Dependency Property and fully supports data binding.

A flag that indicates whether the state of the control current supports the GoBack action (true) or not (false).

true if this instance can go back; otherwise, false. In the WPF control, this property is implemented as a Dependency Property and fully supports data binding.

A flag that indicates whether the WebBrowser is initialized (true) or not (false).

true if this instance is browser initialized; otherwise, false.

ParentFormMessageInterceptor hooks the Form handle and forwards the move/active messages to the browser, the default is true and should only be required when using set to true.

By default when is called the underlying Browser Hwnd is only parked (moved to a temp parent) when is true, there are a few other cases where parking of the control is desired, you can force parking by setting this property to true.

You may wish to set this property to true when using the browser in conjunction with https://github.com/dockpanelsuite/dockpanelsuite

Initializes static members of the class.

Handles the event.

The sender. The instance containing the event data.

This constructor exists as the WinForms designer requires a parameterless constructor, if you are instantiating an instance of this class in code then use the constructor overload instead. Using this constructor in code is unsupported and you may experience 's when attempting to access some of the properties immediately after instantiation.

Initializes a new instance of the class. **Important** - When using this constructor the property will default to .

html string to be initially loaded in the browser. (Optional) Request context that will be used for this browser instance, if null the Global Request Context will be used.

Initializes a new instance of the class. **Important** - When using this constructor the property will default to .

The address. (Optional) Request context that will be used for this browser instance, if null the Global Request Context will be used.

Required for designer support - this method cannot be inlined as the designer will attempt to load libcef.dll and will subsequently throw an exception. TODO: Still not happy with this method name, need something better

If not in design mode; Releases unmanaged and - optionally - managed resources for the

to release both managed and unmanaged resources; to release only unmanaged resources.

Releases unmanaged and - optionally - managed resources for the

to release both managed and unmanaged resources; to release only unmanaged resources. This method cannot be inlined as the designer will attempt to load libcef.dll and will subsequently throw an exception.

Loads the specified URL.

The URL to be loaded.

The javascript object repository, one repository per ChromiumWebBrowser instance.

Raises the event.

An that contains the event data.

Override this method to handle creation of WindowInfo. This method can be used to customise aspects of browser creation including configuration of settings such as . Window Activation is disabled by default, you can re-enable it by overriding and removing the WS_EX_NOACTIVATE style from .

Window handle for the Control Window Info To re-enable Window Activation then remove WS_EX_NOACTIVATE from ExStyle


             const uint WS_EX_NOACTIVATE = 0x08000000;
             windowInfo.ExStyle &= ~WS_EX_NOACTIVATE;

Called after browser created.

The browser.

Sets the address.

The instance containing the event data.

Sets the loading state change.

The instance containing the event data.

Sets the title.

The instance containing the event data.

Sets the tooltip text.

The tooltip text.

Manually implement Focused because cef does not implement it.

true if focused; otherwise, false. This is also how the Microsoft's WebBrowserControl implements the Focused property.

When minimized set the browser window size to 0x0 to reduce resource usage. https://github.com/chromiumembedded/cef/blob/c7701b8a6168f105f2c2d6b239ce3958da3e3f13/tests/cefclient/browser/browser_window_std_win.cc#L87

Show the browser (called after previous minimised)

Returns the current IBrowser Instance

browser instance or null

Initialization settings. Many of these and other settings can also configured using command-line switches.

ChromiumWebBrowser Control Designer

Receives a call when the control that the designer is managing has painted its surface so the designer can paint any additional adornments on top of the control.

args

Adjusts the set of properties the component exposes through a TypeDescriptor.

properties

ChromiumWidgetHandleFinder is a helper class used to find the child Hwnd for the browser instance.

Class Name of the Chrome_RenderWidgetHostHWND Child Window

EnumWindowProc delegate used by

A handle to a child window of the parent window specified in EnumChildWindows The application-defined value given in EnumChildWindows To continue enumeration, the callback function must return true; to stop enumeration, it must return false.

Chromium's message-loop Window isn't created synchronously, so this may not find it. If so, you need to wait and try again later.

ChromiumWebBrowser instance Handle of the child HWND with the name returns true if the HWND was found otherwise false.

Helper function used to find the child HWND with the ClassName matching Chromium's message-loop Window isn't created synchronously, so this may not find it. If so, you need to wait and try again later. In most cases you should use the overload.

control Handle class name used to match Handle of the child HWND with the name returns true if the HWND was found otherwise false.

Provides a convenient implement that can be used without having to create your own class

ChromiumWidgetMessageInterceptor constructor

Control is used to handled the event so we can automatically call . If null then you are responsible for calling Hwnd to intercept messages for.

Func to be used to intercept messages, null to clear an existing function.

Called when the has been created. When called you must add the control to it's intended parent so the can be calculated to set the initial size correctly.

popup host control url

Called when the is to be removed from it's parent. When called you must remove/dispose of the .

popup host control browser

A WinForms Specific implementation that simplifies the process of hosting a Popup as a Control/Tab. This implementation returns true in so no WM_CLOSE message is sent, this differs from the default CEF behaviour.

NOTE: DevTools popups DO NOT trigger OnBeforePopup.

The will be called when the has been created. When the is called you must add the control to it's intended parent so the can be calculated to set the initial size correctly.

Action to be invoked when the Popup is to be destroyed. instance allowing you to chain method calls together

The will be called when the is to be removed from it's parent. When the is called you must remove/dispose of the .

Action to be invoked when the Popup is to be destroyed. instance allowing you to chain method calls together

Create a new instance of the which can be used to create a WinForms specific implementation that simplifies the process of hosting a Popup as a Control/Tab.

LifeSpanHandlerBuilder

Fluent LifeSpanHandler Builder

The will be called when the has been created. When the is called you must add the control to it's intended parent so the can be calculated to set the initial size correctly.

Action to be invoked when the Popup is to be destroyed. instance allowing you to chain method calls together

The will be called when the is to be removed from it's parent. When the is called you must remove/dispose of the .

Action to be invoked when the Popup is to be destroyed. instance allowing you to chain method calls together

Creates an implementation that can be used to host popups as tabs/controls. The resulting returns true in so no WM_CLOSE message is sent, this differs from the default CEF behaviour.

a instance

Chromium Browser Host Control, provides base functionality for hosting a CefBrowser instance (main browser and popups) in WinForms.

IntPtr that represents the CefBrowser Hwnd Used for sending messages to the browser e.g. resize

Set to true while handing an activating WM_ACTIVATE message. MUST ONLY be cleared by DefaultFocusHandler.

true if this instance is activating; otherwise, false.

Gets the default size of the control.

The default of the control.

Makes certain keys as Input keys when CefSettings.MultiThreadedMessageLoop = false

key data true for a select list of keys otherwise defers to base.IsInputKey

Raises the event.

An that contains the event data.

Resizes the browser to the specified and . If and are both 0 then the browser will be hidden and resource usage will be minimised.

width height

Resizes the browser.

width height To avoid the Designer trying to load CefSharp.Core.Runtime we explicitly ask for NoInlining.

Show the browser (called after previous minimised)

Default implementation of for the WinForms implementation

Called when the browser component has received focus.

the ChromiumWebBrowser control the browser object Try to avoid needing to override this logic in a subclass. The implementation in DefaultFocusHandler relies on very detailed behavior of how WinForms and Windows interact during window activation.

Called when the browser component is requesting focus.

the ChromiumWebBrowser control the browser object Indicates where the focus request is originating from. Return false to allow the focus to be set or true to cancel setting the focus.

Called when the browser component is about to lose focus. For instance, if focus was on the last HTML element and the user pressed the TAB key.

the ChromiumWebBrowser control the browser object Will be true if the browser is giving focus to the next component and false if the browser is giving focus to the previous component.

ControlExtensions.

Executes the Action asynchronously on the UI thread, does not block execution on the calling thread. No action will be performed if the control doesn't have a valid handle or the control is Disposed/Disposing.

the control for which the update is required action to be performed on the control

Executes the Action sync on the UI thread, blocks execution on the calling thread. No action will be performed if the control doesn't have a valid handle or the control is Disposed/Disposing.

the control for which the update is required action to be performed on the control

Activates the specified control.

The control. true if XXXX, false otherwise.

Returns whether the supplied control is the currently active control.

the control to check true if the control is the currently active control

Selects the next control.

The control. if set to true [next].

ParentFormMessageInterceptor - hooks into the parent forms message loop to incercept messages like WM_MOVE

Keep track of whether a move is in progress.

Used to determine the coordinates involved in the move

Store the previous window state, used to determine if the Windows was previously and resume rendering

Gets or sets the browser.

The browser.

Gets or sets the parent form.

The parent form.

Called when the parent form is moving

Initializes a new instance of the class.

The browser.

Call to force refinding of the parent Form. (i.e. top level window that owns the ChromiumWebBrowserControl)

Adjust the form to listen to if the ChromiumWebBrowserControl's parent changes.

The ChromiumWebBrowser whose parent has changed. The instance containing the event data.

Handles the event.

The sender. The instance containing the event data.

Handles the event.

The sender. The instance containing the event data.

Invokes the default window procedure associated with this window.

A that is associated with the current Windows message.

Called when [moving].

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Releases unmanaged and - optionally - managed resources.

true to release both managed and unmanaged resources; false to release only unmanaged resources.

When overridden in a derived class, manages an unhandled thread exception.

An that specifies the unhandled thread exception.

Class NativeMethods.

The w m_ move

The w m_ moving

The w m_ activate

WinForms specific implementation, has events the implementation exposes.

Helper extensions for performing common CefSharp related WinForms tasks

Manually call https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-destroywindow passing in the handle returned from . This method can be used to manually close the underlying CefBrowser instance. This will avoid the WM_Close message that CEF sends by default to the top level window. (Which closes your application). This method should generally only be used in the WinForms version.

the ChromiumWebBrowser instance If the function succeeds, the return value is true.


            //Invoke on the CEF UI Thread
            Cef.UIThreadTaskFactory.StartNew(() =>
            {
              var closed = chromiumWebBrowser.DestroyWindow();
            });

Open DevTools using as the parent control. If inspectElementAtX and/or inspectElementAtY are specified then the element at the specified (x,y) location will be inspected. For resize/moving to work correctly you will need to use the implementation. (Set to an instance of )

instance Control used as the parent for DevTools (a custom control will be added to the collection) x coordinate (used for inspectElement) y coordinate (used for inspectElement) Returns the that hosts the DevTools instance if successful, otherwise returns null on error.

Open DevTools using your own Control as the parent. If inspectElementAtX and/or inspectElementAtY are specified then the element at the specified (x,y) location will be inspected. For resize/moving to work correctly you will need to use the implementation. (Set to an instance of )

instance Action that is Invoked when the DevTools Host Control has been created and needs to be added to it's parent. It's important the control is added to it's intended parent at this point so the can be calculated to set the initial display size. x coordinate (used for inspectElement) y coordinate (used for inspectElement) Returns the that hosts the DevTools instance if successful, otherwise returns null on error.