Application methods

The Application interface supports the following methods:

Alert(strMessage, [strTitle]) 
Returns  No return value 
Description  Displays an alert dialog with the specified message, and title if supplied.  
Usage 
JScript  Application.Alert("strMessage", ["strTitle"]);  
VBScript  Application.Alert "strMessage", ["strTitle"] 
Example 
// SoftQuad Script Language JSCRIPT:
Application.Alert("Your Message Here", "Your Title");
 

Beep 
Returns   No return value. 
Description  Makes a `beep' sound. 
Usage 
JScript  Application.Beep(); 
VBScript  Application.Beep 

CopyAssetFile(strSrcFile, strDestFile, [boolForceUpdate=false]) 
Returns   Boolean 
Description 

Copies the file at strSrcFile (which can be a file at any location or a URL) to the file strDestFile. Will not overwrite an existing file unless boolForceUpdate is true, and then only if the file is writable. strDestFile can be in one of four folders (and their subfolders):

  • The Assets folder
  • The folder containing the active document
  • The folder where documents are being opened from (the folder that the Open dialog currently displays)
  • The folder where documents are being saved to (the folder that the Save As dialog currently displays)

CopyAssetFile will create folders if necessary.

 
Usage 
JScript  Application.CopyAssetFile(strSrcFile, strDestFile, [boolForceUpdate]); 
VBScript  Application.CopyAssetFile(strSrcFile, strDestFile, [boolForceUpdate]) 

Confirm(strMessage, [strTitle]) 
Returns  Boolean 
Description  Displays a confirmation dialog box, displaying strMessage, and having title strTitle (if specified), containing [OK] and [Cancel] buttons. Clicking on these buttons returns true and false, respectively. 
Usage 
JScript  Application.Confirm("strMessage", ["strTitle"]);  
VBScript  Application.Confirm("strMessage", ["strTitle"]) 
Example 
// SoftQuad Script Language JSCRIPT:
var rVal;
rVal = Application.Confirm("Are you sure?", "Confirm");
Application.Alert(rVal);
 

DisableMacro(strMacroName) 
Returns   No return value 
Description 

Disables the macro strMacroName by disabling its shortcut key, and graying out its toolbar button and menu item (if any). The macro can still be run from the Macros dialog and Macros toolbar. This method is intended to be used only in the special On_Update_UI macro. Whenever On_Update_UI is called, any macros that were disabled the last time On_Update_UI was executed are automatically enabled again.

It is a good idea to have a macro that can be disabled in this way check for conditions that may also make it undesirable to run the macro from the Macros dialog or Macros toolbar when it is disabled. If the macro should not be run in this way, it can issue a `beep' using Application.Beep . If you know that you will never want to run it from the Macros dialog or Macros toolbar, set the macro's hide attribute to true (you should do this after you associate the macro with a toolbar and/or menu item).

 
Usage 
JScript  Application.DisableMacro("strMacroName"); 
VBScript  Application.DisableMacro "strMacroName"  
Example 
<MACRO name="On_Update_UI" lang="JScript">
// SoftQuad Script Language JSCRIPT:
if (!Document.IsValid) {
   DisableMacro("SaveAsRTF");
}
</MACRO>
 

DisablePlainTextView 
Returns   No return value 
Description  Disables the HoTMetaL PRO Plain Text view. Designed for customizers who do not want to make this view available to users. This method can be used at any time, but it is primarily intended to be used in the special On_Document_Open macro. 
Usage 
JScript  Application.DisablePlainTextView(); 
VBScript  Application.DisablePlainTextView 

EnableModeless(booleanProp) 
Returns  No return value 
Description  Enables or disables all currently visible modeless dialogs, depending on the value of booleanProp. Unexpected results may occur if one of the modeless dialogs becomes hidden between execution of EnableModeless(false) (disable) and EnableModeless(true) (enable); you should code so as to avoid this situation.  
Usage 
JScript  Application.EnableModeless(booleanProp);  
VBScript  Application.EnableModeless booleanProp 
Example 
// SoftQuad Script Language JSCRIPT:
// disable modeless dialogs
Application.EnableModeless(false);  
 

