{
* This Source Code Form is subject to the terms of the Mozilla Public License,
* v. 2.0. If a copy of the MPL was not distributed with this file, You can
* obtain one at http://mozilla.org/MPL/2.0/
*
* Copyright (C) 2005-2013, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* Implements a base class for all frames that contain a web browser control.
}
unit FrBrowserBase;
interface
uses
// Delphi
OleCtrls, SHDocVw, Classes, Controls, ExtCtrls, Forms, Windows,
// Project
Browser.UController, Browser.UHTMLEvents, UCSSBuilder, UMenus;
type
/// <summary>Type of event triggered when frame that hosts a TWebBrowser
/// needs CSS.</summary>
/// <remarks>Such events can be handled by forms that own the frame to modify
/// default CSS.</remarks>
/// <param name="Sender">TObject [in] Reference to frame triggering event.
/// </param>
/// <param name="CSSBuilder">TCSSBuilder [in] Object containing information
/// about existing CSS. This can be modified and/or added to.</param>
TBrowserBuildCSSEvent = procedure(Sender: TObject;
const CSSBuilder: TCSSBuilder) of object;
type
/// <summary>
/// Base class for all frames that contain a web browser control. Creates a
/// web browser controller object and sets default characteristics of
/// controlled browser object. Also provides methods to handle activation of
/// browser, HTML events, access selected links, trigger pop-up menus and
/// provide information about the browser control.
/// </summary>
TBrowserBaseFrame = class(TFrame, IPopupMenu)
pnlBrowser: TPanel;
wbBrowser: TWebBrowser;
/// <summary>Handles event triggered when frame is entered. Activates
/// browser.</summary>
procedure FrameEnter(Sender: TObject);
strict private
var
/// <summary>Object used to control web browser.</summary>
fWBController: TWBController;
/// <summary>Handler for OnBuildCSS event.</summary>
fOnBuildCSS: TBrowserBuildCSSEvent;
/// <summary>Handler for OnHTMLEvent event.</summary>
fOnHTMLEvent: THTMLEvent;
/// <summary>Handles browser UI manager's OnUpdateCSS event. Passes CSS
/// to be used by browser control via CSS parameter.</summary>
procedure UpdateCSS(Sender: TObject; var CSS: string);
/// <summary>Makes browser the active control of the parent form.</summary>
procedure MakeBrowserActiveControl;
/// <summary>Triggers any selected link in web browser control.</summary>
procedure TriggerActiveLink;
strict protected
/// <summary>Returns reference to form that hosts the frame or nil if there
/// is no host form.</summary>
function ParentForm: TForm;
/// <summary>Builds required default CSS using given TCSSBuilder object.
/// </summary>
/// <remarks>Can be overridden to modify the CSS.</remarks>
procedure BuildCSS(const CSSBuilder: TCSSBuilder); virtual;
/// <summary>Handles web browser control's OnEnter event. Makes browser
/// control the active control of the host form.</summary>
procedure BrowserActivate(Sender: TObject); virtual;
/// <summary>Handles event triggered by web browser controller when a key
/// is pressed in the browser control.</summary>
/// <remarks>Browser is prevented from handling any key press where we
/// don't want browser's default action or we want an opportunity to handle
/// the key press in owning form or main application.</remarks>
/// <param name="Sender">TObject [in] Not used.</param>
/// <param name="Msg">TMSG [in] Message generating accelerator translation
/// request.</param>
/// <param name="CmdID">DWORD [in] Not used.</param>
/// <param name="Handled">Boolean [in/out] False when passed in. Set to
/// True as required to prevent web browser handling key press.</param>
procedure TranslateAccelHandler(Sender: TObject; const Msg: TMSG;
const CmdID: DWORD; var Handled: Boolean);
/// <summary>Navigates to a URL. Action peformed depends on URL's protocol.
/// </summary>
/// <param name="URL">string [in] URL to be navigated to.</param>
/// <returns>Boolean. True if navigation was handled by method, False if
/// not.</returns>
function DoNavigate(const URL: string): Boolean;
/// <summary>Handler for web browser controller's OnNavigate event.
/// Navigates to given URL.</summary>
/// <param name="Sender">TObject [in] Not used.</param>
/// <param name="URL">string [in] URL to be navigated to.</param>
/// <param name="Cancel">Boolean [in/out] False when passed in. Set to True
/// to cancel browser's own navigation if navigation is handled by the
/// application. Left False if browser is to handle navigation.</param>
procedure NavigateHandler(Sender: TObject; const URL: string;
var Cancel: Boolean);
/// <summary>Handles "standard" web browser events.</summary>
/// <remarks>
/// <para>Checks for shift key when link is clicked and inhibits default
/// browser action of opening in IE. Instead URL is opened according to
/// protocol handler.</para>
/// <para>All events are passed to this object's OnHTMLEvent
/// event.</para>
/// </remarks>
/// <param name="Sender">TObject [in] Object that triggered event.</param>
/// <param name="EventInfo">THTMLEventInfo [in] Provides information about
/// the event.</param>
procedure HTMLEventHandler(Sender: TObject;
const EventInfo: THTMLEventInfo); virtual;
/// <summary>Handles browser window's onerror event. Generates and handles
/// an EBug exception to report the error.</summary>
/// <remarks>
/// <para>Parameters are used in exception error message.</para>
/// <para>Handles parameter is set True to inhibit browser control's script
/// error dialog box.</para>
/// </remarks>
procedure HTMLWindowErrorHandler(Sender: TObject; const Desc, URL: string;
const Line: Integer; var Handled: Boolean); virtual;
/// <summary>Web browser controller object.</summary>
property WBController: TWBController read fWBController;
public
/// <summary>Creates frame with given owner and creates and initialises
/// browser controller.</summary>
constructor Create(AOwner: TComponent); override;
/// <summary>Tears down frame.</summary>
destructor Destroy; override;
/// <summary>Checks if browser control has a pop-up menu.</summary>
/// <remarks>Method of IPopupMenu.</remarks>
function HasPopup: Boolean;
/// <summary>Displays browser control's menu for active element at given
/// point.</summary>
/// <remarks>Method of IPopupMenu.</remarks>
procedure Popup(const Pt: TPoint);
/// <summary>Checks if browser control is currently active.</summary>
/// <remarks>Method of IWBInfo.</remarks>
function IsBrowserActive: Boolean;
/// <summary>Checks whether text can be copied to clipboard from browser
/// control.</summary>
/// <remarks>Method of IClipboardMgr</remarks>
function CanCopy: Boolean;
/// <summary>Copies selected text from browser control to clipboard.
/// </summary>
/// <remarks>Method of IClipboardMgr.</remarks>
procedure CopyToClipboard;
/// <summary>Checks whether text can be selected in browser control.
/// </summary>
/// <remarks>Method of ISelectionMgr.</remarks>
function CanSelectAll: Boolean;
/// <summary>Selects all text in browser control.</summary>
/// <remarks>Method of ISelectionMgr.</remarks>
procedure SelectAll;
/// <summary>Event triggerd when default CSS is required by browser
/// control.</summary>
property OnBuildCSS: TBrowserBuildCSSEvent
read fOnBuildCSS write fOnBuildCSS;
/// <summary>Event triggered when supported HTML events are intercepted.
/// </summary>
property OnHTMLEvent: THTMLEvent
read fOnHTMLEvent write fOnHTMLEvent;
end;
implementation
uses
// Delphi
SysUtils, Messages, Graphics,
// Project
UAnchors, UColours, UCSSUtils, UExceptions, UFontHelper, UProtocols, UUtils;
{$R *.dfm}
{ TBrowserBaseFrame }
procedure TBrowserBaseFrame.BrowserActivate(Sender: TObject);
begin
MakeBrowserActiveControl;
end;
procedure TBrowserBaseFrame.BuildCSS(const CSSBuilder: TCSSBuilder);
var
CSSFont: TFont;
begin
// <img> tag style: no borders
with CSSBuilder.AddSelector('img') do
AddProperty(TCSS.HideBorderProp(cssAll));
// Default <a> tag style: fall back links for unknown link classes.
// Each link type is expected to define own colour as a minimum.
with CSSBuilder.AddSelector('a') do
begin
AddProperty(TCSS.ColorProp(clDefaultLink));
AddProperty(TCSS.TextDecorationProp([ctdUnderline]));
end;
// <a class="help-link"> override
with CSSBuilder.AddSelector('a.help-link') do
begin
AddProperty(TCSS.ColorProp(clHelpLink));
end;
// <a class="snippet-link"> and <a class="category-link"> overrides
with CSSBuilder.AddSelector('a.snippet-link, a.category-link') do
begin
AddProperty(TCSS.ColorProp(clDBLink));
AddProperty(TCSS.FontStyleProp(cfsItalic));
AddProperty(TCSS.TextDecorationProp([ctdNone]));
end;
with CSSBuilder.AddSelector('a:hover.snippet-link, a:hover.category-link') do
begin
AddProperty(TCSS.BorderProp(cssBottom, 1, cbsDotted, clDBLink));
end;
// <a class="command-link"> override
with CSSBuilder.AddSelector('a.command-link') do
begin
AddProperty(TCSS.ColorProp(clCommandLink));
AddProperty(TCSS.FontStyleProp(cfsItalic));
AddProperty(TCSS.TextDecorationProp([ctdNone]));
end;
with CSSBuilder.AddSelector('a:hover.command-link') do
begin
AddProperty(TCSS.BorderProp(cssBottom, 1, cbsDotted, clCommandLink));
end;
with CSSBuilder.AddSelector('.no-link-decoration a:hover') do
AddProperty(TCSS.HideBorderProp(cssBottom));
// <a class="external-link"> override
with CSSBuilder.AddSelector('a.external-link') do
begin
AddProperty(TCSS.ColorProp(clExternalLink));
end;
// <var> tag style
with CSSBuilder.AddSelector('var') do
begin
AddProperty(TCSS.ColorProp(clVarText));
AddProperty(TCSS.FontStyleProp(cfsItalic));
end;
// <code> tag style
with CSSBuilder.AddSelector('code') do
begin
CSSFont := TFont.Create;
try
TFontHelper.SetDefaultMonoFont(CSSFont);
AddProperty(TCSS.FontProps(CSSFont));
finally
CSSFont.Free;
end;
end;
// .warning class style: mainly for use inline
with CSSBuilder.AddSelector('.warning') do
begin
AddProperty(TCSS.ColorProp(clWarningText));
AddProperty(TCSS.FontWeightProp(cfwBold));
end;
end;
function TBrowserBaseFrame.CanCopy: Boolean;
begin
Result := WBController.UIMgr.CanCopy;
end;
function TBrowserBaseFrame.CanSelectAll: Boolean;
begin
Result := WBController.UIMgr.CanSelectAll;
end;
procedure TBrowserBaseFrame.CopyToClipboard;
begin
WBController.UIMgr.CopyToClipboard;
end;
constructor TBrowserBaseFrame.Create(AOwner: TComponent);
begin
inherited;
Assert(AOwner is TWinControl, ClassName + '.Create: AOwner not a TForm');
fWBController := TWBController.Create(wbBrowser);
fWBController.UIMgr.Show3dBorder := False;
fWBController.UIMgr.OnTranslateAccel := TranslateAccelHandler;
fWBController.UIMgr.OnUpdateCSS := UpdateCSS;
fWBController.UIMgr.OnBrowserActivate := BrowserActivate;
fWBController.IOMgr.OnNavigate := NavigateHandler;
fWBController.IOMgr.OnHTMLEvent := HTMLEventHandler;
fWBController.IOMgr.OnHTMLWindowError := HTMLWindowErrorHandler;
end;
destructor TBrowserBaseFrame.Destroy;
begin
FreeAndNil(fWBController);
inherited;
end;
function TBrowserBaseFrame.DoNavigate(const URL: string): Boolean;
var
Protocol: TProtocol; // object used to handle certain URL protocols
begin
// If protocol handler recognises a URL's protocol it deals with it in its
// execute method and returns true. This return value is also returned by this
// method. If the protocol handler does not recognise a protocol its Execute
// method does nothing and returns false and this method returns false.
Protocol := TProtocolFactory.CreateHandler(URL);
try
Result := Protocol.Execute;
finally
FreeAndNil(Protocol);
end;
end;
procedure TBrowserBaseFrame.FrameEnter(Sender: TObject);
begin
MakeBrowserActiveControl;
end;
function TBrowserBaseFrame.HasPopup: Boolean;
begin
Result := WBController.UIMgr.SupportsPopupMenu;
end;
procedure TBrowserBaseFrame.HTMLEventHandler(Sender: TObject;
const EventInfo: THTMLEventInfo);
var
ALink: IDispatch; // any <a> tag generating (or wrapping tag generating) event
begin
try
// Trigger OnHTMLEvent: uses original sender
if Assigned(fOnHTMLEvent) then
fOnHTMLEvent(Sender, EventInfo);
// We only handle onclick events if they've not already been handled and
// cancelled
if EventInfo.Cancelled
or not EventInfo.IsEvent(
THTMLDocumentEvents2Sink.EventIntf,
THTMLDocumentEvents2Sink.DISPID_OnClick
) then
Exit;
// We only handle clicks on <a> tags or tags within <a> tags (eg <img>)
ALink := TAnchors.FindEnclosingAnchor(EventInfo.Args.srcElement);
if not Assigned(ALink) then
Exit;
if EventInfo.Args.shiftKey then
begin
// User pressed shift key:
// prevent default browser action by cancelling the event
EventInfo.Cancelled := True;
// navigate according to protocol handler
DoNavigate(TAnchors.GetURL(ALink));
end;
except
Application.HandleException(ExceptObject);
end;
end;
procedure TBrowserBaseFrame.HTMLWindowErrorHandler(Sender: TObject; const Desc,
URL: string; const Line: Integer; var Handled: Boolean);
const
ErrorMessage = 'An unexpected error occurred loading a document or running a '
+ 'script in the browser control hosted by frame %0:s:'#10#10
+ 'Document: %2:s, line %3:d'#10
+ 'Error: "%1:s"';
begin
try
raise EBug.CreateFmt(
ErrorMessage, [ClassName, Desc, URIBaseName(URL), Line]
);
except
Application.HandleException(ExceptObject);
end;
Handled := True;
end;
function TBrowserBaseFrame.IsBrowserActive: Boolean;
begin
Result := ParentForm.ActiveControl = wbBrowser;
end;
procedure TBrowserBaseFrame.MakeBrowserActiveControl;
begin
if ParentForm <> nil then
ParentForm.ActiveControl := wbBrowser;
end;
procedure TBrowserBaseFrame.NavigateHandler(Sender: TObject;
const URL: string; var Cancel: Boolean);
begin
try
Cancel := DoNavigate(URL);
except
Application.HandleException(ExceptObject);
Cancel := True;
end;
end;
function TBrowserBaseFrame.ParentForm: TForm;
var
ParentCtrl: TWinControl; // moves up tree of parent controls
begin
ParentCtrl := Self.Parent;
while Assigned(ParentCtrl) and not (ParentCtrl is TForm) do
ParentCtrl := ParentCtrl.Parent;
if ParentCtrl is TForm then
Result := ParentCtrl as TForm
else
Result := nil;
end;
procedure TBrowserBaseFrame.Popup(const Pt: TPoint);
begin
WBController.UIMgr.ShowPopupMenu(Pt);
end;
procedure TBrowserBaseFrame.SelectAll;
begin
WBController.UIMgr.SelectAll;
end;
procedure TBrowserBaseFrame.TranslateAccelHandler(Sender: TObject;
const Msg: TMSG; const CmdID: DWORD; var Handled: Boolean);
// ---------------------------------------------------------------------------
/// Posts a key down and key up message to frame's parent window using wParam
/// and lParam values of message passed to outer method.
procedure PostKeyPress(const DownMsg, UpMsg: UINT);
begin
PostMessage(Parent.Handle, DownMsg, Msg.wParam, Msg.lParam);
PostMessage(Parent.Handle, UpMsg, Msg.wParam, Msg.lParam);
end;
// ---------------------------------------------------------------------------
var
ShiftState: TShiftState; // state of key modifiers
PostMsg: Boolean; // whether to post message to parent
begin
PostMsg := False;
// We only handle key down messages
if ((Msg.message = WM_KEYDOWN) or (Msg.message = WM_SYSKEYDOWN)) then
begin
// Record state of modifier keys
ShiftState := Forms.KeyDataToShiftState(Msg.lParam);
// Process key pressed (wParam field of Msg)
case Msg.wParam of
Ord('A')..Ord('Z'), Ord('0')..Ord('9'):
// We pass Ctrl key with any alphanumeric keys to parent. This enables
// any of application's shortcut keys to be handled by associated action
if (ShiftState = [ssCtrl])
or (ShiftState = [ssCtrl, ssShift])
or (ShiftState = [ssCtrl, ssShift, ssAlt]) then
PostMsg := True;
VK_F1..VK_F24:
// We post all function keys with any modifier to parent to allow
// processing there. It is particularly important for pass on F5 to
// prevent browser from refreshing and F1 to enable help.
// NOTE: we assume all function keys have contiguous codes.
PostMsg := True;
VK_LEFT, VK_RIGHT, VK_HOME:
// We post Alt+Left, Alt+Right and Alt+Home keys to parent to enable
// application to call any associated actions
if ShiftState = [ssAlt] then
PostMsg := True;
VK_INSERT, VK_DELETE:
// We post Ctrl+Ins and Ctrl+Del to parent to enable application to
// call any associated actions
if ShiftState = [ssCtrl] then
PostMsg := True;
VK_TAB:
// We post Ctrl+Tab and Shift+Ctrl+Tab to parent to enable tab switching
// where browser is hosted by a tab set of some description
if (ShiftState = [ssCtrl]) or (ShiftState = [ssCtrl, ssShift]) then
PostMsg := True;
VK_RETURN:
// We handle Ctrl+Return to trigger any active link. This message is not
// posted to parent, but is handled here and browser is prevented from
// processing the keypress further
if (ShiftState = [ssCtrl]) or (ShiftState = []) then
begin
TriggerActiveLink; // uses new tab if Ctrl key pressed.
Handled := True;
end;
VK_ESCAPE:
// We pass on all ESC key presses
PostMsg := True;
end;
if PostMsg then
begin
// Any message for which posting is required is posted to window that owns
// frame, and is therefore passed to main application.
case Msg.message of
WM_KEYDOWN: PostKeyPress(WM_KEYDOWN, WM_KEYUP);
WM_SYSKEYDOWN: PostKeyPress(WM_SYSKEYDOWN, WM_SYSKEYUP);
end;
// We consider all posted messages as handled to prevent browser
// processing them further
Handled := True;
end;
end;
end;
procedure TBrowserBaseFrame.TriggerActiveLink;
begin
TAnchors.ClickActiveLink(wbBrowser.Document);
end;
procedure TBrowserBaseFrame.UpdateCSS(Sender: TObject; var CSS: string);
var
CSSBuilder: TCSSBuilder; // object used to build CSS
begin
CSSBuilder := TCSSBuilder.Create;
try
BuildCSS(CSSBuilder);
if Assigned(fOnBuildCSS) then
fOnBuildCSS(Self, CSSBuilder);
CSS := CSSBuilder.AsString;
finally
FreeAndNil(CSSBuilder);
end;
end;
end.
