OnBeginUpgrade event

Applies to

acAutoUpgrader component.

Declaration

type

TacAUBeginUpgradeEvent = procedure(Sender: TObject;

const UpgradeMsg: String; UpgradeMethod: TacUpgradeMethod;

Files: TStringList; var CanUpgrade: Boolean) of object;

property OnBeginUpgrade: TacAUBeginUpgradeEvent;

Description

The OnBeginUpgrade event occurs when newer version of your application is available for download and AutoUpgrader are ready to upgrade it.

The OnBeginUpdate event occurs after successful downloading of the Info-file (which contains upgrade information), from location specified in InfoFileURL property. AutoUpgrader parses the info-file and retrieve the information required for upgrade. Some of this information passes to the OnBeginUpgrade event handler as parameters:

Parameter

Meaning

UpgradeMsg

this is the text string, specified in the downloaded Info-file, which describes release notes or new features in recent version. See UpgradeMsg property of the InfoFile structure for more information;

UpgradeMethod

determines how the application should be updated. Value can be either umAutoUpgrade (updated files will be automatically downloaded and replaced) or umRedirectToURL (user will redirected to first URL listed in Files parameter). See UpgradeMethod property for more information;

Files

the list of URLs to files which should be downloaded and updated locally;

CanUpgrade

set this variable to False if you do NOT want to continue the upgrade. To decide whether you want to download each file separately — use OnFileStart event.

At once after this event the AutoUpgrader will show the "Application update wizard" (if it is Enabled).

Example 1 (can be used if you want to implement custom dialog box which informs user about new version and prompts upgrade)

procedure TForm1.acAutoUpgrader1BeginUpgrade(Sender: TObject;

const UpgradeMsg: string; UpgradeMethod: TacUpgradeMethod;

Files: TStringList; var CanUpgrade: Boolean);

begin

CanUpgrade := Application.MessageBox('New version available. Would you like to upgrade?',

PChar(Application.Title), MB_YESNO or MB_ICONQUESTION) = ID_YES;

end;

Example 2 (awaiting while user click Next button, then do upgrade)

// This example demonstrates how to:

// 1. Check application for its updates;

// 2. Display the update information in some custom wizard (in OnBeginUpgrade event handler);

// 3. Do not upgrade imediately, wait until user press "Next" button (but don't smoke

//    the CPU with constant Application.ProcessMessages loop)

type

TCustomWizardForm = class(TForm)

public

WaitEvent: THandle; // handle for Wait and StopWait routines

ContinueUpgrade: Boolean;

end;

implementation

uses acUtils;

procedure TCustomWizardForm.FormShow(Sender: TObject);

begin

acAutoUpgrader1.CheckUpdate;

end;

procedure TCustomWizardForm.acAutoUpgrader1BeginUpgrade(Sender: TObject; const UpgradeMsg: String;

UpgradeMethod: TacUpgradeMethod; Files: TStringList; var CanUpgrade: Boolean);

begin

ContinueUpgrade := False;  // by default

Wait(WaitEvent, INFINITE); // wait for some action (until StopWait is called or application terminated)

CanUpgrade := ContinueUpgrade;

end;

// this will stop waiting and switch to next page of wizard

procedure TCustomWizardForm.WizardNextButtonClick(Sender: TObject);

begin

ContinueUpgrade := True;

StopWait(WaitEvent);

end;

See also

OnEndUpgrade, OnProgress, OnFileStart and OnFileDone events;

Wizard structure.