Table of Contents
Table of Contents
Managing Browser Engine

EO.WebBrowser supports multiple browser engines in a single application. A browser engine can be dynamically created and shut down by code and provides isolation to sessions, history, cache and cookies. Typical usage of separate browser engine includes supporting incognito mode or multiple user session in the same application. You can also apply different engine options (such as proxy settings) on different engine.

Default Engine and Additional Engines

Setting Engine Options

Associating an Engine to a WebView

Starting and Stopping an Engine

Default Engine and Additional Engines

By default, all WebViews are created using the "Default" engine, which can be accessed through the EO.WebEngine.Engine.Default static property.

You can also create additional engines through code via EO.WebEngine.Engine.Create method. The following code demonstrates how to create a new engine with name "test":

Copy 
//Create an Engine with name "test"
EO.WebEngine.Engine engine = EO.WebEngine.Engine.Create("test");

Once an engine is created, you can access it through the Engine class's FromName or FromID method. Note that multiple engines can have the same names but each engine always have a unique ID. If you create multiple engines with the same name, then only the last one will be returned by FromName method.

Setting Engine Options

Each Engine maintains its own copy of engine options, which can be accessed through EO.WebEngine.Engine.Options property. The following code demonstrates how to set the UI language of an engine:

Copy 
//Set the engine's UI language to French
engine.Options.UILanguage = "fr";

It is common that you may not need any additional engine and only need to set the options for the default engine. The following code demonstrates how to set the options for the default engine:

Copy 
//Set the default engine's UI language to French
EO.WebEngine.Engine.Default.Options.UILanguage = "fr";

Note that engine options are applied when the engine starts, which typically occurs when the first WebView that uses the engine is created. As such setting engine options after that point would have no effect.

Each engine also maintains an instance of an EO.WebEngine.WebViewOptions that serves as the default WebView options of all WebViews managed by that engine. See here for more information on how to set WebView options (options for each WebView instance).

Associating an Engine to a WebView

By default, a WebView is automatically associated to the Default engine unless you explicitly associate it to a different engine. You can associate it to a different engine by setting the WebView's Engine property before creating the WebView. The following code associates "webView1" to "engine1":

Copy 
//Associate webView1 to engine1
webView1.Engine = engine1;

Note that you must set the Engine property before the WebView has been created, otherwise an exception will be thrown.

To associate an engine to a WebView created through a ThreadRunner object, pass the engine object to the ThreadRunner's constructor:

Copy 
//Create a ThreadRunner and associate it to engine1
EO.WebBrowser.ThreadRunner threadRunner = new EO.WebBrowser.ThreadRunner(engine1);

//Create a new WebView through the ThreadRunner, since the
//ThreadRunner is associated to engine1, the WebView is also
//automatically associated to engine1
EO.WebBrowser.WebView webView = threadRunner.CreateWebView();

Starting and Stopping an Engine

Generally, it is not necessary to explicitly either start or stop an engine.

You can call the Engine's Start method to start the browser engine, but usually this is not necessary since Start will be automatically called when the first WebView associated to the engine is being created. One reason you may want to call Start explicitly is to speed up WebView creation time. For example, if you do not need a WebView immediately after your application starts, you can start the engine in the background so that when a WebView is needed the engine has already been initialized.

All engines are automatically stopped when your application exits. So it is not necessary for you to stop them explicitly. However sometimes you may want to explicitly stop an engine earlier, especially if your application needs to repeatedly create new engines. In that case you should call the engine's Stop method to stop those engines you no longer needs to save resources.

You may also call Stop and pass true to the deleteCache parameter to automatically delete the cache used by that engine as soon as the engine stops.

Once an Engine is stopped, it can not be restarted unless its AllowRestart property is set to true. All WebViews associated to the engine are also automatically destroyed when an engine stops.