{
* 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) 2008-2013, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* Implements a static class that manages user's interaction with user database.
}
unit UUserDBMgr;
interface
uses
// Delphi
Classes,
// Project
DB.UCategory, UBaseObjects, UView;
type
/// <summary>Static class that manages user's interaction with user database
/// and performs move and backup operations on it.</summary>
TUserDBMgr = class(TNoConstructObject)
strict private
/// <summary>OnClose event handler for open dialogue box. Checks if
/// dialogue box can close.</summary>
/// <param name="Sender">TObject [in] Reference to dialogue box in
/// question.</param>
/// <param name="CanClose">Boolean [in/out] Set to True to permit dialogue
/// to close or False to inhibit closure.</param>
class procedure CanOpenDialogClose(Sender: TObject; var CanClose: Boolean);
/// <summary>OnClose event handler for save dialogue box. Checks if
/// dialogue box can close.</summary>
/// <param name="Sender">TObject [in] Reference to dialogue box in
/// question.</param>
/// <param name="CanClose">Boolean [in/out] Set to True to permit dialogue
/// to close or False to inhibit closure.</param>
class procedure CanSaveDialogClose(Sender: TObject; var CanClose: Boolean);
/// <summary>Creates a list of user defined categories.</summary>
/// <param name="IncludeSpecial">Boolean [in] Flag indicating whether list
/// should include special, non-deletable, categories.</param>
/// <returns>Required category list.</returns>
/// <remarks>Caller must free the returned object.</remarks>
class function CreateUserCatList(
const IncludeSpecial: Boolean): TCategoryList;
public
/// <summary>Enables user to adds a new user defined snippet to the
/// database using the snippets editor.</summary>
class procedure AddSnippet;
/// <summary>Enables user to edit the snippet with the given name using the
/// snippets editor.</summary>
/// <remarks>The named snippet must be user defined.</remarks>
class procedure EditSnippet(const SnippetName: string);
/// <summary>Duplicates the snippet specified by the given view as a user
/// defined snippet with name specified by user.</summary>
class procedure DuplicateSnippet(ViewItem: IView);
/// <summary>Deletes the snippet specified by the given view from the
/// database.</summary>
/// <remarks>The given snippet must be user defined.</remarks>
class procedure DeleteSnippet(ViewItem: IView);
/// <summary>Checks if given view item can be duplicated.</summary>
/// <remarks>To be duplicated view must be a snippet.</summary>
class function CanDuplicate(ViewItem: IView): Boolean;
/// <summary>Checks if the given view item specifies an editable snippet.
/// </summary>
class function CanEdit(ViewItem: IView): Boolean;
/// <summary>Adds a new category, specified by the user, to the database.
/// </summary>
class procedure AddCategory;
/// <summary>Deletes a user specified category from the database.</summary>
class procedure DeleteACategory;
/// <summary>Renames a user specified category.</summary>
class procedure RenameACategory;
/// <summary>Checks if it is possible for any categories to be renamed.
/// </summary>
class function CanRenameACategory: Boolean;
/// <summary>Checks if it is possible for any categories to be deleted.
/// </summary>
class function CanDeleteACategory: Boolean;
/// <summary>Saves the current user database to disk.</summary>
class procedure Save(ParentCtrl: TComponent);
/// <summary>Checks if the user database can be saved.</summary>
class function CanSave: Boolean;
/// <summary>Creates a backup of the user database in a file specified by
/// the user.</summary>
class procedure BackupDatabase(ParentCtrl: TComponent);
/// <summary>Restores the user database from a backup file specified by the
/// user.</summary>
class function RestoreDatabase(ParentCtrl: TComponent): Boolean;
/// <summary>Moves the user database to a new location specified by the
/// user.</summary>
class procedure MoveDatabase;
end;
implementation
uses
// Delphi
SysUtils, Dialogs, Windows {for inlining},
// Project
DB.UMain, DB.USnippet,
FmAddCategoryDlg, FmDeleteCategoryDlg, FmDuplicateSnippetDlg,
FmRenameCategoryDlg, FmSnippetsEditorDlg,
{$IFNDEF PORTABLE}
FmUserDataPathDlg,
{$ENDIF}
FmWaitDlg,
UConsts, UExceptions, UIStringList, UMessageBox, UOpenDialogEx,
UOpenDialogHelper, UReservedCategories, USaveDialogEx, USnippetIDs,
UUserDBBackup, UWaitForThreadUI;
type
/// <summary>Base class for classes that execute a user database management
/// function in a thread while displaying a "wait" dialogue box if necessary.
/// </summary>
/// <remarks>The class is marked abstract because it cannot be used directly.
/// </remarks>
TUserDBWaitUI = class abstract(TNoConstructObject)
strict private
const
/// <summary>Time to elapse before wait dialogue is displayed.</summary>
PauseBeforeDisplay = 500;
/// <summary>Minimum time to display wait dialogue box.</summary>
MinDisplayTime = 1000;
strict protected
/// <summary>Runs a thread and displays a wait dialogue box if the
/// thread takes more that a given time to execute. Blocks until the
/// thread terminates.</summary>
/// <param name="Thread">TThread [in] Thread to execute.</param>
/// <param name="DlgOwner">TComponent [in] Component that owns the dialogue
/// box, over which it is aligned.</param>
/// <param name="WaitCaption">string [in] Caption to be displayed in wait
/// dialogue box.</param>
class procedure RunThreadWithWaitDlg(const Thread: TThread;
const DlgOwner: TComponent; const WaitCaption: string);
end;
type
/// <summary>Class that saves user database to disk in a thread while
/// displaying a "wait" dialogue box if necessary.</summary>
TUserDBSaveUI = class sealed(TUserDBWaitUI)
strict private
type
/// <summary>Thread that performs user database save operation.</summary>
TSaveThread = class(TThread)
strict protected
/// <summary>Saves the user database.</summary>
procedure Execute; override;
public
/// <summary>Constructs a new, suspended, thread instance.</summary>
constructor Create;
end;
public
/// <summary>Performs the user database save operation in a background
/// thread and displays a wait diaogue box if the operation takes more than
/// a given time to execute. Blocks until the thread terminates.</summary>
/// <param name="AOwner">TComponent [in] Component that owns the dialogue
/// box, over which it is aligned.</param>
class procedure Execute(AOwner: TComponent);
end;
type
/// <summary>Class that restores a backup of the user database in a thread
/// while displaying a "wait" dialogue box if necessary.</summary>
TUserDBRestoreUI = class sealed(TUserDBWaitUI)
strict private
type
/// <summary>Thread that performs restore operation.</summary>
TRestoreThread = class(TThread)
strict private
var
/// <summary>Name of backup file to be restored.</summary>
fBakFileName: string;
strict protected
/// <summary>Restores the user database from a backup.</summary>
procedure Execute; override;
public
/// <summary>Constructs a new, suspended, thread that can restore the
/// database from the given backup file.</summary>
constructor Create(const BakFileName: string);
end;
public
/// <summary>Performs a user database restoration operation from in a
/// background thread and displays a wait diaogue box if the operation
/// takes more than a given time to execute. Blocks until the thread
/// terminates.</summary>
/// <param name="AOwner">TComponent [in] Component that owns the dialogue
/// box, over which it is aligned.</param>
/// <param name="BakFileName">string [in] Name of backup file to be
/// restored.</param>
class procedure Execute(AOwner: TComponent; const BakFileName: string);
end;
type
/// <summary>Class that creates a backup of the user database in a thread
/// while displaying a "wait" dialogue box if necessary.</summary>
TUserDBBackupUI = class sealed(TUserDBWaitUI)
strict private
type
/// <summary>Thread that performs backup operation.</summary>
TBackupThread = class(TThread)
strict private
var
/// <summary>Name of backup file to be created.</summary>
fBakFileName: string;
strict protected
/// <summary>Backs up the user database.</summary>
procedure Execute; override;
public
/// <summary>Constructs a new, suspended, thread that can backup the
/// database to the given backup file.</summary>
constructor Create(const BakFileName: string);
end;
public
/// <summary>Performs a user database backup operation from in a background
/// thread and displays a wait diaogue box if the operation takes more than
/// a given time to execute. Blocks until the thread terminates.</summary>
/// <param name="AOwner">TComponent [in] Component that owns the dialogue
/// box, over which it is aligned.</param>
/// <param name="BakFileName">string [in] Name of backup file to be
/// created.</param>
class procedure Execute(AOwner: TComponent; const BakFileName: string);
end;
{ TUserDBMgr }
class procedure TUserDBMgr.AddCategory;
begin
// all work takes place in dialog box
TAddCategoryDlg.Execute(nil);
end;
class procedure TUserDBMgr.AddSnippet;
begin
// Display Add Snippet dialog box which performs update of database.
TSnippetsEditorDlg.AddNewSnippet(nil);
end;
class procedure TUserDBMgr.BackupDatabase(ParentCtrl: TComponent);
var
SaveDlg: TSaveDialogEx; // save dialog box used to name backup file
resourcestring
// Dialog box caption
sCaption = 'Save Backup';
begin
// Get backup file name from user via standard save dialog box
SaveDlg := TSaveDialogEx.Create(nil);
try
SaveDlg.OnCanClose := CanSaveDialogClose;
SaveDlg.Title := sCaption;
SaveDlg.Options := [ofShowHelp, ofExtensionDifferent, ofPathMustExist,
ofNoTestFileCreate, ofEnableSizing];
SaveDlg.HelpKeyword := 'SaveBackupDlg';
if SaveDlg.Execute then
// Perform backup
TUserDBBackupUI.Execute(ParentCtrl, SaveDlg.FileName);
finally
SaveDlg.Free;
end;
end;
class function TUserDBMgr.CanDeleteACategory: Boolean;
var
CatList: TCategoryList; // list of user deletable categories
begin
CatList := CreateUserCatList(False); // builds list of deletable user cats
try
Result := CatList.Count > 0;
finally
CatList.Free;
end;
end;
class function TUserDBMgr.CanDuplicate(ViewItem: IView): Boolean;
begin
Result := Supports(ViewItem, ISnippetView);
end;
class function TUserDBMgr.CanEdit(ViewItem: IView): Boolean;
var
SnippetView: ISnippetView; // ViewItem as snippet view if supported
begin
Assert(Assigned(ViewItem), ClassName + '.CanEdit: ViewItem is nil');
Result := Assigned(ViewItem)
and Supports(ViewItem, ISnippetView, SnippetView)
and SnippetView.Snippet.UserDefined;
end;
class procedure TUserDBMgr.CanOpenDialogClose(Sender: TObject;
var CanClose: Boolean);
var
FileName: string; // name of file entered in dialog box
resourcestring
// Error message
sFileDoesNotExist = '"%s" does not exist.';
begin
CanClose := False;
FileName := FileOpenEditedFileName(Sender as TOpenDialogEx);
if not FileExists(FileName) then
begin
// Specified file doesn't exist: inhibit closure
TMessageBox.Error(
Sender as TOpenDialogEx,
Format(sFileDoesNotExist, [FileName])
);
Exit;
end;
// All OK: allow closure
CanClose := True;
end;
class function TUserDBMgr.CanRenameACategory: Boolean;
var
CatList: TCategoryList; // list of user renamable categories
begin
CatList := CreateUserCatList(True); // build list of all user categories
try
Result := CatList.Count > 0;
finally
CatList.Free;
end;
end;
class function TUserDBMgr.CanSave: Boolean;
begin
// We can save database if it's been changed
Result := (Database as IDatabaseEdit).Updated;
end;
class procedure TUserDBMgr.CanSaveDialogClose(Sender: TObject;
var CanClose: Boolean);
var
FileName: string; // name of file entered in dialog box
resourcestring
// Error message
sOverwritePrompt = '"%s" already exists. OK to overwrite?';
begin
FileName := FileOpenEditedFileName(Sender as TSaveDialogEx);
if FileExists(FileName) then
// File exists: allow closure if user permits file to be overwritten
CanClose := TMessageBox.Confirm(
Sender as TSaveDialogEx,
Format(sOverwritePrompt, [FileName])
);
end;
class function TUserDBMgr.CreateUserCatList(
const IncludeSpecial: Boolean): TCategoryList;
var
Cat: TCategory; // references each category in snippets database
begin
Result := TCategoryList.Create;
for Cat in Database.Categories do
if Cat.UserDefined and
(IncludeSpecial or not TReservedCategories.IsReserved(Cat)) then
Result.Add(Cat);
end;
class procedure TUserDBMgr.DeleteACategory;
var
CatList: TCategoryList; // list of deletable categories
begin
CatList := CreateUserCatList(False);
try
// all work takes place in dialog box
TDeleteCategoryDlg.Execute(nil, CatList)
finally
CatList.Free;
end;
end;
class procedure TUserDBMgr.DeleteSnippet(ViewItem: IView);
// Builds a list of snippet names from a given snippet ID list.
function SnippetNames(const IDList: ISnippetIDList): IStringList;
var
ID: TSnippetID; // loops through all IDs in list
Snippet: TSnippet; // snippet corresponding to ID
begin
Result := TIStringList.Create;
for ID in IDList do
begin
Snippet := Database.Snippets.Find(ID);
Result.Add(Snippet.DisplayName);
end;
end;
var
Dependents: ISnippetIDList; // list of dependent snippet IDs
Referrers: ISnippetIDList; // list referring snippet IDs
ConfirmMsg: string; // message displayed to confirm deletion
Snippet: TSnippet; // snippet being deleted
resourcestring
// Prompts & error messages
sConfirmDelete = 'Please confirm you wish to delete %s';
sConfirmDeleteEx = 'Please confirm you wish to delete %0:s.' + EOL2
+ 'Deleting this snippet will also remove it from the cross reference list '
+ 'of the following snippets:' + EOL + ' %1:s';
sHasDependents = 'Sorry, this snippet can''t be deleted. It is required by '
+ 'the following snippets:' + EOL + ' %s';
begin
Assert(Supports(ViewItem, ISnippetView),
ClassName + '.Delete: Current view is not a snippet');
Snippet := (ViewItem as ISnippetView).Snippet;
Assert(Snippet.UserDefined,
ClassName + '.Delete: Snippet must be user defined');
// Check if snippet has dependents: don't allow deletion if so
Dependents := (Database as IDatabaseEdit).GetDependents(Snippet);
if Dependents.Count > 0 then
begin
TMessageBox.Error(
nil,
Format(
sHasDependents,
[SnippetNames(Dependents).GetText(',' + EOL + ' ', False)]
)
);
Exit;
end;
// Get permission to delete. If snippet has dependents list them in prompt
Referrers := (Database as IDatabaseEdit).GetReferrers(Snippet);
if Referrers.Count = 0 then
ConfirmMsg := Format(sConfirmDelete, [Snippet.DisplayName])
else
ConfirmMsg := Format(
sConfirmDeleteEx,
[
Snippet.DisplayName,
SnippetNames(Referrers).GetText(',' + EOL + ' ', False)
]
);
if TMessageBox.Confirm(nil, ConfirmMsg) then
(Database as IDatabaseEdit).DeleteSnippet(Snippet);
end;
class procedure TUserDBMgr.DuplicateSnippet(ViewItem: IView);
begin
Assert(CanDuplicate(ViewItem),
ClassName + '.DuplicateSnippet: ViewItem can''t be duplicated');
TDuplicateSnippetDlg.Execute(nil, (ViewItem as ISnippetView).Snippet);
end;
class procedure TUserDBMgr.EditSnippet(const SnippetName: string);
var
Snippet: TSnippet; // reference to snippet to be edited
begin
Snippet := Database.Snippets.Find(SnippetName, True);
if not Assigned(Snippet) then
raise EBug.Create(ClassName + '.EditSnippet: Snippet not in user database');
TSnippetsEditorDlg.EditSnippet(nil, Snippet);
end;
class procedure TUserDBMgr.MoveDatabase;
begin
// This dialogue box not available in portable edition
{$IFNDEF PORTABLE}
TUserDataPathDlg.Execute(nil);
{$ENDIF}
end;
class procedure TUserDBMgr.RenameACategory;
var
CatList: TCategoryList; // list of user defined categories
begin
CatList := CreateUserCatList(True);
try
// all work takes place in dialog box
TRenameCategoryDlg.Execute(nil, CatList)
finally
CatList.Free;
end;
end;
class function TUserDBMgr.RestoreDatabase(ParentCtrl: TComponent): Boolean;
var
Dlg: TOpenDialogEx; // open dialog box used to select backup file
resourcestring
sCaption = 'Open Backup File'; // dialog box caption
begin
// Get name of backup file from user via standard open dialog box
Dlg := TOpenDialogEx.Create(nil);
try
Dlg.OnCanClose := CanOpenDialogClose;
Dlg.Title := sCaption;
Dlg.Options := [ofShowHelp, ofPathMustExist, ofHideReadOnly,
ofEnableSizing];
Dlg.HelpKeyword := 'RestoreBackupDlg';
Result := Dlg.Execute;
if Result then
// Perform restoration
TUserDBRestoreUI.Execute(ParentCtrl, Dlg.FileName);
finally
Dlg.Free;
end;
end;
class procedure TUserDBMgr.Save(ParentCtrl: TComponent);
begin
TUserDBSaveUI.Execute(ParentCtrl);
end;
{ TUserDBWaitUI }
class procedure TUserDBWaitUI.RunThreadWithWaitDlg(const Thread: TThread;
const DlgOwner: TComponent; const WaitCaption: string);
begin
try
TWaitForThreadUI.Run( // this blocks until thread completes
Thread,
TWaitDlg.CreateAutoFree(DlgOwner, WaitCaption),
PauseBeforeDisplay,
MinDisplayTime
);
except
raise TExceptionHelper.Clone(ExceptObject as Exception);
end;
end;
{ TUserDBSaveUI }
class procedure TUserDBSaveUI.Execute(AOwner: TComponent);
resourcestring
// Caption for wait dialog
sWaitCaption = 'Saving user database...';
var
Thread: TSaveThread; // thread that performs save operation
begin
Thread := TSaveThread.Create;
try
RunThreadWithWaitDlg(Thread, AOwner, sWaitCaption);
finally
Thread.Free;
end;
end;
{ TUserDBSaveUI.TSaveThread }
constructor TUserDBSaveUI.TSaveThread.Create;
begin
inherited Create(True);
end;
procedure TUserDBSaveUI.TSaveThread.Execute;
begin
(Database as IDatabaseEdit).Save;
end;
{ TUserDBRestoreUI }
class procedure TUserDBRestoreUI.Execute(AOwner: TComponent;
const BakFileName: string);
resourcestring
// Caption for wait dialog
sWaitCaption = 'Restoring database files...';
var
Thread: TRestoreThread; // thread that performs restore operation
begin
Thread := TRestoreThread.Create(BakFileName);
try
RunThreadWithWaitDlg(Thread, AOwner, sWaitCaption);
finally
Thread.Free;
end;
end;
{ TUserDBRestoreUI.TRestoreThread }
constructor TUserDBRestoreUI.TRestoreThread.Create(const BakFileName: string);
begin
inherited Create(True);
fBakFileName := BakFileName;
end;
procedure TUserDBRestoreUI.TRestoreThread.Execute;
var
UserDBBackup: TUserDBBackup;
begin
UserDBBackup := TUserDBBackup.Create(fBakFileName);
try
UserDBBackup.Restore;
finally
UserDBBackup.Free;
end;
end;
{ TUserDBBackupUI }
class procedure TUserDBBackupUI.Execute(AOwner: TComponent;
const BakFileName: string);
resourcestring
// Caption for wait dialog
sWaitCaption = 'Backing up database...';
var
Thread: TBackupThread; // thread that performs restore operation
begin
Thread := TBackupThread.Create(BakFileName);
try
RunThreadWithWaitDlg(Thread, AOwner, sWaitCaption);
finally
Thread.Free;
end;
end;
{ TUserDBBackupUI.TBackupThread }
constructor TUserDBBackupUI.TBackupThread.Create(const BakFileName: string);
begin
inherited Create(True);
fBakFileName := BakFileName;
end;
procedure TUserDBBackupUI.TBackupThread.Execute;
var
UserDBBackup: TUserDBBackup; // object used to perform backup
resourcestring
// Dialog box caption
sCaption = 'Save Backup';
begin
UserDBBackup := TUserDBBackup.Create(fBakFileName);
try
UserDBBackup.Backup;
finally
UserDBBackup.Free;
end;
end;
end.
