PenCommander Scripting Language

What is PenCommand?

A PenCommand is a sequence of instructions that are performed when a command is called. Each PenCommand has a name. The name can be any sequence of numbers or letters up to 11 symbols long. The name cannot contain the following characters: # * < > @ and the white space. The @ character is reserved to for system commands and cannot be used for user-defined commands. For the best recognition results, we strongly recommend that you use only a...z and 0...9 characters for PenCommand names. Examples of correct PenCommand names include: “select”, “address”, “sel”, “a23”, etc. Incorrect names include: “my_home_address” (too long), “#account” (starts with ‘#’), and “*test” (starts with ‘*’). PenCommand Names are case insensitive. For example, “BTW”, “Btw” or “btw” are all recognized as the same name.

There are various categories of elementary instructions that can be used to build PenCommands. For example, “type predefined text”, “start program”, “delay execution”, “call user defined function”, etc.

Examples of PenCommands

PenCommands are written in PenCommander Script. A simplified form of PenCommand is a “Text Only” command. To create and edit Text Only PenCommands, you do not need to know the scripting language. You can use the Add PenCommand Wizard to create new Text Only PenCommands quickly and easily.

PenCommander Scripting Language

PenCommand Definition (extension) describes the sequence of instructions comprising the command. Its format:

Note: Command ID and special symbol names are case insensitive.

PenCommander execution process

PenCommander interprets instructions from the definitions of its commands one by one until the end of the definition. Some instructions can return a non-success return code (e.g. “Load library”, “Ask variable” etc.), in which case the execution of a PenCommand is interrupted and the error handler instruction is performed (if defined).

 

General commands

Mouse commands

Variable commands and symbols

Internal commands

Advanced commands


Variables

There are some internal variables which can be used in the parameter area of a PenCommand script:

You can omit the index digit 0 (e.g. <*str> is equal to <*str0>).

See Also
Special Symbols
Type Command



Type command

Keyword <#Type>
Parameters Any text string, including Special Symbols and Variables.
Action Emulates keyboard activity (e.g. for text input).
Remarks Parameter string for this command can include Special Symbols (e.g. “Escape”, “Home”, “BackSpace”, etc.) and Variables (*str1, *int1, etc.).

Important Note Any text after <#Type> command is treated as a parameter through the end of the file. <#Type> should be the last keyword in the PenCommand. To output '<' character use '<<'.

Examples:
// type 'John Smith'
<#type>John Smith
// type String0 variable
<#type><*str>
// type Ctr+C
<#Type><*ctr_dn>c<*ctr_up>

See Also
Special Symbols



Special symbols

Special symbols to use in the <#Type> command only.

See Also
Type Command



Show Options dialog command

Keyword <#Options>
Parameters Ignored.
Action Shows the CalliGrapher Options dialog box (starts Configuration Manager).


Show Message command

Keyword <#ShowMsg>
Parameters Text to show in the message box.
Action Shows Message Box with the given text.
Remarks You can use the symbol sequence ‘\n’ to force the new line in the message.

Example:
<#ShowMsg>Error while performing the PenCommand <*str7>.



Show Corrector window command

Keyword <#Corr>
Parameters Ignored.
Action Shows the CalliGrapher Corrector window in the Write Anywhere mode
Remarks This command has the same result as the Correct gesture.
Note: not supported in the Write Pad mode.


Set Symbol variable

Keyword <#SetSymb0> - <#SetSymb9>
Parameters Character to place to the symbol variable.
Action Set the appropriate symbol variable to given value.
Remarks Variable index 0 can be omitted. Only the first symbol from the Parameters area is used.

Example:
// Set Symbol0 to '®'
<#SetSymb>®

See Also
Ask Symbol variable
Variables



Set String variable

Keyword <#SetStr0> - <#SetStr9>
Parameters String to place to the string variable.
Action Set the appropriate string variable to given value.
Remarks Variable index 0 can be omitted.

Example:
// Set file name to String 4
<#SetStr4><*str3>\myfile.txt

See Also
Ask String variable
Variables



Set Integer variable

Keyword <#SetInt0> - <#SetInt9>
Parameters Number to place to the integer variable.
Action Set the appropriate integer variable to given value.
Remarks Variable index 0 can be omitted.

