CEF4Delphi

Description

CEF4Delphi is an open source project created by Salvador Díaz Fau to embed Chromium-based browsers in applications made with Delphi or Lazarus/FPC.

Introduction

CEF4Delphi is based on DCEF3, made by Henri Gourvest, which is adapted to the 2623 branch of CEF3. In order to have Chromium-based web browser tabs in BriskBard it's necessary to use the latest stable branch of CEF3 and have frequent updates. DCEF3 hasn't been updated in the last months so it was decided to create a new project.

The main goal of CEF4Delphi is to simplify, whenever is possible, the work necessary to upgrade it to the latest version of CEF3. To achieve this goal it was necessary to take the following measures :

  • Some redundancies were removed. The OSR TChromium component was merged into TChromium.
  • The code comments copied from CEF3 were removed. The comments in CEF3 are updated as frequently as the code and they can be replaced by a reference to the CEF3 file where you can find them.
  • The code is now spread over many smaller units.
  • There are new comments with the equivalencies between classes and types of CEF4Delphi and CEF3.

The latest version of CEF4Delphi uses the branch 3396 of CEF3. More precisely, it uses CEF 3.3440.1805.gbe070f9 which includes Chromium 68.0.3440.84

CEF4Delphi was developed and tested on Delphi 10.2 Tokyo and it has been tested in Delphi 7, Delphi XE, Delphi 10 and Lazarus 1.8.4 with FPC 3.0.4. CEF4Delphi includes VCL, FireMonkey (FMX) and Lazarus components tested in 32 and 64 bits.

If you wish to test CEF4Delphi consider downloading the latest Delphi Community Edition from Embarcadero for free.

It's also possible to test CEF4Delphi downloading Lazarus/FPC for free.

Overview

Before using CEF4Delphi with an aplication made with Delphi or Lazarus it's necessary to understand that CEF4Delphi is a wrapper that uses CEF3's C API and, in turn, CEF3 insulates the user from the underlying Chromium and Blink code complexity.

CEF4Delphi's overview

Links

CEF4Delphi project :

Chromium Embedded Framework (CEF3) project :

CEF3 binaries used by CEF4Delphi :

Compatibility

Google announced that they would drop Windows XP support for Chrome in 2015. The last CEF3 branch that was compatible with Windows XP was 2623, released in 2016.

Since CEF4Delphi uses the latest CEF3 branch, it's not compatible with Windows XP, Windows Vista, Windows Server 2003 and Windows Server 2008.

CEF4Delphi needs Windows 7, 8, 8.1, 10 or newer to make it work but if you need to test some other Windows version just download and try to run the CEF3 Sample Application from the CEF3's downloads page.

If you need to support Windows XP and Vista in your app use OldCEF4Delphi.

Installation

To build and install CEF4Delphi in the latest version of Delphi you need to follow these steps :

  1. Download the latest version of CEF4Delphi from GitHub.
  2. Decompress CEF4Delphi into a directory and make sure your user has write privileges in that directory.
  3. Run Delphi.
  4. Add the CEF4Delphi's source directory to the Library path in Delphi inside the Tools->Options menu. The Options window will show up and there you have to click on Environment Options->Delphi Options->Library, select the right platform (32 or 64 bits) and add directory in Library path.
  5. Open the file CEF4Delphi.dproj from Delphi if you only want the VCL components. If you want VCL and FireMonkey (FMX) components, open CEF4Delphi_FMX.dproj.
  6. Right-click on the CEF4Delphi.bpl icon inside the Project manager and select the Build option.
  7. Right-click on the CEF4Delphi.bpl icon inside the Project manager and select the Install option.

To compile and install CEF4Delphi in Delphi 7 you need to follow these steps :

  1. Download the latest version of CEF4Delphi from GitHub.
  2. Decompress CEF4Delphi into a directory and make sure your user has write privileges in that directory.
  3. Run Delphi.
  4. Add the CEF4Delphi's source directory to the Library path in Delphi inside the Tools->Environment options menu. The Environment Options window will show up and there you have to select the Library tab to modify the Library path.
  5. Open the file CEF4Delphi_D7.dpk from Delphi.
  6. Click on the Compile button.
  7. Click on the Install button.

To compile and install CEF4Delphi in Lazarus you need to follow these steps :

  1. Download the latest version of CEF4Delphi from GitHub.
  2. Decompress CEF4Delphi into a directory and make sure your user has write privileges in that directory.
  3. Run Lazarus.
  4. Open the file cef4delphi_lazarus.lpk from the Package->Open Package File (*.lpk)... menu.
  5. Click on the Compile button in the package window.
  6. Click on the Use button and select the Install option.

