From 312c9530bba3a50812471ef7d780396d01af2382 Mon Sep 17 00:00:00 2001 From: salvadordf Date: Thu, 3 Aug 2023 15:50:13 +0200 Subject: [PATCH] Added more XML documentation --- source/uCEFApp.pas | 11 +- source/uCEFApplication.pas | 7 +- source/uCEFApplicationCore.pas | 1450 ++++++++++++++++++++------ source/uCEFBrowserProcessHandler.pas | 25 +- source/uCEFInterfaces.pas | 229 ++++ source/uCEFLoadHandler.pas | 59 +- source/uCEFRenderProcessHandler.pas | 24 +- source/uCEFResourceBundleHandler.pas | 9 +- source/uCEFTypes.pas | 21 + update_CEF4Delphi.json | 2 +- 10 files changed, 1456 insertions(+), 381 deletions(-) diff --git a/source/uCEFApp.pas b/source/uCEFApp.pas index e90b466c..6bad23c9 100644 --- a/source/uCEFApp.pas +++ b/source/uCEFApp.pas @@ -58,10 +58,11 @@ uses type /// - /// + /// Implement this interface to provide handler implementations. Methods will be + /// called by the process and/or thread indicated. /// /// - /// Implements ICefApp + /// CEF source file: /include/capi/cef_app_capi.h (cef_app_t) /// TCefAppOwn = class(TCefBaseRefCountedOwn, ICefApp) protected @@ -275,7 +276,8 @@ end; procedure TCustomCefApp.OnBeforeCommandLineProcessing(const processType: ustring; const commandLine: ICefCommandLine); begin try - if (FCefApp <> nil) then FCefApp.Internal_OnBeforeCommandLineProcessing(processType, commandLine); + if (FCefApp <> nil) then + IAppplicationCoreEvents(FCefApp).doOnBeforeCommandLineProcessing(processType, commandLine); except on e : exception do if CustomExceptionHandler('TCustomCefApp.OnBeforeCommandLineProcessing', e) then raise; @@ -285,7 +287,8 @@ end; procedure TCustomCefApp.OnRegisterCustomSchemes(const registrar: TCefSchemeRegistrarRef); begin try - if (FCefApp <> nil) then FCefApp.Internal_OnRegisterCustomSchemes(registrar); + if (FCefApp <> nil) then + IAppplicationCoreEvents(FCefApp).doOnRegisterCustomSchemes(registrar); except on e : exception do if CustomExceptionHandler('TCustomCefApp.OnRegisterCustomSchemes', e) then raise; diff --git a/source/uCEFApplication.pas b/source/uCEFApplication.pas index 639d9f46..3536d0f4 100644 --- a/source/uCEFApplication.pas +++ b/source/uCEFApplication.pas @@ -94,6 +94,7 @@ type FContextInitializedHandlers : TMethodList; procedure CallContextInitializedHandlers(Data: PtrInt); + procedure doOnContextInitialized; override; {$ENDIF} procedure BeforeInitSubProcess; override; @@ -107,8 +108,6 @@ type property DestroyAppWindows : boolean read FDestroyAppWindows write FDestroyAppWindows; {$IFDEF FPC} - procedure Internal_OnContextInitialized; override; // In UI thread - Procedure AddContextInitializedHandler(AHandler: TNotifyEvent); Procedure RemoveContextInitializedHandler(AHandler: TNotifyEvent); {$ENDIF} @@ -268,9 +267,9 @@ begin end; {$IFDEF FPC} -procedure TCefApplication.Internal_OnContextInitialized; +procedure TCefApplication.doOnContextInitialized; begin - inherited Internal_OnContextInitialized; + inherited doOnContextInitialized; Application.QueueAsyncCall(@CallContextInitializedHandlers, 0); end; diff --git a/source/uCEFApplicationCore.pas b/source/uCEFApplicationCore.pas index f4321ee2..a659a45b 100644 --- a/source/uCEFApplicationCore.pas +++ b/source/uCEFApplicationCore.pas @@ -94,7 +94,7 @@ type /// /// Parent class of TCefApplication used to simplify the CEF initialization and destruction. /// - TCefApplicationCore = class + TCefApplicationCore = class(TInterfacedObject, IAppplicationCoreEvents) protected // Fields used to populate TCefSettings FNoSandbox : boolean; @@ -142,8 +142,6 @@ type FForceFieldTrials : ustring; FForceFieldTrialParams : ustring; FSmoothScrolling : TCefState; - FFastUnload : boolean; - FDisableSafeBrowsing : boolean; FMuteAudio : boolean; FSitePerProcess : boolean; FDisableWebSecurity : boolean; @@ -267,10 +265,6 @@ type procedure SetResourcesDirPath(const aValue : ustring); procedure SetLocalesDirPath(const aValue : ustring); {$IFDEF MSWINDOWS} - /// - /// Set to true (1) before calling Windows APIs like TrackPopupMenu that enter a - /// modal message loop. Set to false (0) after exiting the modal message loop. - /// procedure SetOsmodalLoop(aValue : boolean); {$ENDIF} procedure SetKioskPrinting(aValue : boolean); @@ -357,6 +351,38 @@ type function Load_cef_types_linux_h : boolean; function Load_cef_time_h : boolean; + // ICefApp + procedure doOnBeforeCommandLineProcessing(const processType: ustring; const commandLine: ICefCommandLine); virtual; + procedure doOnRegisterCustomSchemes(const registrar: TCefSchemeRegistrarRef); virtual; + + // ICefBrowserProcessHandler + procedure doOnRegisterCustomPreferences(type_: TCefPreferencesType; registrar: PCefPreferenceRegistrar); virtual; + procedure doOnContextInitialized; virtual; + procedure doOnBeforeChildProcessLaunch(const commandLine: ICefCommandLine); virtual; + procedure doOnScheduleMessagePumpWork(const delayMs: Int64); virtual; + procedure doGetDefaultClient(var aClient : ICefClient); virtual; + + // ICefResourceBundleHandler + function doGetLocalizedString(stringid: Integer; var stringVal: ustring): Boolean; virtual; + function doGetDataResource(resourceId: Integer; var data: Pointer; var dataSize: NativeUInt): Boolean; virtual; + function doGetDataResourceForScale(resourceId: Integer; scaleFactor: TCefScaleFactor; var data: Pointer; var dataSize: NativeUInt): Boolean; virtual; + + // ICefRenderProcessHandler + procedure doOnWebKitInitialized; virtual; + procedure doOnBrowserCreated(const browser: ICefBrowser; const extra_info: ICefDictionaryValue); virtual; + procedure doOnBrowserDestroyed(const browser: ICefBrowser); virtual; + procedure doOnContextCreated(const browser: ICefBrowser; const frame: ICefFrame; const context: ICefv8Context); virtual; + procedure doOnContextReleased(const browser: ICefBrowser; const frame: ICefFrame; const context: ICefv8Context); virtual; + procedure doOnUncaughtException(const browser: ICefBrowser; const frame: ICefFrame; const context: ICefv8Context; const V8Exception: ICefV8Exception; const stackTrace: ICefV8StackTrace); virtual; + procedure doOnFocusedNodeChanged(const browser: ICefBrowser; const frame: ICefFrame; const node: ICefDomNode); virtual; + procedure doOnProcessMessageReceived(const browser: ICefBrowser; const frame: ICefFrame; sourceProcess: TCefProcessId; const aMessage: ICefProcessMessage; var aHandled : boolean); virtual; + + // ICefLoadHandler + procedure doOnLoadingStateChange(const browser: ICefBrowser; isLoading, canGoBack, canGoForward: Boolean); virtual; + procedure doOnLoadStart(const browser: ICefBrowser; const frame: ICefFrame; transitionType: TCefTransitionType); virtual; + procedure doOnLoadEnd(const browser: ICefBrowser; const frame: ICefFrame; httpStatusCode: Integer); virtual; + procedure doOnLoadError(const browser: ICefBrowser; const frame: ICefFrame; errorCode: TCefErrorCode; const errorText, failedUrl: ustring); virtual; + procedure ShutDown; procedure FreeLibcefLibrary; function ExecuteProcess(const aApp : ICefApp) : integer; @@ -387,48 +413,73 @@ type constructor Create; destructor Destroy; override; procedure AfterConstruction; override; + /// + /// Used to add any command line switch that is not available as a + /// TCEFApplicationCore property. + /// procedure AddCustomCommandLine(const aCommandLine : string; const aValue : string = ''); + /// + /// Used to check the CEF binaries manually. + /// function CheckCEFLibrary : boolean; + /// + /// Used to initialize CEF in the main browser process. In case CEF is + /// configured to used the same executable for all processes then all + /// processes must call this function. CEF can only be initialized once + /// per process. This is a CEF feature and there's no workaround. This + /// function returns immediately in when called in the main process and + /// it blocks the execution when it's called from a CEF subprocess until + /// that process ends. + /// function StartMainProcess : boolean; + /// + /// Used to initialize CEF in the subprocesses. This function can only be + /// used when CEF is configured to use a different executable for the + /// subprocesses. This function blocks the execution until the process ends. + /// function StartSubProcess : boolean; - + /// + /// Perform a single iteration of CEF message loop processing. This function is + /// provided for cases where the CEF message loop must be integrated into an + /// existing application message loop. Use of this function is not recommended + /// for most users; use either the RunMessageLoop function or + /// TCefSettings.multi_threaded_message_loop if possible. When using this + /// function care must be taken to balance performance against excessive CPU + /// usage. It is recommended to enable the TCefSettings.external_message_pump + /// option when using this function so that + /// ICefBrowserProcessHandler.OnScheduleMessagePumpWork callbacks can + /// facilitate the scheduling process. This function should only be called on + /// the main application thread and only if cef_initialize() is called with a + /// TCefSettings.multi_threaded_message_loop value of false (0). This function + /// will not block. + /// procedure DoMessageLoopWork; + /// + /// Run the CEF message loop. Use this function instead of an application- + /// provided message loop to get the best balance between performance and CPU + /// usage. This function should only be called on the main application thread + /// and only if cef_initialize() is called with a + /// TCefSettings.multi_threaded_message_loop value of false (0). This function + /// will block until a quit message is received by the system. + /// procedure RunMessageLoop; + /// + /// Quit the CEF message loop that was started by calling + /// RunMessageLoop. This function should only be called on the main + /// application thread and only if RunMessageLoop was used. + /// procedure QuitMessageLoop; + /// + /// Update the DeviceScaleFactor value with the current monitor scale. + /// procedure UpdateDeviceScaleFactor; virtual; - {$IFDEF MACOSX} - procedure InitLibLocationFromArgs; + /// + /// This procedure is only available in MacOS to read some configuration + /// settings from the command line arguments. + /// + procedure InitLibLocationFromArgs; {$ENDIF} - - // Internal procedures. Only ICefApp, ICefBrowserProcessHandler, - // ICefResourceBundleHandler, ICefRenderProcessHandler, ICefRegisterCDMCallback and - // ICefLoadHandler should use them. - procedure Internal_OnBeforeCommandLineProcessing(const processType: ustring; const commandLine: ICefCommandLine); - procedure Internal_OnRegisterCustomSchemes(const registrar: TCefSchemeRegistrarRef); - procedure Internal_OnRegisterCustomPreferences(type_: TCefPreferencesType; const registrar: TCefPreferenceRegistrarRef); - procedure Internal_OnContextInitialized; virtual; - procedure Internal_OnBeforeChildProcessLaunch(const commandLine: ICefCommandLine); - procedure Internal_OnScheduleMessagePumpWork(const delayMs: Int64); - function Internal_GetLocalizedString(stringId: Integer; var stringVal: ustring) : boolean; - function Internal_GetDataResource(resourceId: Integer; var data: Pointer; var dataSize: NativeUInt) : boolean; - function Internal_GetDataResourceForScale(resourceId: Integer; scaleFactor: TCefScaleFactor; var data: Pointer; var dataSize: NativeUInt) : boolean; - procedure Internal_OnWebKitInitialized; - procedure Internal_OnBrowserCreated(const browser: ICefBrowser; const extra_info: ICefDictionaryValue); - procedure Internal_OnBrowserDestroyed(const browser: ICefBrowser); - procedure Internal_OnContextCreated(const browser: ICefBrowser; const frame: ICefFrame; const context: ICefv8Context); - procedure Internal_OnContextReleased(const browser: ICefBrowser; const frame: ICefFrame; const context: ICefv8Context); - procedure Internal_OnUncaughtException(const browser: ICefBrowser; const frame: ICefFrame; const context: ICefv8Context; const exception: ICefV8Exception; const stackTrace: ICefV8StackTrace); - procedure Internal_OnFocusedNodeChanged(const browser: ICefBrowser; const frame: ICefFrame; const node: ICefDomNode); - procedure Internal_OnProcessMessageReceived(const browser: ICefBrowser; const frame: ICefFrame; sourceProcess: TCefProcessId; const aMessage: ICefProcessMessage; var aHandled : boolean); - procedure Internal_OnLoadingStateChange(const browser: ICefBrowser; isLoading, canGoBack, canGoForward: Boolean); - procedure Internal_OnLoadStart(const browser: ICefBrowser; const frame: ICefFrame; transitionType: TCefTransitionType); - procedure Internal_OnLoadEnd(const browser: ICefBrowser; const frame: ICefFrame; httpStatusCode: Integer); - procedure Internal_OnLoadError(const browser: ICefBrowser; const frame: ICefFrame; errorCode: Integer; const errorText, failedUrl: ustring); - procedure Internal_GetDefaultClient(var aClient : ICefClient); - - // Properties used to populate TCefSettings (cef_settings_t) - /// /// Set to true (1) to disable the sandbox for sub-processes. See /// cef_sandbox_win.h for requirements to enable the sandbox on Windows. Also @@ -460,7 +511,7 @@ type /// must be an absolute path. Also configurable using the "main-bundle-path" /// command-line switch. /// - property MainBundlePath : ustring read FMainBundlePath write FMainBundlePath; // Only used in macOS + property MainBundlePath : ustring read FMainBundlePath write FMainBundlePath; /// /// Set to true (1) to enable use of the Chrome runtime in CEF. This feature /// is considered experimental and is not recommended for most users at this @@ -665,120 +716,660 @@ type /// TCefRequestContextSettings.cookieable_schemes_exclude_defaults values. /// property CookieableSchemesList : ustring read FCookieableSchemesList write FCookieableSchemesList; + /// + /// See the CookieableSchemesList property. + /// property CookieableSchemesExcludeDefaults : boolean read FCookieableSchemesExcludeDefaults write FCookieableSchemesExcludeDefaults; + /// + /// Runs the renderer and plugins in the same process as the browser. + /// + /// + /// Uses the following command line switch: --single-process + /// + property SingleProcess : Boolean read FSingleProcess write FSingleProcess; + /// + /// Enable media (WebRTC audio/video) streaming. + /// + /// + /// Uses the following command line switch: --enable-media-stream + /// + property EnableMediaStream : boolean read FEnableMediaStream write FEnableMediaStream; + /// + /// Enable speech input (x-webkit-speech). + /// + /// + /// Uses the following command line switch: --enable-speech-input + /// + property EnableSpeechInput : boolean read FEnableSpeechInput write FEnableSpeechInput; + /// + /// Bypass the media stream infobar by selecting the default device for media streams (e.g. WebRTC). Works with --use-fake-device-for-media-stream. + /// + /// + /// Uses the following command line switch: --single-process + /// + property UseFakeUIForMediaStream : boolean read FUseFakeUIForMediaStream write FUseFakeUIForMediaStream; + /// + /// Enable screen capturing support for MediaStream API. + /// + /// + /// Uses the following command line switch: --enable-usermedia-screen-capturing + /// + property EnableUsermediaScreenCapturing : boolean read FEnableUsermediaScreenCapturing write FEnableUsermediaScreenCapturing; + /// + /// Enable GPU hardware acceleration. + /// + /// + /// Uses the following command line switch: --disable-gpu + /// Uses the following command line switch: --disable-gpu-compositing + /// + property EnableGPU : boolean read FEnableGPU write FEnableGPU; + /// + /// List of feature names to enable. + /// + /// + /// Uses the following command line switch: --enable-features + /// The list of features you can enable is here: + /// https://chromium.googlesource.com/chromium/src/+/master/chrome/common/chrome_features.cc + /// https://source.chromium.org/chromium/chromium/src/+/main:content/public/common/content_features.cc + /// https://source.chromium.org/search?q=base::Feature + /// + property EnableFeatures : ustring read FEnableFeatures write FEnableFeatures; + /// + /// List of feature names to disable. + /// + /// + /// Uses the following command line switch: --disable-features + /// The list of features you can disable is here: + /// https://chromium.googlesource.com/chromium/src/+/master/chrome/common/chrome_features.cc + /// https://source.chromium.org/chromium/chromium/src/+/main:content/public/common/content_features.cc + /// https://source.chromium.org/search?q=base::Feature + /// + property DisableFeatures : ustring read FDisableFeatures write FDisableFeatures; + /// + /// Enable one or more Blink runtime-enabled features. + /// + /// + /// Uses the following command line switch: --enable-blink-features + /// The list of Blink features you can enable is here: + /// https://cs.chromium.org/chromium/src/third_party/blink/renderer/platform/runtime_enabled_features.json5 + /// + property EnableBlinkFeatures : ustring read FEnableBlinkFeatures write FEnableBlinkFeatures; + /// + /// Disable one or more Blink runtime-enabled features. + /// + /// + /// Uses the following command line switch: --disable-blink-features + /// The list of Blink features you can disable is here: + /// https://cs.chromium.org/chromium/src/third_party/blink/renderer/platform/runtime_enabled_features.json5 + /// + property DisableBlinkFeatures : ustring read FDisableBlinkFeatures write FDisableBlinkFeatures; + /// + /// Set blink settings. Format is [=[=],... + /// The names are declared in Settings.json5. For boolean type, use "true", "false", + /// or omit '=' part to set to true. For enum type, use the int value of the + /// enum value. Applied after other command line flags and prefs. + /// + /// + /// Uses the following command line switch: --blink-settings + /// The list of Blink settings you can disable is here: + /// https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/core/frame/settings.json5 + /// + property BlinkSettings : ustring read FBlinkSettings write FBlinkSettings; + /// + /// This option can be used to force field trials when testing changes locally. + /// The argument is a list of name and value pairs, separated by slashes. + /// If a trial name is prefixed with an asterisk, that trial will start activated. + /// For example, the following argument defines two trials, with the second one + /// activated: "GoogleNow/Enable/*MaterialDesignNTP/Default/" This option can also + /// be used by the browser process to send the list of trials to a non-browser + /// process, using the same format. See FieldTrialList::CreateTrialsFromString() + /// in field_trial.h for details. + /// + /// + /// Uses the following command line switch: --force-fieldtrials + /// https://source.chromium.org/chromium/chromium/src/+/master:base/base_switches.cc + /// + property ForceFieldTrials : ustring read FForceFieldTrials write FForceFieldTrials; + /// + /// This option can be used to force parameters of field trials when testing + /// changes locally. The argument is a param list of (key, value) pairs prefixed + /// by an associated (trial, group) pair. You specify the param list for multiple + /// (trial, group) pairs with a comma separator. + /// Example: "Trial1.Group1:k1/v1/k2/v2,Trial2.Group2:k3/v3/k4/v4" + /// Trial names, groups names, parameter names, and value should all be URL + /// escaped for all non-alphanumeric characters. + /// + /// + /// Uses the following command line switch: --force-fieldtrial-params + /// https://source.chromium.org/chromium/chromium/src/+/master:components/variations/variations_switches.cc + /// + property ForceFieldTrialParams : ustring read FForceFieldTrialParams write FForceFieldTrialParams; + /// + /// On platforms that support it, enables smooth scroll animation. + /// + /// + /// Uses the following command line switch: --enable-smooth-scrolling + /// + property SmoothScrolling : TCefState read FSmoothScrolling write FSmoothScrolling; + /// + /// Mutes audio sent to the audio device so it is not audible during automated testing. + /// + /// + /// Uses the following command line switch: --mute-audio + /// + property MuteAudio : boolean read FMuteAudio write FMuteAudio; + /// + /// Enforces a one-site-per-process security policy: Each renderer process, for its + /// whole lifetime, is dedicated to rendering pages for just one site. Thus, pages + /// from different sites are never in the same process. A renderer process's access + /// rights are restricted based on its site.All cross-site navigations force process + /// swaps.