FileExists(strPath) 
Returns  Boolean 
Description  Returns a boolean indicating whether the file strPath exists.  
Usage 
JScript  Application.FileExists("strPath");  
VBScript  Application.FileExists("strPath") 
Example 
// SoftQuad Script Language JSCRIPT:
var exists;
exists=Application.FileExists("c:\\data\\food.xml");
 

FileToString(strPath) 
Returns  String 
Description  Returns the contents of the file strPath as a string. In effect, this enables you to read the file strPath and assign it to a variable. 
Usage 
JScript  Application.FileToString("strPath");  
VBScript  Application.FileToString("strPath") 
Example 
// SoftQuad Script Language JSCRIPT:
var docPath = "c:\\data\\mundo.txt";
if (Application.ReadableFileExists(docPath)) {
// This will return all the contents of the 
// file in string format
  var docToString= Application.FileToString(docPath);
} 
else {
  Application.Alert("Unable to read file.");
}
 

Help(intHelpType, [longContextID]) 
Returns  No return value 
Description  Run a command from the HoTMetaL PRO Help menu, determined by the value of intHelpType. Allowed values are:
  • 0: Help Contents
  • 1: Search for Help on...
  • 2: How to use Help
  • 4: SoftQuad Home Page
  • 7: About HoTMetaL...
  • 8: Display help topic with context ID longContextId in the HoTMetaL PRO help file.
 
Usage 
JScript  Application.Help(intHelpType [, longContextID]);  
VBScript  Application.Help intHelpType [, longContextID] 
Example 
// SoftQuad Script Language JSCRIPT:
Application.Help(0); 
//brings up the Help Contents dialog
 

HelpContext(strHelpFile, longContextID) 
Returns  No return value 
Description  Displays the help page containing the context ID longContextID, from the help file strHelpFile
Usage 
JScript  Application.HelpContext("strHelpFile", longContextID);  
VBScript  Application.HelpContext "strHelpFile", longContextID  
Example 
// SoftQuad Script Language JSCRIPT:

Application.HelpContext("hmpro6.hlp", 138);
 

HelpFinder(strHelpFile) 
Returns  No return value 
Description  Opens the help file strHelpFile
Usage 
JScript  Application.HelpFinder("strHelpFile");  
VBScript  Application.HelpFinder "strHelpFile" 
Example 
// SoftQuad Script Language JSCRIPT:
// Open the HoTMetaL PRO help file

Application.HelpFinder("hmpro6.hlp");
 

MessageBox(strMessage, longButtons, [strTitle]) 
Returns  Long 
Description  Displays a message box containing the text strMessage, with the (optional) title strTitle. The button configuration is determined by the longButtons value. The return value depends on which button the user clicks on.  
Usage 
JScript 
Application.MessageBox(strMessage,
    longButtons, [strTitle]);
 
VBScript 
Application.MessageBox(strMessage,
    longButtons, [strTitle])
 
Example 
// SoftQuad Script Language JSCRIPT:
var ans = Application.MessageBox("Can't save",
    18, "Warning");
// Using the warning icon (16), and the abort, 
// retry, and ignore buttons (2), 
// we have a input parameter of 18. 
Application.Alert(ans);
 

longButtons values

The first group of values (0 to 5) describes the number and type of buttons displayed in the dialog box; the second group (16, 32, 48, 64) describes the icon style; the third group (0, 256, 512, 768) determines which button is the default; and the fourth group (0, 4096) determines the modality of the message box. When adding numbers to create a final value for the argument buttons, use only one number from each group.