Usage

Before you use CEF4Delphi for the first time it's highly recommended to read all the information about CEF3 and the design documents of Chromium.

The CEF3 API documents are available at magpcss.org and there is extensive information about the CEF3 usage in its source code comments.

As you can see in the documentation, CEF3 uses multiple processes and it'll run the same executable or a different one to create them. That's why CEF3 needs to be initialized before TApplication runs.

CEF4Delphi simplifies all CEF3 initialization thanks to GlobalCEFApp, which is an instance of the TCEFApplication class.

Since TApplication must only be initialized and run in the main process, it's necessary to create GlobalCEFApp and call GlobalCEFApp.StartMainProcess to detect if that is the main process.

Delphi applications use to have this code in the DPR file :

program Project1; uses Vcl.Forms, Unit1 in 'Unit1.pas' {Form1}; {$R *.res} begin Application.Initialize; Application.MainFormOnTaskbar := True; Application.CreateForm(TForm1, Form1); Application.Run; end.

To include CEF4Delphi you only have to add uCEFApplication and WinApi.Windows to the uses clause, create the GlobalCEFApp global variable, call the GlobalCEFApp.StartMainProcess function and free GlobalCEFApp in the last step. You also have to add the SetPEFlags directive.

program Project1; uses Vcl.Forms, WinApi.Windows, uCEFApplication, Unit1 in 'Unit1.pas' {Form1}; {$R *.res} {$SetPEFlags IMAGE_FILE_LARGE_ADDRESS_AWARE} begin GlobalCEFApp := TCefApplication.Create; if GlobalCEFApp.StartMainProcess then begin Application.Initialize; Application.MainFormOnTaskbar := True; Application.CreateForm(TForm1, Form1); Application.Run; end; GlobalCEFApp.Free; end.

The GlobalCEFApp creation must be in the DPR file and the call to GlobalCEFApp.StartMainProcess must be in a if..then clause.

GlobalCEFApp.StartMainProcess will return True if it detects that it's running in the main process and only then Application.Initialize, Application.MainFormOnTaskbar, Application.CreateForm and Application.Run will only be executed.

If you wish a different CEF3 configuration you only have to modify the properties of GlobalCEFApp before the GlobalCEFApp.StartMainProcess function call.

Almost all TCefApplication's properties have the same meaning as the fields of cef_settings_t but it also includes the events from CefApp, CefBrowserProcessHandler, CefRenderProcessHandler and CefResourceBundleHandler.

Other properties in TCefApplication :

  • Cookies : Directory where the web browser cookies are stored.
  • DeleteCache : Set to True if you wish to delete the cache during initialization.
  • DeleteCookies : Set to True if you wish to delete the cookies during initialization.
  • FlashEnabled : Set to True if you wish to use the version of Adobe Flash Player (PPAPI) installed in the operating system.
  • CheckCEFFiles : Set to True if you wish to check the integrity of the CEF3 files during the initialization.
  • EnableMediaStream : Set to True if you wish to enable media (WebRTC audio/video) streaming.
  • EnableSpeechInput : Set to True if you wish to enable speech input (x-webkit-speech).
  • SmoothScrolling : Set to STATE_ENABLED, STATE_DISABLED or STATE_DEFAULT to enable smooth scroll animation.
  • FastUnload : Set to True to speed up the tab/window close.
  • EnableHighDPISupport : Set to True to support high DPI.
  • MuteAudio : Set to True to mute all audio.
  • EnableGPU : Set to True to enable hardware acceleration.
  • DisableSafeBrowsing : Set to True to disable the Google Safe Browsing features.
  • CustomFlashPath : Directory with the Adobe Flash libraries.
  • ShowMessageDlg : Set to True to show error messages in case some CEF3 files are missing.
  • SetCurrentDir : Set to True to set the current application directory before loading the CEF3 libraries.
  • ReRaiseExceptions : Set to True to enable internal exceptions.
  • CheckDevToolsResources : Set to True to check if the DevTools resources are present.
  • LocalesRequired : List of locale resources that need to be present.
  • SitePerProcess : Enforces a one-site-per-process security policy.
  • DisableWebSecurity : Disable the safety measures that block local files from being loaded.
  • ShutdownWaitTime : Time in milliseconds that TCefApplication will wait before shutting down.
  • MustFreeLibrary : Set to False with large apps to avoid shutdown problems.
  • DisablePDFExtension : Set to True to disable the PDF viewer and download PDF files automatically.

