{
* 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) 2013, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* Implements a slide-in notification window that appears at the bottom right
* of its parent window.
}
unit Notifications.UWindow;
interface
uses
// Delphi
Classes, StdCtrls, ExtCtrls, Controls, Buttons, Generics.Collections,
Windows {must come before Graphics}, Graphics, Messages, SyncObjs,
// Project
Notifications.UData, UStructs;
type
/// <summary>VCL control that encapsulates notification window that appears
/// at the bottom right of its parent window and can be animated to slide on
/// and off screen.</summary>
TNotificationWindow = class(TCustomControl)
public
type
/// <summary>
/// <para>Possible states of notification window.</para>
/// <para>- nwsOpen - window is fully open.</para>
/// <para>- nwsClosed - window is fully closed (hidden).</para>
/// <para>- nwsOpening - window is transitioning from closed to open.
/// </para>
/// <para>- nwsClosing - window is transitioning from open to closed.
/// </para>
/// </summary>
TState = (nwsOpen, nwsClosed, nwsOpening, nwsClosing);
strict private
const
/// <summary>Custom window message used to indicate window has been
/// concealed (i.e. slide-out has completed).</summary>
WM_CONCEALED = WM_USER + 234;
/// <summary>Colour that defines starting point (top) of window's
/// gradient fill.</summary>
GradColour1 = clWhite;
/// <summary>Colour that defines end point (bottom) of window's gradient
/// fill.</summary>
GradColour2 = $edbc96;
/// <summary>Colour of window border.</summary>
BorderColour = $cc8888;
/// <summary>Step size used when slliding window in or out.</summary>
/// <remarks>A complete move is taken to range from 0.0 to 1.0.</remarks>
SlideStep = 0.02;
/// <summary>Spacing between paragraphs of text from Contents property.
/// </summary>
ParaSpacing = 4;
/// <summary>Character used for close button.</summary>
/// <remarks>Character must be rendered in Marlett font.</remarks>
CloseButtonChar = #$75;
/// <summary>Character used for help button.</summary>
/// <remarks>Character must be rendered in Marlett font.</remarks>
HelpButtonChar = #$73;
strict private
var
/// <summary>Value of DisplayLock property.</summary>
fDisplayLock: TSimpleEvent;
/// <summary>Value of State property.</summary>
fState: TState;
/// <summary>Stores the properties and tasks associated with the last
/// window displayed.</summary>
/// <remarks>This record is updated by every call to the SlideIn method.
/// It is undefined until SlideIn is first called.</remarks>
fNotificationData: TNotificationData;
/// <summary>Button used to close (hide) an open window.</summary>
fCloseBtn: TSpeedButton;
/// <summary>Button used to display context sensitive help.</summary>
fHelpBtn: TSpeedButton;
/// <summary>Button used to perform any task associated with current
/// notification.</summary>
fTaskBtn: TButton;
/// <summary>Displays window's title text.</summary>
fTitleLbl: TLabel;
/// <summary>Timer used to automatically close (hide) an open window
/// after a specified time.</summary>
fHideTimer: TTimer;
/// <summary>Bounding rectangle of 'light bulb' glyph in window.
/// </summary>
fGlyphBounds: TRectEx;
/// <summary>Maintains a list of labels used to display the paragraphs
/// of text from the Contents property.</summary>
fContentLblList: TObjectList<TLabel>;
/// <summary>'Light bulb' glyph displayed in window.</summary>
fLightBulb: TBitmap;
strict private
/// <summary>Handles the custom message sent when the window has been
/// concealed after sliding off screen.</summary>
/// <remarks>The window display lock event is signalled.</remarks>
procedure WMConcealed(var Msg: TMessage); message WM_CONCEALED;
/// <summary>OnClick event handler for task button. Calls any callback
/// procedure registered for the current task.</summary>
procedure TaskBtnClick(Sender: TObject);
/// <summary>Creates labels required to display given content.</summary>
/// <remarks>One label is created for each element of the given array.
/// </remarks>
procedure CreateContentLabels(const AContent: TArray<string>);
/// <summary>Getter for DisplayTime property.</summary>
function GetDisplayTime: Cardinal;
/// <summary>Setter for DisplayTime property.</summary>
procedure SetDisplayTime(const MS: Cardinal);
/// <summary>Sets window property values for current notification and
/// rearranges and sizes window accordingly.</summary>
procedure UpdateWindow;
/// <summary>Creates and initialises all the window's controls.</summary>
procedure CreateCtrls;
/// <summary>Handles clicks on Close button by hiding (closing) window.
/// </summary>
/// <remarks>Does nothing if window is not fully open.</remarks>
procedure CloseBtnClickHandler(Sender: TObject);
/// <summary>Handles clicks on Help button by displaying any help topic
/// specified by the HelpKeyword field of the current notification data
/// record.</summary>
/// <remarks>Does nothing if the help keyword is the empty string.
/// </remarks>
procedure HelpBtnClickHandler(Sender: TObject);
/// <summary>Closes (hides) the window when the timer's event fires.
/// </summary>
/// <remarks>The event is ignored if the window is not fully open.
/// </remarks>
procedure TimerTickHandler(Sender: TObject);
strict protected
/// <summary>Sets this control's parent to the given control. Ensures that
/// this window is aligned at the bottom right of the parent window.
/// </summary>
procedure SetParent(AParent: TWinControl); override;
/// <summary>Paints window background and glyph.</summary>
procedure Paint; override;
public
/// <summary>Creates and initialises a new component instance.</summary>
constructor Create(AOwner: TComponent); override;
/// <summary>Destroys the current component instance.</summary>
destructor Destroy; override;
/// <summary>Sizes and locates the window. ALeft is ignored and is always
/// set so that the window appears at the right edge of the parent window.
/// </summary>
procedure SetBounds(ALeft, ATop, AWidth, AHeight: Integer); override;
/// <summary>Opens (displays) the window with the content and tasks
/// specified by the given notification data records. The window slides
/// on-screen.</summary>
/// <remarks>
/// <para>Does nothing unless State = nwsClosed.</para>
/// <para>State = nwsOpening while window is sliding and changes to
/// nwsOpen when it is fully hidden.</para>
/// <para>The window display lock is closed iff State = mwsClose when the
/// method is called.</para>
/// </remarks>
procedure SlideIn(const N: TNotificationData);
/// <summary>Closes (hides) the window by sliding it off-screen.</summary>
/// <remarks>
/// <para>Does nothing unless State = nwsOpen.</para>
/// <para>State = nwsClosing while window is sliding and changes to
/// nwsClosed when it is fully hidden.</para>
/// <para>Posts a WM_CONCEALED message when the window is fully closed.
/// </para>
/// </remarks>
procedure SlideOut;
/// <summary>Event object used as lock when window is displayed.
/// </summary>
/// <remarks>This lock is used by calling code to prevent them from
/// trying to display the window until it is closed.</remarks>
property DisplayLock: TSimpleEvent read fDisplayLock;
/// <summary>Current state of window.</summary>
/// <remarks>State is always nwsClosed when the window is created, i.e. it
/// is hidden by default.</remarks>
property State: TState read fState;
/// <summary>Amount of time, in milliseconds, the notification is to be
/// displayed before being hidden automatically.</summary>
/// <remarks>
/// <para>Defaults to 10000 (10 seconds).</para>
/// <para>If DisplayTime is zero the notification is not hidden
/// automatically.</para>
/// </remarks>
property DisplayTime: Cardinal read GetDisplayTime write SetDisplayTime;
end;
implementation
uses
// Delphi
GraphUtil, Math,
// Project
UCtrlArranger, UFontHelper, UGraphicUtils, UHelpMgr, UUtils;
{ TNotificationWindow }
procedure TNotificationWindow.CloseBtnClickHandler(Sender: TObject);
begin
SlideOut; // does nothing if State <> nwsOpen
end;
constructor TNotificationWindow.Create(AOwner: TComponent);
resourcestring
sDefaultTitle = 'Notification';
begin
inherited Create(AOwner);
fContentLblList := TObjectList<TLabel>.Create(True);
Width := 300;
Height := 150;
ControlStyle := ControlStyle - [csOpaque];
Anchors := [akBottom, akRight];
Color := $FFFFFF;
Visible := False;
fState := nwsClosed;
fLightBulb := TBitmap.Create;
fLightBulb.LoadFromResourceName(HInstance, 'NOTIFICATION');
CreateCtrls;
fTitleLbl.Caption := sDefaultTitle;
fHideTimer.Interval := 10000;
fDisplayLock := TSimpleEvent.Create;
fDisplayLock.SetEvent;
UpdateWindow;
end;
procedure TNotificationWindow.CreateContentLabels(
const AContent: TArray<string>);
var
Para: string;
Lbl: TLabel;
begin
fContentLblList.Clear; // frees any existing labels
for Para in AContent do
begin
Lbl := TLabel.Create(nil);
Lbl.Parent := Self;
TFontHelper.SetDefaultFont(Lbl.Font);
Lbl.Caption := Para;
Lbl.AutoSize := False;
Lbl.WordWrap := True;
fContentLblList.Add(Lbl);
end;
end;
procedure TNotificationWindow.CreateCtrls;
resourcestring
sDontShowText = 'Don''t show this notification again.';
sHelpBtnHint = 'Help';
sCloseBtnHint = 'Hide this window';
// Creates a new speed button with a character from the Marlett font as
// caption and with given OnClick event handler.
function CreateSymbolButton(Symbol: Char; ClickHandler: TNotifyEvent;
const Hint: string):
TSpeedButton;
begin
Result := TSpeedButton.Create(Self);
Result.Parent := Self;
Result.Width := 16;
Result.Height := 20;
Result.Flat := True;
Result.OnClick := ClickHandler;
Result.Font.Name := 'Marlett';
Result.Font.Size := 9;
Result.Caption := Symbol;
Result.ShowHint := Hint <> '';
Result.Hint := Hint;
end;
begin
// create title label
fTitleLbl := TLabel.Create(Self);
fTitleLbl.Parent := Self;
fTitleLbl.Font.Style := [fsBold];
fTitleLbl.Font.Size := fTitleLbl.Font.Size + 1;
fTitleLbl.AutoSize := False;
fTitleLbl.EllipsisPosition := epEndEllipsis;
TFontHelper.SetDefaultBaseFont(fTitleLbl.Font);
// create task button with default size (width changed to suit text)
fTaskBtn := TButton.Create(Self);
fTaskBtn.Parent := Self;
fTaskBtn.Visible := False;
fTaskBtn.Enabled := False; // enabled only when window displayed
fTaskBtn.OnClick := TaskBtnClick;
// create close button with down arrow symbol
fCloseBtn := CreateSymbolButton(
CloseButtonChar, CloseBtnClickHandler, sCloseBtnHint
);
// create help button with "?" symbol
fHelpBtn := CreateSymbolButton(
HelpButtonChar, HelpBtnClickHandler, sHelpBtnHint
);
fHelpBtn.Visible := False;
// create timer used to automatically hide window
fHideTimer := TTimer.Create(Self);
fHideTimer.Enabled := False;
fHideTimer.OnTimer := TimerTickHandler;
end;
destructor TNotificationWindow.Destroy;
begin
fLightBulb.Free;
fContentLblList.Free;
fDisplayLock.SetEvent;
fDisplayLock.Free;
inherited;
end;
function TNotificationWindow.GetDisplayTime: Cardinal;
begin
Result := fHideTimer.Interval;
end;
procedure TNotificationWindow.HelpBtnClickHandler(Sender: TObject);
begin
if fNotificationData.HelpKeyword <> '' then
HelpMgr.ShowHelp(fNotificationData.HelpKeyword);
end;
procedure TNotificationWindow.Paint;
begin
GradientFillCanvas(Canvas, GradColour1, GradColour2, ClientRect, gdVertical);
Canvas.Pen.Color := BorderColour;
Canvas.Brush.Style := bsClear;
Canvas.Rectangle(ClientRect);
Canvas.BrushCopy(
fGlyphBounds,
fLightBulb,
TRectEx.Create(0, 0, fLightBulb.Width, fLightBulb.Height),
clFuchsia
);
end;
procedure TNotificationWindow.SetBounds(ALeft, ATop, AWidth, AHeight: Integer);
var
ParentBounds: TRectEx;
begin
if Assigned(Parent) then
begin
// align at bottom right of parent
ParentBounds := Parent.ClientRect;
ALeft := ParentBounds.Right - AWidth - 6;
end;
inherited SetBounds(ALeft, ATop, AWidth, AHeight);
end;
procedure TNotificationWindow.SetDisplayTime(const MS: Cardinal);
begin
fHideTimer.Interval := MS;
end;
procedure TNotificationWindow.SetParent(AParent: TWinControl);
begin
inherited;
SetBounds(0, 0, Width, Height);
end;
procedure TNotificationWindow.SlideIn(const N: TNotificationData);
var
ClosedTop: Integer;
OpenedTop: Integer;
Range: Integer;
Scale: Double;
begin
if State <> nwsClosed then
Exit;
fNotificationData := N;
UpdateWindow;
fDisplayLock.ResetEvent;
fState := nwsOpening;
ClosedTop := Parent.ClientRect.Bottom + 1;
OpenedTop := Parent.ClientRect.Bottom - Height;
Range := ClosedTop - OpenedTop;
Top := ClosedTop;
Visible := True;
Scale := SlideStep;
while Scale < 1.0 - SlideStep do
begin
Top := ClosedTop - Round(Range * Scale);
Scale := Scale + SlideStep;
Pause(2);
end;
Top := OpenedTop;
fState := nwsOpen;
fTaskBtn.Enabled := True;
fHideTimer.Enabled := DisplayTime > 0;
end;
procedure TNotificationWindow.SlideOut;
var
ClosedTop: Integer;
OpenedTop: Integer;
Range: Integer;
Scale: Double;
begin
if State <> nwsOpen then
Exit;
fHideTimer.Enabled := False;
fTaskBtn.Enabled := False;
fState := nwsClosing;
ClosedTop := Parent.ClientRect.Bottom + 1;
OpenedTop := Parent.ClientRect.Bottom - Height;
Range := ClosedTop - OpenedTop;
Top := OpenedTop;
Scale := SlideStep;
while Scale < 1.0 - SlideStep do
begin
Top := OpenedTop + Round(Range * Scale);
Scale := Scale + SlideStep;
Pause(2);
end;
Top := ClosedTop;
Visible := False;
fState := nwsClosed;
PostMessage(Handle, WM_CONCEALED, 0, 0);
end;
procedure TNotificationWindow.TaskBtnClick(Sender: TObject);
begin
if Assigned(fNotificationData.TaskCallback) then
fNotificationData.TaskCallback();
end;
procedure TNotificationWindow.TimerTickHandler(Sender: TObject);
begin
fHideTimer.Enabled := False;
SlideOut; // does nothing if State <> nwsOpen
end;
procedure TNotificationWindow.UpdateWindow;
const
MarginLR = 8;
MarginTB = 8;
CtrlVSpacing = 8;
GlyphSize = 24;
TextLeftOffset = MarginLR + GlyphSize + 8;
var
Lbl: TLabel;
NextTop: Integer;
ParaTop: Integer;
TextWidth: Integer;
TopRowHeight: Integer;
begin
// Set control content and state for current notification data
fTitleLbl.Caption := fNotificationData.Title;
CreateContentLabels(fNotificationData.Content);
if Assigned(fNotificationData.TaskCallback) then
begin
fTaskBtn.Caption := fNotificationData.TaskPrompt;
fTaskBtn.Visible := True;
end
else
begin
fTaskBtn.Caption := '';
fTaskBtn.Visible := False;
end;
fHelpBtn.Visible := fNotificationData.HelpKeyword <> '';
// Find height of "top row" of controls - title and close button plus help
// button if visible: they are all centred in this row.
TCtrlArranger.SetLabelHeight(fTitleLbl);
TopRowHeight := Max(fTitleLbl.Height, fCloseBtn.Height);
if fHelpBtn.Visible then
TopRowHeight := Max(TopRowHeight, fHelpBtn.Height);
// Locate left hand "light bulb" glyph
fGlyphBounds := TRectEx.CreateBounds(
MarginLR, MarginTB, GlyphSize, GlyphSize
);
// Set "close" and "help" button locations
if fHelpBtn.Visible then
begin
fHelpBtn.Left := Width - MarginLR - fHelpBtn.Width;
fHelpBtn.Top := MarginTB + (TopRowHeight - fHelpBtn.Height) div 2;
fCloseBtn.Left := fHelpBtn.Left - fCloseBtn.Width;
end
else
fCloseBtn.Left := Width - MarginLR - fCloseBtn.Width;
fCloseBtn.Top := MarginTB + (TopRowHeight - fCloseBtn.Height) div 2;
// Set title size and location
fTitleLbl.Width := fCloseBtn.Left - 4 - TextLeftOffset;
fTitleLbl.Left := TextLeftOffset;
fTitleLbl.Top := MarginTB + (TopRowHeight - fTitleLbl.Height) div 2;
// Get width available for text / check box in main body
TextWidth := Width - MarginLR - TextLeftOffset;
// Create labels to display content paragraphs and locate them one below the
// other.
ParaTop := MarginTB + TopRowHeight + CtrlVSpacing;
for Lbl in fContentLblList do
begin
Lbl.Top := ParaTop;
Lbl.Left := TextLeftOffset;
Lbl.Width := TextWidth;
TCtrlArranger.SetLabelHeight(Lbl);
Inc(ParaTop, Lbl.Height + ParaSpacing);
end;
NextTop := ParaTop - ParaSpacing + CtrlVSpacing;
// Set location and size of task button
if fTaskBtn.Visible then
begin
fTaskBtn.Left := TextLeftOffset;
fTaskBtn.Width := StringExtent(fTaskBtn.Caption, fTaskBtn.Font).cx
+ 28;
fTaskBtn.Top := NextTop;
NextTop := TCtrlArranger.BottomOf(fTaskBtn, CtrlVSpacing);
end;
// Set required window height
Height := NextTop - CtrlVSpacing + MarginTB;
end;
procedure TNotificationWindow.WMConcealed(var Msg: TMessage);
begin
fDisplayLock.SetEvent;
end;
end.