Value   Description  
0  Display OK button only 
1  Display OK and Cancel buttons 
2  Display Abort, Retry, and Ignore buttons 
3  Display Yes, No, and Cancel buttons 
4  Display Yes and No buttons 
5  Display Retry and Cancel buttons 
16  Display Critical Message icon 
32  Display Warning Query icon 
48  Display Warning Message icon 
64  Display Information Message icon 
0  First button is default 
256  Second button is default 
512  Third button is default 
768  Fourth button is default 
0  Application modal; the user must respond to the message box before continuing work in the current application. 
4096  System modal; all applications are suspended until the user responds to the message box. 

Message box return values

Value   Button Pressed  
OK 
Cancel 
Abort 
Retry 
Ignore 
Yes 
No 

NoticeBox(strMessage, strBut1, [strBut2], [strBut3], [strTitle])  
Returns  Long 
Description  Displays a notice box containing the text strMessage. Up to three buttons, with labels strBut1, strBut2, and strBut3 can be specified. The return values are 1, 2, or 3, corresponding to the button clicked by the user. The first button is the initial default. If strBut3 is omitted then a [Cancel] button with return value 3 is displayed. Pressing Esc or Alt+F4 always returns 3.  
Usage 
JScript  Application.NoticeBox("strMessage", "strBut1", ["strBut2"], ["strBut3"], ["strTitle"]);  
VBScript  Application.NoticeBox("strMessage", "strBut1", ["strBut2"], ["strBut3"], ["strTitle"])  
Example 
// SoftQuad Script Language JSCRIPT:
var ans = Application.NoticeBox("myMessage", "Yes",
       "No", "Abort", "Proceed?");
Application.Alert(ans);
 