To add command line arguments use the AddCustomCommandLine procedure with any of the switches in these lists : peter.sh, cef_switches.cc.

If you need to use another executable for subprocesses check the SubProcess demo, configure the BrowserSubprocessPath property of TCefApplication with the name of the executable and create a crash_reporter.cfg file as described here.

After that, you must add different components depending on the type of application that you want :

  • Regular browser UI window : Add a TChromium and a TCEFWindowParent to the Form where you want to have a web browser and then call the CreateBrowser function with the TCEFWindowParent instance as the first parameter. Alternatively you can add a TChromiumWindow, which is a class that inherits from TCEFWindowParent and has a TChromium child control. Take a look at the SimpleBrowser and SimpleBrowser2 demos for more details.
  • Off-Screen Rendering : Add a TChromium to the Form and call the CreateBrowser without parameters. Be sure to set GlobalCEFApp.WindowlessRenderingEnabled to True. Check the SimpleOSRBrowser demo for more details.

As you can see in the source code, TChromium has the functions, procedures and events of :

Other properties and functions in TChromium that you may find interesting :

  • IncZoomStep, DecZoomStep, ResetZoomStep : Used to zoom in or out.
  • CustomHeaderName, CustomHeaderValue : Used to send customized headers on every request.
  • DoNotTrack : Set to True if you want to send the DNT header.
  • SendReferrer : Set to True if you want to send the 'referer' header.
  • ProxyType, ProxyServer, ProxyPort, ProxyUsername, ProxyPassword, ProxyScriptURL, ProxyByPassList : Proxy configuration as described here.
  • SpellChecking : Set to True if you want to enable the spell checker.
  • SpellCheckerDicts : Comma delimited list of language codes used by the spell checker, for example 'es-ES,en-US,fr-FR,de-DE,it-IT'.

As all other CEF3 applications, you must copy the CEF3 binary distribution files to the directory where your CEF4Delphi application is located. Those files are part of a package called Standard Distribution and it's available at the CEF3 downloads page.

Once you've downloaded and decompressed the Standard Distribution package for the windows platform of your choice, you must copy the contents of the Release and Resources directories to the directory of your application's exe. Here's an screenshot of the final layout :

Final layout of the CEF3 binary distribution files with the application.
Final layout of the CEF3 binary distribution files with the application.
Notice how cef_sandbox.lib and libcef.lib can be omitted.

In case you want to move all CEF3 binaries to another directory you can set the GlobalCEFApp.FrameworkDirPath, GlobalCEFApp.ResourcesDirPath and GlobalCEFApp.LocalesDirPath before the GlobalCEFApp.StartMainProcess call in the DPR file.

If the CEF3 binaries are not correctly copied in the right directory you may see these error messages depending on the GlobalCEFApp properties : CEF binaries missing, CEF framework files missing, CEF resources missing or CEF locale files missing.

It's extremely important to only use the version of the CEF3 binary distribution files specified in the introduction. CEF3 evolves very rapidly and changes are introduced in every version.

If you try to use a different version your application could crash or, depending on the GlobalCEFApp properties, you may see this error message : Unsupported CEF version.

Debugging

CEF3 uses several processes and that can make your app difficult to debug in Delphi but in those situations you can use the following tools :

  • Set GlobalCEFApp.SingleProcess to True before the GlobalCEFApp.StartMainProcess call in the DPR file. That will force CEF3 to use only one process and Delphi can debug it without problems. This single process mode should only be used for debugging purposes.
  • Use several processes but select the option Run->Run Without Debugging... in Delphi. Then click on Run->Attach To Process... and select the process you wish to debug.
  • Use the debug.log file to log custom text messages with the CefLog function like the DOMVisitor demo does. It's necesary to set the GlobalCEFApp.LogFile and GlobalCEFApp.LogSeverity properties before the GlobalCEFApp.StartMainProcess call in the DPR file.
  • In case of using javascript you can use the DevTools to read the console messages and to debug the javascript code. The MiniBrowser demo has all you need to add the DevTools to your app.