Example:
// Set Integer0 variable to 1000
<#SetInt>1000

See Also
Ask Integer variable
Variables



Set Error Handler command

Keyword <#DoIfErr>
Parameters Name of a PenCommand to execute.
Action Save name of a PenCommand as the error handler name.
Remarks This command sets the PenCommand name as an error handler. If the subsequent instructions in the current PenCommand definition return an error code (e.g. <#LoadLib> could not load user library), than the error handler PenCommand will be executed (if defined). This setting is good only for the PenCommands currently being executed and has no effect upon the nesting ones.

Example:
// Set error handler name to "%loaderr"
<#DoIfErr>%loaderr
// Load library0 "mylib.dll"
<#LoadLib>mylib.dll
// Set error handler name to "%callerr"
<#DoIfErr>%caller
// Call "MyFunc" from library0
<#CallLib>myfunc
// Turn of error handling
<#DoIfErr>
// Free Library0
<#FreeLib>

See Also
Load User Library (DLL)


Release Mouse Button command

Keyword <#BtnRlse>
Parameters Two integer values separated by a comma that specify X and Y mouse coordinates in pixels relative to the upper-left corner of the screen.
Action Emulates a left mouse button release (up) command at the specified coordinates.
Remarks This command can be used to emulate a left button up command at the specified location. The keyword should be followed by 2 integer values which specify X and Y coordinates relative to the upper-left corner of the screen. The mouse button up message is posted to the foreground window.

Example:
// emulate button up  at (200, 14)
<#BtnRlse>200,14

See Also
Click Mouse Button command
Press Mouse Button command


Click Mouse Button command

Keyword <#BtnClick>
Parameters Two integer values separated by comma that specify X and Y mouse coordinates relative to the upper-left corner of the screen in pixels.
Action Emulates a single left mouse button click at the specified coordinates.
Remarks This command can be used to emulate a left button down command at the specified location. The keyword should be followed by 2 integer values which specify X and Y coordinates relative to the upper-left corner of the screen. The mouse click message is posted in the foreground window.

Example:
// emulate button click at (200, 14)
<#BtnClick>200,14

See Also
Double-click Mouse Button command
Release Mouse Button command
Press Mouse Button command


Double-click Mouse Button command

Keyword <#DblClick>
Parameters Two integer values separated by comma that specify X and Y mouse coordinates relative to the upper-left corner of the screen in pixels.
Action Emulates a left mouse button double-click at the specified coordinates.
Remarks This command can be used to emulate a left button double-click command at the specified location. The keyword should be followed by 2 integer values which specify X and Y coordinates relative to the upper-left corner of the screen. The mouse double-click message is posted in the foreground window.

Example:
// emulate double-click at (200, 14)
<#DblClick>200,14

See Also
Click Mouse Button command
Release Mouse Button command
Press Mouse Button command


Press Mouse Button command

Keyword <#BtnPress>
Parameters Two integer values separated by a comma that specify X and Y mouse coordinates in pixels relative to the upper-left corner of the screen.
Action Emulates a left mouse button down command at the specified coordinates.
Remarks This command can be used to emulate a left button down command at the specified location. The keyword should be followed by 2 integer values which specify X and Y coordinates relative to the upper-left corner of the screen. The mouse button down message is posted to the foreground window.

Example:
// emulate button down at (200, 14)
<#BtnPress>200,14

See Also
Click Mouse Button command
Release Mouse Button command


Open File (Run Program) command

Keyword <#Start> "<file name>"
Parameters Path to the file to open or execute and [optional parameter string for starting program]. The file name can also be an URL (http://www.phatware.com) or an email address.
Action Starts a program, opens a file or URL, or sends email to specified address.
Remarks You must use quotes if file name contains spaces. Program parameters should be separated from the program name by the space symbol. If the file name parameter is an URL, the default Internet browser will be launched. If the file name parameter is an email address, the default email client will be launched.

Examples:
// start Pocket Word
<#Start>pword.exe

// Open "C:\My Documents\test.doc" file
<#Start>"C:\My Documents\test.doc"

// Compose email message
<#Start> "info@phatware.com"

// Open URL
// Copy the selected text to the <*str9> variable
<#Macro>clip
// Open URL stored in the <*str9> variable
<#Start> "<*str9>


Free user library (DLL)

Keyword <#FreeLib0> - <#FreeLib9>
Parameters Ignored.
Action Releases a user-defined DLL and unloads it from the memory.
Remarks Library index 0 can be omitted.

Example:
<#FreeLib3>

See Also
Load user library (DLL)
Call procedure from user library (DLL)



Load user library (DLL)

Keyword <#LoadLib0> - <# LoadLib9>
Parameters Path to user Dynamic Link Library (DLL) file to load.
Action Loads a user-defined Dynamic Link Library (DLL).
Remarks Library index 0 can be omitted. If file name includes spaces – use quotes.

Example:
<#LoadLib>\mylib.dll

See Also
Free user library (DLL)
Call procedure from user library (DLL)



Call procedure from user library (DLL)

Keyword <#CallLib0> - <#CallLib9>
Parameters Calling procedure name [optional parameters string for procedure].
Action Calls user defined procedure from a user-defined Dynamic Link Library (DLL).
Remarks Library index 0 can be omitted. Procedure name and parameters string must be separated by the space symbol. User defined procedure has access to internal PenCommand variables and can change them.

Note: You can find the example in the CalliGrapher Users Guide.

See Also
Free user library (DLL)
Load procedure from user library (DLL)
PenCommander user-defined functions



Delay command

Keyword <#Delay>
Parameters Time interval for delay (in milliseconds)
Action Delay PenCommand execution.
Remarks This command usually is used to give the system some time to perform the previously asked action before performing the next script command (e.g. wait after <#start> command).

Example:
// wait 1 second
<#Delay>1000



Comment command

Keyword <#>
Parameters Any text string (symbol ‘<’ should be doubled)
Action None.
Remarks There is another form of Comment-command: you can place a double slash “//” in the beginning of line. In this case the whole following line will be treated as a comment.

Example:
<#> This is the comment.
// PenCommand to place the address



Ask Symbol variable command

Keyword <#AskSymb0> - <#AskSymb9>
Parameters Title text to show in the dialog box.
Action Show dialog box for symbol value input. Set the appropriate symbol variable to given value.
Remarks Variable index 0 can be omitted. Current value of variable will be shown in the input field of dialog box.

Example:
// Place result to symbol4 variable
<#AskSymb4>Enter first letter for searching:

See Also
Set Symbol variable
Variables



Ask String variable command

Keyword <#AskStr0> - <#AskStr9>
Parameters Title text to show in the dialog box.
Action Show dialog box for string value input. Set the appropriate string variable to given value.
Remarks Variable index 0 can be omitted. Current value of variable will be shown in the input field of dialog box.

Example:
// Place result to *str4 variable
<#AskStr4>Please enter program file name:

See Also
Set String variable
Variables



Ask Integer variable command

Keyword <#AskInt0> - <#AskInt9>
Parameters Title text to show in the dialog box.
Action Show dialog box for integer value input. Set the appropriate integer variable to given value.
Remarks Variable index 0 can be omitted. Current value of variable will be shown in the input field of dialog box.

Example:
// Place result to *int2 variable
<#AskInt2>Please, Enter Zoom Percent:

See Also
Set Integer variable
Variables



Execute PenCommand command

Keyword <#Macro>
Parameters Name of the PenCommand to execute.
Action Executes a PenCommand.
Remarks The next PenCommand will be processed after this step of execution. Not more than 10 PenCommand execution levels can be nested. No recursion is allowed.

Examples:
// perform the PenCommand 'all'
<#Macro>all
// perform the PenCommand with its name taken from the variable String3
<#Macro><*str3>


Dial phone number command

Keyword <#Dial> ["<phone number>"] [P]
Parameters Phone number to dial. This parameter is required. Phone number may be enclosed in quotes.
Use the optional parameter P if you want to see the confirmation window before dialing the number.
Action Dial specified phone number.
Remarks If you use the P option, the phone number must be enclosed in quotes. This command may not be available on devices that do not have telephone module.

Examples:
// copy the selected text into the <*str9> variable
<#Macro>clip
// Dial the phone number stored in <*str9>
<#Dial> "<*str9>" P


Capture image/video command

Keyword <#Capture> [mode] ["<default folder>"] ["<default name>"]
Parameters Capture mode: SI - capture a still image (default); VO - capture a video clip without audio; AV - capture a video clip with audio.
<default folder> - specifies the directory for storing the captured picture or video file. If not specified, the image is stored in the directory defined in Pictures & Video > Camera Options > Type filename prefix:. If the directory does not exist, an error is generated.
<default name> - Specifies the file name for the captured still image or video clip. Still images on Windows Mobile-based devices conform to the JPEG standard. As a result, file names for still images must end in *.jpg. There is no restriction for naming video files, other than the file format must be supported by Windows Media Player Mobile. Since different video encoders can use differing naming conventions, it is important that the file name has the correct extension. To be safe, you can simply use do not specify the name. If this parameter is not specified, then the file name specified in Pictures & Video > Camera Options > Save files to: is used. If the file already exists, it is overwritten.
Action Captures still image (JPEG), video only, or video and audio with the built-in camera (if present).
Remarks This PenCommand is supported on Windows Mobile 5.0 or later only. The command can be used without parameters, in which case it will capture a still image and store in the default folder. The file name of the captured image is stored in the <*Str8> variable. If <*Str8> already contains data it will be overwritten.

Examples:
// Capture still image
<#Capture>

// Capture video & audio
<#Capture> AV
<#ShowMsg>New video file "<*Str8>".


Send SMS command

Keyword <#Sms> ["<address>"] ["<message>"] [P]
Parameters <address> - SMS address (phone number) of the recipient. It must be enclosed in quotes. If you do not know the address in advance, you use the empty string (""). If the address is an empty string, you will be prompted to enter the address of the recipient before the message is sent.
<message> - Message text; limited to 1000 characters; must be enclosed in quotes.
P
- Use this optional parameter if you want to see the confirmation window before sending SMS. Prompt window always appears if the <address> or the <message> or both parameters are empty.
Action Send SMS message.
Remarks Address and message parameters must be enclosed in quotation marks. If you want to specify the message text only, you must use an empty string as the SMS address, for example: <#Sms> "" "test message". You can also use this command without any parameters, in which case you will be prompted to enter recipient address and message text. This command may not be available on devices that do not have telephone module.

Examples:
// copy the selected text into the <*str9> variable
<#Macro>clip
// Send text stored in <*str9> as SMS
// PenCommand will prompt to enter the recipient address
<#Sms> "" "<*str9>"


Send Email command

Keyword <#Email> ["<service>"] ["<address>"] ["<message>"] [P]
Parameters <service> - email service name. To send email via the default email service use the empty string ("").
<address> - email address of the recipient. It must be enclosed in quotes. If you do not know the address in advance, you use the empty string (""). If the address is an empty string, you will be prompted to enter the address of the recipient before the message is sent. You can also specify multiple email addresses separated by semicolon.
<message> - Email message text; limited to 2000 characters; must be enclosed in quotes.
P
- Use this optional parameter if you want to see the confirmation window before sending the email message. Prompt window always appears if the <address> or the <message> or both parameters are empty.
Action Send email message.
Remarks Service name, address and message parameters must be enclosed in quotation marks. If you want to specify the message text only, you must use empty strings as the service name and the email address, for example: <#Email> "" "" "test message". You can also use this command without any parameters, in which case you will be prompted to select email service, and enter recipient address and message text.
The first line of the message text  (up to 120 characters) is used as the email subject.

Examples:
// copy the selected text into the <*str9> variable
<#Macro>clip
// Send text stored in <*str9> as email
// PenCommand will prompt to enter the recipient address
<#Email> "" "" "<*str9>"
// Send email to the address stored in <*str9>
<#Email> "" "<*str9>" "Test email message"


Show Shape Selector command

Keyword <#Shape>
Parameters None.
Action Opens the Letter Shape Selector dialog box for the current configuration.


Show/Hide Custom Keyboard command

Keyword <#CustKbrd>
Parameters None.
Action Toggles the CalliGrapher Custom keyboard.
Remarks This command is equivalent to the up/down gesture when nothing is selected.


Show/Hide Full Keyboard command

Keyword <#Kbrd>
Parameters None.
Action Toggles the CalliGrapher Full keyboard.
Remarks This command is equivalent to the function of the Keyboard button in CalliGrapher toolbar.


Start PhatPad command

Keyword <#PhatPad>
Parameters None.
Action Starts PhatWare PhatPad application (if installed).
Remarks This command is equivalent to the function of the Scratchpad button in CalliGrapher toolbar.


Show/Hide Toolbar command

Keyword <#Toolbar>
Parameters None
Action Toggles the visible state of CalliGrapher toolbar in the Write Anywhere mode.
Remarks This command is not supported in the Write Pad mode.


Create New Macro command

Keyword <#NewMacro>
Parameters None
Action Shows the Add Simple PenCommand dialog box. If any text is selected in the active application it will be copied into the dialog box.


Rotate Screen command

Keyword <#ScrMode>
Parameters 0 - Portrait mode
1 - Right-handed landscape mode
2 - Upside-down portrait mode
3 - Left-handed landscape mode
none - rotate to the next mode
Action Rotates Pocket PC screen to a certain position.
Remarks This command is only supported on the latest models of Pocket PC 2003 that natively support landscape mode. Some older devices also could be upgraded to the latest version of the Microsoft Windows Mobile software that supports screen rotation. If you are not sure whether your Pocket PC supports landscape mode, contact the manufacturer of the device.
 

Example:
<#ScrMode> // rotate to the next orientation



Set Recognition Mode command

Keyword <#RecMode>
Parameters 0 - Normal mode
1 - Capitals mode
2 - Numeric mode
3 - Internet mode
none - selects next recognition mode
Action Changes CalliGrapher recognition mode (mixed, capital, numeric, internet).


Set Recognition Direction command

Keyword <#RecDir>
Parameters 0 - Normal orientation
1 - Device turned right 45 degrees
2 - Device turned right 90 degrees
3 - Device turned 180 degrees
4 - Device turned left 90 degrees
5 - Device turned left 45 degrees
none - selects next direction
Action Changes CalliGrapher recognition direction (screen orientation)


Select CalliGrapher Configuration command

Keyword <#Cfg>
Parameters Configuration name
(if name is not given the next configuration is selected)
Action Switches active CalliGrapher configuration.


PenCommander user-defined functions

PenCommander includes macrousr.dll which is loaded when the system PenCommand @CgrOnInit is executed. This DLL is located in \Windows folder and includes the following functions which can be called using the <#CallLib> keyword.

 

Function: UsrEmptyClipboard
Action: This function empties the clipboard and frees handles to data in the clipboard.
Parameters: None.

Example:
// Empty clipboard
<#CallLib>UsrEmptyClipboard

[top]

 

Function: UsrSetStrFromClipboard <strnum>
Action: This function copies the text from the system clipboard to the specified string variable. If the clipboard content is larger than 255 characters, it will be truncated.
Parameters:

strnum 0-based index of string variable that receives Clipboard data. Must be a positive integer number between 0 and 9.

Example:
//Copy selected text to str#9
<#CallLib>UsrEmptyClipboard
<#Type><*ctr_dn>C<*ctr_up>
<#Delay>400
<#CallLib>UsrSetStrFromClipboard 9

[top]

 

Function: UsrSetClipboardFromStr <strnum>
Action: This function copies the text from the specified string variable to the system clipboard.
Parameters:

strnum 0-based index of string variable containing the text you want to put to the clipboard. Must be a positive integer number between 0 and 9.

Example:
//Copy string #3 to clipboard
<#CallLib>UsrSetClipboardFromStr 3
<#Delay>500

[top]

 

Function: UsrMathFuncs <funcname> <param1> [param2]
Action: This function uses the mathematical function <funcname> to calculate a new value. The result is displayed in the message box that appears when the calculation is completed.
Parameters:

funcname Math function name. Could be one of the following values:

  • sqrt – calculates square root of param1
  • power – calculates param1 raised to the power of param2
  • exp – calculates the exponential of param1
  • sin - determines the sine of a param1 (an angle in radians)

param1 first function parameter
param2 second function parameter (where required).

Example:
//Math Power function applied to selected text
<#Macro>clip
<#CallLib>UsrMathFuncs power <*str9>

[top]

 

Function: UsrTextStat
Action: This function calculates clipboard text statistics, such as number of symbols, words, sentences and paragraphs. The result is displayed in the message box.
Parameters: None.

Example:
//Get statistics for the selected text
<#Macro>clip
<#CallLib>UsrTextStat

[top]

 

Function: UsrMakeList
Action: This function makes a list of words from the clipboard text. The result is copied back to the clipboard.
Parameters: None.

Example:
//Create word list for the selected text
<#Macro>clip
<#CallLib> UsrMakeList

[top]

 

Function: UsrPutTimeToStr <strnum> [format]
Action: This function copies the current time into the specified string variable. The time is formatted according to current local settings.
Parameters:

strnum 0-based index of string variable that receives Clipboard data. Must be a positive integer number between 0 and 9
fomat
optional parameter which indicates the time format: 1 - long time format (with seconds); 0 – short time format

Example:
//Type current time
<#CallLib>UsrPutTimeToStr 5
<#Type><*str5>

[top]

 

Function: UsrPutDateToStr <strnum> [format]
Action: This function copies the current date into the specified string variable. The date is formatted according to current local settings.
Parameters:

strnum 0-based index of string variable that receives Clipboard data. Must be a positive integer number between 0 and 9
fomat
optional parameter which indicates the time format: 1 - long date format;  0 - short date format

Example:
//Insert current date
<#CallLib>UsrPutDateToStr 5 1
<#Type><*str5>

[top]

 

Function: UsrSendForegroundMessage <resnum> <msg> [wParam] [lParam]
Action: This function sends the specified message to a foreground window. It calls the window procedure for the foreground window and does not return until the window procedure has processed the message. If there is no foreground window, the function returns an error.
Parameters:

resnum 0-based index of numeric variable that receives the return value of the SendMessage function. Must be a positive integer number between 0 and 9.
msg specifies the message to be sent
wParam Specifies additional message-specific information (optional; if not specified, set to 0)
lParam Specifies additional message-specific information (optional; if not specified, set to 0)

Example:
// Get window text length
<#CallLib>UsrSendForegroundMessage 1 14

[top]

 

Function: UsrSendFocusMessage <resnum> <msg> [wParam] [lParam]
Action: This function sends the specified message to a window that currently has a keyboard focus. It calls the window procedure for the focused window and does not return until the window procedure has processed the message. If there is no focused window, the function returns an error.
Parameters:

resnum 0-based index of numeric variable that receives the return value of the SendMessage function. Must be a positive integer number between 0 and 9.
msg specifies the message to be sent
wParam Specifies additional message-specific information (optional; if not specified, set to 0).
lParam Specifies additional message-specific information (optional; if not specified, set to 0).

Example:
// Select all text in the edit box
<#CallLib>UsrSendFocusMessage 1 177 0 -1

[top]

 

Function: UsrPostForegroundMessage <msg> [wParam] [lParam]
Action: This function places a message in the message queue associated with the thread that created the foreground window and then returns without waiting for the thread to process the message. If there is no foreground window, the function returns an error.
Parameters:

msg specifies the message to be sent (required)
wParam Specifies additional message-specific information (optional; if not specified, set to 0)
lParam
Specifies additional message-specific information (optional; if not specified, set to 0)

Example:
// Close dialog box (emulate OK button press)
<#CallLib>UsrPostForegroundMessage 1 273 1

[top]

 

Function: UsrPostFocusMessage <msg> [wParam] [lParam]
Action: This function places a message in the message queue associated with the thread that created the window that has the current keyboard focus and then returns without waiting for the thread to process the message. If there is no foreground window, the function returns an error.
Parameters:

msg specifies the message to be sent (required)
wParam Specifies additional message-specific information (optional; if not specified, set to 0)
lParam Specifies additional message-specific information (optional; if not specified, set to 0)

Example:
// Paste data from clipboard
<#CallLib>UsrPostFocusMessage 770

[top]