PathToURL(strPath [, strBase]) 
Returns  String 
Description  If only strPath is provided, returns a URL corresponding to strPath. If strBase is specified, the return value is a URL corresponding to strPath, relative to strBase. strBase can be a path, relative URL, or file:/// URL to a `base' document. 
Usage 
JScript  Application.PathToURL("strPath" [,"strBase"]);  
VBScript  Application.PathToURL("strPath" [,"strBase"]) 
Example 
// SoftQuad Script Language JSCRIPT:
var u1, u2;
u1=Application.PathToURL("c:\\dir1\\dir2\\test.htm);
// Displays "file:///c|/dir1/dir2/test.htm"
Application.Alert(u1);
u2=Application.PathToURL("c:\\dir1\images\one.gif",
      "c:\\dir1\\dir2\\test.htm);
// Displays "..\images\one.gif"
Application.Alert(u2);
 

Prompt(strMessage, [strText], [intLength], [intMaxLength], [strTitle])  
Returns  String 
Description  Displays a dialog box containing a text box, above which is displayed the text strMessage. The dialog also contains [OK] and [Cancel] buttons. The text box will contain the default text strText, if specified. intLength and intMaxLength specify the size and maximum length of the text box. strTitle specifies a title for the dialog box. The text in the entry box is returned if the user clicks on [OK]; a null string is returned if the user clicks on [Cancel.] 
Usage 
JScript  Application.Prompt("strMessage", ["strText"], [intLength], [intMaxLength], ["strTitle"]);  
VBScript  Application.Prompt("strMessage", ["strText"], ["intLength"], ["intMaxLength"], ["strTitle"]) 
Example 
// SoftQuad Script Language JSCRIPT:

//Displays a text entry box with "Jams O'Donnell" 
// as the default entry
var you;
you=Application.Prompt("Enter your name", 
         "Jams O'Donnell");
 

Quit([intSaveChanges=0]) 
Returns  No return value 
Description  Quits HoTMetaL PRO, and may save changes to documents, depending on the value of intSaveChanges. The allowed values are:
  • 0: prompt the user to save changes (the default)
  • 1: save changes without prompting
  • 2: do not save changes
 
Usage 
JScript  Application.Quit([SaveChanges]);  
VBScript  Application.Quit [SaveChanges] 
Example 
// SoftQuad Script Language JSCRIPT:
// Quit and save all changes
Application.Quit(1); 
 

ReadableFileExists(strPath) 
Returns  Boolean 
Description  Indicates whether the file strPath exists and is readable. Returns false for never-saved documents. 
Usage 
JScript  Application.ReadableFileExists("strPath");  
VBScript  Application.ReadableFileExists("strPath") 
Example 
// SoftQuad Script Language JSCRIPT:
var readable;
var docPath = ActiveDocument.FullName;
readable = Application.ReadableFileExists(docPath);
 

RefreshMacros 
Returns   No return value 
Description  Refresh macros by reloading the currently loaded macro files. 
Usage 
JScript  Application.RefreshMacros(); 
VBScript  Application.RefreshMacros  

Run(strMacroName) 
Returns  No return value 
Description  Runs the macro named strMacroName.  
Usage 
JScript  Application.Run("strYourMacroName");  
VBScript  Application.Run ["strYourMacroName"] 
Example 
// SoftQuad Script Language JSCRIPT:
Application.Run("macroName");
 

RunKeyedMacro(strShortcutKey) 
Returns   No return value 
Description  Runs the macro that has the specified strShortcutKey.  
Usage 
JScript  Application.RunKeyedMacro("strShortcutKey"); 
VBScript  Application.RunKeyedMacro "strShortcutKey"  
Example 
// SoftQuad Script Language JSCRIPT:
Application.RunKeyedMacro("Ctrl+Alt+G");
 

UniqueFileName(strDirectory, strPrefix, [strExtension])  
Returns  String 
Description  Returns a filename, starting with strPrefix, that is not present in the folder strDirectory. The filename will have extension strExtension if specified; otherwise it will have the extension .tmp is used. strPrefix can be up to 3 characters long.  
Usage 
JScript  Application.UniqueFileName("strDirectory", "strPrefix", ["strExtension"]);  
VBScript  Application.UniqueFileName("strDirectory", "strPrefix", ["strExtension"]) 
Example 
// SoftQuad Script Language JSCRIPT:
// Return a unique filename in C:\ that 
// begins with "b" and has the extension ".sys"
var str = Application.UniqueFileName("C:", "b", ".sys");
Application.Alert(str);
 

URLToPath(strURL, [ strBase]) 
Returns  String 
Description  If only strURL is specified, returns a path corresponding to the URL strURL. strBase can be a path pointing to a document. If strURL is a relative URL, and strBase is specified, returns a full path corresponding to strURL using strBase as the base path. 
Usage 
JScript  Application.URLToPath("strURL" [,"strBase"]);  
VBScript  Application.URLToPath("strURL" [,"strBase"]) 
Example 
// SoftQuad Script Language JSCRIPT:
var p1, p2;
p1=Application.URLToPath("file:///c|/data/index.html");
// Displays "c:/data/index.html"
Application.Alert(p1);
p2=Application.URLToPath("../images/one.gif", 
      "d:\\dir1\\dir2\\test.htm");
// Displays "d:\dir1\images\one.gif"
Application.Alert(p2);
 

WritableDirExists(strPath) 
Returns  Boolean 
Description  Indicates whether the folder strPath exists and is writable. 
Usage 
JScript  Application.WritableDirExists("strPath");  
VBScript  Application.WritableDirExists("strPath") 
Example 
// SoftQuad Script Language JSCRIPT:
var exists;
var appPath = Application.Path;
exists=Application.WritableDirExists(appPath);
 

WritableFileExists(strPath) 
Returns  Boolean 
Description  Indicates whether the file strPath exists and is writable. 
Usage 
JScript  Application.WritableFileExists("strPath");  
VBScript  Application.WritableFileExists("strPath") 
Example 
// SoftQuad Script Language JSCRIPT:
var docPath = ActiveDocument.FullName;
Application.Alert(Application.WritableFileExists(docPath));
 


Right arrow
Next Topic
Left arrow
Previous Topic
Table of contents
Table of Contents

Copyright © SoftQuad Software Inc. 1999