Demos

  • SimpleBrowser : The simplest web browser made with CEF4Delphi. It uses a TChromiumWindow component.
  • SimpleBrowser2 : The simplest web browser made with CEF4Delphi. It uses a combination of two components : TChromium and TCEFWindowParent.
  • MiniBrowser : A web browser using a TChromium and a TCEFWindowParent. It has custom context menus, basic web browser interface, developer tools, zoom, printing, proxy settings and some extra functions to copy the HTML and JavaScript printing.
  • SimpleOSRBrowser : A web browser using TChromium in OSR mode in case you need offscreen rendering.
  • CustomResourceBrowser : A simple browser that shows customized resources and web pages instead of Internet websites.
  • DOMVisitor : A basic DOM visitor using the CEF3 classes. It includes node search and DOM iteration.
  • FullScreenBrowser : Simple full screen browser that uses TChromium and TCEFWindowParent. It uses the ESC key to exit.
  • JavaScript : Set of JavaScript dialogs and integration demos with extensions, window bindings, function executions, evaluations and process messaging.
  • MDIBrowser : Multiple TChromium components in one MDI application.
  • ToolBoxBrowser : Multiple TChromium components in one application using ToolBox forms.
  • SchemeRegistrationBrowser : Complete URL scheme registration that shows customized web pages.
  • SubProcess : In case you can't use the main exe for all CEF3 processes you can use this demo.
  • CookieVisitor : Uses TCefCookieManagerRef to read all the cookies.
  • TabbedBrowser : Multiple TChromium and TCEFWindowParent components in tab sheets.
  • ExternalPumpBrowser : Browser made with the TChromium and TCEFWindowParent components using the external message pump configuration.
  • OSRExternalPumpBrowser : Browser in OSR mode using the external message pump configuration.
  • SimpleExternalPumpBrowser : Browser made with the TChromiumWindow component using the external message pump configuration.
  • SimpleServer : HTTP and websockets server made with the TCEFServerComponent component for communication between applications in localhost.
  • MDIExternalPumpBrowser : Multiple TChromium components in one MDI application using the external message pump configuration.
  • FMXExternalPumpBrowser : A web browser using TFMXChromium in a FireMonkey application.
  • ResponseFilterBrowser : A browser made with the TChromium and TCEFWindowParent components using a custom response filter.
  • PopupBrowser : This demo shows how to use custom forms with popup windows in OSR mode.
  • PopupBrowser2 : This demo shows how to use custom forms with popup windows in normal mode.
  • SimpleFMXBrowser : The simplest web browser made with CEF4Delphi and FireMonkey components. It uses TFMXChromium and TFMXWindowParent.
  • SimpleLazarusBrowser : The simplest web browser made with Lazarus and CEF4Delphi. It uses TChromium and TWindowParent.
  • SimpleLazOSRBrowser : A web browser made with Lazarus using TChromium in OSR mode.
  • DLLBrowser : A web browser created from a DLL.
  • FMXToolBoxBrowser : Multiple TFMXChromium components in one FireMonkey application using ToolBox forms.

To test the demos follow these instructions :

  1. Download the CEF3 binaries used by CEF4Delphi : 32 bit - 64 bit
  2. Decompress the CEF3 binaries in a temporary directory.
  3. Copy the contents from the Release and Resources directories to the BIN directory in CEF4Delphi.
  4. Build the demo.
  5. Run the demo.

Codecs

Due to licensing issues and the US patent law, the CEF3 binaries available at Spotify have the proprietary codecs disabled. If you use those binaries, any website that offers media using H264 won't work.

In case you need to use those codecs, you can build the CEF3 binaries yourself as described in this forum thread.

Browser plugins and extensions

Currently CEF3 only supports the Adobe Flash PPAPI plugin. NaCl plugins, NPAPI plugins and browser extensions are not supported but there's a feature request to add extensions.

Google dropped support of NPAPI plugins in Chromium 45 released in September 2015. Only the CEF3 branches older than 2454 support NPAPI plugins for Java, Silverlight or Facebook video.

About the name

CEF4Delphi is just a numeronym and it should be interpreted as CEF for Delphi. It doesn't mean that it's based in CEF4.

How to help

If you wish to help in this project you can make a donation by clicking this button :

You can also help by telling your friends about this project, sharing the messages of this project on the social networks, writing articles about this project on your website, making suggestions, reporting issues, etc.

If you shop online you can also help by using these links for your purchases :




This article was updated on August 4th, 2018.


Copyright © 2018  All rights reserved.
Cookie usage

By browsing our site you agree to our use of cookies. You will only see this message once.
Find out more
Ok