Navigation: For Developers > Extend Functionality with HEScript >
|
|
Navigation: For Developers > Extend Functionality with HEScript >
|
|
Welcome to the HEScript Function Reference. This comprehensive guide will empower you to harness the full potential of HEScript in controlling your ebook or application's behavior and interacting with the HTML Executable runtime module and Windows environment.
HEScript scripts are tailored to enhance your application's capabilities. They provide a wide array of internal functions and macros that can be seamlessly integrated into your scripts.
📚 Notes:
ØSome internal functions, although not listed here, can be utilized in system HTML pages. Feel free to reach out to us for more information.
ØExplore additional references to Pascal Object on DelphiBasics.
The `MessageBox` function allows you to display user-friendly message boxes, akin to the Windows API MessageBox.
function MessageBox(const Text: String; const Title: String; const Flags: Integer): Integer;
•Text: Content of the message box.
•Title: Title of the message box.
•Flags: A set of bit flags that dictate the content and behavior of the box. For detailed information, check here.
Flag examples:
oMB_OK
oMB_OKCANCEL
oMB_YESNOCANCEL
oMB_YESNO
Additionally, you can use:
•MB_ICONSTOP
•MB_ICONINFORMATION
•MB_ICONWARNING
•Result (integer): Returns IDOK, IDCANCEL, etc., based on the user's selection.
Display a customizable message box with the `MessageDlg` function.
function MessageDlg(const Message: String; const Title: String; DialogType: TMsgDlgType; Buttons: TMsgDlgButtons): Integer;
•Message: Content of the message box.
•Title: Title of the message box.
•DialogType: Enumerated values like mtWarning, mtError, mtInformation, mtConfirmation, or mtCustom.
•Buttons: Flags defining the message box buttons, such as mbYes, mbNo, mbOK, mbCancel. Example: [mbYes, mbNo].
Example:
MessageDlg("My message", "My title", mtInformation, [mbOK]);
For more details, refer to DelphiBasics.
Note: Avoid calling this function during initialization or when the publication exits.
`SetUIProp` sets the value of a specified property for a control.
procedure SetUIProp(const id, propname, propval: String);
•id: Name of the control.
•propname: Name of the property.
•propval: New value (always a string).
Retrieve the value of a specified property for a control with the `GetUIProp` function.
function GetUIProp(const id, propname: String): String;
•id: Name of the control.
•propname: Name of the property.
•result: The property's value (in string format). If the control is not found, an error may occur.
Modify the status bar text with the `ChangeStatusBar` function.
procedure ChangeStatusBar(const Text: String; Reset: Boolean);
•Text: New text to display in the status bar.
•Reset: If true, the text will be set as the default.
Control the display of navigation panels using the `ShowLeftPanel` function.
procedure ShowLeftPanel(const id: Integer; OpenIt: Boolean);
•Id: Index of the panel you wish to display.
•OpenIt: If false, the navigation panel is hidden (regardless of the Id). If true, the panel is displayed.
Possible ID values:
•1: Search
•2: Table of Contents (TOC)
•3: unused
•4: Favorites
Please note that the navigation panel must be enabled in HTML Executable to ensure proper functionality.
Retrieve the index of the currently displayed navigation panel using the `GetLeftPanel` function.
function GetLeftPanel: Integer;
•Result: Index of the currently displayed panel. Returns 0 if no panel is displayed.
Display the About box with the `ShowAboutBox` function.
procedure ShowAboutBox;
Show and hide a "Please wait..." dialog box using the `ManageWaitForm` function.
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 calling `ManageWaitForm(True, "...")`, don't forget to call `ManageWaitForm(False, "...")` to hide the dialog box.
Navigate to the specified URL or execute a hescript command with the `GoToPage` function.
procedure GoToPage(const Name, Window: String);
•Name: Partial or full URL, hescript command, or internal protocol (e.g., ghe://heserver/).
•Window: the name of the window for the navigation. Cabn be one of the special HTML Executable targets.
Display the HTML page corresponding to the given map ID using the `UseMapID` function.
procedure UseMapID(const ID: Integer);
•ID: Map ID of the HTML page. More information here.
Refresh the entire page with the `ReloadPage` function.
procedure ReloadPage;
Retrieve the full URL of the currently displayed HTML page with the `GetCurrentHTMLPagePath` function.
function GetCurrentHTMLPagePath: String;
•Result: The full URL of the current page.
Terminate the publication with the `ExitPublication` function.
procedure ExitPublication;
Execute common navigation commands with the `NavigateCommand` function.
procedure NavigateCommand(const Command: Integer);
•Command: One of the following values:
o0: Return to the previous page (back).
o1: Move to the next page (forward).
o2: Unused
o3: Copy selected text to clipboard.
o4: Select the entire page.
o5: Paste text from clipboard.
o6: Page zoom in.
o7: Page zoom out.
o8: Unused
o9: Cut selected text to clipboard.
o10: Show developer tools (or hide them)
Navigate to the previous page in a Browse Sequence.
procedure SeqGoPrevious;
Navigate to the next page in a Browse Sequence.
procedure SeqGoNext;
Execute a script function in an HTML page (JavaScript).
procedure ExecuteHTMLScript(const CommandLine, Page: String);
•CommandLine: The JavaScript code to run,
•Page: Leave empty.
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')", "JavaScript");
Refresh the Table of Contents.
procedure RefreshTOC;
Especially useful when working with the Visibility HEScript function.
Load the Table of Contents from an XML file previously saved with HTML Executable.
procedure LoadTOCfromXMLFile(SourceFile: String);
•SourceFile: Full path to an existing XML file. If the XML file is stored inside the publication, use UnpackTemporaryResource first.
If SourceFile is empty, the publication loads the default Table of Contents.
Load an external PDF file directly into the publication's built-in PDF viewer (requires the built-in PDF viewer option to be turned on).
procedure LoadPDFFromFile(PDFPath: String);
•PDFPath: Full path to the PDF file you want to open. The PDF file must exist.
Send commands to the built-in PDF viewer.
function PDFViewerCommand(Command: Integer; Param: Integer): Integer;
•Command: A unique identifier for the command to be sent. See the list of all available commands.
•Param: An integer parameter related to the command sent.
•Result: Result from the built-in PDF viewer.
Send commands to the built-in PDF viewer.
function PDFViewerCommandStr(Command: Integer; Param: Integer): Integer;
•Command: A unique identifier for the command to be sent.
•Param: An integer parameter related to the command sent.
•Result: Result from the built-in PDF viewer.
These functions provide advanced control and interaction with the publication's content, including the ability to execute scripts, navigate sequences, and work with external files.
Get the value of a global variable.
function GetGlobalVar(const Name, DefaultIfNotFound: String): String;
•Name: Name of the global variable.
•DefaultIfNotFound: Value to return if the global variable is not found.
•Result: The value of the variable if it exists; otherwise, the value of DefaultIfNotFound.
Use global variables to store or exchange data between different scripts.
If several instances of a publication are running, call this function to force all global variables (only the persistent ones) to get the same value as the ones of the publication that made the call.
procedure SynchronizeGlobalVar;
Persistent global variables can be used to share data between several instances of a publication.
Return 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.
Return a unique system ID based on hardware specifications.
function GetManualHardwareID(method: Integer): String;
•method: Method identifier to compute the unique ID.
o0: Serial number of the first hard disk.
o1: Manufacturer-allocated number used to identify the physical media.
o2: CPU specifications such as CPU ID.
o3: Manufacturer-allocated number of the first hard disk.
If an error occurs, an empty value is returned.
Write 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
Write 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.
Read 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.
Read 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.
Return the unique ID of the runtime module used to run this publication.
function GetViewerSerial: String;
Provides an easy way to control the display of a block of HTML text. Works with HTML tags such as `<div>`, `<p>`, `<ul>`, `<form>`, `<table>`, and more. The block tag must contain an `ID=` attribute to identify it.
procedure ShowHTMLBlockID(const ID: String; Visible: Boolean);
•ID: ID of the HTML block.
•Visible: Setting Visible to False hides the block, and setting it to True displays the block.
This function works both in HTML Viewer and Internet Explorer (IE) browser publications.
Sets the value of a form field.
procedure SetFormControlValue(const ControlName, PropertyName, PropertyValue: String);
•ControlName: Name of the control or form field. There is no need to indicate which form the field belongs to, but your controls should have unique names on an HTML page.
•PropertyName: Which property should be set.
•PropertyValue: The new value to give to the property.
Gets the value of a form field.
function GetFormControlValue(const ControlName, PropertyName, DefValue: String): String;
•ControlName: Name of the control or form field. There is no need to indicate which form the field belongs to, but your controls should have unique names on an HTML page.
•PropertyName: The property whose value should be read.
•DefValue: The value if the control is not found.
•Result: Returns the value of the property in string format.
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.
Prints the current HTML page.
procedure PrintPages;
•Prints the current document. The standard Print Dialog will be shown.
Generates the HTML code for the given string.
function StrToHTML(const Str: String): String;
•Str: The string you want to convert to HTML.
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.
Opens an external document or program file (advanced: lets you specify the operation to execute).
function OpenFileAdv(const Filename, Parameters, Verb: String; State: Integer): Integer;
•Filename: Full path to the file you want to open or run.
•Parameters: Optional command line parameters.
•Verb: Specifies the action to be performed: open, runas, print…
•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.
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's 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.
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.
Returns the full path to a temporary file.
function GetTemporaryFilename: String;
This function may be useful for functions like SaveFormResultsToFile.
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.
Displays the standard File Open dialog box.
function OpenFileDialog(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).
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).
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.
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.
function UnpackVirtualResource(const SourceName: String; const DestFile: String): String;
For advanced users only.
•SourceName: Virtual path to the file you want to extract from the publication's data.
•DestFile: The path where the virtual resource should be unpacked to.
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.
Registers a Trial publication. Only working if you have a Trial publication. You should then call ActivateCertificate in order to apply changes.
procedure RegisterPub(name, data1, data2, key: String);
•Name: User name.
•Data1, Data2: Optional. Used to generate the key.
•Key: The key specified by the user.
This function will replace the current registration information items with the provided ones. For security reasons, it does not check the validity of the key: at the next startup, the publication will run with the certificate whose key was made for.
Forces the trial publication to activate the certificate that matches the current registration items saved by RegisterPub.
function ActivateCertificate: String;
Should only be used after a call to RegisterPub, and followed by ExitPublication. Returns the name of the selected certificate. Empty if no certificate matches.
Returns the name of the current certificate. Only working if you have a Trial publication.
function GetCurrentCertificate: String;
Sets the current certificate to the default one.
procedure SetDefaultCertificate;
This function causes the publication to come back to the Default certificate. If the default certificate has an expiration period, this period is automatically expired.
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.
Computes the MD5 hash sum of a Unicode string.
function MD5OfAStringUnicode(const Str: UnicodeString): UnicodeString;
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.
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”.
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).
Starts a timer to trigger an event, either one time or repeatedly, after a measured interval. Write the code that you want to occur at the specified time inside the UserMain's OnTimer function event.
procedure StartTimer(const TimerName: String; const Interval: Cardinal);
•TimerName: Name of the custom timer. NOT CURRENTLY USED. Just leave empty.
•Interval: Determines the amount of time, in milliseconds, that passes before the timer initiates another OnTimer event. For example, 1000 for one second. Note: A 0 value is valid, however, the timer won't call an OnTimer event for a value of 0.
Stops a timer that was created by StartTimer.
procedure StopTimer(const TimerName: String);
•TimerName: Name of the custom timer. NOT CURRENTLY USED. Just leave empty.
Converts a normal Unicode string to a UTF8 encoded string.
function StrUnicodeToUtf8(const Str: String): String;
•Str: The string you want to convert.
Converts a UTF8 encoded string to a normal Unicode string.
function StrUtf8ToUnicode(const Str: String): String;
•Str: The string you want to convert.
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.
Retrieves the contents from the Windows Clipboard as text.
function GetClipboardText: String;
Generates a random Integer number within the range RangeFrom to RangeTo inclusively.
function RandomRange(const RangeFrom, RangeTo: Integer): Integer;
To delve further into HEScript and expand your scripting capabilities, you can explore the following resources:
Additionally, if you want to understand how to use the Script Manager effectively:
These resources will provide you with more insights into HEScript and its practical applications.