HEScript Function Reference

HEScript scripts are especially designed to control the application's behavior and to communicate with the environment (Windows...).

You have a lot of internal functions that can be called from within the HEScript script functions/procedures.

Notes:

  • A lot of internal functions are not listed here at this time (but may be used in system HTML pages for instance). Please ignore them or contact us for more information.
  • You can find additional references to Pascal Object on http://www.delphibasics.co.uk/

Interface functions

Function name Description & prototype Parameters, example, remarks
MessageBox Displays a message box (similar to the Windows API MessageBox)

function MessageBox(const Text: String; const Title: String; const Flags: Integer): Integer;
* Text: the contents of the message box.
* Title: the title of the message box.
* Flags: set of bit flags that determine the contents and behavior of the box. More information here.
May be MB_OK, MB_OKCANCEL, MB_YESNOCANCEL, MB_YESNO, ….
plus MB_ICONSTOP, MB_ICONINFORMATION, MB_ICONWARNING…
* Result (integer): may be IDOK, IDCANCEL, …, IDYES, IDNO depending on the button selected by the user.
MessageDlg Displays a skinnable message box.

function MessageDlg (const Message : string; const Title: String; DialogType : TMsgDlgType; Buttons : TMsgDlgButtons) : Integer;
* Message: the contents of the message box.
* Title: the title of the message box.
* DialogType: can be one of the following enumerated values: mtWarning, mtError, mtInformation, mtConfirmation or mtCustom.
* Buttons: set of flags between [ ] that define the buttons of the message box: mbYes, mbNo, mbOK, mbCancel. Examples: [mbYes, mbNo] or [mbOK]
* Result (integer): may be IDOK, IDCANCEL, …, IDYES, IDNO depending on the button selected by the user.

Example:

MessageDlg(“My message”, “My title”, mtInformation, [mbOK]);

More details available here

Note: this function should not be called in the initialization event nor when the publication exits.
SetUIProp Sets the value of the specified property of a control whose name is given by id. For internal use.

procedure SetUIProp(const id, propname, propval: String);
* id: name of the control.
* propname: name of the property.
* propval: new value to give (always string).
GetUIProp Gets the value of the specified property of a control whose name is given by id. For internal use.

function GetUIProp(const id, propname: String): String;
* id: name of the control.
* propname: name of the property.
* result: the value of the property (in string format). If the control is not found, an error may occur.
ChangeStatusBar Sets the text of the status bar.

procedure ChangeStatusBar(const Text: String; Reset: Boolean);
* Text: new text to show in the status bar.
* Reset: if true, the text will be set as the default text.
ShowAboutBox Shows the About box.

procedure ShowAboutBox;
ManageWaitForm Shows and then hides a “Please wait…” dialog box.

procedure ManageWaitForm(Show: Boolean; Text: String);
* Show: True to show the dialog box, False to hide it.
* Text: text to display on the dialog box.

After having called ManageWaitForm(True, ”….”), do not forget to call ManageWaitForm(False, ”….”) to hide the dialog box.
Function name Description & prototype Parameters, example, remarks
GoToPage Displays (or executes) the specified URL.

procedure GoToPage(const Name, Window: String);
* Name: partial or full URL to display. This can be a single HTML page, a full URL (you can use the ghe://heserver/ internal protocol, or standard protocols like http, ftp, etc…) or even an hescript:// command.
* Window: do not use at this time (internal use only). Leave empty ””.
ReloadPage Reloads the entire page (refresh).

procedure ReloadPage;
GetCurrentHTMLPagePath Returns the full URL to the current HTML page displayed.

function GetCurrentHTMLPagePath: String;
* Result: the full URL to the current displayed page.
ExitPublication Terminates the publication.

procedure ExitPublication;
NavigateCommand Executes a common navigation command.

procedure NavigateCommand(const Command: Integer);
* Command: one of the following values:
0: return to the previous page (back).
1: move to the next page (forward).
2: unused.
3: copy selected text to clipboard.
4: select the entire page.
5: paste text from clipboard.
6: page zoom in.
7: page zoom out.
8: unused.
9: cut selected text to clipboard.
10: view source.
11: del selected text.
12: show Chromium developer tools.
13: update Chromium preferences (for instance, if you modified [proxy settings](proxy-settings))
ExecuteLiveHEScript Compiles and executes HEScript code at runtime.

function ExecuteLiveHEScript(const Code: String): String;
* Code: the HEScript code you want to execute. It must include begin and end;
Example to run a simple HEScript code:

ExecuteLiveHEScript("begin ShowMessage(""Test""); end;", false);

ExecutePHPScript Executes PHP code and optionally returns the output from PHP.

function ExecutePHPScript(const PHPCode: String): String;
* PHPCode: the PHP code you want to execute. It must include <?php and ?>.
* Result: output from PHP

Example to run a simple PHP code:

procedure TestRunScript;
var
SRes: String;
begin
SRes := ExecutePHPScript("<?php echo 'TEST'; ?>");
ShowMessage(SRes);
end;

The ExecutePHPScript function will return TEST

ExecuteHTMLScript Executes a JavaScript function in the current HTML page.

procedure ExecuteHTMLScript(const CommandLine, scriptURL: String);
* CommandLine: the script function you would like to call including its optional arguments.
* scriptURL: URL to the page for the context

Example: to call this simple JavaScript function:
<script language="JavaScript"> <!-- function Say(what) { window.alert(what) } --> </script>

use this:
ExecuteHTMLScript("Say('this is what I say')", "about:blank");

Management functions

Function name Description & prototype Parameters, example, remarks
SetGlobalVar Sets the value and properties of a global variable.

procedure SetGlobalVar(const Name, Value: String; const IsStored: Boolean);
* Name: name of the global variable.
* Value: new value for the global variable.
* IsStored: indicates whether the global variable is a persistent one, i.e. it is stored in the publication's state data file and restored when the publication is run again.

Use global variables to store or exchange data between different scripts.
GetGlobalVar Gets the value of a global variable.

function GetGlobalVar(const Name, DefaultIfNotFound: String): String;
* Name: name of the global variable.
* DefaultIfNotFound: what the function should return if the global variable is not found.
* Result: the value of the variable if it exists, otherwise the value of DefaultIfNotFound.

Publications use a lot of internal global variables. You can get a list of interesting ones here.
SynchronizeGlobalVar If several instances of a publication are running, call this function to force all global variables (only the persistent ones: see above) to get the same value as the ones of the publication who made the call.

procedure SynchronizeGlobalVar;
Persistent global variables can be used to share data between several instances of a publication.
GetString Returns the value of a resource string.

function GetString(const ID: String): String;
* ID: name of the resource string.
* Result: the value of the resource string, or empty if not found.
GetManualHardwareID Returns a unique system ID based on hardware specifications.

function GetManualHardwareID(method: integer): String;
* method: method identifier to compute the unique ID.
0: serial number of the first hard disk
1: manufacturer-allocated number used to identify the physical media
2: CPU specifications such as CPU ID
3: manufacturer-allocated number of first hard disk.

If an error occurs, an empty value is returned.
WriteRegStr Writes a string entry in the Windows registry.

procedure WriteRegStr(Root: Integer; Key,Ident,Value: String);
* Root: root key ID, see list below.
* Key: name of the subkey.
* Ident: name of the entry.
* Value: string value to be written.

List of root key IDs:

0: HKEY_CLASSES_ROOT
1: HKEY_CURRENT_CONFIG
2: HKEY_CURRENT_USER
3: HKEY_DYN_DATA
4: HKEY_LOCAL_MACHINE
5: HKEY_USERS
WriteRegDW Writes an integer entry in the Windows registry.

procedure WriteRegDW(Root: Integer; Key,Ident: String; Value: Integer);
* Root: root key ID, see list above.
* Key: name of the subkey.
* Ident: name of the entry.
* Value: integer value to be written.
ReadRegStr Reads the value of a string entry from the Windows registry.

function ReadRegStr(Root: Integer; Key,Ident,Default: String): String;
* Root: root key ID, see list above.
* Key: name of the subkey.
* Ident: name of the entry.
* Default: default return value if the entry is not found.
* Result: the value of the string entry.
ReadRegDW Reads the value of an integer entry from the Windows registry.

function ReadRegDW(Root: Integer; Key,Ident: String; Default: Integer): Integer;
* Root: root key ID, see list above.
* Key: name of the subkey.
* Ident: name of the entry.
* Default: default return value if the entry is not found.
* Result: the value of the integer entry.

HTML functions

Function name Description & prototype Parameters, example, remarks
GetFormFieldValue Returns the value of a control in the current HTML page.

function GetFormFieldValue(const NameField: String): String;
* NameField: element ID.
SetFormControlValue Sets the value of a form field.

procedure SetFormControlValue(const ControlName, PropertyName, PropertyValue: String);
* Controlname: ID of the element in the HTML page. There is no need to indicate which form the field belongs to. However your controls should have unique names in an HTML page.
* PropertyName: IGNORED.
* PropertyValue: the new value for the element.

This function works only in HTML Viewer publications!
You can use this function at any time, it does not require a form to be submitted first contrary to the previous functions.
ShowFindDialog Displays the Find Text dialog (search in the current HTML page only)

procedure ShowFindDialog(const FindText: String);
* FindText: default text to search for. Parameter only used with HTML Viewer publications.
PrintPDF Export the current webpage to a PDF file. Users are prompted for the output PDF filename.

procedure PrintPDF;
No parameters.
PrintPDFFile Export the current webpage to the specified PDF file. No prompt for users.

procedure PrintPDFFile(PDFFile: String);
PDFFile: full path to the PDF file to be created.
PrintPages Show the Print Page dialog box to let end users print the current webpage.

procedure PrintPages;
No parameters.
StrToHTML Generates the HTML code for the given string.

function StrToHTML(const Str: String): String;
* Str: the string you want to convert to HTML.
LoadHTMLFromMemory Loads the HTML contents from a TMemoryStream and displays it.

procedure LoadHTMLFromMemory(Contents: TMemoryStream; const Target: String);
* Contents: a TMemoryStream object that contains HTML data. The function does not free it.
* Target: leave it to ””.

Program /File / Folder functions

Function name Description & prototype Parameters, example, remarks
OpenFile Opens an external document or program file.

function OpenFile(const Filename, Parameters: String; State: Integer): Integer;
* Filename: full path to the file you want to open or run.
* Parameters: optional command line parameters.
* State: window state. May be SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, SW_HIDE…
* Result: successful if greater than 31.

For executable files, you may also use RunAProgram.
UnpackTemporaryResource Extracts a file from the publication's data (it must have been compiled) to a temporary file and returns the path to this file. The file is normally removed when the publication closes.

function UnpackTemporaryResource(const SourceName: String): String;
* SourceName: virtual path to the file you want to extract from the publication's data.
* Result: full path to the extracted temporary file on the user hard disk.

You can use this function to extract and run special files that cannot be handled by the publication, such as video, executable, etc…
Useful with OpenFile.
ExportAFile Same as the previous function, except that it will display a Save As dialog box, and the file is not temporary. Acts as when you download a file from the Internet.

function ExportAFile(const SourceName: String; PromptTitle, DefFilename: String): String;
* SourceName: virtual path to the file you want to extract from the publication's data.
* PromptTitle: the title of the Save As dialog box.
* DefFilename: the default filename that should be used. It can be “*.*”.
* Result: full path to the final unpacked file.

The file is not removed! Useful if you want to let your end users “download” files from your publication.
GetTemporaryFilename Returns the full path to a temporary file.

function GetTemporaryFilename: String;
This function may be useful for functions like SaveFormResultsToFile.
RunAProgram Executes the specified executable program file.

function RunAProgram(const Filename, Params, WorkingDir: String; Wait: Boolean; DispWindow: Integer): Boolean;
* Filename: full path to the .exe file you want to run.
* Params: optional command line parameters.
* WorkingDir: the path to the folder that should be set as the system current one.
* Wait: indicates whether the publication “sleeps” until the end of the program's execution.
* DispWindow: window state. May be SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, SW_HIDE…
* Result: True if the program was run successfully.

It does not work with document files.
OpenFileDialog Displays the standard File Open dialog box.

function OpenFileDialog(const aTitle, aFilename, aDefaultExt, aFilter, aInitialDir: String): String;

Example:
var
S: String;
begin
S := OpenFileDialog(“Select a File”, “*.*”, “*.*”, “All files (*.*)|*.*”, ””);
* aTitle: title of the dialog box.
* aFilename: default filename.
* aDefaultExt: default extension.
* aFilter: file extension filter.
* aInitialDir: initial directory.

Result: returns the full path to the selected file. If canceled, returns an empty string.

Warning: the Main Window must be available (do not use this function in an event like OnPubLoaded).
SaveFileDialog Displays the standard File Save As dialog box.

function SaveFileDialog(const aTitle, aFilename, aDefaultExt, aFilter, aInitialDir: String): String;
* aTitle: title of the dialog box.
* aFilename: default filename.
* aDefaultExt: default extension.
* aFilter: file extension filter.
* aInitialDir: initial directory.

Result: returns the full path to the selected file. If canceled, returns an empty string.

Warning: the Main Window must be available (do not use this function in an event like OnPubLoaded).
SelectDirectory Displays a browse folder dialog box.

function SelectDirectory(const Caption: String; const Root: String): String;
* Caption: indicative text asking for the folder.
* Root: the root folder. Optional: leave it empty to use the Desktop as the root folder.

Result: returns the full path to the selected folder. If canceled, returns an empty string.
ClearVirtualCache Clears the entire virtual memory storage.

procedure ClearVirtualCache;
For advanced users only.
UnpackVirtualResource function UnpackVirtualResource(const SourceName: String; const DestFile: String): String;

Extracts a file from the publication's data (it must have been compiled) to the virtual memory storage and returns the path to this file. The file only exists in memory: it is not on the hard disk. Nevertheless, it works as if it was on the hard disk at the specified path.
For advanced users only.

* SourceName: virtual path to the file you want to extract from the publication's data.
* DestFile: optional, a full path to the output virtual file. If you leave it empty, the path will be “publication's temporary folder+filename”.
* Result: full path to the virtual file or empty if an error occurred.

RemoveVirtualResource procedure RemoveVirtualResource(const DestFile: String);

Removes a file from the virtual memory storage and frees associated memory.
For advanced users only.

DestFile: full path to the virtual file that should be deleted.
GetSpecialFolderPath Returns the path to a special Windows folder

function GetSpecialFolderPath( FolderID: integer): String;
* FolderID: CSIDL_xxx value.
Result: full path to the folder.

Miscellaneous functions

Function name Description & prototype Parameters, example, remarks
ReplaceString Returns a string with occurrences of one substring replaced by another substring

function ReplaceString(const Original,OldPattern, NewPattern: string): String;
* Original: original string with old patterns.
* OldPattern: string to replace.
* NewPattern: the new string that takes the place.
* Result: the new string with all replaced patterns.

Similar to StringReplace in Delphi SysUtils.
MD5OfAString Converts the string to UTF-8 if not ANSI and computes the MD5 hash sum.

function MD5OfAString(const Str: String): String;
* Str: string you want to get the MD5 sum of.
Conversion from Unicode to UTF8 is done automatically.
* Result: string format of the MD5 sum.
MD5OfAStringUnicode Computes the MD5 hash sum of a Unicode string.

function MD5OfAStringUnicode(const Str: String): String;
* Str: string you want to get the MD5 sum of.
* Result: string format of the MD5 sum.
MD5OfAFile Gets the MD5 hash sum of the specified file.

function MD5OfAFile(const Path: String): String;
* Path: full path to the file you want to get the MD5 sum of.
* Result: string format of the MD5 sum.
InputBox Prompts your end users for a query (a dialog box is shown)

function InputBox(const Query, Title, Default: String): String;
* Query: the prompt text. Tells your end users what you are asking.
* Title: title of the dialog box.
* Default: the default value to display in the field.
* Result: returns what end users answered or an empty value if they chose “Cancel”.
TrayChangeIcon Change the icon displayed in the tray (if tray icon enabled)

procedure TrayChangeIcon(const IconFile: String);
* IconFile: full path to an external icon file, or virtual path to an icon file compiled inside the application.
The file must be a true icon file (.ICO extension).
ParamStr Returns the index-th parameter passed to the program using the command line.

function ParamStr(index: Integer): String;
* Index: index of the parameter you want to obtain.

Note: use double quotes to wrap multiple words as one parameter (such as long file names containing spaces).
StartTimer Starts the timer specified by TimerName to trigger an event, either one time or repeatedly, after a measured interval.
procedure StartTimer(const TimerName: String; const Interval: Cardinal);
* TimerName: name of the timer defined in the UI.
* Interval: determines the amount of time, in milliseconds, that passes before the timer initiates another action.
For example 1000 for one second. Note: A 0 value is valid, however the timer won't call the action for a value of 0.
StopTimer Stops a timer that was started by StartTimer.

procedure StopTimer(const TimerName: String);
* TimerName: name of the timer.
StrUnicodeToUtf8 Converts a normal Unicode string to a UTF8 encoded string.

function StrUnicodeToUtf8(const Str: String): String;
* Str: the string you want to convert.
StrUtf8ToUnicode Converts a UTF8 encoded string to a normal Unicode string.

function StrUtf8ToUnicode(const Str: String): String;
* Str: the string you want to convert.
SetClipboardText Set the contents of the Windows Clipboard to the text from Data.

procedure SetClipboardText(const Data: String);
* Data: the text data to put in the clipboard.
GetClipboardText Retrieves the contents from the Windows Clipboard as text.

function GetClipboardText: String;
RandomRange Generates a random Integer number within the range RangeFrom to RangeTo inclusively.

function RandomRange(const RangeFrom, RangeTo: Integer): Integer;

Some Delphi classes like TStringList, TMemoryStream are also supported.

To use these classes, you must define the Classes unit at the top of your scripts:

uses Classes;

To use the TRegistry object, define the Registry unit at the top of your scripts:

uses Registry;

For instance, the following script lets you remove a registry key:

uses Registry; 
procedure Test1;
var
reg: TRegistry;
begin
reg := TRegistry.Create;
reg.RootKey := HKEY_LOCAL_MACHINE;
reg.DeleteKey("Software  HEViewer  Coucou"); 
reg.CloseKey(); 
reg.Free;
end;

Some Windows dialog boxes such as Pick Color dialog box are also available through the script engine if you define the Dialogs unit:

uses Dialogs;

procedure StartIt;
var
 CD: TColorDialog;
 S: String;
begin
 CD := TColorDialog.Create(nil);
 CD.Execute(0);
 S := inttostr(CD.Color);
 ShowMessage(S);
 CD.Free;
end; 

Introduction to Scripting

Using the Script Manager