Introduction

Macro Toolworks
by Pitrinec Software

www.MacroToolworks.com


Starting Program

After program installation, its group is created in the Start menu. To start the program just click program’s item in the Start menu. When the program is running, user can see its icon in the Taskbar tray area. Clicking on the icon will show/hide the program’s main window.

Running Program As a Service

It is possible (in Windows 2000, Windows XP or newer) to run the program as a service. Instead of starting Macro Toolworks as described above, run _prog_service.bat file that is located in Macro Toolworks installation folder. The Macro Toolworks will be started as usually but in addition, it will stay running even after a user is logged off the computer.


Macros, Creating Macros

Macro File

Macros are saved in a macro file. The name of the macro file currently opened in the Macro Toolworks is showing in the main program window title bar. One file contains multiple macros and groups so it is easy to backup or move all created macros to other computer. The user only needs take care of a single file. The file has .4mt.4pk.4cm.4ws.4tw extension.

Data Security Within a Macro File

The file is encrypted using in-house encryption technology so that its content cannot be viewed in any file viewer or other program. In addition, the macro files created in Macro Toolworks "Professional" edition are also encoded using AES industry standard cryptography algorithm. It ensures that all sensitive data within the macro file (macro text, passwords) are highly secure and safe from unauthorized retrieval. The AES encryption is indicated by "AES:Yes" in lower-right area of the main window. If "AES:No" is showing then the AES encryption is not applied to the macro file (editions other than "Professional").


Creating New File, Opening File

Macros created in the program are saved in a file, by default, located in the directory where the program is installed. User can create a new file using “File/New” menu command or open an existing file by clicking on “File/Open” menu command.
User can use the same macros on different computers (desktop and laptop) - just copy the macro file from one computer (desktop machine, for example) to other computer (laptop, for example).


Merging Two Files

It is possible to merge two files using "File/Insert" menu command. This command allows user to select a macro file that is to be added to currently opened macro file. After file is inserted, new group with the name of the inserted file is created in the left pane tree.

Note: Merging two files is something else than sharing macros.


HTML Output

Printable HTML Output

It is possible to export whole the macro file content to an HTML file that can be viewed using a web browser. This feature can be used for publishing macros on web, printing macro list or other processing of macros.

HTML File: Generated HTML file.

Include macro content: If checked, also macro script is included to the HTML output. Otherwise the macro is not included.

Selected group only: If checked, only macros from currently selected group are exported to the HTML file. Otherwise whole the macro file content is exported.


Macro Groups

Macros are organized in user defined hierarchical groups (left pane in the main window). This allows user to logically organize macros. It is possible to use drag & drop to change the hierarchical structure of the groups. If Ctrl key is held down on drop then the group is moved as a child group, otherwise it is added as a neighbor.

1. Group Properties - General:

  • Label - the name of the group

  • Description - user can put any description or notes here.

  • Password - user can password protect macros from this group.

  • Change icon - button to select/change icon.

  • Disabled - if checked, all macros from the given group do not react to their defined triggers.

  • Remote macro call (RMC) enabled - if checked then it is possible to call macros from this group over network from a remote computer (read more also in: main settings section, <remote_macro_call> command). It is good idea to password protect the group if the RMC is enabled.

  • Default trigger type - the user select what kind of macro trigger is by default assigned to new macros from this group.

If the default trigger type is "Toolbar button" then there are additional settings:

  • Tab in main toolbar - if selected then the group is represented as a tab in main toolbar. Macros from this group will be (by default, if not specified otherwise) showing as buttons in this toolbar tab.

  • Flying toolbar - if selected then the group is represented as a flying toolbar (toolbar window). Macros from this group will be (by default, if not specified otherwise) showing as buttons in this flying toolbar. There are some additional settings:
    [ ] Attach ... - the flying toolbar is always positioned to active window title bar.
    [ ] Autohide - the toolbar only shows in its total size if mouse cursor is positioned on it.
    [ ] Show button text     - if checked, the button text is shown next to button icon.

  • Submenu - if selected then the group is represented as a submenu. Macros from this group will be (by default, if not specified otherwise) showing as submenu items.

  • No toolbar - if selected then the group has no visual representation and macros from this group (by default) do not show in any toolbar or submenu.

[ ] Use custom color option allows a user to define a toolbar/submenu/tab background color.

If the default trigger type is "Toolbar button" then there are additional settings:

  • Tab in main toolbar - if selected then the group is represented as a tab in main toolbar. Macros from this group will be (by default, if not specified otherwise) showing as buttons in this toolbar tab.

  • Flying toolbar - if selected then the group is represented as a flying toolbar (toolbar window). Macros from this group will be (by default, if not specified otherwise) showing as buttons in this flying toolbar. There are some additional settings:
    [ ] Attach ... - the flying toolbar is always positioned to active window title bar.
    [ ] Autohide - the toolbar only shows in its total size if mouse cursor is positioned on it.
    [ ] Show button text     - if checked, the button text is shown next to button icon.

  • Submenu - if selected then the group is represented as a submenu. Macros from this group will be (by default, if not specified otherwise) showing as submenu items.

  • No toolbar - if selected then the group has no visual representation and macros from this group (by default) do not show in any toolbar or submenu.

[ ] Use custom color option allows a user to define a toolbar/submenu/tab background color.

2. Group Properties - Scope:

It is possible to make macros from the given group windows specific. This means that the macros will be available only in windows user specifies. There are three options available:

  • Macros are available in all windows (this is default).

  • Macros are available only in windows user specifies.

  • Macros are available in windows other then user specifies.

See also “Scope Of Macros” section.

3. Before/After Macro:

For each macro group, the user can specify so called "before" macro and "after" macro. The "before" macro is automatically executed before macro from this group, the "after" macro is executed after macro execution is finished. Example: Let's say we have a group with five macros named 1,2,3,4,5 and the macro 1 is defined as "before" macro and macro 2 is defined as "after" macro. Now when user starts macro 4, for example, the macro 1 is executed, then macro 4 is executed and then macro 2 is executed.

In addition, it is possible to define "before code" and "after code" macro code. The "before code" macro code is inserted on begin of each macro from the group. The "after code" macro code is added to the end of each macro from the group. The "before code" and "after code" allow users to simply modify macro execution globally without necessity to manually rewrite each of them. The "before code" can be used to check for specific conditions that must be fulfilled in order to run a macro (for example, if the computer is connected to internet, if required window is opened, etc.) or to include (<-include-> command) a library file with pre-defined procedures.

4. Group Properties - Fonts:

User can select fonts used for macro editing in this tab.


Macros, Creating Macros

Macros

List of macros from the selected group is shown in the macros view (upper right pane in the main window). Properties of the macro selected in this list are displayed in a tabbed view below .


Starting Program

Macros and Clipboard Macros

There are two basic macro types: Macros and Clipboard Macros.

  • Macros
    Macros have a wild range of possible use - from simple text insertion to sophisticated scripts    . When the macro is started by the user then the macro text is being "executed" by Macro Toolworks. If there are commands in the macro text then they are executed and the rest of the macro text is simply sent to target application as set of keystrokes.
  • Clipboard Macro
    Clipboard Macro is simply clipboard content saved for later pasting in target application. When such a clipboard macro is started then the saved clipboard data are pasted to target application. Unlike macros, the clipboard macros can contain graphics, formatted text etc. but cannot contain commands.


Macros, Creating Macros

Creating New Macro

There are several ways how to create new macro - (i) “Insert/Add Macro” main menu item, (ii) right click in the macros view and select “Add Macro” menu item or (iii) using “Add Macro” toolbar button. Novice users may appreciate "Add Wizard" feature that is available on "Ctrl+W" hotkey (or from program's menu and toolbar as well). The macro wizard guides user through whole the macro creation process and gives user better understanding of how the macros are organized in the program and how all the macro options/settings/attributes can be later accessed and changed.

Creating New Clipboard Macro

Again, there are several ways how to create new clipboard macro - (i) “Insert/Add Clipboard Macro” main menu item, (ii) right click in the macros view and select “Add Clipboard Macro” menu item or (iii) using “Add Clipboard Macro” toolbar button. Novice users may appreciate "Add Wizard" feature that is available on "Ctrl+W" hotkey (or from program's menu and toolbar as well).


Macro recording

Other way how to create certain type of macros - macros that “playback” keystrokes and/or mouse clicks - is recording. During macro recording, all keystrokes and mouse clicks user performs are recorded to the new macro. There are several ways how to issue new macro recording - (i) “Insert/Record Macro” main menu item, (ii) right click in the macros view and select “Record Macro” menu item or (iii) using “Add” toolbar button and “Record Macro” menu item.

1. Events to Record

In this first step, the user can select what events (mouse or keyboard or both) should be recorded:

  • Keyboard - if checked, all keyboard events (keystrokes) are recorded.
  • Mouse - if checked, all mouse clicks are recorded.
  • Record mouse movements - if checked, mouse movements are also recorded so that mouse cursor movements are smooth when playing macro back. (Note: The size of macro recorded is much bigger.)
  • Mouse coordinates - specifies if mouse coordinates is relative to:
    1. Absolute (screen) coordinates
    2. Coordinates relative to active window
    3. Coordinates relative to current mouse position
  • Record timing information - if checked, timing information is saved during macro recording.

Use "Default" button to pre-select default settings suitable for majority of users.

2. Save Macro

In this step, the user defines where to save the macro recorded in memory:

  • Add new item to the currently selected group - new macro is added to the currently selected group.
  • Overwrite currently selected macro - currently selected macro is overwritten by the new one recorded.
  • Add new macro to this group - macro is added to the group selected using “Select” button.
  • Overwrite this macro - macro selected using “Select” button is overwritten by the recorded one.

Use "Default" button to pre-select default settings suitable for majority of users.

3. Window to Activate

It is possible to define now what window will be activated on macro playback start:

  • None - the macro playback will start in the currently active window. This option is used for macros that are intended to work in multiple different windows.
  • Default window - window specified is activated before macro playback starts.
  • Capture window - the window to activate is captured on the start of macro recording (the window where first keystroke or mouse click occurs).
  • Enter or select window - window specified is activated before macro playback starts.

[ ] When necessary, add macro code to always activate proper window
For reliable macro playback it is necessary that the keystrokes and mouse clicks are played back in the correct window - the same window they were recorded in. If this option is checked then a "wait for window" code is being added to the recorded macro. This code ensures that keystrokes or mouse clicks are not performed before expected window appears.

Use "Default" button to pre-select default settings suitable for majority of users.

5. Ready to Start

Macro recording is started after user clicks “Record Now!” button. There is option to postpone macro recording using “Shift” key. If user holds “Shift” key down and clicks “Record Now!” button then the macro recording is started after “Shift” key is released. This allows user to use mouse to activate (bring to front) appropriate window for macro recording.
During macro recording it is possible to insert <pause> command by pressing "Pause/Break" keyboard key. The <pause> command, during macro execution (not recording), stops macro and allows user to insert some text or do something else with the computer. When "Enter" key is hit, the macro continues execution.


Macro Definition

Macro properties are defined in macro definition view. This view consists of several tabs. When user changes macro definition it is necessary to click OK button to confirm changes (or Cancel button to cancel the changes).

● Macro General Info

General macro properties like name and description are specified here. Macro name is not only a macro identifier for user’s reference. It can be also used to start this macro from another macro using <run> command or it can be used to start the macro remotely over network using <remote_macro_call> command.

● Macro Triggers

Keyboard Triggers:

Keyboard triggers allow user to start macro via keyboard directly from other program. There are two types of keyboard triggers: text shortcut and hot-key.

Text Shortcut
Text shortcut is a short text that user defines to start macro. Macro is started after the user types the text shortcut and hits “space bar” which is default “expand key”. This is default behavior that can be modified using text shortcut options:

  • Do not delete shortcut - if checked, then the text shortcut user types in order to start macro is not deleted in prior to macro execution. Example: Let's say the text shortcut is "misc" and macro is "ellaneous". After user types "misc" (plus hitting expand key) the macro is started without deleting the "misc" already typed and result will be "miscellaneous".
  • Auto-expand - macro will be started without necessity to hit space bar (or other defined expand key) after the text shortcut is typed. This option causes the macro is started when the last character of the text shortcut is pressed.
  • Can be part of word - the text shortcut can be a part of a longer text. If this option is checked then, for example, the text shortcut "soft" is expanded when user types "supersoft ".
  • Case insensitive - if checked, the text shortcut is text insensitive. For example, if text shortcut is “.mysct” the typing “.Mysct” will also start the macro.
  • Follow case - this option is enabled only if “case insensitive” option is checked. This option makes sense only for text replacement macros (macros that replaces text shortcut by other - usually longer - text). The option has this meaning: Let’s say we have text shortcut “tta” and macro containing just replacement text “tetraethyl alcohol”. If user types “tta” the it is replaced by “tetraethyl alcohol”. If user types “Tta” it is replaced by “Tetraethyl alcohol”. And if user types “TTA” then it is replaced by “TETRAETHYL ALCOHOL”.

Text shortcut doesn't have to be unique. If there are more macros with the same text shortcut, list of all macros is displayed to user to choose the required one.
Text shortcuts can contain international characters like ë, ü, á, õ, etc.
Text shortcut cannot contain space bar (and the key defined to expand text shortcut if it is different from the space bar).
Text shortcut cannot contain any of the characters defined in the "Word-breaking characters" field of the main settings window.

Hot-Key

  • Hot-key (main) is a combination of keys like Ctrl+C, Alt+T, etc. When user presses hot-key, associated macro is started. Hot-key doesn't have to be unique. If there are multiple macros with the same hot-key defined, list of all macros is shown and the user can select the desired one.
  • Extended hot key is an optional and can be used when user has the same hot key used for several different macros. Instead of selecting macro to run from menu the user can define the extended hot key. In such case the program works this way: The user hits (main) hot key. The program finds that there are multiple macros with such hot key and that the macros have extended hot keys defined. So the program waits until the user hits extended hot key in order to select the desired one.
    This option gives user ability to define hot keys for different actions more logically since the hot key space is much larger.
  • Start macro after all hotkey keys are released: This option solves conflict cases when macro is started while user still keeps control keys down and such control keys conflict with the macro content. Example: Let's say hot key is Ctrl+Alt+X and the macro contains <delete> key. If user still holds Ctrl+Alt down when the macro executes <delete> key it can happen that the computer recognizes the current state of the keyboard as Ctrl+Alt+Delete and shows the "Ctrl+Alt+Del Window". This option allows user to prevent this.

Mouse Triggers:

Mouse triggers allow user to start macro using mouse while working with other program. There are several mouse actions available to be defined as a macro trigger: mouse click, double click, shake mouse, hold mouse button down, etc. The mouse action can be combined with a control key and/or mouse button.
Example: Let’s select “Move mouse to upper screen edge” mouse action and check “Alt” control key and check “Right” mouse button. The macro is started only when user moves mouse cursor to upper screen edge while holding “Alt” key down and “Right” mouse button down.

Scheduled Triggers:

It is possible to schedule macro to run at defined time or when a specific event occurs:

  • Time schedule - macro can be scheduled to run once (at the time and date specified by "start at") or every minute, day, week or month between start and end time and date (if specified).

  • Window - macro is started when a window is opened, activated, deactivated or closed. The window is specified the same way as “scope window".

  • File - macro is started when a file is created, changed or deleted or if the size of the file is bigger or smaller than a defined value. The full path to the file must be specified.

  • Folder - macro is started when a file of the given folder created/changed/deleted. Unlike “file” option above, this option allows to watch multiple files. The files are defined using wildcards. For example, “\\server1\sharedfiles\*.doc”. This will watch all .doc files from “\\server1\sharedfiles\” folder. Full path of the file(s) that trigger the macro is saved to macro variable. This allows macro developer to determine what file caused the macro to run and perform required action.

  • Drive - the macro can be started when free space on a drive ("c:", "d:", etc.) is smaller or bigger than a defined value.

  • Display pixel - the macro is started when color of the defined pixel on display is changed.

  • Idle - or the macro can be started if there is not an activity (keystroke or mouse event) for specified amount of minutes

  • Windows Shutdown - macros can be scheduled to run when the Windows shutdown. To run macro on Windows startup make the WinScheduler to load on Windows startup (go to the Main Settings) and check "Run this macro on the program startup" in the Item Settings dialog box, Options tab.

Toolbar Button:

Macros are started by clicking on toolbar button or submenu item.

  • Button shows in toolbar
    The name of the toolbar (group with "Default trigger type" set to "Toolbar Button" and "Toolbar type" set to "Tab in main toolbar" or "Flying toolbar"). If <THIS> is selected then the macro is showing as a button in a toolbar represented by this group. If <NONE> is selected then the macro is not showing as a button.

Type of button:

  • Separator
    The macro is showing as a separator in the toolbar. Such macro is usually empty (has no macro text) and its purpose is just to make the toolbar buttons better organized.

  • Macro button
    Such macro shows as a button in the toolbar. Clicking on that toolbar button the macro text (defined in "Macro Text" tab) is executed.

  • Submenu button
    This macro is showing in the toolbar as a button that opens submenu if clicked. The submenu is defined by the submenu name (group with "Default trigger type" set to "Toolbar Button" and "Toolbar type" set to "Submenu").

● Macro Text

Macro text tab allows the user to edit and debug actual macro code. The macro can be edited either as a raw text ("Macro source code" tab) or using descriptive representation of the macro code ("Descriptive macro code" tab).

There are several toolbar buttons available for macro code manipulation:

  • Run macro
    When clicked the macro text execution is started.

  • Validate macro
    When clicked the macro text is validated.

  • Add command
    This button opens a window with available commands and system variables. Selected command can be either added to the end of the macro text or to the place where cursor is currently located.

  • Edit command
     When clicked, a dialog box for visual editing of currently selected command (command with cursor/caret on it) is shown.

  • Cut
    Cuts the selected piece of macro text and places it to clipboard.

  • Copy
    Copies the selected piece of macro text to clipboard.

  • Paste
    Pastes text from clipboard to the macro text.

  • Delete
    Deletes selected piece of the macro text.

  • Record macro
    Starts macro recording.

  • Start debugging
    When the button is clicked the macro text execution is started in debugging mode. This mode allows the user to execute the macro text slowly, step-by-step and watch its behavior including macro variable values.

● Macro Settings

  • Add to tray menu - if checked, the macro will be added to the tray menu (menu that appears when the program’s tray icon is right-clicked) for quick access.
  • Use this macro as template - if checked, this macro will be available in “Create from template” list. This allows user to prepare several predefined macros that can be used as templates for quick creation of similar macros.
  • Run macro in separate process - see details here.
  • Run this macro on the program start up - if checked, the macro is automatically executed when the program starts.
  • Paste macro - if this option is checked, the macro is pasted to target application as it is. This means that the macro text is not executed but it is just put to the clipboard and pasted in target application. This option only makes sense for macros that contains no commands or special keys. For example, larger pieces of text, text that contains international (UNICODE) characters, etc..
  • Lock keyboard and mouse while macro is running - if checked, the keyboard and mouse is locked during macro execution. This means that user cannot affect macro execution by moving mouse to other position or by hitting keys on the keyboard. From other hand, when this option is checked, it is not possible to stop macro execution by pressing "Shift+Esc" key combination. In a case macro is running and it is necessary to unlock mouse and keyboard again in order to stop macro execution ("Shift+Esc") then press Ctrl+Alt+Del.
  • Macro playback speed - there are several options how fast the macro should be executed. This option allows user to slow down certain macros that run on a program that can only handle keystrokes sent slowly.
  • Repeat macro - number of repetition after the macro is started.

● Macro Scope

It is possible to define scope (in what applications/windows the macro can be started using define trigger) in this tab. The scope can be defined either individually for each macro, or it can be defined for whole macro group in macro group settings dialog box.


Make Changes In Multiple Macros

In a case it is necessary to do a systematic change on multiple (all) macros, it is possible to use "Make Change In Multiple Macros" dialog box. Using this dialog box, it is possible to change any attribute of multiple macros at ones. User selects what attribute is to be changed, new value and defines weather the operation is to be executed on selected macros only or on all macros from the current group.

This feature is available from "Edit/Multiple macros changes..." menu command.


Scope Of Macros

If not defined other way, macros run (can be started using defined trigger) in any application (window). However, there is also ability to define certain windows where macro can run. When such a defined window is active, user can use macro trigger to start the macro. If other window is active the trigger simply doesn't take any affect and macro is not started. This feature can be used to:

1. For different applications, create different macros that all use the same trigger. (From the user's point of view, the macros, for example, will do the same thing but macro for each application will be programmed different way.)

2. Create macro that works only in specific application(s) while the trigger doesn't take effect in other applications.

There are two levels where it is possible to define macro's specific windows:

1. Macro - the scope can be defined individually for each macro in macro definition area, in "Scope" tab.

2. Group - the scope can be defined for whole macro group in the "Group settings" dialog box, in "Scope" tab.

Each specific window is identified by four parameters. It is not necessary to define all of them if it is not necessary.

Main window title: It is title of the application's main window. It is possible to use just partial text (for example, if "Notepad" is used instead of "Untitled - Notepad" all Notepad windows match this identification). After user retrieves the window title using "Retrieve" button, it is possible to adjust it by editing in the edit box.

Main window class: The window class is something that is hidden to user. Window class can be considered as a "type" of the window. (For example, all Internet Explorer windows have the same window class although each window has different window title.)

Child window title: This parameter allows user to specify a certain dialog box, toolbox or document window within an application. For example, if "Main window title" and "Main window class" are empty and "Child window title" is define to be "Find" then this identification matches find dialog boxes in all applications (MS Word, Notepad, Internet Explorer, etc.)

Child window class: This is similar as in the "Main window class". Just this class name is used to identify dialog box, toolbox or document window and not main window.


Running Macro

When macro is running, progress bar with “Stop” button is showing in lower right corner of computer screen. User can click on "Stop" button and exit macro execution or click "Pause" button to pause and resume the macro execution. Macro execution can be also stopped resp. paused by “Shift+Esc” key combination resp. "Pause" key. The progress bar can be turned off in main settings dialog box.

Except macro triggers (see “macro triggers”), there are also other options how to run macros:

  • Tray Menu
    User can right click on the program’s tray icon and select from macros listed on the top of the menu shown. There are listed only macros with “Add to tray menu” option checked.
  • Main Window
    The macro can be started from the main window using either toolbar button or "Tools/Run Macro" menu item.
  • All Macros List
    The user can right click on the tray icon and select "All Macros List" menu item. User can select macro in the dialog box shown and click “Run” button.
  • From Link
    User can create "Desktop Shortcut" (menu item "Tools / Create Desktop Shortcut") to an item and run the macro by double-clicking on the desktop shortcut.
  • Drag & Drop
    You can drag an item in the main window and drop it on a window you want to run the macro in.
  • <run> Command
    Macro can be run from other macro using <run> command.
  • <remote_macro_call> Command
    Macro can be run over network from other macro located on remote computer using <remote_macro_call> command.


Run Macro From Other Program

  1. Running macro saved in macro file:
    It is possible to start macro saved in a macro file from other program or using a command line (Windows "Run" dialog box or command prompt window). Just start the program with this parameters:

    -run:    NameOfTheMacroToRun MacroFilePath
    For example, "C:\Program Files\....\_prog.exe -run:Update C:\Program Files\....\mymacrofile.4...

    This will cause the macro program is loaded to the memory, opens the file specified in the parameter and runs the defined macro. Then the program exits. Subsequent macro calls invoked by <run> command are properly executed.

  2. Running macro from currently opened macro file:
    If the macro program is running with a macro file opened, then it is possible to start a macro from the opened macro file using “RunMacro.exe“ program. It takes macro name as a parameter and causes the macro is executed.

    Example: “RunMacro.exe mymacro” will cause the “mymacro” macro is started.

    Since both macro program and macro file are already loaded in computer memory the macro execution is significantly faster than case #1 above. The same as above, subsequent macro calls invoked by <run> command are properly executed.

  3. Running macro saved in .MCR text file:
    It is possible to write macro to a text file with ".mcr" extension. Macro that is saved in such a (text) file can be started just by double-clicking in the Windows Explorer or other file management program. Running .MCR macro is faster then running the same macro using approach #1 above because it is not necessary to load a macro file (probably with many other macros defined). Subsequent macro calls invoked by <run> command fails - the .MCR macro should not contain <run> command.


Run In Separate Process

During a macro execution no other macro can start. This is not convenient for macros that can take very long to finish (for example, FTP download). In such case there is an option to start time consuming macro in separate process so that it doesn't block other macros from starting. In addition, this option allows user to run macros concurrently or run them as a service or on other user's account.

Starting macro in separate process means, that a new executable (_prog.exe) to run the macro is loaded to computer memory and the macro execution continues within the executable. When macro execution is finished, the executable is released from the computer memory again. There are three ways how the program can be started:

1. Normal (as currently logged user) - this is the default option.

2. Run as different user - this option allows user to start macro on other user's account. It is necessary to specify user name and password (and, optionally, domain). In addition, this option requires specific user rights to be set in Windows: Act as part of the operating system (SE_TCB_NAME), Bypass traverse checking (SE_CHANGE_NOTIFY_NAME) , Replace a process level token (SE_ASSIGNPRIMARYTOKEN_NAME), Increase quotas (SE_INCREASE_QUOTA_NAME).
There is "WhoAmI.exe" utility that is part of the program distribution. You can create simple macro consisting just from <execappex>("whoami.exe","","",0,0) command. When the macro is started a WhoAmI.exe dialog box shows user name of the account under which the WhoAmI.exe program was started. This can be used to make sure the macro is started on right account.

3. "As administrator" (Vista and newer only) - this allows to run macro "as administrator" (with higher priority) on Vista and newer. The higher priority is necessary for certain Windows operations (the operations that were not restricted in XP and older - write to some registry locations, block keyboard and mouse, etc.).


Sharing Macros

Network users can share macros over the network. Shared macros are saved in a special file that has to be located on a network drive (directory) all user can access. Each user that wants to use shared macros has to enable "Allow shared macros" option in the main settings dialog box and specify the path to the shared macros file in the main settings window.

Note for advanced users: If the shared macros file cannot be opened (because the network drive is not accessible or for other reason) a macro called "_xSharedMacroFileNotFound" is started if it exists in currently loaded macro file. This allows a user to handle situation when shared macro file cannot be opened programatically.

Shared Macros File Editing

To create a shared macros file, create a new file using "File/New" menu item. Name the new file so that the name is different than other files users use (for example, "SharedMacros"). Edit the file (create macros) and save it on shared network drive on the network.

Note: The shared macros can be edited only when shared macros file is directly opened in the program using "File/Open". This means that if a user (administrator) wants to make changes to shared macros then the file needs to be opened using “File/Open” menu item.


Import/Export

The program allows to export/import data to/from text file. The import/export feature is intended to allow user to simply exchange macros between different macro files. When exporting macros, user selects multiple (or just one) macros in the macro list and right-clicks on them. A menu with "Export" item is shown and after user specifies target text file, all selected macros are exported to a text file. Similar way, the user can import the macros from the text file previously created using "Export" feature.


Main Program Settings

Main program settings dialog box is available through “Tools/Options” menu item from the main window or from tray menu.

General

User-defined Hot-keys:

  • All macros list - hot key that brings up window with list of all macros.
  • Enable/Disable trigger - hot key to enable/disable macro triggers.
  • Start / stop macro recording - hot key to start macro recording.
  • Show / hide main window - hot key to show or hide main window.

  • Play sound when executing macro - if checked, defined sound (.wav file) is played when macro is started. A dialog box to define sound file is shown when the unchecked option is changed to checked.
  • Speed of macro keystrokes sending - this option allows user to control how fast the program sends keystrokes when playing macro back. This option can be programmatically changed within each macro using <faston> and <fastoff> commands (<faston> changes the speed to “highest” and <fastoff> to “slow”).
  • Do not show macro execution progress window - if checked, the macro execution progress window is not showing.
  • Log macro execution - if enabled, the start & stop macro execution time is added to the log.txt file. The file is available from the "View/Show Log File" main menu item.
  • Automatically report errors during macro execution - if this option is checked and an error appears during macro execution (some command, for example "copy file" fails) an error window is shown to user immediately. This option can be overwritten by using <me_error_nodisplay> and <me_error_display> commands in macro.
  • Auto-save - if checked, the changes made to macro file are automatically saved every couple minutes. In addition, all changes are automatically saved on program shutdown (without showing "Do you want to save..." dialog box to user).
  • Automatically detect new version available - if this option is enabled, the program connects to its home page (if the user is connected to Internet) and detects weather a new version is available.

Shared macro file options:

  • Allow shared items - if checked, multiple users on network can share macros saved in the file specified in "shared file path" field.
  • Shared file path – full path to the shared macros file.
  • Reload when change is detected - if a change in the shared macro file is detected, the macro file is automatically reloaded so that users always have the most recent version of the shared macros.
  • Confirm reloading - if checked, the user is asked (using a message box) to confirm shared macro file reloading.

    For more information regarding sharing macros see Shared macros topic.

More options:

  • Use list box to select from macros with the same trigger - It is possible to define macros with the same trigger. When the trigger fires and this option is checked, a list box with the macros with the trigger fired is shown to select required macro to run. If this option is unchecked, a menu instead of list box is shown.
  • Do not show "Macro execution stopped" message... - It is possible to stop (break) macro execution using "Shift+Esc" hotkey. By default, if the macro is stopped this way, a message is shown to user. This option allows to disable the message.
  • Do not show "Macro is paused" window... - if checked, this message is not showing.
  • Locate macro execution error if a macro command fails - if a macro command fails during macro execution and this option is checked, the program automatically navigates to macro that failed and highlights the command that failed. This simplifies error detection and allows faster macro development.
  • Always start minimized to tray - if checked, the program always starts minimized to the Taskbar tray icon. Otherwise the program starts in the same position as it was before exiting.
  • Show tips - if checked, tips are showing during working with the program.
  • Start automatically on Windows Startup - if checked the programs automatically loads on Windows startup.
  • Save settings on exit - if checked, all the changes made in settings, window position, etc. is saved on the programs exit.

Remote macro call port - the port number (default is 20304) used to invoke macro execution from macro on remote computer over network using <remote_macro_call> command. If the port field is empty or contains "0" then the remote macro call feature is disabled and it is not possible to invoke macro from remote computer. This is indicated by "RMC Disabled" text showing in the lower right area of the Macro Toolworks main window. If the port number is other than 0 then it is allowed to invoke macro execution (only for macros from groups that have remote macro call enabled - see macro groups) from remote computers and this fact is indicated by "RMC Enabled" text in lower right window area.

Keyboard Tab

  • Expand shortcut after pressing - check the keys you want to use to start text shortcut expansion. (The keys that need to be hit after a text shortcut is typed - see macro triggers ID_TUTORIAL_TRIGGER.)
  • Do not delete expand key - if checked the expand key is not deleted.
  • Non-text shortcut characters - the characters listed here cannot be part of text shortcut. This means that text shortcut recognition is restarted when such character is typed. Some keys causes this automatically (for example, page up, page down, tab, arrow keys, enter, etc.) but additional characters can be specified here.
    For example, we have "sct" text shortcut. When typing "(sct " the "sct" shortcut is correctly expanded only if the "(" character is listed in "non-text shortcut characters" field.
  • Keyboard triggers assistant
    • Auto-text and text shortcut assistant
      This is a small window that appears any time when the user is typing a text that (partially) matches defined text shortcut or auto-text. The window lists all the auto-text items and text shortcuts that are available in the window (application) the user is typing in. The best fitting item is being pre-selected in the list and user can use run the item by pressing "Alt+Right Arrow" key combination. The user can also jump into the Assistant window using a user defined hotkey (by default it is "Alt+." key combination) and navigate in the list using "Up" and "Down" keys.

      [ ] Disable auto-text and text shortcut assistant - if checked, this type of assistant is disabled and is not showing.
    • Hotkey assistant
      This is the same small window as described above. It appears any time the user presses a control key (for example "Ctrl" key) and such a key is part of a macro hotkey available in the currently active application. Again, all available hotkeys are listed and best fitting one is pre-selected.

      [ ] Disable hotkey assistant - if checked, this type of assistant is disabled and is not showing.

Mouse Tab

  • Automatically activate ... - if checked, the program will automatically activate window with the mouse cursor (so that it is not necessary to click on it to activate it).
  • Auto scrolling - if checked, special auto scrolling feature is enabled. To scroll larger documents using this feature follow this:
    1. Within the document, press right (middle) mouse button and hold it down.
    2. Move the mouse cursor up/down within the document while still holding the mouse button down. The document should scroll.
    3. Release the mouse button when you want to stop the scrolling.
    This feature will make scrolling documents easier even if you do not have a wheel mouse.
  • Show mouse cursor position - if checked, small window displaying the actual mouse cursor position is shown. The window displays the mouse coordinate either in absolute screen coordinates or in coordinates relative to the currently active window.

Macro Toolbars Tab

  • Main Toolbar
    • Auto hide - if enabled, the toolbar is hidden if the mouse cursor is out of the toolbar area. If the toolbar is not docked it is hidden to the toolbar edge that is closest to a screen edge. It means that it can be hidden to any of the top, right, bottom or left edge depending on the toolbar position on the screen.
    • Disabled - when checked, the main toolbar is not showing.
    • Always on top - if enabled, the toolbar is top most window that is never overlapped by other windows.
    • Dock - if checked, the toolbar is "docked" on a selected screen's edge.
    • Icon sizes - allows selecting between small and large icons both for toolbar and submenus.
    • Show tab text - if checked, the tab name is displayed within each tab.
    • Show tab icon - if checked, the tab icon is displayed within each tab.
    • Disable tabs - if checked, tabs are hidden and the toolbar is smaller.
    • Tabs position - tabs can be positioned on top, left, right or bottom site of the toolbar. Note that on old Win95 systems it is possible that only "top" position will work properly.
    • Sort tabs - defines if the tabs are sorted alphabetically or by the user-defined order (order of the macro groups representing the toolbars).
  • Auto-open/auto-close submenu - if checked, it is not necessary to click on submenu button in order to open submenu. Also, if the mouse cursor is not over the submenu then it is closed automatically without necessity to click on desktop or other application.
  • Disable all - if checked, the main toolbar is disabled (not available) as well as all defined floating toolbars.
  • Show button text - if checked, macro name is showing along with macro icon (button icon).
  • Sort buttons - defines if the buttons are sorted alphabetically or by the user-defined order (order of the macros in the macro list defined by the "order" column).


Lock Mode

The program can be switched to the mode in which no settings can be changed (macro settings, group settings, main settings). This mode can be used in the case when the user wants to prevent the macros from changing made accidentally by himself or by other user. The lock mode is password protected.

Lock mode is available from the main menu through the "File/Lock Mode" menu item.

Please note that the lock mode is something different from the macro password protection.


Macro Password Protection

It is possible to password protect macros so that no one who doesn't know the password can see the macro definition, edit it or run it. The password protection is implemented on the group level. This means that user defines password for the given group and all the macros from this group are password protected. To define password, go to the group settings window and press "Password" button.

  • Password - type your desired password here.
  • Confirm password - retype the password to make sure you didn't mistype.
  • Require password: Always - the password is required any time you want to run or edit password protected macro.
  • Require password: When there was no an activity... - the password is required only if there wasn't mouse or keyboard activity for longer than the given time.
  • Do not require password to run macros - if checked, the macros can be run without password. However, they cannot be viewed or modified.


Lock Mode

AES Macro File Encryption

User can protect the macro file by strong AES encryption. This is optional feature available in Professional edition of the Macro Toolworks. It can be turned on/off in "more settings" in main settings dialog box. If this feature is turned on then all macros (macro texts) and all passwords stored in macro file are encrypted using AES algorithm. This means that all personal information (credit card numbers, access passwords, etc.) are safe and well protected. The AES encryption together with macros password protection gives the user safe platform for automation of web form filling, auto-logging and many other tasks that include security sensitive information.


Multi-user Support, Server Installation

There are two ways how to minimize effort when maintaining multiple users of the program within an organization:

1. Automated Update

In the network environment, it is possible to define a network directory that is used as a server for software update. On the program startup, the software version on the workstation is compared with the software version on the network and if a newer version is available, it is automatically updated. This feature allows administrator to manually update software only on one computer (the network directory) and all other installations on other workstations are updated automatically.

To enable this feature, you have to follow this:

1. Installation package has to be modified before the program is installed on user's machine. It is necessary to do this:

a) Unzip the installation package to some folder.

b) Modify the options.ini file so that "updatepath", "verid", "dirs" and "files" keys exist in "update" section. Example:

[update]
updatepath=\\server1\update_software
verid=pitrinec_6.00
files=*.exe;*.dll;*.gif;*.ico;*.htm;
dirs=help;icons;scripts;custom

c) Create zip package again (if required).

2. Install the program on a network directory defined in "updatepath". It is necessary all users can access (read) this directory from their workstations.

3. Install program on client's computers.

If an administrator wants to install new version downloaded from the vendor (Pitrinec), then just do step #2 above - install the new version to the "updatepath" directory. This is all that must be done. Each client's copy is to be automatically updated on the first program restart.

If the administrator wants to modify current version by adding or changing some files in "Custom" folder (macro files, examples, etc.), then do this:

A) Modify the installation package as required. Specify other "verid" value (for example, "6.00_internalupdate1") in options.ini file. (And it is also possible to change "files", "dirs" values if required).

B) Install this changed package to the "updatepath" folder. Each client's copy is to be automatically updated on the first program restart.

Keys meaning:
updatepath - defines the installation directory on a server. All users have to be able to access this directory from their machines.
files - the names of files to update delimited by ; Wild chars (*?) are allowed.
dirs - the names of directories to update delimited by ; Wild chars (*?) are allowed.
verid - the program (package) id. This id is changed by the program vendor when a new version is released. But also administrator can change this id in order to update clients installations when required.

2. Server Installation

The program can keep multiple users settings while it is installed just once on the computer. This feature allows multiple users to share one installation on the network server (or local machine) and minimize disk space required and maintenance effort (makes upgrading easy even if there are many users on the net).

Information about all the users is stored in the users.ini file that resides in the same directory where the product is installed. The file is a text file that can be edited by any raw text editor like Notepad. The file structure is as follows:

[header]
 num_of_users=2

 [1]
name=oscar
path=\\server\users\oscar

[2]
name=debie
path=\\server\users\debie

Note: The path name may not end with \ character! The [1], [2], etc., sections have to start by [1] and end by [num_of_users]. The number of users is limited by your license.

Starting Program

There are two ways how to start the program with user's settings loaded:

1. PATH_TO_THE PROGRAM /user:?
Where the PATH_TO_THE PROGRAM is full path to the software executable. When the program starts with this "/user:?" parameter a login dialog expecting user name (from the users.ini file above) to be inserted appears.

2. PATH_TO_THE PROGRAM /user:USER_NAME
Where the PATH_TO_THE PROGRAM is full path to the software executable and USER_NAME is the user name from the users.ini file above. This will start the program without any login dialog.

Adding New User

To add new user follow these steps:

1. Create new user's directory where the program can save settings and data files. You can create a copy of the "UserDir-Template".

2. Increase the number of users in [header] section of users.ini file.

3. Add new user section (for example, [10] if there are ten users) and specify users name and the user's directory path (as per 1 above):

[10]
name=hugo
path=\\server\users\hugo

4. On the user's workstation, create a link to the executable command line as described in "Starting Program" section above.


Install Automation

Silent Install

It is possible to install the program silently without a user interaction. The installation program "setup.exe" can be run with following parameters:

-silent
This option cause the setup runs without any user interaction. The program is installed to a default folder and a default program group in Start menu. User can specify other destination folder and group using following parameters.

-InstFolder:"A folder path"
This parameter defines the destination installation folder. If not specified, a program folder is created in "Program Files" folder by default.

-SMProgFolder:"A prog group name"
This parameter defines the name of the program group in the Start menu.

Command line example:

setup.exe -silent -InstFolder:"c:\program files\OtherFolder" -SMProgFolder:"OtherStartMenuGroup"


Macros, Creating Macros

Program Hotkeys

The program has built-in some keyboard shortcuts that can be used to perform certain actions from keyboard (instead of necessity to use mouse clicks):

Hotkey | Action
Ctrl+N | Create new macro file.
Ctrl+O | Open a macro file.
Ctrl+S | Save changes made to currently opened macro file.
Ctrl+C | Copy.
Ctrl+V | Paste.
Del | Delete selected macro(s)/group.
Ctrl+F | Show list of all defined macros.
F3 | Find text in the macros.
Ctrl+W | Start add wizard.
Ctrl+I | Add macro.
Ctrl+L | Add clipboard macro.
Ctrl+T | Create new macro from template.
Ctrl+R | Record new macro.
Ctrl+D | Add group.
Ctrl+G | Run selected macro.
Ctrl+A | Select all macros (in the macro list pane).
Ctrl+P | Open main settings dialog box.
Alt+E | Edit the current command (in macro text editor pane).
Alt+A | Add currently selected command (in commands and system variables tree) to the end of the macro.
Alt+I | Insert currently selected command (in commands and system variables tree) to the current position in the macro text.
Alt+H | Open help file for the current command (in macro text editor pane).
F11 | Maximize/Restore macro text pane.
Alt+D | Switch to descriptive macro code (in macro text editor pane).
Alt+R | Switch to macro source code (in macro text editor pane).
Alt+O | OK & save changes made in macro text or macro settings.
Alt+C | Cancel & disregard changes made in macro text or macro settings.
Alt+right arrow | Jump to next command (in macro text editor).
Alt+left arrow | Jump to previous command (in macro text editor).
Alt+up arrow | Jump to previous macro.
Alt+down arrow | Jump to next macro.
Tab | Switch between groups, macros list and macro text panes.
Ctrl+Page Down | Switch between "macro General Info", "Triggers", "Macro Text", "Macro Settings" and "Macro Scope" tabs.
Ctrl+Page Up | Switch between "macro General Info", "Triggers", "Macro Text", "Macro Settings" and "Macro Scope" tabs.
F5 | Start macro debugging.
F10 | Execute next command (in debugging mode).
F9 | Show variable content view window (in debugging mode).


Macro Language

Macro language contains over 150 commands and system variables and allows a user to create macros/scripts to automate many tasks. Before the user starts writing its own macros it is recommended to read about syntax, commands and variables.


Language Overview

Macro Language Commands

The simpliest macro is just a text like "Hello World!". When "played back", keystrokes to produce given text are sent so that the text is "typed" to the target application (usually application that is active - i.e., receiving keyboard focus). Such simple macros are used to quicklly insert often used pieces of text (phrases, e-mail addresses, paragraphs, etc.) to different applications and documents. However, macros can also contain some commands. If there is a command within the macro then it is automatically recognized and executed.

Commands have its special syntax that makes it easier to recognize them within the whole macro text. The command usually looks like this:
<some_command>("param1", param2, ...)

Parameter can be:

  1. Static text (constant)
  2. Variable
  3. Combination of a static text and variables. Variable used in a combination with static text must be enclosed in % chars (“a text %vVariable% text continues…). For example, to create a file with name based on the current date you can use this: <filecreate>(“c:\myfiles\%_vCurrDate_Year%-%_vCurrDate_MM%-%_vCurrDate_DD%.doc”,0). This will create c:\myfiles\2000-08-19.doc file.
  4. Expression
    Expressions have this syntax: EXPR(expression) or EXPRXX(expression) where XX specifies how many digits follow after decimal point (real numbers). Expressions can be used as a parameter for almost all commands (see examples below).

    Expressions support all basic mathematical operations and supports brackets.

    Example1: <mm>(EXPR(%_vScreenWidth%/2), EXPR(%_vScreenHeight%/2))
    Example2: <varset>("vPercent=EXPR(100*(%vItems%/%vItemsTotal%))","")

    The expressions support also time arithmetic's. The time must be in appropriate format which is "YYYY.MM.DD HH:MM:SS". The difference between two times is "time span" that has this format "Days HH:MM:SS". The time span is also used to add/subtract amount of time to/from given time. This operations are supported:

    "Days HH:Mi:SS" = "YYYY.MM.DD HH:Mi:SS" - "YYYY.MM.DD HH:Mi:SS"
    "YYYY.MM.DD HH:Mi:SS" = "YYYY.MM.DD HH:Mi:SS" + "Days HH:Mi:SS"
    "YYYY.MM.DD HH:Mi:SS" = "YYYY.MM.DD HH:Mi:SS" - "Days HH:Mi:SS"
    "Days HH:Mi:SS" = "Days HH:Mi:SS"+"Days HH:Mi:SS"
    "Days HH:Mi:SS" = "Days HH:Mi:SS"-"Days HH:Mi:SS"

    Example3: <varset>("vTomorrowDate=EXPR(%_vCurrDateTime_ForCalc%+1 0:0:0)","") <#> What date will be 1 day later (next day)?
    Example4: <varset>("vDate=EXPR(%_vCurrDateTime_ForCalc%-10 13:45:10)","") <#> What date was before 10 days, 13 hours, 45 minutes and 10 seconds?
    Example5: <varset>("vTimeSpan=EXPR(%_vCurrDateTime_ForCalc%-2005.11.21 13:45:00)","") <#> How much time left since 2005/11/21, 13:45:00?

    There are these limitations on time input: 1970 <= YYYY <= 3000; 1 <= MM <= 12; 1 <= DD <= 31; 0 <= HH <= 23; 0 <= Mi <= 59; 0 <= SS <= 59

There are also commands that have no parameters. Such commands look like this: <command_noparam>. An example of such command can be <F1> that cause F1 key is pressed, <rundlg> that cause that Windows "Run dialog" is opened, etc.

Each command can be visually edited so that it is not necessary to know the command syntax - just put cursor on the command and use "Edit command" button. There are 150+ commands designed to accomplish variety Windows automation tasks.

Special keys (like 'Enter', 'Page Down', etc.) use the same syntax as commands with no parameters:
<enter>
<pgdn>

Very important macro command is <cmds> command. This command tells the macro language engine that only commands should be executed and the rest of the macro text should be ignored. This <cmds> command is usually the first macro command in the macros that only consist of macro commands and their purpose is not inserting any text (send keystrokes).


Language Overview

Macro Language Variables

There is also a support for variables implemented. There are three basic types of variables:

  • Macro local variables - user defines these variables using <varset> command. The variable name can be any string (characters such +, -, \, /, <, >, *, :, (, ), [, ] should not be used) and the variable is known only inside the macro it is defined.
  • Global variables - there are two types of global variables that differ by scope:
    - macro global variable - the variable is known in all the macros (called from each other using <run> command) during the macro execution. The macro global variable must begin with the "gm_" prefix (for example, "gm_varName").
    - application global variable - the variable is known during the whole application session (the value is remembered until the program is closed). The application global variable must begin with the "ga_" prefix (for example, "ga_varCurrentProject").
  • System variables - the variables provide system dependent information. Cannot be changed by <varchng> command (are "read-only").
  • Parameters - if a procedure parameter starts with "par" prefix (for example, "parInputText") then the parameter is local only within the procedure. Otherwise the parameter is either macro local or global as described above.
  • Local procedure variables - if a variable defined within a procedure starts with "lpv" (local procedure variable) prefix (for example, "lpvTemporaryVariable") then the variable is known and can be accessed only within the procedure.

All the variables (except system variables) can be used also as an array without any special declaration. For the array, this syntax is used:
varVariableName[index].

For the multiple dimension arrays this syntax is used: varVariableName[index1:index2:index3:....:indexN].

Array variables do not have a value assigned automatically. Until the user assigns a value to a given variable (for example, using <varset>("vName[10]=John","") command) the variable "does not exist". This can be detected using "_vDoesVariableExist_VARNAME" system variable (_vDoesVariableExist_vName[10] from our example). The system variable contains 0 if the variable does not exist or 1 if it does.


 System Variables

System variables provide many information that can be used in macro commands. System variables content is set by program automatically and cannot be changed using a macro command like other variables.

In addition to the system variables listed below, also environment variables such as %ProgramFiles% can be used in macro commands.

Window Related |
_vActiveWindow _vActiveWindow_HWND _vActiveWindowChild | Title of the currently active window. HWND of the currently active window. Title of the currently active child window (dialog box, toolbox, document window).
_vActiveWindowChild_HWND | HWND of the currently active child window (dialog box, toolbox, document window).
_vActiveWindowPrev _vActiveWindowPrev_HWND | Title of the previously active window. HWND of the previously active window .
_vWinFromMouseCur _vWinFromMouseCur_HWND | Title of main window with mouse over. HWND of main window with mouse over
_vChildWinFromMouseCur | Title of child window (dialog box, toolbox, document window) with mouse over.
_vChildWinFromMouseCur_HWND | HWND of child window (dialog box, toolbox, document window) with mouse over.
_vKeybdFocusWindow | Title of the window that is currently receiving keyboard input.
_vKeybdFocusWindow_HWND | HWND of the window that is currently receiving keyboard input.
_vKeybdFocus Control | Title of the window control that is currently receiving keyboard input.
_vKeybdFocusControl_HWND | HWND of the window control that is currently receiving keyboard input.
_vWinRectX1, _vWinRectY1, _vWinRectX2, _vWinRectY2, _vWinWdt, _vWinHgt, _vWinTitle, _vWinState, _vWinActive, _vWinClass , _vWinHWND | Attributes of the window retrieved using <wininfo> command.
_vMonitorCount _vMonitorPrimary _vMonitorWorkAreaX_MNum | Number of monitors Primary monitor number (starts from 0). Upper left X coordinate of a monitor work area. (Replace MNum by monitor number such as 0 - _vMonitor WorkX_0)
_vMonitorWorkAreaY_MNum _vMonitorWorkAreaCX_MNum _vMonitorWorkAreaCY_MNum _vMonitorScreenX_MNum _vMonitorScreenY_MNum _vMonitorScreenCX_MNum _vMonitorScreenCY_MNum | Upper left Y coordinate of a monitor work area. Width of a monitor work area. Height of a monitor work area. Upper left X coordinate of a monitor screen. Upper left Y coordinate of a monitor screen. Width of a monitor screen. Height of a monitor screen.
Date & Time Related |
_vCurrDate_Day | Day of the current date (e.g., 9 if the date is 02/09/2000).
_vCurrDate_DD | Day of the current date in the DD format (e.g., 09)
_vCurrDate_DayName | Name of the day of the current date (e.g., Sunday, Monday, etc.).
_vCurrDate_DayOfWeek | Day of the week (e.g, 1 for Sunday, 2 for Monday, …, 7 for Saturday).
_vCurrDate_Month | Month of the current date (e.g., 02 if the date is 02/19/2000).
_vCurrDate_MM | Month of the current date in the MM format (e.g., 02).
_vCurrDate_Year | Year of the current date (e.g., 2000 if the date is 02/19/2000).
_vCurrDate_YY | Year of the current date in the YY format (e.g., 00).
_vCurrDate_MonthName | Name of the month of the current date (e.g., February if the date is 02/19/2000).
_vCurrDate_DDMMYYYY | Contains current date in DD/MM/YYYY form.
_vCurrDate_MMDDYYYY | Contains current date in MM/DD/YYYY form.
_vCurrTime_Hour12 | Contains hour of the current time (e.g., 2 if the current time is 2:15:00 PM).
_vCurrTime_Hour24 | Contains hour of the current time (e.g., 14 if the current time is 2:15:00 PM).
_vCurrTime_Minute | Contains minute of the current time (e.g., 15 if the current time is 2:15:00 PM).
_vCurrTime_Second | Contains second of the current time (e.g., 0 if the current time is 2:15 PM).
_vCurrTime_AMPM | Contains PM/AM of the current time (e.g., PM if the current time is 2:15 PM).
_vCurrTime_Total | Contains the number of milliseconds elapsed from the last reboot.
_vCurrDateTime_ForCalc | The macro language natively supports time calculations, however, the time needs to be in appropriate format which is "YYYY.MM.DD HH:MM:SS" (read more here ). This system variable contains current time in this format.
. |
Files & Folders: |
_vDirDateTime | Contains a string with current time and "Dir" prefix that can be used for file/directory naming. Example: "Dir_2007_11_24_~14~45~03"
_vFileDateTimeTXT | Contains a string with current time and "File" prefix and ".txt" extension that can be used for files naming. Example: "File_2007_11_24_~14~45~03.txt"
_vFileDateTimeDAT | Contains a string with current time and "File" prefix and ".dat" extension that can be used for files naming. Example: "File_2007_11_24_~14~45~03.dat"
_vFolder_AppData | Contains path to the application data folder.
_vFolder_CommonDesktop | Contains path to the all users desktop folder.
_vFolder_CommonPrograms | Contains path to the all users start menu programs folder.
_vFolder_CommonStartMenu | Contains path to the all users start menu folder.
_vFolder_Cookies | Contains path to the cookies folder.
_vFolder_Desktop | Contains path to the desktop folder.
_vFolder_Favourites | Contains path to the favorites folder.
_vFolder_Personal | Contains path to the personal folder.
_vFolder_Programs | Contains path to the start menu programs folder.
_vFolder_Recent | Contains path to the recent files folder.
_vFolder_SendTo | Contains path to the "send to" folder.
_vFolder_StartMenu | Contains path to the start menu folder.
_vFolder_Startup | Contains path to the start menu start up folder.
_vFolder_Templates | Contains path to the templates folder.
_vFolder_Windows | Contains path to the windows folder.
_vFolder_System | Contains path to the system folder.
_vFolder_Temp | Contains path to the temporary folder.
_vFolder_AdminTools | Contains path to the admin tools folder.
_vFolder_BitBucket | Contains path to the recycle bin folder.
_vFolder_CDBurnArea | Contains path to the folder where files to be burned are stored.
_vFolder_CommonAdminTools | Contains path to the folder with admin tools for all users.
_vFolder_CommonAltStartup | Contains path to the folder corresponding with nonlocalized Startup program group for all users.
_vFolder_CommonDocuments | Contains path to the documents folder for all users.
_vFolder_CommonMusic | Contains path to the music folder for all users.
_vFolder_CommonPictures | Contains path to the pictures folder fro all users.
_vFolder_CommonTemplates | Contains path to the templates folder for all users.
_vFolder_CommonVideo | Contains path to the videos folder for all users.
_vFolder_Fonts | Contains path to the fonts folder.
_vFolder_InternetCache | Contains path to the IE cache folder.
_vFolder_MyDocuments | Contains path to the documents folder for logged user.
_vFolder_MyMusic | Contains path to the music folder for logged user.
_vFolder_MyPictures | Contains path to the pictures folder for logged user.
_vFolder_MyVideo | Contains path to the videos folder for logged user.
_vFolder_Resources | Contains path to the resource data folder.
_vReportDateTimeTXT | Contains a string with current time and "Report" prefix and ".txt" extension that can be used for files naming. Example: "Report_2007_11_24_~14~45~03.dat"
Drag & Drop: | The variables described here are only accessible after user drops file(s) on macro toolbar button. (Macro toolbars are only available in MacroToolbar and Macro Toolworks products.) The variables allow to further process (delete, copy, rename, etc.) the file(s) dropped.
_vDropFile_FileFullPath | Full path to the file dropped.
_vDropFile_FileName | File name of the file dropped.
_vDropFile_FileDir | Directory of the file dropped.
_vDropFile_Num | The number of files dropped
Special Characters |
_vKeyReturn | 'Return' (new line) key (use this key to add a new line to a text in variable). Is equivalent to \r\n codes.
_vKeyNewLine | Contains equivalent to \n code (new line).
_vKeyCR | Contains equivalent to \r code (carriage return).
_vKeyTab | 'Tab' key (use this key to add 'tab' to a text in variable).
_vQuoteChar | “ character (use this key to add “ to a text).
_vKeySpace | “space” character
_vKeyPercent | % character
_vKeyBigger | > character
_vKeySmaller | < character
_vKeyBracketL | ( character
_vKeyBracketR | ) character
Mouse & Keyboard Related |
_vLastMouseClick | Contains last mouse click event in the <waitfor> command: <mlbu> - left button click <mmbu> - middle button click <mrbu> - right button click
_vLastKey | Contains last key pressed in the <waitfor> command.
_vMousePosX | Mouse cursor position in the screen coordinates - X.
_vMousePosY | Mouse cursor position in the screen coordinates - Y.
_vIsCapsLockON | Is set to YES if CapsLock is on. Otherwise the variable contains NO.
_vIsNumLockON | Is set to YES if NumLock is on. Otherwise the variable contains NO.
_vIsScrollLockON | Is set to YES if ScrollLock is on. Otherwise the variable contains NO.
. |
Clipboard Related |
_vClpFormats | Contains comma separated list of formats of data currently saved in clipboard.
_vClpSize | Contains size of clipboard data.
_vClpText | Contains text clipboard data (if currently available).
. |
Macro Flow Related |
_vCanceled | The variable is set to 1 if a command (<form_show>, <extmacro>, <listbox>, <varset>, <var_oper>) si canceled by user. Otherwise the variable contains 0.
_vLoopCounter | Loop counter (see <begloop> and <endloop> commands). Starts from 1.
_vLoopCounter0 | Loop counter (see <begloop> and <endloop> commands). Starts from 0.
_vIsConnectedToInternet | If the computer is connected to the Internet the variable value is equal to YES otherwise it is NO.
_vErr | If an error occurs during macro execution, the error description is saved in this variable.
_vIsExecOnlyCommands | After <cmds> command is executed, this variable content is YES. By default and after <keys> command is executed it is NO.
_vWinStarting | If the program is set to automatically start on windows startup then the _vWinStarting contains "YES" when the program is starting on windows startup. Otherwise the value is "NO".
_vMacroParameter | This variable contains parameter that is passed to macro started using following commands: <run> <extmacro> <remote_macro_call> [Note: Unlike other system variables, the value of this variable can be changed using <varset> command.]
_vMacroResult | This variable contains result returned from macro started using following commands: <run> <extmacro> <remote_macro_call> [Note: Unlike other system variables, the value of this variable can be changed using <varset> command.]
_vMacroFileLoaded | Full path to the macro file currently loaded in the program. It is also possible to write to this variable in order to force the program to load other macro file: <varset>("_vMacroFileLoaded=c:\....\otherfile.4tw","") Note: The other file is loaded when there is no macro currently executing.
_vMacroSharedFileLoaded | Full path to the shared macro file currently loaded in the program.
_vMacroFileFolder | Folder where the currently loaded macro file resides. It is ended by \.
_vRunningMacroName | Contains name of the currently running macro.
_vRunningMacroId | Contains Id of the currently running macro.
_vMsgButton | The variable contains YES if "Yes" button was clicked in the <msg> command, otherwise it contains NO.
_vIsMacroEnabled_MACRONAME | Such system variable exist for each macro. The variable contains "1" if the macro is enabled, otherwise it is "0". For example, if the macro name is "MyMacro1" then the associated system variable is "_vIsMacro_Enabled_MyMacro1".
_vIsGroupEnabled_MACRONAME | Such system variable exist for each macro group. The variable contains "1" if the macro group is enabled, otherwise it is "0". For example, if the name of macro group is "FileMacros" then the associated system variable is "_vIsGroupEnabled_MyMacro1".
_vDoesVariableExist_VARIABLE | Such system variable exist for each variable. The variable contains "1" if the variable exists, otherwise it is "0". For example, if the name of a variable is "vMyData" then the associated system variable is "_vDoesVariableExist_vMyData".
_vWaitForImage_PosX | This variable contains X position of the image that was found on the screen during <waitfor>(...IMAGE_ON_SCREEN...) command.
_vWaitForImage_PosY | This variable contains Y position of the image that was found on the screen during <waitfor>(...IMAGE_ON_SCREEN...) command.
_vSharedMacros_ReloadNow | Can be used to commands the program to reload shared macros. Use: <varset>("_vSharedMacros_ReloadNow=YES","").
_vOpt_SharedMacros_Enable | This system variable contains information whether shared macros are enabled/disabled. It can be also used to programmatically enable/disable shared macros. <varset>("_vOpt_SharedMacros_Enable=YES","") command causes the shared macro file is enabled while <varset>("_vOpt_SharedMacros_Enable=NO","") command causes the shared macro file is disabled.
_vOpt_SharedMacros_File | This system variable contains file shared macros file path. It can be programmatically set: <varset>("_vOpt_SharedMacros_File=c:\macroFiles\shared.4tw","") command causes the shared macro file is set to "c:\macroFiles\shared.4tw".
Other: |
_vLastWebPageLoaded | This variable contains URL of the web page last opened using <www_open> or <www_fillform>..
_vOS_UserDefaultLanguageID | Contains the language identifier of the current Windows user locale.
_vOS_SystemDefaultLanguageID | Contains the language identifier of the Windows system locale.
_vStrEmpty | Empty string (use this variable to assign empty string to a variable).
_vIsScreensaverRunning | YES if screen saver is running.
_vIsScreensaverEnabled | YES if screen saver is enabled.
_vOperatingSystemVersion | Operating system version.
_vScreenWidth | Screen width in pixels.
_vScreenHeight | Screen height in pixels.
_vThisProgramVersion | Contains #THIS_PROGRAM# internal version.

Example:

<#> This macro shows how to use system variables
<#>
<execappex>("notepad.exe","","",0,0)

Active window title: <varout>("_vActiveWindow",0)
Current mouse position: (<varout>("_vMousePosX",0), <varout>("_vMousePosY",0))

System folders:
<varout>("_vFolder_AppData",0)
<varout>("_vFolder_CommonDesktop",0)
<varout>("_vFolder_CommonPrograms",0)
<varout>("_vFolder_CommonStartMenu",0)
<varout>("_vFolder_Cookies",0)
<varout>("_vFolder_Desktop",0)
<varout>("_vFolder_Favourites",0)
<varout>("_vFolder_Personal",0)
<varout>("_vFolder_Programs",0)
<varout>("_vFolder_Windows",0)
<varout>("_vFolder_System",0)


How To Write Reliable Macros?

It often happens that a macro (macro that sends keystrokes or uses mouse events) user creates (records) works fine at the development time but starts being unreliable later (after user reboots computer, installs new software etc.). This is not a problem of the macro program but it is natural problem of Windows events timing. One simple example:
Let's say user wants to create macro that will do this: Start Notepad and type "Hello" in it. This is quite simple and user quickly creates this macro:

<lwinkey>r<lwinkey>notepad.exe<enter>Hello

The macro will do this: opens Run dialog box (<lwinkey>r<lwinkey>), types "Notepad.exe" in it, hits Enter key to run Notepad and types "Hello" in it. In 90% cases, It will work OK. But what if: (i) computer is busy and Run dialog appears many seconds after all the keystrokes (Notepad.exe Hello) are already sent out, (ii) a newly installed software user re-defines LWinKey+R hot key and Run dialog doesn't appear at all. In such cases the macro fails doing what's expected without any notice to the user. The macro language has commands that make it possible to write the same macro safe way:

<lwinkey>r<lwinkey><cmds> <#> Open Run dialog

<waitfor>("WIN","ACT","Run",5,0) <#> Wait for the dialog to become active
<if_str>("_vErr==NO")
<keys>notepad.exe<newline><cmds> <#> No (timeout) error? Let the dialog to start Notepad then...
<else>
<msg>(-100,-100,"%_vQuoteChar%Run%_vQuoteChar% dialog faild to open.","Message",1)
<exitmacro>
<endif>

<waitfor>("WIN","ACT","Notepad",5,0) <#> Wait for Notepad to become active
<if_str>("_vErr==NO")
<keys>Hello<cmds> <#> No (timeout) error? Send keystrokes to Notepad then...
<else>
<msg>(-100,-100,"%_vQuoteChar%Notepad%_vQuoteChar% not activated.","Message",1)
<exitmacro>
<endif>

This code is much longer compare to the original macro, right. But the macro execution result is always deterministic: Macro either executes OK or any failure is properly handled. This becomes important especially for more complex macros that use many users in larger corporations.

There are a few advises that should help you to write macros that are more reliable:

1. Some time an application the macro runs in is too slow to process all the input (keystrokes sent) in time. In such case it can help to use <wx>(250) command that stops macro execution for 250ms and gives the application time to process previous input before the macro continues.

2. If you write a macro that starts an application and then sends keystrokes into it, it is necessary to wait until the application loads. You can use <waitfor> command right after the command you use to start the application. The <waitfor> command waits until specified window appears on the screen or until it times out (timeout sets _vErr system variable and thus can be handled in the macro code).

3. If you write a macro that copies some selected data (text, bitmap, etc.) using clipboard, it is recommended to use <clp_copyselected> command (this command waits until data are really copied to clipboard before macro execution continues) or use <waitfor> command to wait until the data are actually saved in the clipboard.

4. Replace all keystrokes and mouse actions by other commands if possible. This means that if something can be done using a macro language command instead of using keyboard or mouse then always use the command. For example, people often tend to open applications by simulating clicks on desktop or Start menu. This has many drawbacks and it is always better to use <execappex> command. We can simplify and make our sample above more robust using this command:

<cmds>
<execappex>("Notepad.exe","","",0,0)
<waitfor>("WIN","ACT","Notepad",5,0)
<if_str>("_vErr==NO")
<keys>Hello<cmds>
<else>
<msg>(-100,-100,"%_vQuoteChar%Notepad%_vQuoteChar% not activated.","Message",1)
<exitmacro>
<endif>


Commands

Available commands are logically organized in groups. Each command comes with a simple example showing how to use the command in a macro.


 Advanced Scripting

Note: Advanced scripting feature is available only in “Advanced Scripting Edition” of this software.

By advanced scripting we mean support for other, industry standard, languages. Currently, we support Basic Script, VB Script and Java Script.

Basic Script is Visual Basic for Application™ compatible language built on top of popular SAX Basic engine. The Basic Script comes with powerful editor (features syntax highlighting, tool tips), debugger, dialog editor, language reference help and other tools necessary for comfortable scripts development. Basic Script features more commands then native macro language and allows user to write more complex scripts: use OLE, DDE, create dialogs, use mathematical functions and much more.

As for the VB Script and Java Script, the level of support is limited to execution (there is not a debugger or editor for VB Script and Java Script).

Script can be either “embedded” or “external”. Embedded script is an integral part of macro source code (the embedded script source code is part of the macro source code) while external script is saved in other file.

Embedded script commands:

<script_basic> Basic Script
<script_vbs> VB Script
<script_js> JavaScript

External script commands:

<script_file> External Script File

Visual Basic for Application is trademark of Microsoft Corporation.


 <script_basic> : Basic Script (Embedded)

Encloses “Basic Script” script within a macro. It is possible to exchange data between the program native macro language variables and the Basic Script variables. The variable content exchange is done through DDE - see the samples below.

Syntax:

<script_basic> A script source code goes here…</script_basic>

Examples:

1. This macro sample counts Sin(1) and displays it in Notepad:

<#> Count sin(1), put it to clipboard and show it in Notepad
<#>
<cmds>
<script_basic>
Sub Main
s = Sin(1)
Clipboard s
End Sub
</script_basic>
<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","OPEN","Notepad",5,0)
<keys><ctrl>v<ctrl>

 2. This macro sample shows how to retrieve value of _vCurrDate_DDMMYYYY native macro language system variable and save it in Basic Script variable:

<cmds>|
<script_basic>
Sub Main
ChanNum = DDEInitiate("MacroEngine","MacroGetVar")
Var$ = DDERequest$(ChanNum,"_vCurrDate_DDMMYYYY")
DDETerminate ChanNum
MsgBox Var
End Sub
</script_basic>

3. This macro sample shows how to send data from basic script code to native macro:

<cmds>
<script_basic>

Sub Main
ChanNum = DDEInitiate("MacroEngine","MacroSetVar")
Var = "vVar=Hello from Basic script!"
DDEExecute (ChanNum, Var)
DDETerminate ChanNum
End Sub

</script_basic>
<msg>(-100,-100,"vVar","Data Retrieved From Basic Script",1)


 <script_file> : External Script

Executes a script saved in an external file.

Syntax:

<script_file>(“Script file name”, Wait for script to finish)

Script file name:
Script file to run. There are these file types supported:
.bss – Basic Script file
.bsx – encoded Basic Script file
.vbs – VB Script file
.js - Java Script file

The file should be either full path (e.g., "c:\myscripts\script1.bss") or just file name (e.g., "script.bss"). Partial or relative paths (e.g., "..\scripts\script.bss") are not supported at this time. All the scripts that you call using just the name (e.g., "script.bss") must be saved in the "scripts" directory. In the “Basic Script” scripts, it is possible to use '#Uses "some-file" directives that allows to use symbols defined in other modules. In the "uses" directives, both BSS and BSX files can be used (they also have to be in "scripts" directory or full path must be supplied).

Wait for script to finish:
If equal to 1, the macro waits until script execution is finished.
If equal to 0, the macro continues execution without waiting for script to finish.

Example:

<#> This macro runs selected script
<#>
<cmds>
<var_oper>(vScript,"*.bss",SELECT_FILE,"Select Script To Run","", "0")
<if_str>("_vCanceled==1") <exitmacro> <endif>

<script_file>("vScript",0)


 <script_vbs> : VB Script (Embedded)

Encloses “VBScript” script within a macro.

Syntax:

<script_vbs>A script source code goes here…</script_vbs>

Note: You have to have installed “VB Script” scripting host to be able to run JavaScript scripts. The scripting host is automatically installed with MSIE 4.0 or later.

Example:

<#> Very simple VB Script example
<cmds>
<script_vbs>
MsgBox("This is VB Script")
</script_vbs>


<script_js> : Java Script (Embedded)

 <script_js> : Java Script Embedded

Encloses “JavaScript” script within a macro.

Syntax:

<script_js>A script source code goes here…</script_js>

Note: You have to have installed JavaScripts scripting host to be able to run JavaScript scripts. The scripting host is automatically installed with MSIE 4.0 or later.

Example:

<#> This is very simple JavaScript example
<cmds>

<script_js>

function Hello()
{
var WSHShell = WScript.CreateObject("WScript.Shell");
WSHShell.Popup("Hello, this is JavaScript");
}

Hello()

</script_js>


 Insert Text (Send Keystrokes)

By default, whole the macro text is executed by the macro engine. This means that macro engine takes the macro text and considers it as a set of keystrokes to be sent to currently active window (target window). This is very handy for macros that consist (mostly) from text to be inserted to a target application. For example, let's have this macro:

Hello,
thanks for your e-mail.

This macro, when played back, will insert the above too lines to the target application. This allows users to create this kind of "text expand" macro simply by just typing required text in macro editor.
From other hand, there are also macros that do something that has nothing to do with inserting text (sending keystrokes) - file operation macros, download/upload from/to internet, changing registry, and many many other. For such kind of macros it is not convenient that each new line (Enter key) is processed since it might affect the macro execution. For this reason, there is <cmds> command. It causes that only commands (for example, <filecopy>, <ftp_putfile>, etc.) are executed and all other text is ignored. The opposite command is <keys> command that switch macro engine back to default behavior, i.e., all the macro text is executed (including new line interpreted as an "Enter" key).
Control Keys

Normal keys (like A-Z, 0-9, Page Down, Tab, etc.) are sent by macro engine as key “press” and key “release” sequence. Control keys (e.g., Alt, Ctrl, Shift, etc.), that changes keyboard context, are different. The first occurrence of such key in the macro has meaning "press key down" key and the second occurrence has meaning "release" key. This means that, for example, "Ctrl+K" keystroke is represented as "<ctrl>k<ctrl>".

Some keys (for example, right Control key, or NumPad Enter key) are so called “extended” keys. To simulate extended key keystroke use <extkey> command before the key. For example, <extkey><newline> sequence has the same effect as pressing NumPad Enter key.

<back> | Back
<shift> | Shift
<alt> | Alt
<esc> | Escape
<pgdn> | Page down
<home> | Home
<up> | Up arrow key
<right> | Right arrow key
<delete> | Delete
<F1>-<F24> | F1 - F24 function keys
<clear> | Clear
<execkey> | Execute key
<rwinkey> | Right Windows key
<scroll> | Scroll
<numpad0> - <numpad9> | Numpad keys 0 - 9
<numpad*> | Numpad * key
<numpad/> | Numpad / key
<newline> | Enter (return)
<ctrl> | Ctrl
<capslock> | Caps Lock
<pgup> | Page up
<end> | End
<left> | Left arrow key
<down> | Down arrow key
<insert> | Insert
<tab> | Tab
<break> | Break
<select> | Select
<lwinkey> | Left Windows key
<appskey> | Application key
<numlock> | Num Lock
<numpad+> | Numpad + key
<numpad-> | Numpad - key
<printscreen> | Print Screen

Windows2000 Keys:

<browser_back>

<browser_forward>

<browser_refresh>

<browser_stop>

<browser_search>

<browser_favorites>

<browser_home>

<volume_mute>

<volume_down>

<volume_up>

<media_nexttrack>

<media_prevtrack>

<media_stop>

<media_play_pause>

<launch_mail>

<launch_media_select>

<launch_app1>

<launch_app2>


<label> : Label

 <key_down> : Press Key Down
<key_up> : Release Key (Key Up)

The <key_down> and <key_up> commands are not intended for inserting text (sending keystrokes) to currently active window (target application) which can be done much simpler way. However, sometimes there can be a specific needs that require to work with keys on "down - up" bases (for example, when it is required to hold a key down for specific amount of time).

Syntax:

<key_down>(Key, Extended)
<key_up>(Key, Extended)

Key
The key to press/release such as A, B, 1, /, etc. For Shift, Ctrl, F1, etc., keys <shift>, <ctrl>, <F1> syntax needs to be used.

Extended
If 1, the extended key pressed/released. Otherwise have to be 0.

Example:

<#> This command presses down "A" key and releases it one second later
<cmds>
<key_down>(<shift>,0)
<key_down>(A,0)
<wx>(1000)
<key_up>(A,0)
<key_up>(<shift>,0)


 <keys_block> : Block Keys
<keys_unblock> : Unblock Keys

This command blocks keyboard keys. It can be used when it is necessary to disable keyboard input during macro execution, for example, before "wait for key" command (<waitfor>). If it is required to disable keyboard keys during macro execution from the begin to the end, it is possible to use "Lock keyboard and mouse while macro is running" option in the macro settings tab.
To unblock keyboard, use <keys_unblock> command.

Syntax:

<keys_block>
<keys_unblock>

Example:

<#> This macro shows how to use 'keys_block' and 'keys_unblock' commands
<#>
<cmds>
<msg>(32,32,"Waiting untill 'a' key is pressed....","Message",0)
<keys_block>
<waitfor>("KEY","PRESS","a",50,0)
<keys_unblock>


<keys_unblock> : Unblock Keys

<keys_block> : Block Keys
<keys_unblock> : Unblock Keys

This command blocks keyboard keys. It can be used when it is necessary to disable keyboard input during macro execution, for example, before "wait for key" command (<waitfor>). If it is required to disable keyboard keys during macro execution from the begin to the end, it is possible to use "Lock keyboard and mouse while macro is running" option in the macro settings tab.
To unblock keyboard, use <keys_unblock> command.

Syntax:

<keys_block>
<keys_unblock>

Example:

<#> This macro shows how to use 'keys_block' and 'keys_unblock' commands
<#>
<cmds>
<msg>(32,32,"Waiting untill 'a' key is pressed....","Message",0)
<keys_block>
<waitfor>("KEY","PRESS","a",50,0)
<keys_unblock>


<mm> - Mouse Move

<mm>
Mouse Move

Moves mouse cursor to required position. The position is in absolute screen coordinates by default. There are these three commands that can precede the <mm> command and change the mouse move coordinates meaning:

<mousemove_absolute> - mouse cursor position is in absolute screen coordinates
<mousemove_relative_win> - mouse cursor position is relative to currently active window
<mousemove_relative_pos> - mouse cursor position is relative to current mouse cursor position

Syntax:
<mm>(Xpos, Ypos)
Xpos : X-coordinate of the new mouse cursor position.
Ypos : Y-coordinate of the new mouse cursor position.

Example:

<#> This macro moves the mouse cursor to position (100,100)
<#> and than - after 2 seconds - to position (-10, -10) relative to
<#> position (100, 100)
<cmds>

<mm>(100,100)

<wx>(2000)

<mousemove_relative_pos>
<mm>(-10,-10)


 <#> : Comment

The <#> syntax allows a user to insert a comment to macro. The comment is ignored during macro execution and doesn't affect macro functionality any way. Location in "Available Commands" tree: Comment Syntax: <#> Comment follows….

Example:

<#> This is a comment that is ignored…
and this text is not a comment and will be send to a target application…


 <date> : Insert Date

Inserts formatted date information (e.g., 02/24/2000) into the currently active window.

Syntax:

<date>(Format, Separator, DayLZ, MonthLZ, Shift, "SaveToVariable")

Format
The format index (the first format has index 0).

Separator
Separator character: .,/- etc.

DayLZ
If 1, the day is displayed with leading zero (e.g., 02). If 0, the day is displayed without leading zero (e.g., 2).

MonthLZ
If 1, the month is displayed with leading zero (e.g., 09). If 0, the month is displayed without leading zero (e.g., 9).

Shift
The date shift in days relative to the current date. 0 for no shift (today's date), -1 for date one day back (yesterday), +1 for date one day later (tomorrow), etc.

SaveToVariable
Variable that receives the date. If this variable name is an empty string, the date is send to active application as a set of keystrokes.

Example:

<#> Run this example in Notepad:
Current date is: <date>(1,"/",1,1,0,"")
Current date is: <date>(10,"/",1,1,0,"")
Yesterday: <date>(1,"/",1,1,-1,"")


 <time> : Insert Time

Inserts formatted time information (e.g., 2:09 AM) into the currently active window.

Syntax:

<time>(Shift, HourLZ, MinuteLZ, AmPm, TimeBase,"SaveToVariable")

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.
Can be a number or variable containing numeric value.

HourLZ
If 1, the hour is displayed with leading zero (e.g., 02). If 0, the hour is displayed without leading zero (e.g., 2).
Can be a number or variable containing numeric value.

MinuteLZ
If 1, the minute is displayed with leading zero (e.g., 09). If 0, the minute is displayed without leading zero (e.g., 9).
Can be a number or variable containing numeric value.

AmPm
If 1, "AM" (or "PM") is displayed next to the time (e.g., 2:09 AM). It is not displayed If AmPm is 0.
Can be a number or variable containing numeric value.

TimeBase
If 0, the 24 hours time base is used. If 1, the 12 hours time base is used.

SaveToVariable
Variable that receives the time. If this variable name is an empty string, the time is send to active application as a set of keystrokes.

Example:

<#> Run this macro in Notepad:
Current time (24-hours base, no AM/PM) is: <time>(0,1,1,0,0,"")
Current time (12-hours base, with AM/PM) is: <time>(0,1,1,1,1,"")


 <td:d> : Today's Day

Inserts date's day into the currently active window.

Syntax:

<td:d>(Shift)

Shift
The date shift in days relative to the current date. 0 for no shift (today's date), -1 for date one day back (yesterday), +1 for date one day later (tomorrow), etc.

Example:

Today's day: <td:d>(0)
Tomorrow's day: <td:d>(1)


<td:d> : Today's Day (With Leading Zero)

 <td:dlz> : Today's Day (With Leading Zero)

Inserts date's day (with leading zero, e.g., 02) into the currently active window.

Syntax:

<td:dlz>(Shift)

Shift
The date shift in days relative to the current date. 0 for no shift (today's date), -1 for date one day back (yesterday), +1 for date one day later (tomorrow), etc.

Example:

Today's day: <td:dlz>(0)
Tomorrow's day: <td:dlz>(1)


 <td:m> : Today's Month

Inserts date's month (e.g., 2) into the currently active window.

Syntax:

<td:m>(Shift)

Shift
The date shift in days relative to the current date. 0 for no shift (today's date), -1 for date one day back (yesterday), +1 for date one day later (tomorrow), etc.

Example:

Today it is month: <td:m>(0)
Tomorrow it will be month: <td:m>(1)


<td:m> : Today's Month

 <td:mlz> : Today's Month (With Leading Zero)

Inserts date's month (with leading zero, e.g., 02) into the currently active window.

Syntax:

<td:mlz>(Shift)

Shift
The date shift in days relative to the current date. 0 for no shift (today's date), -1 for date one day back (yesterday), +1 for date one day later (tomorrow), etc.

Example:

Today it is month: <td:mlz>(0)
Tomorrow it will be month: <td:mlz>(1)


 <td:y> : Today's Year

Inserts date's year (e.g., 2003) into the currently active window.

Syntax:

<td:y>(Shift)

Shift
The date shift in days relative to the current date. 0 for no shift (today's date), -1 for date one day back (yesterday), +1 for date one day later (tomorrow), etc.

Example:

Today it is year: <td:y>(0)
Tomorrow it will be year: <td:y>(1)


 <ct:h24> : Current Time - Hour (24 Based)

Inserts hour (e.g., 15) into the currently active window.

Syntax:

<ct:h24>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Current time hour: <ct:h24>(0)
One minute later it will be hour: <ct:h24>(1)


<ct:h24> : Current Time - Hour (24 Based, With Leading Zero)

 <ct:h24lz> : Current Time - Hour (24 Based, With Leading Zero)

Inserts hour (with leading zero, e.g., 05) into the currently active window.

Syntax:

<ct:h24lz>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Current time hour: <ct:h24lz>(0)
One minute later it will be hour: <ct:h24lz>(1)


 <ct:h12> : Current Time - Hour (12 Based)

Inserts hour (e.g., 3) into the currently active window.

Syntax:

<ct:h12>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Current time hour: <ct:h12>(0)
One minute later it will be hour: <ct:h12>(1)


<ct:h12> : Current Time - Hour (12 Based, With Leading Zero)

 <ct:h12lz> : Current Time - Hour (12 Based, With Leading Zero)

Inserts hour (with leading zero, e.g., o3) into the currently active window.

Syntax:

<ct:h12lz>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Current time hour: <ct:h12lz>(0)
One minute later it will be hour: <ct:h12lz>(1)


 <ct:m> : Current Time - Minute

Inserts minute (e.g., 6) into the currently active window.

Syntax:

<ct:m>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Current time minute: <ct:m>(0)
One minute later it will be: <ct:m>(1)


<ct:m> : Current Time - Minute

 <ct:mlz> : Current Time - Minute (With Leading Zero)

Inserts minute (with leading zero, e.g., 06) into the currently active window.

Syntax:

<ct:mlz>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Current time minute: <ct:mlz>(0)
One minute later it will be: <ct:mlz>(1)


 <ct:ampm> : Current Time - am/pm

Inserts "am" (or "pm") into the currently active window.

Syntax:

<ct:ampm>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Morning or afternoon ? <ct:ampm>(0)
...and one minute later ? <ct:ampm>(1)


 <ct:AMPM> : Current Time - AM/PM

Inserts "AM" (or "PM") into the currently active window.

Syntax:

<ct:AMPM>(Shift)

Shift
The time shift in minutes relative to the current time. 0 for no shift, -1 for time one minute back, +1 for time one minute later, etc.

Example:

Morning or afternoon ? <ct:AMPM>(0)
...and one minute later ? <ct:AMPM>(1)


 <execappex> : Start Application

Starts (executes) application.

Syntax:

<execappexe>("AppFile", "Params", "Dir", StartState, Reserved, Timeout)

AppFile
(Full) path to the application's file (e.g., "c:\program files\app\app.exe").
Can be a static text or variable containing text.

Params
List of parameters the application should be started with (e.g., "/n /g").
Can be a static text or variable containing text.

Dir
Start up directory. The directory is made current before the application is started.
Can be a static text or variable containing text.

StartState
The state of the window:
0 - Normal
1 - Maximized
2 - Minimized
Can be a number or variable containing numeric value.

Reserved
Must be 0.

Timeout
Insert timeout in seconds if it is desired to wait with further macro execution until the started application finishes. If this parameter is 0 or left blank then the macro execution continues immediately after the application is started.

Example:

<#> This command starts Notepad maximized.
<#>
<cmds>
<execappex>("notepad.exe","","",1,0)


 <run_ctxcommand> : Run Context Menu Command

When a user right-clicks on a file in Windows Explorer a menu so called “context menu” is shown. There are listed several commands a user can perform with the file (like “Open”, “Delete”, “Copy”, etc.). It is possible to perform any of such a command using <run_ctxcommand>.

Syntax:

<run_ctxcommand>("File", Menu Command, Reserved1, Reserved2)

File
(Full) path to the file (e.g., "c:\mydocuments\doc1.doc") to run a command on.
Can be a static text or variable containing text.

Menu Command
Menu command as shown on the menu. For example: Open, Copy, Delete, etc. If the command is in submenu then use following syntax: Send To/My Documents, WinZip/Add to Zip file…, etc.
Can contain also wildcards (* and ?) that can be used to omit problems with national characters.

Reserved1
Must be 0.

Reserved2
Must be 0.

Example 1:

<#> This command opens property dialog of “C:\temp” directory
<#>
<cmds>
<run_ctxcommand>("c:\temp",Properties,0,0)

Example 2:

<#> This command opens property dialog of “C:\temp” directory
<#>
<cmds>
<run_ctxcommand>("c:\temp",?roperties,0,0)


 <run> : Run Other Macro

Runs other macro (specified by name). It is possible to pass the called macro a parameter and it is also possible to receive a return data from the called macro. If the called macro returns some data then the data are available through "_vMacroResult" system variable right after the <run> command finishes execution.

Syntax:

<run>("MacroName or ID", "Parameter")

MacroName or ID
Name or ID (showing in the "general" tab in macro definition view) of the macro to run.

Parameter
Parameter that will be passed to the remote macro. The called macro can retrieve the parameter data from "_vMacroParameter" system variable.

Example:

<#> This example shows how to call a macro called "ToUpper" using <run> command.
<#> We pass parameter "lowercase string" that the "ToUpper"
<#> macro converts to uper case and passes back as a result.
<#>
<cmds>
<run>("ToUpper","lowercase string")
<msg>(-100,-100,"%_vMacroResult%","And the result is",1,0,0)

Example how the "ToUpper" macro is implemented:

<#> This macro converts input parameter to upper case and returns it as a result.
<cmds>
<var_oper>(_vMacroResult,"%_vMacroParameter%",STR_UPPER,"2","1", "0")


 <extmacro> : Run External Macro

Runs macro saved in an external text file. It is possible to pass the external macro a parameter and it is also possible to receive a return data from the macro. If the macro returns some data then the data are available through "_vMacroResult" system variable right after the <extmacro> command finishes execution.

Syntax:

<extmacro>("MacroFile", Clipboard, "Parameter")

MacroFile
Name of the macro to run. (The macro name should be unique if it is run from other macros using <run> command).

Clipboard
If 1, the text from the MacroFile is inserted to the active window through the clipboard. (This option is intended only for plain text with no commands.)
If 0, the macro from the MacroFile is played back the same way as it was regular macro.

Parameter
Parameter that will be passed to the remote macro. The called macro can retrieve the parameter data from "_vMacroParameter" system variable.

Example:

<#> This macro starts macro from external file.
<#>
<cmds>
<extmacro>("%_vMacroFileFolder%Samples\Simple form example.mcr",0)

Example 2:

<#> This example shows how to call a macro that converts passed parameter to uper case and passes back as a result.
<#>
<cmds>
<extmacro>("%_vMacroFileFolder%Samples\ToUpper.mcr",0,"convert to upper case this, please")
<msg>(-100,-100,"%_vMacroResult%","And the result is",1,0,0)

Example how the "ToUpper.mcr" macro is implemented:

<#> This macro converts input parameter to upper case and returns it as a result.
<cmds>
<var_oper>(_vMacroResult,"%_vMacroParameter%",STR_UPPER,"2","1", "0")


<beep> : Play Sound

<remote_macro_call> : Remote Macro Call

This command calls macro located on a remote computer over network. On the remote computer, there must be #THIS_PROGRAM# family product running with the "remote macro call" feature enabled. Read more also here and here..

Syntax:

<remote_macro_call>("Remote IP Address", "Port", "Macro Name", "Parameter", "Password Required", "Timeout", "Wait Until Finishes")

Remote IP Address
This is IP address of the remote computer where macro we want to call resides.

Port
This is a communication port number (default is 20304).

Macro Name
Name of the macro to run.

Parameter
Parameter that will be passed to the remote macro. The remote macro can retrieve the parameter data from "_vMacroParameter" system variable.

Password Required
Needs to be 1 if a password to start macro is required. Otherwise it is 0.

Timeout
Timeout in milliseconds. If this command does not finishes before the timeout then it fails.

Wait Until Finishes
Needs to be set to 1 if it is required to wait until the remote macro finishes execution. The remote macro may return a result data that can be retrieved from "_vMacroResult" system variable. If it is not required to wait until the remote macro finishes then set this parameter to 0.

Example:

<#> This is how we call a macro on remote computer.
<#> We pass parameter "lowercase string" that the remote
<#> macro converts to uper case and passes back as a result.
<#>
<cmds>
<remote_macro_call>("100.0.0.100","20304","ToUpper_Remote","lowercase string","0","10","1")
<msg>(-100,-100,"%_vMacroResult%","Remote Macro Results",1,0,0)

Example how the "ToUpper_Remote" macro is implemented on the remote site:

<#> This macro converts input parameter to upper case and returns it as a result.
<cmds>
<var_oper>(_vMacroResult,"%_vMacroParameter%",STR_UPPER,"2","1", "0")


 <varset> : Assign Variable Value

Declares variable and sets its value.

Syntax:

<varset>("Variable", "MessageTitle")

Variable
Defines variable and its value in the form VARIABLE_NAME=VALUE. Variable can be any string (different from system variables ID_SYSTEMVARIABLES). The value can be either constant string or other variable or empty string. There are four basic behaviors of the command:
1. VALUE is supplied. In such case the variable is assigned the VALUE. For example, "vNumber=10" or "vName=John".
2. List of possible values is supplied in VALUE. Each single item in the list is separated by "|" character. For example, "vNames=Jane|Paul|Chris|Michael".
3. VALUE is an empty string ("vName="). In such the case, a dialog window with the MessageTitle appears and prompts user to enter the variable value. Note: To assign an empty string to the variable use this construction: "vEmptyStr=_vStrEmpty".
4. VALUE is equal to "YES/NO". In such the case, a "yes/no" message box withMessageTitle appears. If user selects "yes" button the "YES" value is assigned to the variable. If the user selects "no" button the "NO" value is assigned. For example, "vDoYouWant=YES/NO".

In cases #2 and #3 above, if user clicks "Cancel" button the _vCanceled system variable is set to 1 (otherwise it is 0) to allow macro designer to distinguish between situations when OK or Cancel button was clicked.

Instead of using VARIABLE_NAME=VALUE syntax, also VARIABLE_NAME=!VALUE can be used. In this case, the VALUE is assigned to the variable and the rules #2 - #4 above are not applied (hard assignement).

MessageTitle
A title of the window that appears in cases 1 and 3 above.

Example:

<#> This macro demonstrates <varset> command
<#>
<cmds>

<varset>("vName=","Insert Your Name")
<if_str>("_vCanceled==1") <exitmacro> <endif>

<varset>("vShow=YES/NO","Do you want to see your name ?")

<if_str>("vShow==YES")
<msg>(100,100,"vName","Your name is:",1)
<endif>

<varset>("vName=Jane|Paul|Michael|Chris","Who is my best friend ?")
<if_str>("_vCanceled==1") <exitmacro> <endif>

<if_str>("vName==Jane")
<msg>(100,100,"Yes!","Message",1)
<else>
<msg>(100,100,"No!","Message",1)
<endif>


 <var_oper> : Modify Variable Value

Performs selected operation on input variable (or constant string/value) and saves the result to other variable.

Syntax:

<var_oper>(ResultVar, "Input", Operation, Param1, Param2, Param3)

ResultVar
Variable that receives result of the operation.

Input
Either variable or constant text (string, numerical value) to perform operation on.

Operation
One of these operations:

CALC_EXPRESSION
- calculates arithmetical expression defined by input. Param1 tells how many numbers will follow after decimal point.

RANDOM_NUMBER
- generates random number from 0 to Param1 range.

SELECT_FILE
- shows “Open File” dialog and saves full path of the selected file to ResultVar. If user clicks "Cancel" button the _vCanceled system variable is set to 1 (otherwise it is 0) to allow macro designer to distinguish between situations when OK or Cancel button was clicked.

SELECT_FOLDER
- shows “Select Folder” dialog and saves full path of the selected folder to ResultVar. If user clicks "Cancel" button the _vCanceled system variable is set to 1 (otherwise it is 0) to allow macro designer to distinguish between situations when OK or Cancel button was clicked.

GET_TEXT_FROM_CLIPBOARD
- copies text from clipboard to ResultVar.

STR_APPEND
- appends the Input to the content of ResultVar.

STR_LEFT
- characters from begin of the Input (number of characters is given by Param1) are copied to ResultVar.

STR_RIGHT
- characters from end of the Input (number of characters is given by Param1) are copied to ResultVar.

STR_MID
- characters beginning at Param1 position (number of characters is given by Param2) are copied to ResultVar.

STR_TRIMLEFT

- characters specified in Param1 are deleted from begin of the Input.
STR_TRIMRIGHT
- characters specified in Param1 are deleted from end of the Input.

STR_INSERT
- string defined by Param2 is inserted to Input string to position Param1.

STR_REPLACE
- In the Input, original string Param1 is replaced by Param2.

STR_DELETE
- in the Input, deletes Param2 (number of characters to delete) characters starting at position Param1.

STR_FIND
- finds first occurrence of the Param1 string in the Input. The search is started from Param2 position.

STR_UPPER
- converts Input to upper case.

STR_LOWER
- converts Input to lower case.

STR_LENGTH
- returns length of the Input.

STR_GET_CHAR
- returns character from the Param1 position in the Input.

STR_TOGGLE_CASE
- changes upper case to lower case and vice versa.

STR_SENTENCE_CASE
- changes first character on begin of each sentence to upper case.

STR_INTERSPACES
- extra space is added to next to each Input character. Example: “ABC” is changed to “A B C “.

STR_FIRST_UPPER
- changes first character of Input to upper case.

TEXT_GET_WORD
- retrieves a word from Param1 position within Input. Param2 contains characters user can exclude from default word delimiters ( ;,\t\n\r?!.:). This means that if "." is excluded from the delimiters then "www.my7thsite.com" is returned as a single word. Otherwise it is returned as three words.

TEXT_GET_NUMOFWORDS
- return number of words in Input. Param2 contains characters user can exclude from default word delimiters ( ;,\t\n\r?!.:).

TEXT_GET_LINE
- retrieves line number Param1 (line numbers start at 0) from Input.

TEXT_GET_NUMOFLINES
- returns number of lines in Input.

TEXT_JUSTIFY
- justifies the Input text so that all lines have the same length defined by Param1. If the Param1 is –1 the length of all lines is the same as the first line.

TEXT_INDENT_LEFT
- removes leading spaces on begin of each Input line.

TEXT_INDENT_RIGHT
- adds extra spaces on begin of each Input line.

TEXT_ADDNUMBERING
- justifies and adds numbering to paragraphs of Input text. Paragraphs are delimited by empty line. Param1 defines width of the justified text. If the Param1 is –1 the length of all lines is the same as the first line. Param2 defines numbering style. It can be one of the follows:
"1)", "1.", "1/", "A)", "A.", "A/", "a)", "a.", "a/", "-", "#", "*"
TEXT_CENTER
- centers Input text. Param1 defines width of the text.

TEXT_UNDERLINE_LIKE
- extra line consisting of “-“ characters is added to Input.

TEXT_ALIGN_LEFT
- aligns Input text left by removing spaces on begin of each line.

TEXT_ALIGN_RIGHT
- aligns Input text to right by adding extra spaces on begin of each line. Param1 defines width of the text. If the Param1 is –1 the width is given by the width of the first line.

ARRAY_SORT_STRING
- sorts ResultVar array (array variable) of strings. If Param1 is 1 then sorting is case sensitive. Param2 (if specified) is delimiter that delimits the input string so that only the part before delimiter is taken for the comparison. Example: If variable string is "Smooth, John, john@e-mail.net" and delimiter is "," only the "Smooth" is used for comparison. If no delimiter is defined whole "Smooth, John, john@e-mail.net" string is used for comparison.

ARRAY_SORT_NUM
- sorts ResultVar array (array variable) of numbers. The Param2 meaning is the same as in ARRAY_SORT_STRING above.

ARRAY_DELETEALLITEMS
- deletes all items of the ResultVar array (array variable).

ARRAY_DELETEITEM
- removes specific item from the ResultVar array (array variable). Param1 is an index of the item to remove.

ARRAY_INSERTITEM
- inserts item to defined position in the ResultVar array (array variable). Param1 is new item position and Input is value of the newly inserted item.

ARRAY_FINDITEM
- searches for the specified value (text) in Param2 array (array variable). Param1 is an index to start searching from. Input is the text to search for. If an array item matches search criteria then the item index is saved to ResultVar variable. The search only succeeds if whole the item value is equal to Input value (matching is case sensitivity).

ARRAY_FINDITEM_NOCASE
- searches for the specified value (text) in Param2 array (array variable). Param1 is an index to start searching from. Input is the text to search for. If an array item matches search criteria then the item index is saved to ResultVar variable. The search only succeeds if whole the item value is equal to Input value - but matching is not case sensitive.

ARRAY_FINDITEM_PARTIALMATCH
- searches for the specified value (text) in Param2 array (array variable). Param1 is an index to start searching from. Input is the text to search for. If an array item matches search criteria then the item index is saved to ResultVar variable. The search succeeds if the item value contains Input value (matching is case sensitivity). For example, an array item "jim@InterCTX.com" matches "CTX" Input value.

ARRAY_FINDITEM_PARTIALMATCH_NOCASE
- searches for the specified value (text) in Param2 array (array variable). Param1 is an index to start searching from. Input is the text to search for. If an array item matches search criteria then the item index is saved to ResultVar variable. The search succeeds if the item value contains Input value - but matching is not case sensitive. For example, an array item "jim@InterCTX.com" matches "interctx" Input value.

ARRAY_SIZE
- returns the highest index with variable set.

IS_VAR_DEFINED
- returns 1 if the variable specified in Param2 is already defined. Otherwise it returns 0.

Param1
Parameter that depends on operation.

Param2
Parameter that depends on operation.

Param3
Parameter that depends on operation.

Example:

<#> This example converts text in clipboard to upper-case
<#>
<cmds>
<var_oper>(vClipboardText,"",GET_TEXT_FROM_CLIPBOARD,"","", "0")
<if_str>("vClipboardText!=_vStrEmpty")

<var_oper>(vClipboardText,"%vClipboardText%",STR_UPPER,"","", "0")
<clpput>("vClipboardText")
<msg>(-100,-100,"Text in clipboard is converted to uppercase.","Message",1)

<endif>


 <var_parse> : Parse Text (Variable Value)

This command parses input text (variable value). Parts of the input text are expected to be delimited by characters (space, comma, new line, etc.) defined as a command parameter. The parsed parts of the input text are saved in parameter variable (array). In addition, each parsed part can be trimmed using characters defined.

Syntax:

<var_parse>("Input", “Delimiters”, “Trim characters”, VariablePieces, VariableNumOfPiecese)

Input
Text (or variable containing text) to be parsed.

Delimiters
Characters used to delimit input text (for example, dot, comma, space new line, etc.).

Trim characters
Characters used to trim each parsed part of the input text.

VariablePieces
Variable (array) that receives each input text piece parsed.

VariableNumOfPieces
Variable that receives the number of pieces.

Example:

<#> This example shows how to use <var_parse> command
<#> The input text consisting from names delimited by comma
<#> will be parsed and each name will be shown in message box.
<cmds>
<var_parse>("Peter, Paul, John, Jim ",","," ",vName,vNumOfNames)
<begloop>(vNumOfNames)
<msg>(100,100,"vName[_vLoopCounter0]","Message",1)
<endloop>


 <varout> : Send Variable Value To Target Application

Sends (outputs) variable's value to the active window as a sequence of keystrokes or through the clipboard.

Syntax:

<varout>("Variable", HowToInsert)

Variable
Variable to send out.

HowToInsert
If 0, the variable content is send to the active window the way it is defined in program settings ("Options" dialog box - click "Tools/Options" menu command).
If 1, the variable value is send to the active window through the clipboard.
If 2, the variable value is send to the active window as a sequence of keyboard keystrokes.

Example:

<#> This macro demonstrates use of <varout> command
<#> The macro activates Notepad and writes a text in it.
<#>
<cmds>
<if_win>("Notepad","OPEN",0)
<actwin>("Notepad",0,0,"no")
<waitfor>("WIN","ACT","Notepad",5,0)
<if_win>("Notepad","ACT",0)
<varset>("vText=This is Notepad","")
<varout>("vText",0)
<endif>
<else>
<msg>(100,100,"Notepad is not running.","Message",1)
<endif>)


 <var_save> : Save Variable To File

Saves (persists) variable value to a file. The variable content can be later loaded again using <var_load> command. The same file can be used for multiple (unlimited number) variables because each variable has its own section within the file.

Syntax:

<var_save>("Variable", "File")

Variable
Variable to save value to file.

File
The file to save variable value to.

Example:

<#> This macro demonstrates use of <var_load> and <var_save> commands
<#>
<cmds>
<varset>("vName=John","")
<var_save>("vName","c:\_myvars.dat")
<varset>("vName=Michael","")
<var_load>("vName","c:\_myvars.dat")
<msg>(100,100,"vName","Message",1)


 <var_load> : Load Variable From File

Loads variable value from a file. (The value was previously saved using <var_save> command.)

Syntax:

<var_load>("Variable", "File")

Variable
Variable to load value from file.

File
The file created by <var_save> command that contains variable value.

Example:

<#> This macro demonstrates use of <var_load> and <var_save> commands
<#>
<cmds>
<varset>("vName=John","")
<var_save>("vName","c:\_myvars.dat")
<varset>("vName=Michael","")
<var_load>("vName","c:\_myvars.dat")
<msg>(100,100,"vName","Message",1)


<proc_def_begin> : Begin Of Procedure

This command defines begin of procedure. Procedure is a piece of macro code that can be called using <proc_call> command from other places within the macro. Procedure can contain any number of parameters. Procedures do not return any value but it is possible to pass results out of the procedure using reference parameters. Reference parameter, instead of containing value, contains name of the variable it references to. To tell the procedure that a parameter is reference to a variable, this syntax is used: &parParam3&. Such syntax means, that parParam3 (parParam3 is just example) holds the name of variable passed as a parameter in <proc_call> command. Example: Let's have <proc_def_begin>(P1, "parParam1","&parParam2&") and let's have procedure call <proc_call>(P1, "555", "vResult"). Now, any modification of Param2 (that is is done within the P1 procedure) is actually done on vResult variable since the parParam2 is not a variable that holds any value but it just references to vResult variable. It is not allowed to have reference variable and other (global) variable of the same name. This means, for example, that if there is "&vInput&" reference parameter then it is not possible to have other variable named "vInput"!
When getting actual value of the referenced variable, it is always necessary to enclose it to % since parParam2 gives you name of the variable it references to while %parParam2% gives the value stored.

If a procedure parameter starts with "par" prefix (for example, "parInputText") then the parameter is local only within the procedure and cannot be accessed out of the procedure. In addition, if a variable defined within a procedure starts with "lpv" (local procedure variable) prefix (for example, "lpvTemporaryVariable") then the variable is known and can be accessed only within the procedure. See more about variables and language rules here.
It is not allowed to define procedure within other procedure (embedded <proc_def_begin>). The procedure definition must be ended by <proc_def_end> command.
 See more in the example below.

Syntax:

<proc_def_begin>(ProcedureName, "parParam1", "parParam2", ...., parParamN")

ProcedureName
Unique name of the procedure. The name is used as a parameter in <proc_call> command to identify what procedure to call.

parParam1, parParam2,...,parParamN
Any number of parameters.

Example:

<#> This example shows how to use procedures
<cmds>
<proc_def_begin>(AddQuotes,"parStringInput", "&parStringOutput&")
<varset>("parStringOutput=%_vQuoteChar%%parStringInput%%_vQuoteChar%","")
<proc_def_end>

<proc_def_begin>(ConvertToUpper,"parStringInput","&parStringOutput&")
<var_oper>(parStringOutput,"%parStringInput%",STR_UPPER,"2","", "0")
<proc_def_end>

<varset>("vMyText=","Insert text to modify:")
<if_str>("_vCanceled==1")<exitmacro><endif>

<proc_call>(ConvertToUpper,"%vMyText%", "vMyText" )
<proc_call>(AddQuotes,"%vMyText%", "vMyText" )

<msg>(-100,-100,"%vMyText%","Message",1)


 <proc_call> : Call Procedure

This command allows to call procedures defined using <proc_def_begin> ... <proc_def_end> commands. When calling a procedure, it is always necessary to pass expected parameters (as they are defined in the <proc_def_begin> command). If a parameter is defined as a reference (see <proc_def_begin> help section for details) then it is necessary to use variable as the parameter (it is not possible to use a constant in this case).

Syntax:

<proc_call>(ProcedureName, "parParam1", "parParam2", ...., parParamN")

ProcedureName
Unique name of the procedure to call. It is expected that a procedure with this name is defined using <proc_def_begin> command.

parParam1, parParam2,...,parParamN
Any number of parameters.

Example:

<#> This example shows how to use procedures
<cmds>
<proc_def_begin>(AddQuotes,"parStringInput", "&parStringOutput&")
<varset>("parStringOutput=%_vQuoteChar%%parStringInput%%_vQuoteChar%","")
<proc_def_end>

<proc_def_begin>(ConvertToUpper,"parStringInput","&parStringOutput&")
<var_oper>(parStringOutput,"%parStringInput%",STR_UPPER,"2","", "0")
<proc_def_end>

<varset>("vMyText=","Insert text to modify:")
<if_str>("_vCanceled==1")<exitmacro><endif>

<proc_call>(ConvertToUpper,"%vMyText%", "vMyText" )
<proc_call>(AddQuotes,"%vMyText%", "vMyText" )

<msg>(-100,-100,"%vMyText%","Message",1)


 <-include-> : Include File Or Macro

This command allows a user to include (insert) other macro or (text) file to the macro. Before macro execution is started, the <-include-> is replaced by content defined in the command (macro or file). This command makes it possible to use procedures (<proc_call>, <proc_def_begin>) defined in external text (.mcr) files or in other macros.

Syntax:

<-include->("What")

What
This parameter can be one of these:
macro:ExistingMacroName
file:FullPathToExistingFile

Example:

<#> This example shows how to use <-include-> command
<cmds>
<-include->("file:c:\MyMacroLibrary\lib.mcr")
<proc_call>(VeryCommonTask,"1","2","3")


<if_str> : If (Compare Strings)

 <if> : If (Compare Strings and/or Numbers)

This command evaluates the input expression. If the expression is evaluated as a "true" then part of the macro between <if_...> and <endif> (or <else>) is executed. If the expression is evaluated as a "false" then part of the macro between <else> and <endif> (or after <endif> if <else> is not used) is executed.

Operands in the expression can be either numbers or strings.

Syntax:

<if_str>("Expression")

Expression
Expression can contain brackets () and these operators are available:
== (is equal)
!= (is not equal)
<=
<
>=
>
~= (contains substring)
_AND_
_OR_

Expression examples:
Var1==Var2
100<vNum+10
vText~=substring
(x>20) _AND_ (vText~=substring)

Example 1:

<#> This example shows how to use "if" command.
<#>
<cmds>
<varset>("vNum=","Type a number:")
<if>("100<(30+vNum)")
<msg>(-100,-100,"Yes, this is true: 100<30+%vNum%","Message",1,,0)
<else>
<msg>(-100,-100,"No, it is not true: 100<30+%vNum%","Message",1,,2)
<endif>

Example 2:

<#> This example shows how to use "if" command.
<#>
<cmds>
<varset>("vExpr=","Type an expression (example: 100 < 200):")
<if>("vExpr")
<msg>(-100,-100,"Yes, the expression is evaluated as 'TRUE'.","Message",1,,0)
<else>
<msg>(-100,-100,"No, the expression is evaluated as 'FALSE'.","Message",1,,2)
<endif>


 <if_str> : If (Compare Strings)

This command evaluates the input expression. If the expression is evaluated as a "true" then part of the macro between <if_...> and <endif> (or <else>) is executed. If the expression is evaluated as a "false" then part of the macro between <else> and <endif> (or after <endif> if <else> is not used) is executed.

All operands in the expression are treated as strings (unlike <if_num> that treat all operands as numbers).

Syntax:

<if_str>("Expression")

Expression
Expression can contain brackets () and these operators are available:
== (is equal)
!= (is not equal)
<=
<
>=
>
~= (contains substring)
_AND_
_OR_

Expression examples:
Var1==Var2
str1<str2
vText~=substring
(str1<str2) _AND_ (vText~=substring)

Example:

<#> This example shows how to use "if_str" command.
<cmds>
<varset>("v=","Type 'Hello' here")
<if_str>("v==Hello")
<msg>(-100,-100,"Yes! You really typed 'Hello'.","Message",1,,0)
<else>
<msg>(-100,-100,"No, you have typed something different....","Message",1,,2)
<endif>


 <if_num> : If (Compare Numbers)

This command evaluates the input expression. If the expression is evaluated as a "true" then part of the macro between <if_...> and <endif> (or <else>) is executed. If the expression is evaluated as a "false" then part of the macro between <else> and <endif> (or after <endif> if <else> is not used) is executed.

All operands in the expression are treated as numbers (unlike <if_str> that treat all operands as strings).

Syntax:

<if_num>("Expression")

Expression
Expression can contain brackets () and these operators are available:
== (is equal)
!= (is not equal)
<=
<
>=
>
_AND_
_OR_

Expression examples:
Var1==Var2
100<vNum
(x>y) _OR_ (x+10<y)

Example:

<#> This example shows how to use "if_num" command.
<#>
<cmds>
<varset>("vNum=","Insert number smaller than 10:")
<if_num>("vNum>10")
<msg>(-100,-100,"No, this number is bigger than 10!","Message",1,,2)
<else>
<msg>(-100,-100,"Yes, you have passed this test!","Message",1,,0)
<endif>


 <if_win> : If Window...

Window-related condition.

Syntax:

<if_win>("WinTitle", "Condition", Match)

WinTitle
Title of the window to check against the Condition.

Condition
Condition can be one from the following:
"OPEN" - the <if_win> statement is true if window with the WinTitle is opened (exist).
"CLOSE" - the <if_win> statement is true if window with the WinTitle is not opened (no more exist).
"ACT" - the <if_win> statement is true if window with the WinTitle is active (top most, receives keyboard events).
"NOACT" - the <if_win> statement is true if window with the WinTitle is not active (not receives keyboard events).

Match
If 1, WinTitle must exactly match a window title.
If 0, WinTitle can be a substring of a window title.

Example:

<#> This macro shows how to use <if_win> command
<#>
<cmds>
<if_win>("notepad","OPEN",0)
<if_win>("Notepad","ACT",0)
<msg>(100,100,"Notepad is opened and active.","Message",1)
<else>
<msg>(100,100,"Notepad is opened but not active.","Message",1)
<endif>
<else>
<msg>(100,100,"Notepad is not opened.","Message",1)
<endif>


 <if_file> : If File...

File-related condition.

Syntax:

<if_file>("File", "Condition", "Operand")

File
Full path to the file to check against the Condition.

Condition
Condition can be one from the following:
"EXIST" - the <if_file> statement is true if the file exist.
"NOTEXIST" - the <if_file> statement is true if the file does not exist.
"BIGGER" - the <if_file> statement is true if the file size is bigger than the Operand.
"SMALLER" - the <if_file> statement is true if the file size is smaller than the Operand.

Operand
Takes effect only if Condition is "BIGGER" or "SMALLER".

Example:

<#> This macro shows how to use if-file condition
<#>
<cmds>
<if_file>("winmine.exe","EXIST","0")
<msg>(100,100,"Minesweeper game is installed.","Message",1)
<else>
<msg>(100,100,"Minesweeper game is NOT installed.","Message",1)
<endif>


 <if_dir> : If Directory (Folder) ...

Directory (folder) - related condition.

Syntax:

<if_dir>("Directory", "Condition", "Reserved")

Directory
Full path to the directory to check against the Condition.

Condition
Condition can be one from the following:
"EXIST" - the <if_dir> statement is true if the directory exist.
"NOTEXIST" - the <if_dir> statement is true if the directory does not exist.

Reserved
Must be empty string.

Example:

<#> This macro shows how to use if-dir condition
<#>
<cmds>
<if_dir>("c:\windows","EXIST","")
<msg>(100,100,"'c:\windows' exist.","Message",1)
<else>
<msg>(100,100,"'c:\windows' NOT exist.","Message",1)
<endif>


 <if_clp> : If Clipboard...

Clipboard-related condition.

Syntax:

<if_clp>("Condition", "Reserved")

Condition
Condition can be one from the following:
"EMPTY" - the <if_clp> statement is true if the clipboard is empty.
"SET" - the <if_clp> statement is true if the clipboard contains some data.

Reserved
Must be empty string.

Example:

<#> This macro shows how to use if-clp condition
<#>
<cmds>
<if_clp>("EMPTY","")
<msg>(100,100,"Clipboard is empty.","Message",1)
<else>
<varset>("vEmpty=YES/NO","Clipboard is not empty. Do you want to empty it now?")
<if_str>("vEmpty==YES")
<clpempty>
<endif>
<endif>


 <if_key> : If Key Or Mouse Button...

This command is used to determine whether a keyboard key (mouse button) is pressed or not.

Syntax:

<if_key>("Key identifier", "Key state ")

Key identifier
a,b,c,d, etc. key or a special key syntax like <F1>, <shift>, etc or KC:XXX (key code, for example KC:27). The KC:XXX is a key code number of a key on keyboard. The KC:XXX is showing in the main window in lower right area as keys are being hit. This way the user can know what is key code of each keyboard key.

As for the mouse buttons, one of the following identifier can be used:
<mlbd> - left mouse button
<mmbd> - middle mouse button
<mrbd> - right mouse button

Key state
Can be either DOWN or UP

Example:

<#> If-keys command example
<cmds>
<msg>(-100,-100,"Press 'F12' key to continue...","Message",0)
<keys_block>
<label>("loop")
<if_key>("<F12>","DOWN")
<exitmacro>
<endif>
<goto>("loop")


<if_process> : If Process Exist

This command checks whether defined process is running or not.

Syntax:

<if_process> (ExecutableName, Condition)

ExecutableName
Name of the executable file to kill. Example: notepad.exe

Condition
Must be EXIST.

Example:

<#> This example checks whether Notepad is running
<#>
<cmds>
<if_process>(notepad.exe,EXIST)
<msg>(-100,-100,"Notepad is running.","Message",1)
<else>
<msg>(-100,-100,"Notepad is NOT running.","Message",1)
<endif>


<varout> : Send Variable Value To Target Application

<for> : Starts "For" Loop (Conditional)

This command begins loop that allows macro developer to repeat part of macro (between <for> and <for_end> commands) multiple times. Each <for> command must be followed by <for_end> command. Each loop, a condition defined in <for> command is evaluated and if it is evaluated as "not true" then the <for> loop is ended. It is possible to end the <for> loop also using <for_break> command.

Syntax:

<for>("Counter Init", "Condition", "Counter Increase")

Counter Init
Counter variable initialization in form "Variable = value". Example: "VarCounter = 1".

Condition
Condition in the same form as in <if_...> command. Example: "VarCounter < 100".

Counter Increase
The value that defines how to increase the counter value each loop. Example: "1".

Example:

<#> This macro shows how to use "for" loop.
<#> There are two embedded "for" loops.
<#>
<cmds>

<for>("vX=1","vX < 5","1")

<for>("vY=1","vY < 5","1")

<msg>(-100,-100,"Counters [x,y] = [%vX%,%vY%]

Press F10' to exit this macro.","For Counters",0,0,0)

<me_error_nodisplay> <waitfor>("KEY","PRESS","<F10>",1,0)<me_error_clear><me_error_display>

<if_key>("<F10>","DOWN")
<exitmacro>
<endif>

<for_end>

<for_end>


<varout> : Send Variable Value To Target Application

<for_end> : Ends a "For" Loop Block

See also <for> command.

Syntax:

<for_end>

Example:

<#> This macro shows how to use "for" loop.
<#> There are two embedded "for" loops.
<#>
<cmds>

<for>("vX=1","vX < 5","1")

<for>("vY=1","vY < 5","1")

<msg>(-100,-100,"Counters [x,y] = [%vX%,%vY%]

Press 'F10' to exit this macro.","For Counters",0,0,0)

<me_error_nodisplay> <waitfor>("KEY","PRESS","<F10>",1,0)<me_error_clear><me_error_display>

<if_key>("<F10>","DOWN")
<exitmacro>
<endif>

<for_end>

<for_end>


<varout> : Send Variable Value To Target Application

<for_break> : Breaks a "For" Loop Execution

This command breaks a <for> loop execution and cause that the macro continues execution after <for_end> command of the broken <for> loop. See also <for> command.

Syntax:

<for_end>

Example:

<#> This macro shows how to use "for" loop.
<#> There are two embedded "for" loops.
<#>
<cmds>

<for>("vX=1","vX < 5","1")

<for>("vY=1","vY < 50","1")

<msg>(-100,-100,"Counters [x,y] = [%vX%,%vY%]

Press 'F10' to break the y-loop.","For Counters",0,0,0)

<me_error_nodisplay> <waitfor>("KEY","PRESS","<F10>",1,0)<me_error_clear><me_error_display>

<if_key>("<F10>","DOWN")
<for_break>
<endif>

<for_end>

<for_end>


 <goto> : Go To

Jump to other point (defined by <label>) in the macro and continue macro execution from this point.

Syntax:

<goto>("Label")

Label
Name of the point to jump to. For example, <goto>("Section1") jumps to the point <label>("Section1") in the same macro.

Example:

<#> This macro shows how to use 'goto' and 'label' commands
<#>
<cmds>
<varset>("vNumOfLoops=","Insert number of loops (less than 25)")
<if_num>("vNumOfLoops>=25")
<msg>(100,100,"Too many loops spcified.","Message",1)
<goto>("END")
<endif>
<begloop>(vNumOfLoops)
<msg>(-100,-100,"_vLoopCounter","Loop",0)
<wx>(200)
<endloop>

<label>("END")


 <label> : Label

Specifies the point in the macro where you can jump using <goto> command.

Syntax:

<label>("Label")

Label
Name of the point to jump to. For example, <goto>("Section1") jumps to the point <label>("Section1") in the same macro.

Example:

<#> This macro shows how to use 'goto' and 'label' commands
<#>
<cmds>
<begloop>(0)
<if_num>("_vLoopCounter>5")
<msg>(100,100,"Too many loops...","Message",1)
<goto>("END")
<endif>
<endloop>

<msg>(100,100,"OK","Message",1)
<label>("END")


 <begloop> :Begin Loop

Begins loop. The loop allows to repeat some part of macro many times. Each <begloop> commands must be followed by <endloop>.

Syntax:

<begloop>(Repeat)

Repeat
The number of repeats. Can be one of these options:
Repeat > 0 - The Repeat is the actual number of loops to be performed.
Repeat = 0 - The user specifies the number of repeats in the runtime.
Repeat = -1 - The user is asked each loop to continue or stop repeating.

Example:

<#> This example shows how to use loop commands
<#>
<cmds>
<varset>("vNum=","How many Notepads you want to open ?")
<begloop>(vNum)
<execappex>("notepad.exe","","",0,0)
<endloop>


 <pause> : Pause For User's Input

Stops (pauses) macro execution until user presses 'Enter' key.

Syntax:

<pause>

Example:

<#> This macro shows how to use 'pause' command
<#>
<cmds>
<msg>(100,100,"Start Notepad and press 'Enter' key.","Message",0)
<pause>
<msgoff>
<actwin>("notepad",0,0,"no")
<keys>Dear Mr. <msg>(100,100,"Insert the customer name and press 'Enter' key.","Message",0)<pause><msgoff>,

we are writing you this letter because...


<wx> : Wait X Miliseconds

 <wx> : Wait X Milliseconds

Wait for X milliseconds. The behavior of this command depends on the macro playback speed that can user specify for each macro in the "Item Properties" dialog box.

Syntax:

<wx>(Time)

Time
Time to wait in milliseconds.

Example:

<#> This macro shows how to use 'wx' command
<#>
<cmds>
<varset>("vTime=","How many seconds to wait ?")
<var_oper>(vTime,"%vTime%*1000",CALC_EXPRESSION,"0","", "0")
<wx>(vTime)
<msg>(100,100,"Specified time is out.","Message",1)


 <waitfor> : Wait For (Window, Clipboard, Key, Mouse, Web Page)

Wait for a special event (window, clipboard, key, mouse) to occur.

Syntax:

<waitfor>("Object", "Event", "Param", TimeOut, Exact)

Object
Can be one of these:
"WIN" - a window related event is expected
"CLIP" - a clipboard related event is expected
"KEY" - a specific key press is expected
"MOUSE" - a mouse click is expected
"IMAGE_ON_SCREEN_EXACT" - an image on screen will appear/disappear, image must be exactly the same
"IMAGE_ON_SCREEN_TOLERANT" - an image on screen will appear/disappear, image does not has to be exactly the same - some level of tolerance is allowed

Event
These events are supported for particular Object:
"WIN" :
- "OPEN" - wait until the window specified by Param is opened.
- "CLOSE" - wait until the window specified by Param is closed.
- "ACT" - wait until the window specified by Param is activated.
- "NOACT" - wait until the window specified by Param is deactivated.
"CLIP" :
- "EMPTY" - wait until the clipboard is emptied.
- "SET" - wait until some data are put into the clipboard.
"KEY" :
- "" (key is pressed) - wait until some of the keys specified by Param is pressed.
"MOUSE" :
- "" (mouse click) - wait until mouse click specified by Param appears.
"IMAGE_ON_SCREEN_EXACT"
- "APPEAR" - wait until the image appears on screens
- "DISAPPEAR" - wait until the image disappears from screens
"IMAGE_ON_SCREEN_TOLERANT"
- "APPEAR" - wait until the image appears on screens
- "DISAPPEAR" - wait until the image disappears from screens

Param
Has this meaning depending on the Object:
"WIN" - window title
"CLIP" - not used
"KEY" - can be one or more keys. For example, if Param is "abc<F6>KC:27<alt>" the <waitfor> waits until either a or b or c or F6 or ESC or Alt key is pressed. The KC:XXX is a key code number of a key on keyboard. The KC:XXX is showing in the main window in lower right area as keys are being hit. This way the user can know what is key code of each keyboard key.
"MOUSE" - can be one of these:
<mlbu> - left mouse button
<mmbu> - middle mouse button
<mrbu> - right mouse button
"IMAGE_ON_SCREEN_EXACT" - file path to the .bmp file with the image.
"IMAGE_ON_SCREEN_TOLERANT" - file path to the .bmp file with the image.

TimeOut
Timeout in seconds. If 0, the <waitfor> never timeouts. If the command timeouts then _vErr system variable is set. This allows to handle such a case in the macro code.

Exact
Used only for "WIN" Object. If 1, the window title must exactly match the Param. If 0, the Param can be a substring of a window title.

Example:

<#> This macro shows how to use 'waitfor' command
<#>
<cmds>
<msg>(100,100,"Press 'Ctrl' key to continue this macro.","Message",0)
<waitfor>("KEY","","<ctrl>",5,0)
<msgoff>
<msg>(100,100,"Press left mouse button to continue this macro.","Message",0)
<waitfor>("MOUSE","","<mlbu>",5,0)
<msgoff>
<msg>(100,100,"Macro is finished.","Message",1)


 <cmds> : Execute ONLY Commands
<keys> : Execute ALL Macro Text

The <cmds> command changes the macro interpretation. The part of the macro that follows <cmds> is interpreted so that only commands are executed and all the other text (keys) is ignored. This allows to nicely format macro consisting only from commands.

The <keys> causes that all the text (keys) - including new line as an "Enter" key - is interpreted.

Syntax:

<cmds>
<keys>

Example:

<#> This macro shows how to use 'cmds'
<#>
<cmds>

<label>("lbl_Again")
<msg>(100,100,"Starting Notepad ...","Message",0)
<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","OPEN","Notepad",15,0)
<msgoff>

<keys>Hello,

this macro just demonstrates 'cmds/keys' commands.
<cmds>

<varset>("vAgain=YES/NO","Do you want to run this macro again ?")
<if_str>("vAgain==YES")
<goto>("lbl_Again")
<endif>


 <faston> : Send Keystrokes Fast

Specifies that all the keystrokes are send as fast as possible to the destination application. In some cases, the application receiving the keystrokes is not able to respond to all of them in time and some maybe lost (it means that the macro is not functioning properly).

Syntax:

<faston>

Example:

<#> This macro shows how to use 'faston' command.
<#>
<execappex>("notepad.exe","","",0,0)<waitfor>("WIN","ACT","Notepad",10,0)<fastoff>This text is being inserted slower...
<faston>...and this text is being inserted faster.


 <me_error_nodisplay> : Do Not Display Errors

If an error occurs during macro execution, by default, error message is shown to user. This command prevents the message from showing.

<me_error_display> : Display a Message When an Error Occurs
To cause the message is displayed when an error occurs use <me_error_display> command.

<me_error_clear> : Clear Error
Errors that occur are saved in _vErr system variable. This variable can be used to check whether a macro command failed or not. To clear this variable use <me_error_clerar> command.

Syntax:

<me_error_nodisplay>
<me_error_display>
<me_error_clear>

Example:

<#> This macro shows how to use 'me_error_nodisplay'
<#>
<cmds>
<me_error_nodisplay>
<#> Try to get file size of non-existing file. Error
<#> occurs but default (automatic) error message is replaced by the user defined one.
<fileinfo>("c:\notexistingfile.none","SIZE","v1")
<if_str>("_vErr != NO")
<msg>(-100,-100,"Error! This is custom error message. The automatic error message was disabled by 'me_err_nodisplay' command.","Message",1)
<endif>


 <-dbp-> : Debug Break Point

Debugger build in this program allows user to go through macro step-by-step. It is also possible to run macro in normal speed until it reaches <-dbp-> debug break point (there can be many of them within macro). The debug break point doesn’t affect macro execution any way.

Syntax:

<-dbp->

Example:

<#> This macro shows how to use 'debug break point'
<#>
<cmds>
<msg>(-100,-100,"Message 1","Message",1)
<msg>(-100,-100,"Message 2","Message",1)
<-dbp->
<msg>(-100,-100,"Message 3","Message",1)


 <exitmacro> : Exit Macro

This command stops macro execution. If the macro is called using <run> command from other macro, also the calling macro is stopped. The <exitmacro_soft> causes only the current macro execution is stopped - if the macro is called using <run> command the calling macro continues execution.

Syntax:

<exitmacro>
<exitmacro_soft>

Example:

<#> This macro shows how to use <exitmacro> command
<cmds>
<msg>(-100,-100,"Do you want to exit macro execution now?","Message",2)
<if_str>("_vMsgButton==YES")
<exitmacro>
<endif>
<msg>(-100,-100,"OK, macro execution continues then...","Message",1)


 <msg> : Show Message

Shows message window.

Syntax:

<msg>(Xpos, Ypos, "MessageText", "Title", OKButton, Timeout, Icon type, AlwaysOnTop)

Xpos
X-coordinate of the message window position. If Xpos is –100 and Ypos is also –100, the message window is centered on the screen.

Ypos
Y-coordinate of the message window position. If Xpos is –100 and Ypos is also –100, the message window is centered on the screen.

MessageText
Text you want to display in the message window.

Title
Title of the message window.

OKButton
Can be one of these values:
0 - OK button is not shown. The <msgoff> command must be used to close the message window.
1 - OK button is shown in the message window.
2 - Yes and No buttons are shown in the message window. If user clicks Yes button, the _vMsgButton system variable contains YES. Otherwise it contains NO.

Timeout
The timeout in seconds. The message box is automatically closed after this timeout. If set to '0' then the message will not timeout.

Icon type
An icon that shows in the message box:
0 - Information icon
1 - Question icon
2 - Exclamation icon

AlwaysOnTop
If set to "1", the message window is always showing on top of other windows and cannot be overlapped (so that it stays always visible to user). If this parameter is set to "0" then the message window can be overlapped by other windows.

Example:

<#> This macro will show various use of message window
<#>
<cmds>

<msg>(-100,-100,"This is an information message....","Message",1,0,0)

<msg>(-100,-100,"...and this message has 10 seconds timeout....","Message",1,10,0)

<msg>(-100,-100,"...and you can also answer questions....","Message",2,0,1)
<if>("_vMsgButton==YES")
<msg>(-100,-100,"You clicked YES!","Message",1,0,0)
<else>
<msg>(-100,-100,"You clicked NO","Message",1,0,2)
<endif>

<msg>(-100,-100,"And this message without a button will close if you press 'F10' key.","Message",0,0,0)
<waitfor>("KEY","PRESS","<F10>",15,0)
<msgoff>


 <msgoff> : Close Message

This command closes message window with no OK or Yes/No buttons. If a <msg> with no button is not closed by <msgoff> command and <msg> command is called again, the title and text of currently opened message box is updated and message box window is resized (if necessary).

Syntax:

<msgoff>

Example:

<#> This macro will display message window and closes it after 5 seconds
<#>
<cmds>
<msg>(-100,-100,"Wait for 5 seconds...","Message",0)
<wx>(5000)
<msgoff>


 <macromenu> : Macro Menu

This command shows a menu consisting from (enabled) macros found in the defined folder. Clicking on a menu item (macro) will cause that the macro is started.

Syntax:

<macromenu>(Xpos, Ypos, "GroupName", Options)

Xpos
X-coordinate of the menu position. If Xpos is –1 and Ypos is also –1, the menu appears on mouse cursor position.

Ypos
Y-coordinate of the menu position. If Xpos is –1 and Ypos is also –1, the menu appears on mouse cursor position.

GroupName
Macros (name of the macro) from this group will show in the menu.

Options
Can be one of these values:
2 - default behavior.
3 - a prefix (1-9, a-z) is added before each macro name in the menu. This allows user to run macro by pressing the prefix key.
The macro menu is by default sorted alphabetically. If the +4 are added to the options above (so that the options number will be either 6 or 7) then the macro menu is to sorted based on the "Order" column in the macro listing in main window.

Example:

<#> This macro will open menu with macros from
<#> 'New Macro Group' group
<cmds>
<macromenu>(-1,-1,"New Macro Group",3)


 <listbox> : Macro Selection Box

This command displays list of macros a user can choose from. The selected macro is executed and the control is returned to the calling macro again. If user clicks "Cancel" button the _vCanceled system variable is set to 1 (otherwise it is 0) to allow macro designer to distinguish between situations when OK or Cancel button was clicked.

Syntax:

<listbox>("WinTitle", "Macro1-Name", "Macro1-Description, "Macro2-Name", "Macro2-Description"...)

WinTitle
Title of the window that appears.

Macro1-Name
Name of the macro to run (first item in the selection box).

Macro1-Description
Description of the macro to run (first item in the selection box).

Macro2-Name
Name of the macro to run (second item in the selection box).

Macro2-Description
Description of the macro to run (second item in the selection box).

Example:

<#> This macro shows you how to use <listbox> command
<#>
<cmds>
<listbox>("Select your option","_item1","1. Item","_item2","2. Item","_item3","3. Item")


 <menu_additem> : Menu - Add Item

This command adds new item to menu that user later opens on the screen using <menu_show> command.

Syntax:

<menu_additem>("ItemName","ItemId", "Icon File", Icon Index)

ItemName
Name of the item as it shows in the menu. To add submenu items insert ‘.’ (dot) to begin of the item name. To specify end of the submenu, insert just ‘.’ Item. To underline a specific character within the item, insert ‘&’ character right before it.

ItemId
This is optional parameter. If it is supplied, the <menushow> command returns this ItemId rather than ItemName.

Icon File
File containing an icon (.exe, .dll, .ico).

Icon Index
Position of the icon in the file.

Example:

<#> This macro will show how to use 'menu_additem'
<#> and 'menu_show' commands
<cmds>
<menu_additem>("Item 1","","shell32.dll",3)
<menu_additem>("Item 2","","shell32.dll",4)
<menu_additem>("Item 3","","shell32.dll",5)
<menu_additem>(".Item 1 - 1","","shell32.dll",6)
<menu_additem>(".Item 1 - 2","","shell32.dll",7)
<menu_additem>(".Item 1 - 3","","shell32.dll",8)
<menu_additem>(".Item 1 - 4","","shell32.dll",9)
<menu_additem>(".")
<menu_show>(-1,-1,vItem,1,1)
<if_str>("vItem != NO")
<msg>(-100,-100,"Selected item is: %vItem%","Message",1)
<endif>


 <menu_show> : Menu - Show

Opens menu that contains items previously added by <menu_additem> command.

Syntax:

<menu_show>(Xpos, Ypos, Variable, RetValueOption, ItemPrefix)

Xpos
X-coordinate of the menu position. If Xpos is –1 and Ypos is also –1, the menu appears on mouse cursor position.

Ypos
Y-coordinate of the menu position. If Xpos is –1 and Ypos is also –1, the menu appears on mouse cursor position.

Variable
This variable receives the menu item user clicks on. If no menu item is selected, the variable receives “NO” value.

ReturnValueOption
If this parameter is 1, the Variable receives the item name as it was added using <menu_additem> command. If this parameter is 0, the Variable receives the order number of the item clicked.

Options
Can be one of these values:
0 - default behavior.
1 - a prefix (1-9, a-z) is added before each macro name in the menu. This allows user to run macro by pressing the prefix key.

Example:

<#> This macro will show how to use 'menu_additem'
<#> and 'menu_show' commands
<cmds>
<menu_additem>("White")
<menu_additem>("Gray")
<menu_additem>("Black")
<menu_additem>(".RGB")
<menu_additem>(".Red")
<menu_additem>(".Green")
<menu_additem>(".Blue")
<menu_additem>(".")

<menu_show>(-1,-1,vColor,1,1)

<if_str>("vColor != NO")
<msg>(-100,-100,"Selected item is: %vColor%","Message",1)
<endif>


<form_item> : Add Form Item

Defines a form item.

Syntax:

<form_item>("FormID", "ItemLabel", "ItemType", "ItemDefValue", "ItemVariable")

FormID
A text identifier of the form (for example, "FM1"). All the items of the same form must have the same identifier.

ItemLabel
The label that appears above the control in the form window.

ItemType
Item type. Can be one of these:
"LIST" - list (combo) box selection
"EDIT" - edit control (single line)
"CHECK" - check box button
"LINE" - static line
"TEXT" - static text
“BUTTON” - button
“PWD” - password input box
“RADIO” - radio button

ItemDefValue
Defines default the value (the value that initially appears in the form window). Check button (CHECK) and radio button (RADIO) have YES or NO values. Use YES or NO also as default value.

Item Variable
Variable that receives the data (value) the user enters. Check button (CHECK) and radio button (RADIO) have YES or NO values.

Example 1 (edit box, check button, combo box):

<#> This example shows how to use form commands
<#>
<cmds>
<form_item>("FM1","This is a simple calculator for: + - * /","TEXT","0","")
<form_item>("FM1","","LINE","0","")
<form_item>("FM1","Operand 1:","EDIT","0","vOper1")
<form_item>("FM1","Operation:","LIST","Plus|Minus|Multiply|Divide","vOperation")
<form_item>("FM1","Operand 2:","EDIT","0","vOper2")
<form_item>("FM1","","LINE","0","")
<form_item>("FM1","Continue ?","CHECK","YES","vAgain")
<label>("lbl_Again")

<form_show>("FM1","Simple Calculator","calc.exe",0)
<if_str>("_vCanceled==1") <exitmacro> <endif>

<if_str>("vOperation==Plus")
<varchng>("vOper1","+","vOper2")
<endif>
<if_str>("vOperation==Minus")
<varchng>("vOper1","-","vOper2")
<endif>
<if_str>("vOperation==Multiply")
<varchng>("vOper1","*","vOper2")
<endif>
<if_str>("vOperation==Divide")
<varchng>("vOper1","/","vOper2")
<endif>
<msg>(-100,-100,"vOper1","The result is:",1,,0)
<if_str>("vAgain==YES")
<goto>("lbl_Again")
<endif>

Example 2 (radio buttons):

<#> This example shows how to use radio buttons
<#>
<cmds>
<form_item>("FM1","Radio buttons:","TEXT","0","")
<form_item>("FM1","","LINE","0","")
<form_item>("FM1","Option 1","RADIO","NO","vOption[1]")
<form_item>("FM1","Option 2","RADIO","NO","vOption[2]")
<form_item>("FM1","Option 3","RADIO","NO","vOption[3]")
<form_item>("FM1","Option 4","RADIO","YES","vOption[4]")
<form_item>("FM1","Option 5","RADIO","NO","vOption[5]")

<form_show>("FM1","Radio button test","shell32.dll",23,,0,,)

<for>("i=1","i<6","1")

<if>("vOption[i]==YES")
<msg>(-100,-100,"You have selected Option %i%.","Message",1,0,0)
<for_break>
<endif>

<for_end>


<form_show> : Show Form

Shows the form with items previously defined by <form_item> commands. If the user clicks the "Cancel" button, the _vCanceled system variable is set to 1 (otherwise it is 0) to allow the macro designer to distinguish between situations when OK or Cancel button was clicked.

Syntax:

<form_show>("FormID", "WinTitle", "IconFile", IconInx, FromWidth, RemoveItemsOnFormClose, X Position, Y Position, ShowOkCancel)

FormID
A text identifier of the form (for example, "FM1"). All the items of the same form must have the same identifier.

WinTitle
The title of the form window.

IconFile
The full path to the file with the icon desired.

IconInx
Index of the icon within the IconFile.

FormWidth
Width of the form window in pixels. If left empty, the default value is used.

RemoveItemsOnFormClose
If set to 1, all form items are removed after the form is closed. It is necessary to call <form_item> commands before the same form is to be shown again (next <form_show> call). This allows to dynamically change the content of the same form when used multiple times in the macro. If the option is 0, the form items remain attached to the form.

X Position
X-coordinate of the form position on the computer screen. If not supplied, the form is centered.

Y Position
Y-coordinate of the form position on the computer screen. If not supplied, the form is centered.

ShowOkCancel
If this parameter is set to "1" then "OK" and "Cancel" buttons are automatically displayed in the form. If this parameter is set to "0" then "OK" and "Cancel" buttons are not showing in the form window and it contains only controls that are added by <form_item> command.

Example 1 (edit box, check button, combo box):

<#> This example shows how to use form commands
<#>
<cmds>
<form_item>("FM1","This is a simple calculator for: + - * /","TEXT","0","")
<form_item>("FM1","","LINE","0","")
<form_item>("FM1","Operand 1:","EDIT","0","vOper1")
<form_item>("FM1","Operation:","LIST","Plus|Minus|Multiply|Divide","vOperation")
<form_item>("FM1","Operand 2:","EDIT","0","vOper2")
<form_item>("FM1","","LINE","0","")
<form_item>("FM1","Continue ?","CHECK","YES","vAgain")
<label>("lbl_Again")

<form_show>("FM1","Simple Calculator","calc.exe",0)
<if_str>("_vCanceled==1") <exitmacro> <endif>

<if_str>("vOperation==Plus")
<varchng>("vOper1","+","vOper2")
<endif>
<if_str>("vOperation==Minus")
<varchng>("vOper1","-","vOper2")
<endif>
<if_str>("vOperation==Multiply")
<varchng>("vOper1","*","vOper2")
<endif>
<if_str>("vOperation==Divide")
<varchng>("vOper1","/","vOper2")
<endif>
<msg>(-100,-100,"vOper1","The result is:",1,,0)
<if_str>("vAgain==YES")
<goto>("lbl_Again")
<endif>

Example 2 (radio buttons):

<#> This example shows how to use radio buttons
<#>
<cmds>
<form_item>("FM1","Radio buttons:","TEXT","0","")
<form_item>("FM1","","LINE","0","")
<form_item>("FM1","Option 1","RADIO","NO","vOption[1]")
<form_item>("FM1","Option 2","RADIO","NO","vOption[2]")
<form_item>("FM1","Option 3","RADIO","NO","vOption[3]")
<form_item>("FM1","Option 4","RADIO","YES","vOption[4]")
<form_item>("FM1","Option 5","RADIO","NO","vOption[5]")

<form_show>("FM1","Radio button test","shell32.dll",23,,0,,)

<for>("i=1","i<6","1")

<if>("vOption[i]==YES")
<msg>(-100,-100,"You have selected Option %i%.","Message",1,0,0)
<for_break>
<endif>

<for_end>


<varout> : Send Variable Value To Target Application

 <file_encryption> : Encrypt/Decrypt a File

This command encrypts/decrypts a single file.

Syntax:

<file_encryption>("Input File", "Output File", Encryption/Decryption, BitStrength, "Password")

Input File
Full path to a file that is to be encrypted/decrypted. Example: c:\temp\myPrivateInfo.txt.

Output File
Full path to a file that is created as a result of the encryption/decryption of the "Input File". Example: c:\temp\myPrivateInfo.txt.aes.

Encryption/Decryption
This parameter can be one of these:
ENCRYPT_AES - the input file is encrypted using AES.
DECRYPT_AES - the input file (previously encrypted using ENCRYPT_AES) is decrypted.

BitStrength
Strength of the encryption. These values are supported: 128, 192, 256.

Password
User defined password that is used to encrypt/decrypt the input file. A file encrypted by a password can be successfully decrypted again only if the same password is used.

Example 1:

<#> This simple example shows how to encrypt/decrypt file.
<#>
<cmds>

<#> Create folder for sample files
<dircreate>("c:\temp\file_encryption_sample",0)

<#> Create sample file
<data_save>("This is a sample file.","c:\temp\file_encryption_sample\1.file_original.txt","")

<#> Now encrypt the file...
<file_encryption>("c:\temp\file_encryption_sample\1.file_original.txt","c:\temp\file_encryption_sample\2.file_encrypted.txt",ENCRYPT_AES,128,"nyrangers")

<#> ...and decrypt again
<file_encryption>("c:\temp\file_encryption_sample\2.file_encrypted.txt","c:\temp\file_encryption_sample\3.file_decrypted.txt",DECRYPT_AES,128,"nyrangers")

<#> Open folder to see the results
<diropen>("c:\temp\file_encryption_sample",0)

Example 2:

<#> This is more complex example that shows how to encrypt/decrypt file.
<#> The example also shows how to implement a dialog for typing password.
<cmds>

<#> Create folder for sample files
<dircreate>("c:\temp\file_encryption_sample",0)

<#> Create sample file
<data_save>("This is a sample file.","c:\temp\file_encryption_sample\1.file_original.txt","")

<#> Open folder to see the results
<diropen>("c:\temp\file_encryption_sample",0)

<proc_call>(procEnterPassword,"File Encryption Password","vPassword")

<if_str>("vPassword!=_vStrEmpty")

<#> Now encrypt the file...
<file_encryption>("c:\temp\file_encryption_sample\1.file_original.txt","c:\temp\file_encryption_sample\2.file_encrypted.txt",ENCRYPT_AES,128,"%vPassword%")

<proc_call>(procEnterPassword,"The Same File Encryption Password to Decrypt File","vPassword")

<if_str>("vPassword!=_vStrEmpty")

<#> ...and decrypt again
<file_encryption>("c:\temp\file_encryption_sample\2.file_encrypted.txt","c:\temp\file_encryption_sample\3.file_decrypted.txt",DECRYPT_AES,128,"%vPassword%")

<endif>

<endif>

<#> Password procedure
<#>---------------------------------------------------------------------------------------
<proc_def_begin>(procEnterPassword,"parTitle","&parPassword&")

<form_item>("formPWD","Type password:","PWD","","parPassword")
<form_show>("formPWD","%parTitle%","shell32.dll",0,,1,,)

<proc_def_end>
<#>---------------------------------------------------------------------------------------


<filecreate> : Create File

Creates a new empty file.

Syntax:

<filecreate>("File", Reserved)

File
Full path to the file to create (e.g., "c:\mydocuments\empty.doc"). Can be a static text or variable containing text.

Reserved
Must be 0.

Example:

<#> This example creates new empty file c:\newfile.txt
<#>
<cmds>
<filecreate>("c:\newfile.txt",0)


<fileopen> : Open File

Opens file within the associated application.

Syntax:

<fileopen>("File", WindowState)

File
Full path to the file to open (e.g., "c:\mydocuments\letter1.doc"). Can be a static text or variable containing text.

WindowState
The state of the window:
0 – Normal
1 - Maximized
2 - Minimized
Can be a number or variable containing numeric value.

Example:

<#> This command opens file user selects
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1") <exitmacro> <endif>
<fileopen>("vFile",0)


<filecopy> : Copy File(s)

This command copies one or multiple file(s) to defined folder.

Syntax:

<filecopy>("FileSource", "FileDestination", SubDir, Reserved, Number of retries, Variable - Number of files copied, Variable - Number of failures, ")

FileSource
Full path to the file to copy (e.g., "c:\mydocuments\original.doc"). The file path can contain wildcard characters (*?). In such the case all the files matching the pattern are copied.
Can be a static text or variable containing text.

FileDestination
Full path to the new file (e.g., "c:\mydocuments\copy.doc"). If the FileSource contains wildcard characters the FileDestination must specify directory (e.g., "c:\mydocuments") where multiple files are copied.
Can be a static text or variable containing text.

SubDir
Takes effect only if the FileSource contains wildcard characters. If 1, files from all the sub directories are copied as well (if matching the pattern). If 0, files from sub directories are not copied.

Reserved
Must be 0.

Number of retries
If the copy fails the command can retry to copy later. This parameter tells the number of retries.

Variable - Number of files copied
This variable receives the number of files copied. This parameter can be left blank.

Variable - Number of failures
This variable receives the number of failures. This parameter can be left blank.

Errors report file
If a file cannot be copied then it is recorded in report file. This parameter can be left blank.

Parameters
Additional parameters:
"-pr" - show progress window
"-on" - overwrite file only if it is newer.

Example:

<#> This macro copies file you select to the file "c:\filecopy.txt"
<#>
<cmds>

<#> Select file to copy:
<var_oper>(vFile,"*.txt",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1")
<exitmacro>
<endif>

<#> Type destination folder:
<varset>("vDestinationFolder=","Type where to copy the selected file:")
<if_str>("_vCanceled==1")
<exitmacro>
<endif>

<#> Do not show error messages, we will handle errors programatically
<me_error_nodisplay>

<#> Copy file
<filecopy>("vFile","%vDestinationFolder%\filecopy.txt",1,0,3,vC opied,vFailed,"%TEMP%\filecopy_failreport.txt","-pr -on ")

<if>("vFailed<=0")
<msg>(-100,-100,"File was copied OK!","Message",1,0,0)
<else>
<msg>(-100,-100,"File copy FAILED!","Message",1,0,2)
<endif>

<me_error_clear>
<me_error_display>


<filemove> : Move File(s)

This command moves file(s).

Syntax:

<filemove>("FileSource", "FileDestination", SubDir, Reserved)

FileSource
Full path to the file to move (e.g., "c:\mydocuments\original.doc"). The file path can contain wildcard characters (*?). In such the case all the files matching the pattern are moved.
Can be a static text or variable containing text.

FileDestination
Full path to the new file (e.g., "c:\mydocuments\copy.doc"). If the FileSource contains wildcard characters the FileDestination must specify directory (e.g., "c:\mydocuments") where multiple files are moved.
Can be a static text or variable containing text.

SubDir
Takes effect only if the FileSource contains wildcard characters. If 1, files from all the sub directories are moved as well (if matching the pattern). If 0, files from sub directories are not moved.

Reserved
Must be 0.

Example:

<#> This macro moves file you select to "c:\temp\" folder
<#>
<cmds>
<var_oper>(vFile,"*.txt",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1") <exitmacro> <endif>
<filemove>("vFile","c:\temp\",0,0)


<filerename> : Rename File

This command renames specified file.

Syntax:

<filerename>("FileSource", "NewName", Reserved1, Reserved2)

FileSource
Full path to the file to copy (e.g., "c:\mydocuments\original.doc"). Can be a static text or variable containing text.

NewName
New name such as "backup.doc". Can be a static text or variable containing text.

Reserved2
Must be 0.

Reserved2
Must be 0.

Example:

<#> This macro renames file you select to "_renamed.txt".
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1") <exitmacro> <endif>
<filerename>("vFile","_renamed.txt",0,0)


<filedel> : Delete File

This command deletes specified file(s).

Syntax:

<filedel>("File", SubDir, Reserved)

File
Full path to the file to delete (e.g., "c:\mydocuments\original.doc"). The file path can contain wildcard characters (*?). In such the case all the files matching the pattern are deleted.

SubDir
Takes effect only if the File contains wildcard characters. If 1, files from all the sub directories are deleted as well (if matching the pattern). If 0, files from sub directories are not deleted.

Reserved
Must be 0.

Example:

<#> This macro deletes the file you select
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1") <exitmacro> <endif>
<filedel>("vFile",0,0)


<fileinfo> : File Info

Provides information (size, creation time, last access time, last modification time) about specified file.

Syntax:

<fileinfo>("File", "Info", "ResultVar")

File
Full path to the file (e.g., "c:\mydocuments\file.doc").

Info
Specifies the type of information to be retrieved. Can be one of the following values:
"SIZE" - retrieves file size
"TIME_WRITE" - retrieves the last modification time
"TIME_ACCESS" - retrieves the last access time
"TIME_CREATE" - retrieves the creation time

ResultVar
Variable that receives the result.

Example:

<#> This macro retrieves information about the file you select
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<fileinfo>("vFile","SIZE","vFileSize")
<fileinfo>("vFile","TIME_WRITE","vFileTime")
<msg>(-100,-100,"File size is: %vFileSize%
Last modification time is: %vFileTime%","File Info",1)


<data_load> : Load Data From File To Variable

This command loads (textual) data from file (whole the content) and saves them in variable for further processing within the macro.

Syntax:

<data_load>("Variable", "File", "Reserved")

Variable
Variable that receives the file content (text).

File
Full path to the file with data (e.g., "c:\mydocuments\data.txt").

Reserved
Must be empty string "".

Example:

<#> This macro loads the file content to variable
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<data_load>("vFileData","vFile","")
<msg>(-100,-100,"vFileData","File Content",1)


<data_save> : Save Text (Variable Content) To File

Save textual data to file.

Syntax:

<data_save>("Text", "File", "Mode")

Text
Text to be saved (or variable containing text to be saved).

File
Full path to the file with data (e.g., "c:\mydocuments\data.txt").

Mode
Can be one of the following values:
"A" - the data will be appended to the end of the file
"" - (empty) the data will be written to the begin of the file

Example:

<#> This macro adds current date to a new line in the end of the file.
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<varset>("vData=%_vKeyReturn%%_vCurrDate_MMDDYYYY%","")
<data_save>("vData","vFile","A")


<file_enum> : Enumerate Files

This command enumerates files/folders from the given folder using a defined mask (wildcards).

Syntax:

<file_enum>("FileOrFolderSelection", EnumOptions, VarFiles, VarNumOfFiles)

FileOrFolderSelection
File/folder selection pattern containing wildcards. Example: “c:\windows\a*.?if” or "c:\windows\sys*".

EnumOptions
1 - only subfolders are enumerated

2 - only files are enumerated

3 - both subfolders and files are enumerated

VarFiles
Variable (array) that receives files/folders from the Folder that match the mask.

VarNumOfFiles
Variable that receives the number of files/folders saved in the VarFiles.

Example:

<#> This macro shows how to use 'file_enum' command.
<#>
<cmds>
<file_enum>("%_vFolder_Temp%\*.tmp",2,vFiles,vNumOfFiles)
<msg>(-100,-100,"There are %vNumOfFiles% TMP files in %_vQuoteChar%%_vFolder_Temp%%_vQuoteChar% directory.","Message",1)
<varset>("vMsg=_vStrEmpty","")
<begloop>(vNumOfFiles)
<var_oper>(vMsg,"%vMsg%",STR_APPEND,"%_vKeyReturn%%vFiles[_vLoopCounter0]%","", "0")
<endloop>

<msg>(-100,-100,"vMsg","Message",1)


<file_print> : Print File

Prints specified file on a default printer.

Syntax:

<file_print>(File)

File
Full path to the file to be printed.

Example:

<#> This macro prints c:\boot.ini file
<#>
<cmds>
<file_print>(c:\boot.ini)


<varout> : Send Variable Value To Target Application

 <dir_encryption> : Encrypt/Decrypt a Directory (Folder)

This command encrypts/decrypts all files within an input directory (folder) including all sub-folders. Encrypted files are located in output directory. An extension ".aes" is added to the encrypted files. For example, file "Invoice_01256.doc" is encrypted to "Invoice_01256.doc.aes".

Syntax:

<dir_encryption>("Input Directory","Output Directory", Encryption/Decryption, BitStrength, "Password")

Input Directory
Full path to a directory (folder) that is to be encrypted/decrypted. Example: "c:\myPrivateDocuments".

Output Directory
Directory (folder) where encrypted/decrypted files are located. Example: "c:\myPrivateDocuments_Encrypted".

Encryption/Decryption
This parameter can be one of these:
ENCRYPT_AES - the files are encrypted using AES.
DECRYPT_AES - the files (previously encrypted using ENCRYPT_AES) are decrypted.

BitStrength
Strength of the encryption. These values are supported: 128, 192, 256.

Password
User defined password that is used to encrypt/decrypt the files. A directory encrypted by a password can be successfully decrypted again only if the same password is used.

Example 1:

<#> This example shows how to encrypt whole folder.
<#> The second example shows how to decrypt it again.
<cmds>

<#> Create folder for sample files
<dircreate>("c:\temp\dir_encryption_sample",0)

<#> Create sample files
<data_save>("This is a sample file 1.","c:\temp\dir_encryption_sample\1.file_original.txt","")
<data_save>("This is a sample file 2.","c:\temp\dir_encryption_sample\2.file_original.txt","")

<dir_encryption>("c:\temp\dir_encryption_sample", "c:\temp\dir_encryption_sample_Out", ENCRYPT_AES,128,"dirpwd")

<#> Open folder to see the results
<diropen>("c:\temp\dir_encryption_sample_Out",0)

Example 2:

<#> This example shows how to decrypt whole folder.
<#>
<cmds>

<dir_encryption>("c:\temp\dir_encryption_sample_Out","c:\temp\dir_encryption_sample_Decrypted",DECRYPT_AES,128,"dirpwd")

<#> Open folder to see the results
<diropen>("c:\temp\dir_encryption_sample_Decrypted",0)


<dircreate> : Create Directory (Folder)

Creates new directory.

Syntax:

<dircreate>("Dir", Reserved)

Dir
Full path to the directory to be created (e.g., "c:\mydocuments\new").

Reserved
Must be 0.

Example:

<#> This macro creates new directory "c:\newdir\temp"
<#>
<cmds>
<dircreate>("c:\newdir\temp",0)


<diropen> : Open Directory (Folder)

Opens directory in Windows Explorer.

Syntax:

<diropen>("Dir", WinState)

Dir
Full path to the directory to be opened (e.g., "c:\mydocuments").

WinState
The state of the window:
0 - Normal
1 - Maximized
2 - Minimized

Example:

<#> This macro opens directory "c:\"
<#>
<cmds>
<diropen>("c:\",1)


<dircopy> : Copy Directory (Folder)

Copies directory including all subdirectories. The command continues copying files even if some files fails to be copied. Failed files are reported in report file and also number of failures can be saved in user defined variable so that errors can be handled programmatically.

Syntax:

<dircopy>("SourceDir", "DestDir", Reserved, Reserved, Number of retries, Variable - Number of files copied, Variable - Number of failures, ")

SourceDir
Full path to the source directory (e.g., "c:\mydocuments").

DestDir
Full path to the destination directory (e.g., "c:\backup").

Reserved
Must be 0.

Reserved
Must be 0.

Number of retries
If the copy fails the command can retry to copy later. This parameter tells the number of retries.

Variable - Number of files copied
This variable receives the number of files copied. This parameter can be left blank.

Variable - Number of failures
This variable receives the number of failures. This parameter can be left blank.

Errors report file
If a file cannot be copied then it is recorded in report file. This parameter can be left blank.

Parameters
Additional parameters:
"-pr" - show progress window
"-on" - overwrite file only if it is newer.

Example:

<#> This macro copies directory you select to other directory you select.
<#>
<cmds>

<msg>(100,100,"Select folder you want to copy.","Message",0)
<var_oper>(vDirSource,"",SELECT_FOLDER,"Select Source Folder","", "0")
<proc_call>(ExitOnCancel,)
<msgoff>

<msg>(100,100,"Select destination folder.","Message",0)
<var_oper>(vDirDest,"",SELECT_FOLDER,"Select Destination Folder","", "0")
<proc_call>(ExitOnCancel,)
<msgoff>

<msg>(100,100,"Folder copy is in progress. Please wait....","Message",0)
<dircopy>("vDirSource","vDirDest",0,0,3,,vFail,"%TEMP%\DirCopyFailuresReport.txt","-pr -on ")
<msgoff>

<#> --------------------------------------------------------------------

<proc_def_begin>(ExitOnCancel,)
<if_str>("_vCanceled==1")
<exitmacro>
<endif>
<proc_def_end>

<#> --------------------------------------------------------------------


<dirmove> : Move/Rename Directory (Folder)

Moves directory including all subdirectories.

Syntax:

<dirmove>("SourceDir", "DestDir", Reserved, Reserved)

SourceDir
Full path to the source directory (e.g., "c:\mydocuments").

DestDir
Full path to the destination directory (e.g., "c:\newdocs").

Reserved
Must be 0.

Reserved
Must be 0.

Example:

<#> This macro moves directory you select to other directory you select.
<#>
<cmds>

<msg>(100,100,"Select folder you want to move.","Message",0)
<var_oper>(vDirSource,"",SELECT_FOLDER,"Select Source Folder","", "0")
<proc_call>(ExitOnCancel,)
<msgoff>

<msg>(100,100,"Select destination folder.","Message",0)
<var_oper>(vDirDest,"",SELECT_FOLDER,"Select Destination Folder","", "0")
<proc_call>(ExitOnCancel,)
<msgoff>

<msg>(100,100,"Directory move is in progress. Please wait....","Message",0)
<dirmove>("vDirSource","vDirDest",0,0)
<msgoff>

<#> --------------------------------------------------------------------

<proc_def_begin>(ExitOnCancel,)
<if_str>("_vCanceled==1")
<exitmacro>
<endif>
<proc_def_end>

<#> --------------------------------------------------------------------


<dirrename> : Rename Directory (Folder)

Renames directory specified.

Syntax:

<dirrename>("SourceDir", "NewName", Reserved, Reserved)

SourceDir
Full path to the source directory (e.g., "c:\mydocuments").

NewName
New name of the directory (for example, "mydocuments_old").

Reserved
Must be 0.

Reserved
Must be 0.

Example:

<#> This macro renames directory you select.
<#>
<cmds>

<msg>(100,100,"Select folder you want to rename.","Message",0)
<var_oper>(vDirSource,"",SELECT_FOLDER,"Select Source Folder","", "0")
<proc_call>(ExitOnCancel,)
<msgoff>

<dirrename>("vDirSource","RENAMED",0,0)

<#> --------------------------------------------------------------------

<proc_def_begin>(ExitOnCancel,)
<if_str>("_vCanceled==1")
<exitmacro>
<endif>
<proc_def_end>

<#> --------------------------------------------------------------------


<dirdel> : Delete Directory (Folder)

Deletes directory including all subdirectories. The directory doesn't have to be empty - all the files in the directory are deleted.

Syntax:

<dirdel>("Dir", Reserved)

Dir
Full path to the directory to delete (e.g., "c:\olddata").

Reserved
Must be 0.

Example:

<#> This macro deletes directory you select
<#>
<cmds>

<msg>(100,100,"Select folder you want to delete.","Message",0)
<var_oper>(vDir,"",SELECT_FOLDER,"Select Folder","", "0")
<if_str>("_vCanceled==1")
<exitmacro>
<endif>
<msgoff>

<msg>(100,100,"Folder delete process is in progress. Please wait....","Message",0)
<dirdel>("vDir",0)
<msgoff>


<varout> : Send Variable Value To Target Application

 <zip_createfile> : Create ZIP File

This command compresses one or multiple files to a single ZIP file.

Syntax:

<zip_createfile>("ZIP file path", "Input files mask", IncludeSubfolders, "Password")

Zip file path
Full path to the ZIP file to be created. Example: c:\temp\zipfile.zip.

Input files mask
Full file path or wildcard mask of files that will be included (zipped) to the ZIP file. Example: c:\temp\*.txt.

Include Subfolders
If 1, also files from subfolders that match the "Input files mask" are included.
If 0, the files from subfolders are not included.

Password
If a password is provided then the zip file created is password protected.

Example:

<#> This example shows how to zip multiple files to a single ZIP file.
<#>
<cmds>

<#> Create folder for sample files
<dircreate>("c:\temp\zip_sample",0)

<#> Create sample files
<filecreate>("c:\temp\zip_sample\file1.txt",0)
<filecreate>("c:\temp\zip_sample\file2.txt",0)
<filecreate>("c:\temp\zip_sample\file3.txt",0)

<#> Zip files to a zip file
<zip_createfile>("c:\temp\zip_sample\zipfile.zip","c:\temp\zip_sample\*.txt",0, "")

<#> Open folder to see the results
<diropen>("c:\temp\zip_sample",0)


<varout> : Send Variable Value To Target Application

<zip_unzipfile> : Unzip ZIP File (Extract Files from ZIP Archive)

This command extracts files that match defined mask from ZIP file to a folder.

Syntax:

<zip_unzipfile>("ZIP file path", "Destination folder", "Mask", "Password")

Zip file path
Full path to an existing ZIP file. Example: c:\temp\zipfile.zip.

Destination folder
Full path to a folder where the files contained in the ZIP file will be extracted. If the folder does not exist then it is created automatically. Example: c:\temp\unzipDir.

Mask
Wildcard mask to define what files will be extracted. Only mask matching files are extracted. Example: *.txt.

Password
If the zip file is password protected then the password parameter is needed to successfully unzip the file.

Example:

<#> This example shows how to unzip existing ZIP file.
<#>
<cmds>

<#> Create folder for sample files
<dircreate>("c:\temp\zip_sample",0)

<#> Create sample files
<filecreate>("c:\temp\zip_sample\file1.txt",0)
<filecreate>("c:\temp\zip_sample\file2.txt",0)
<filecreate>("c:\temp\zip_sample\file3.txt",0)

<#> Zip files to a zip file
<zip_createfile>("c:\temp\zip_sample\zipfile.zip","c:\temp\zip_sample\*.txt",0)

<#> Unzip file to folder
<zip_unzipfile>("c:\temp\zip_sample\zipfile.zip","c:\temp\zip_sample\unzip","*.txt")

<#> Open folder to see the results
<diropen>("c:\temp\zip_sample\unzip",0)


<varout> : Send Variable Value To Target Application

<zip_create_sfx> : Create Self-extracting ZIP File

This command compresses one or multiple files to a single self-extracting ZIP file.

Syntax:

<zip_create_sfx>("ZIP file path", "Input files mask", Include Subfolders, "Password")

Zip file path
Full path to the self-extracting ZIP file to be created. Example: c:\temp\zipfile-se.exe.

Input files mask
Full file path or wildcard mask of files that will be included (zipped) to the ZIP file. Example: c:\temp\*.txt.

Include Subfolders
If 1, also files from subfolders that match the "Input files mask" are included.
If 0, the files from subfolders are not included.

Startup file
Full path of the file to automatically open when the self-extracting ZIP file finishes files extraction. Example: c:\temp\readme.txt.

Automatically Unzip to Default Temporary Folder
If 1, the files are extracted automatically to the default temporary folder.
If 0, the user is allowed to select a folder where to extract the files.

Password
If a password is provided then the exe file created is password protected.

Example:

<#> This example shows how to create self-extracting ZIP file.
<#>
<cmds>

<#> Create folder for sample files
<dircreate>("c:\temp\zip_sample",0)

<#> Create sample files
<filecreate>("c:\temp\zip_sample\file1.txt",0)
<filecreate>("c:\temp\zip_sample\file2.txt",0)
<filecreate>("c:\temp\zip_sample\file3.txt",0)

<#> Create self-extracting ZIP file
<zip_create_sfx>("c:\temp\zip_sample\zipfile-selfextract.exe","c:\temp\zip_sample\*.txt",0,"c:\temp\zip_sample\file1.txt",0)

<#> Open folder to see the results
<diropen>("c:\temp\zip_sample",0)


Files & Folders

INI Files

This section contains commands for file and folder manipulation.

<fileopen> Open File
<filecreate> Create New File
<filecopy> Copy File(s)
<filemove> Move File(s)
<filerename> Rename File
 <filedel> Delete File(s)
<fileinfo> Retrieve File Information
<file_enum> Enumerate Files and/or Folders
<data_load> Load Data From File To Variable
<data_save> Save Data To File

<dircreate> Create Folder
<diropen> Open Folder
<dircopy> Copy Folder
<dirmove> Move Folder
 <dirrename> Rename Folder
<dirdel> Delete Folder

See also "System Variables" section for this topic related system variables.


<varout> : Send Variable Value To Target Application

<ini_file_write> : Writes Data to INI File

The command writes data to a INI file. INI files internal structure look like this:

...

[Section]
Key1=Some data.
Key2=Other data.
...
KeyN=Even more data.

[Other Section]
Key1=....

...

The <ini_file_write> command writes data to given key in given section.

Syntax:

<ini_file_write>("Section", "Key", "Data", "INI File Path")

Section
Section name in INI file.

Key
Name of the key in the Section.

Data
Data to be written to the given key in given section.

INI File path
Full path to the INI file.

Example:

<#> This sample writes and reads data from INI file.
<#>
<cmds>

<#> Write some data to the INI file first
<ini_file_write>("section1","key1","Value1","%TEMP%\example.ini")

<#> Read the data then...
<ini_file_read>("section1","key1","vValue","%TEMP%\example.ini")

<#> ... and show the data.
<msg>(-100,-100,"vValue","Message",1,0,0)

<#> In the end let's delete the ini file.
<filedel>("%TEMP%\example.ini",0,0,3,,,"",0)


<varout> : Send Variable Value To Target Application

 <ini_file_read> : Reads Data from INI File

The command reads data from a INI file. INI files internal structure look like this:

...

[Section]
Key1=Some data.
Key2=Other data.
...
KeyN=Even more data.

[Other Section]
Key1=....

...

The <ini_file_read> command reads data from given key in given section.

Syntax:

<ini_file_read>("Section", "Key", "VaribleReceivingData", "INI File Path")

Section
Section name in INI file.

Key
Name of the key in the Section.

VariableReceivingData
Variable that receives data retrieved from the given key in given section.

INI File path
Full path to the INI file.

Example:

<#> This sample writes and reads data from INI file.
<#>
<cmds>

<#> Write some data to the INI file first
<ini_file_write>("section1","key1","Value1","%TEMP%\example.ini")

<#> Read the data then...
<ini_file_read>("section1","key1","vValue","%TEMP%\example.ini")

<#> ... and show the data.
<msg>(-100,-100,"vValue","Message",1,0,0)

<#> In the end let's delete the ini file.
<filedel>("%TEMP%\example.ini",0,0,3,,,"",0)


<wwwopen> : Open Web Page

Opens web page in a web browser (currently only Internet Explorer is supported).

Syntax:

<wwwopen>("WebLink", WindowState, Timeout)

WebLink
Link (URL) to the web page (e.g., "http://www.softwareutilities.com"). The link must contain http://, https://, etc. prefix.

WindowState
The state of the window:
0 - Normal
1 - Maximized
2 - Minimized

Timeout
Time in seconds. If the web page is not opened in this time frame then the command fails.

Example:

<#> This command opens pitrinec.com web page
<#>
<cmds>
<wwwopen>("http://wwww.pitrinec.com",0,15)


<wwwopen> : Open Web Page

<www_fillform> : Fill Web Form

This command opens a web page with form and fills the form by user pre-defined values. Only Internet Explorer browser is supported.

Syntax:

<www_fillform>("Web link", "Form fields data", "Submit button", WindowState, Timeout)

Web link
Link (URL) to the web page (e.g., "http://www.pitrinec.com/samples/sampleform.htm").

From fields data
The user defined web form data. The user uses "Retrieve URL and Form data" button in this command edit window. It is possible to edit this field manually, though, it will be very hard in most cases. The format is this: {frame index}{form name}{form item type}{form item name}{form item value}{form item selected}.

Submit button
A form button that is to be automatically "clicked" after the form is filled. If this field is left empty then the form is not submitted.

WindowState
The state of the web browser window:
0 - Normal
1 - Maximized
2 - Minimized

Timeout
Time in seconds the command waits for the web form is loaded and completed.

Example 1:

<#> This simple example shows how to fill web form
<cmds>
<www_fillform>("http://www.pitrinec.com/samples/sampleform.htm","{0}{}{text}{T1}{John}{0}{0}{}{text}{T2}{McKvak}{0}{0}{}{textarea}{S1}{This is my comment:No comment!}{0}{0}{}{}{}{}{0}{0}{}{radio}{R1}{V7}{0}{0}{}{radio}{R1}{V8}{1}{0}{}{radio}{R1}{V9}{0}{0}{}{checkbox}{C1}{ON}{0}{0}{}{checkbox}{C2}{ON}{1}{0}{}{sel-one}{}{1}{0}{0}{}{}{}{}{0}{0}{}{sel-mul}{Dog}{}{0}{0}{}{sel-mul}{Big dog}{}{0}{0}{}{sel-mul}{Big cat}{}{0}{0}{}{sel-mul}{Big mouse}{}{1}{0}{}{sel-mul}{Cat}{}{0}{0}{}{sel-mul}{Mouse}{}{1}{0}{}{submit}{B1}{Submit}{0}","",1,15)

Example 2:

<#> This example shows how to open web page with a form and fill it by user-defined data
<cmds>
<wwwopen>("http://www.pitrinec.com/samples/sampleform.htm",1,15)
<msg>(-100,-100,"Do you want to fill this sample form?","Message",2,0,1)
<if>("_vMsgButton==YES")
<www_fillform>("http://www.pitrinec.com/samples/sampleform.htm","{0}{}{text}{T1}{John}{0}{0}{}{text}{T2}{McKvak}{0}{0}{}{textarea}{S1}{This is my comment:No comment!}{0}{0}{}{}{}{}{0}{0}{}{radio}{R1}{V7}{0}{0}{}{radio}{R1}{V8}{1}{0}{}{radio}{R1}{V9}{0}{0}{}{checkbox}{C1}{ON}{0}{0}{}{checkbox}{C2}{ON}{1}{0}{}{sel-one}{}{1}{0}{0}{}{}{}{}{0}{0}{}{sel-mul}{Dog}{}{0}{0}{}{sel-mul}{Big dog}{}{0}{0}{}{sel-mul}{Big cat}{}{0}{0}{}{sel-mul}{Big mouse}{}{1}{0}{}{sel-mul}{Cat}{}{0}{0}{}{sel-mul}{Mouse}{}{1}{0}{}{submit}{B1}{Submit}{0}","",1,15)
<endif>


<download> : Download File (HTTP)

Downloads file from a remote FTP server.

Syntax:

<download>("LocalFile", "RemoteFile", "UserName", "Password")

LocalFile
Full path to the file on local machine. If the file already exists it will be overwritten without a prior prompt.

RemoteFile
Full path to the remote file (e.g., http://www.pitrinec.com/index.html).

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This sample macro downloads home page file from www.pitrinec.com
<#>
<cmds>

<msg>(32,32,"Where To Save Downloaded File?","Message",0)
<var_oper>(vLocalFolder,"",SELECT_FOLDER,"","", "0")
<if_str>("_vCanceled==1")<exitmacro><endif>
<msgoff>

<download>("%vLocalFolder%\index.html","http://www.pitrinec.com/index.html","","")

<msg>(-100,-100,"File is downloaded. Do you want to open it?","Message",2)
<if_str>("_vMsgButton==YES")
<fileopen>("%vLocalFolder%\index.html",0)
<endif>


<email> : New E-mail Form

Creates new e-mail message using default e-mail client.

Syntax:

<email>("Address", WindowState)

Address
E-mail address (e.g., support@mycompany.com). The address can be empty.

WindowState
The state of the window:
0 - Normal
1 - Maximized
2 - Minimized

Example:

<#> This command creates new mail message
<#>
<cmds>
<email>("",0)


<email_send> : Send E-mail

This command sends e-mail without any user’s interaction.

Syntax:

<email_send>("Subject", “Message”, “RecipientTo”, “RecipientCC”, “RecipientBCC”, “FileAttachments”)

Subject
E-mail subject field.

Message
Message text.

RecipientTo
E-mail address where to send the e-mail. Example: someone@somewhere.net

RecipientCC
E-mail address of whom to send CC (carbon copy). Example: someone@somewhere.net

RecipientCC
E-mail address of whom to send BCC (blind carbon copy). Example: someone@somewhere.net

FileAttachments
Full path to files that will be sent along with the e-mail message. The files are delimited by comma.

Example:

<#> This command automatically sends an e-mail message
<#>
<cmds>
<email_send>("Hello","Hello,
this is just a sample e-mail...","someone@somewhere.net","","","C:\documents\doc1.doc")


<email_smtp_sendmail> : Sends Email from an Account on SMTP Server

This command sends an e-mail using SMTP. Unlike <email_send>, this command does not require any e-mail client to be installed on the computer.

Syntax:

<email_smtp_sendmail>("Server", "User Name", "Password", "Send To", "Subject", "Body", "File Attachment", PortNum, UseSSL)

Server
A SMTP server

Message Number
Message number (index) to get. The first e-mail message has number "0", the second one has "1" and so on....

From Variable
Variable that receives "from" field of the e-mail message.

Subject Variable
Variable that receives "subject" field of the e-mail message.

Body Variable
Variable that receives "body" field of the e-mail message.

File Attachment
This is a full path to the file to attach to the e-mail message.

PortNum
Port number to use. If left empty a default port number is used.

UseSSL
If 0, the SSL is not used otherwise the SSL is used.

Example:

<#> Thic sample shows how send an email.
<cmds>

<email_smtp_sendmail>("myserver.com","myaccount","mypassword","john@something.com","","Hello John","friendly letter from your family. Visit us soon!","",,0)


<ftp_getfile> : Download File (FTP)

Downloads file from a remote FTP server.

Syntax:

<ftp_getfile>("LocalFile", "RemoteFile", "UserName", "Password")

LocalFile
Full path to the file on local machine. If the file already exists it will be overwritten without a prior prompt.

RemoteFile
Full path to the remote file (e.g., ftp://pitrinec.com/pub/hello.txt). The file path can contain * and ? wildcards. In such a case the "LocalFile" parameter must contain folder where to store multiple files received.

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This macro downloads "hello.txt" file from pitrinec.com
<#>
<cmds>

<msg>(32,32,"Where To Save Downloaded File?","Message",0)
<var_oper>(vLocalFolder,"",SELECT_FOLDER,"","", "0")
<if_str>("_vCanceled==1")<exitmacro><endif>
<msgoff>

<ftp_getfile>("%vLocalFolder%\hello.txt","ftp://pitrinec.com/pub/hello.txt","anonymous","")

<msg>(-100,-100,"File is downloaded. Do you want to open it?","Message",2)
<if_str>("_vMsgButton==YES")
<fileopen>("%vLocalFolder%\hello.txt",0)
<endif>


<ftp_putfile> : Upload File (FTP)

Uploads file from local machine to a remote FTP server.

Syntax:

<ftp_putfile>("LocalFile", "RemoteFile", "UserName", "Password")

LocalFile
Full path to the file on local machine. The path can contain * and ? wildcards.

RemoteFile
Full path to the remote file (e.g., ftp://softwareutilities.com/about.txt). If the "LocalFile" field contains wildcards then this field specifies directory where to upload multiple files.

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This macro uploads file to an FTP server
<#>
<cmds>

<form_item>("fm1","Remote file:","EDIT","","vRemoteFile")
<form_item>("fm1","Local file:","EDIT","","vLocalFile")
<form_item>("fm1","User:","EDIT","","vUser")
<form_item>("fm1","Password:","EDIT","","vPassword")

<form_show>("fm1","File Upload","shell32.dll",14)
<if>("_vCanceled==1")<exitmacro><endif>

<ftp_putfile>("vLocalFile","vRemoteFile","vUser","vPassword")


<ftp_delfile> : Delete Remote File (FTP)

Deletes file from a remote FTP server.

Syntax:

<ftp_delfile>("Reserved", "RemoteFile", "UserName", "Password")

Reserved
Must be empty.

RemoteFile
Full path to the remote file (e.g., ftp://softwareutilities.com/about.txt). The path can contain * and ? wildcards.

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This macro deletes file from FTP server
<#>
<cmds>

<form_item>("fm1","Remote file to delete:","EDIT","","vRemoteFile")
<form_item>("fm1","User:","EDIT","","vUser")
<form_item>("fm1","Password:","EDIT","","vPassword")

<form_show>("fm1","FTP: Delete File","shell32.dll",32)
<if_str>("_vCanceled==1")<exitmacro><endif>

<ftp_delfile>("","vRemoteFile","vUser","vPassword")


<ftp_renamefile> : Rename Remote File (FTP)

Renames file on a remote FTP server.

Syntax:

<ftp_renamefile>("RemoteOldlFile", "RemoteNewFile", "UserName", "Password")

RenameOldFile
Full path to the original remote file (e.g., ftp://softwareutilities.com/original.txt).

RemoteNewFile
Full path to the remote new file (e.g., ftp://softwareutilities.com/renamed.txt).

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This macro uploads file to an FTP server
<#>
<cmds>

<form_item>("fm1","Remote file - old name:","EDIT","","vRemoteFileOld")
<form_item>("fm1","Remote file - new name:","EDIT","","vRemoteFileNew")
<form_item>("fm1","User:","EDIT","","vUser")
<form_item>("fm1","Password:","EDIT","","vPassword")

<form_show>("fm1","File Rename","shell32.dll",1)
<if_str>("_vCanceled==1")<exitmacro><endif>

<ftp_renamefile>("vRemoteFileOld","vRemoteFileNew","vUser","vPassword")


<ftp_filesize> : Get Remote File Size (FTP)

This command retrieves size of a file on a remote FTP server.

Syntax:

<ftp_filesize>("vFileSize", "RemoteFile", "UserName", "Password")

vFileSize
Variable that receives file size in bytes.

RemoteFile
Full path to the remote file (e.g., ftp://pitrinec.com/pub/hello.txt).

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This sample retrieves size of file placed on remote FTP server
<#>
<cmds>
<ftp_filesize>("vFileSize","ftp://pitrinec.com/pub/hello.txt","","")
<msg>(-100,-100,"Size of %_vQuoteChar%ftp://pitrinec.com/pub/hello.txt%_vQuoteChar% file is %vFileSize% bytes.","Message",1)


<ftp_filetime> : GetRemote File Time (FTP)

This command retrieves last modification time of a file on a remote FTP server. The time is in form: "MM/DD/YYYY Hour:Minute:Second". If necessary for further time processing, the time can be parsed using <var_parse> command.

Syntax:

<ftp_filetime>("vFileTime", "RemoteFile", "UserName", "Password")

vFileTime
Variable that receives last file modification time in "MM/DD/YYYY Hour:Minute:Second" form.

RemoteFile
Full path to the remote file (e.g., ftp://pitrinec.com/pub/hello.txt).

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This sample retrieves last modification time of file placed on remote FTP server
<#>
<cmds>

<ftp_filetime>("vFileTime","ftp://pitrinec.com/pub/hello.txt","","")
<msg>(-100,-100,"Last modification time of %_vQuoteChar%ftp://pitrinec.com/pub/hello.txt%_vQuoteChar% file is %vFileTime%.","Message",1)

<msg>(-100,-100,"Do you want to parse the time?","Message",2)
<if_str>("_vMsgButton==YES")
<var_parse>("vFileTime","/ :","",vTimeItems,vNumberOfTimeItems)
<begloop>(vNumberOfTimeItems)
<msg>(-100,-100,"%vTimeItems[_vLoopCounter0]%","Time items:",1)
<endloop>
<endif>


<ftp_createdir> : Create Folder On Remote FTP Server

Creates new directory on a remote FTP server.

Syntax:

<ftp_createdir>("Reserved", "RemoteDir", "UserName", "Password")

Reserved
Must be empty.

RemoteDir
Full path to the remote directory to create (e.g., ftp://softwareutilities.com/newdir).

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This macro creates new directory on FTP server
<#>
<cmds>

<form_item>("fm1","Remote directory to create:","EDIT","","vRemoteDir")
<form_item>("fm1","User:","EDIT","","vUser")
<form_item>("fm1","Password:","EDIT","","vPassword")

<form_show>("fm1","FTP: Create Directory","shell32.dll",3)
<if_str>("_vCanceled==1")<exitmacro><endif>

<ftp_createdir>("","vRemoteDir","vUser","vPassword")


<ftp_deldir> : Delete Folder On Remote FTP Server

Deletes directory on a remote FTP server.

Syntax:

<ftp_deldir>("Reserved", "RemoteDir", "UserName", "Password")

Reserved
Must be empty.

RemoteDir
Full path to the remote directory to delete (e.g., ftp://softwareutilities.com/dir).

UserName
User login name. If empty the "anonymous" is considered.

Password
User name login password.

Example:

<#> This macro deletes directory on FTP server
<#>
<cmds>

<form_item>("fm1","Remote directory to delete:","EDIT","","vRemoteDir")
<form_item>("fm1","User:","EDIT","","vUser")
<form_item>("fm1","Password:","EDIT","","vPassword")

<form_show>("fm1","FTP: Delete Directory","shell32.dll",31)
<if_str>("_vCanceled==1")<exitmacro><endif>

<ftp_deldir>("","vRemoteDir","vUser","vPassword")


<varout> : Send Variable Value To Target Application

 <email_pop3_getlist> : Retrieves List of Messages Waiting on POP3 E-mail Account

This command retrieves list of messages waiting on POP3 e-mail account. Before <email_pop3_getlist> command can be called a connection to the e-mail account needs to be opened using <email_pop3_connect> command.

Syntax:

<email_pop3_getlist>("Connection ID", "Number Of Messages Variable", "From Variable Array", "Subject Variable Array")

Connection ID
An identifier of connection to the e-mail account. Connection is opened using <email_pop3_connect> command.

Number of Message Variable
Variable that receives number of e-mail messages waiting on e-mail account.

From Variable Array
Variable (array) that receives "from" field of a waiting e-mail message.

Subject Variable Array
Variable (array) that receives "subject" field of a waiting e-mail message.

Example:

<#> Thic sample shows how to get list of e-mails received on POP3 account.
<cmds>

<#> Connect to POP3 account first:
<email_pop3_connect>("myemails.com","myaccount","737qw7523#$","POP3Connection")

<#> Get list of messages then:
<email_pop3_getlist>("POP3Connection","vNumberOfMessages","vMessages_From","vMessages_Subject")

<#> Disconnect from the account:
<email_pop3_disconnect>("POP3Connection")

<#> Show the list of messages:
<if_num>("vNumberOfMessages > 0")

<varset>("vEmailsList=_vStrEmpty","")

<for>("vEmails=0","vEmails < vNumberOfMessages","1")

<var_oper>(vEmailsList,"%vEmailsList%",STR_APPEND,"vMessages_Subject[vEmails]","", "0")
<var_oper>(vEmailsList,"%vEmailsList%",STR_APPEND,"%_vKeyNewLine%","", "0")

<for_end>

<msg>(-100,-100,"%vEmailsList%","Emails received",1,0,0)

<else>

<msg>(-100,-100,"There are no e-mails received.","Emails received",1,0,2)

<endif>


<varout> : Send Variable Value To Target Application

<email_pop3_getmail> : Retrieves a Message Waiting on POP3 E-mail Account

This command retrieves defined message waiting on POP3 e-mail account. Before <email_pop3_getmail> command can be called a connection to the e-mail account needs to be opened using <email_pop3_connect> command. In addition, it is always good to check for the e-mail existence using <email_pop3_getlist> before retrieving the particular e-mail using the <email_pop3_getmail> command.

Syntax:

<email_pop3_getmail>("Connection ID", "Message Number", "From Variable", "Subject Variable", "Body Variable")

Connection ID
An identifier of connection to the e-mail account. Connection is opened using <email_pop3_connect> command.

Message Number
Message number (index) to get. The first e-mail message has number "0", the second one has "1" and so on....

From Variable
Variable that receives "from" field of the e-mail message.

Subject Variable
Variable that receives "subject" field of the e-mail message.

Body Variable
Variable that receives "body" field of the e-mail message.

Example:

<#> Thic sample shows how to get list of e-mails received on POP3 account.
<cmds>

<#> Connect to POP3 account first:
<email_pop3_connect>("myemails.com","myaccount","737qw7523#$","POP3Connection")

<#> Get number of messages:
<email_pop3_getlist>("POP3Connection","vNumOfMessages","","")

<#> Are there some messages?
<if_num>("vNumOfMessages > 0")

<#> Yes, so let's get the first one:
<email_pop3_getmail>("POP3Connection","0","vFrom","vSubject","vBody")

<#> Show the list of messages:
<msg>(-100,-100,"Subject: '%vSubject%'
From: '%vFrom%'
-----------------------------
%vBody%","Emails received",1,0,0)

<else>
<msg>(-100,-100,"No message is waiting on e-mail account.","Message",1,,2)
<endif>

<#> Disconnect from the account:
<email_pop3_disconnect>("POP3Connection")


<varout> : Send Variable Value To Target Application

<email_pop3_deletemail> : Deletes a Message Waiting on POP3 E-mail Account

This command deletes defined message waiting on POP3 e-mail account. Before <email_pop3_deletemail> command can be called a connection to the e-mail account needs to be opened using <email_pop3_connect> command. In addition, it is always good to check for the e-mail existence using <email_pop3_getlist> before deleting the particular e-mail using the <email_pop3_deletemail> command.

Syntax:

<email_pop3_delete>("Connection ID", "Message Number")

Connection ID
An identifier of connection to the e-mail account. Connection is opened using <email_pop3_connect> command.

Message Number
Message number (index) to delete. The first e-mail message has number "0", the second one has "1" and so on....

Example:

<#> Thic sample shows how to delete e-mail from POP3 account.
<cmds>

<#> Connect to POP3 account first:
<email_pop3_connect>("myemails.com","myaccount","737qw7523#$","POP3Connection")

<#> Get number of messages:
<email_pop3_getlist>("POP3Connection","vNumOfMessages","","")

<#> Are there some messages?
<if_num>("vNumOfMessages > 0")

<#> Do we want to delete the message?
<msg>(-100,-100,"Do you want to delete e-mail message?","Emails received",2,0,1)

<if_str>("_vMsgButton==YES")
<#> Yes, so let's delete the first one:
<email_pop3_deletemail>("POP3Connection","0")
<endif>

<else>
<msg>(-100,-100,"No message is waiting on e-mail account.","Message",1,,2)
<endif>

<#> Disconnect from the account:
<email_pop3_disconnect>("POP3Connection")


<varout> : Send Variable Value To Target Application

<email_pop3_connect> : Connects to POP3 E-mail Account

This command opens a connection to an e-mail account. This command needs to be called before any other <email_pop3_...> is used.

Syntax:

<email_pop3_connect>("Server", "Account", "Password", "Connection ID")

Server
Server where e-mail account exist. Example: myemails.com

Account
The e-mail account name.

Password
The account password.

Connection ID
An identifier of connection to the e-mail account. Other <email_pop3_...> commands use this Id.

Example:

<#> Thic sample shows how to get list of e-mails received on POP3 account.
<cmds>

<#> Connect to POP3 account first:
<email_pop3_connect>("myemails.com","myaccount","737qw7523#$","POP3Connection")

<#> Do what you need here....

<#> Disconnect from the account:
<email_pop3_disconnect>("POP3Connection")


<varout> : Send Variable Value To Target Application

<email_pop3_disconnect> : Disconnects from POP3 E-mail Account

This command closes a connection to an e-mail account. This command needs to be called after all <email_pop3_...> commands are finished.

Syntax:

<email_pop3_disconnect>("Connection ID")

Connection ID
An identifier of connection to the e-mail account.

Example:

<#> Thic sample shows how to get list of e-mails received on POP3 account.
<cmds>

<#> Connect to POP3 account first:
<email_pop3_connect>("myemails.com","myaccount","737qw7523#$","POP3Connection")

<#> Do what you need here....

<#> Disconnect from the account:
<email_pop3_disconnect>("POP3Connection")


<dialup> : Dial Up

Dial up command connects computer to internet (ISP) using phone line.

Syntax:

<dialup>(PhoneBook, User, Password, Domain, Reserved)

PhoneBook
Phone book to be used to connect computer to ISP.

User
Login user name.

Password
Login password.

Domain
Domain (* is default).

Reserved
Must be 0.

Example:

<#> This macro connects computer to ISP.
<#>
<cmds>
<dialup>(ISP-Home,John Smith,6yuT1,*,0)


<hangup> : Hang Up

This command disconnects computer from internet and frees phone line.

Syntax:

<hangup>

Example:

<#> This macro disconnects computer from ISP.
<#>
<hangup>


<netcondrive> : Connect Network Drive

Maps (connects) a network directory to local drive.

Syntax:

<netcondrive>("Drive", "Net Directory", "User Name", "User Password", Restore)

Drive
Drive you want to map the network directory map to (e.g., "X:"). Keep in mind it must be one letter followed by : .

Net Directory
Network directory (for example, "\\server\mydir").

User Name
User name user uses to log on to the machine where the net directory resides.

User Password
Password user uses to log on to the machine where the net directory resides.

Restore
Restore at next logon: If 1 the drive will be automatically mapped at next logon.

Example:

<#> This macro maps a network directory to local drive.
<#>
<cmds>
<netcondrive>("X:","\\server\mzdir","john","jpwd",0)


<netdiscondrive> : Disconnect Network Drive

Disconnects local drive from a network directory.

Syntax:

<netdiscondrive>("Drive", Restore)

Drive
Drive you want to remove (e.g., "X:"). Keep in mind it must be one letter followed by : .

Restore
Restore at next logon: If 1 the drive will be automatically mapped at next logon.

Example:

<#> This macro disconnects drive from a network directory.
<#>
<cmds>
<netdiscondrive>("X:", 0)


<netcondrivedlg> : Shows "Connect Network Drive" Dialog Box

Shows a dialog box to map (connect) network folder to local drive.

Syntax:

<netcondrivedlg>

Example:

<#> This macro opens a dialog box to map network folder to local drive.
<#>
<cmds>
<netcondrivedlg>


<netdiscondrivedlg> : Shows Dialog Box Window to Disconnect Network Drive

Shows a window to disconnects local drive from a network directory.

Syntax:

<netdiscondrivedlg>

Example:

<#> This macro shows a window to disconnect drive from a network directory.
<#>
<cmds>
<netdiscondrivedlg>


<actwin> : Activate Window

Activates specified window. If the window doesn't exist a macro can be started (to open desired application or notify user, for example).

Syntax:

<actwin>("WinTitleOrHWND", Match, WindowState, "MacroRun")

WinTitleOrHWND
Window identifier in form of Window Identification Path or HWND. It identifies window the information is to be retrieved from.

Match
Takes effect only if a window title is used as WinTitleOrHWND parameter. Can be one of these values:
0 - WinTitle can be substring of a window title
1 - WinTitle must exactly match a window title

WindowState
Desired state of the window after the window is activated:
0 - Normal
1 - Minimized
2 - Maximized
3 - Let the state unchanged

MacroRun
Name of the macro to run if the WinTitle doesn't match any existing window. The "no" value means no macro will be run.

Example:

<#> This macro activates "Notepad" window if it is opened
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<actwin>("Notepad",0,0,"no")
<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<winmove> : Move Window

Moves specific window to defined position.

Syntax:

<winmove>("WIP or HWND", WinMatchMatch, Xpos, Ypos)

WIP or HWND
Window identifier in form of Window Identification Path or HWND. It identifies the window that will be moved.

WinMatch
Takes effect only if a window is identified using WIP parameter. Can be one of these values:
0 - match substrings in WIP
1 - match exact strings in WIP

Xpos
X-coordinate of desired window position

Ypos
Y-coordinate of desired window position

Example:

<#> This macro moves "Notepad" window to position (32,32)
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<winmove>("Notepad",0,32,32)
<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<winresize> : Resize Window

Resizes specific window.

Syntax:

<winresize>("WIP or HWND", Match, Width, Height)

WIP or HWND
Window identifier in form of Window Identification Path or HWND. It identifies the window that will be resized.

Match
Takes effect only if a window is identified using WIP parameter. Can be one of these values:
0 - match substrings in WIP
1 - match exact strings in WIP

Width
Desired window's width

Height
Desired window's height

Example:

<#> This macro resizes "Notepad" window to size 300x200
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<winresize>("Notepad",0,300,200)
<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<winstate> : Change Window State

Changes window's state.

Syntax:

<winstate>("WIP or HWND", "State")

WIP or HWND
Window identifier in form of Window Identification Path or HWND. It identifies the window that state is to be changed.

State
Can be one of these values:
"MIN"
"RESTORE"
"MAX"
"ALWAYS_TOP"
"NOT_ALWAYS_TOP"
"HIDE"
"SHOW"

Example:

<#> This macro minimizes "Notepad" window
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<winstate>("Notepad","MIN")
<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<winclose> : Close Window

This command closes specified window. If the specified window is main application window this command causes the application is closed. (If an application cannot be exited this way it is also possible to use <process_kill> command).

Syntax:

<winclose>("WIP or HWND", WinMatch)

WIP or HWND
Window identifier in form of Window Identification Path or HWND. It identifies the window that is to be closed.

WinMatch
Takes effect only if a window is identified using WIP parameter. Can be one of these values:
0 - match substrings in WIP
1 - match exact strings in WIP

Example:

<#> This macro closes "Notepad" window
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<winclose>("Notepad",0)
<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<wininfo> : Retrieve Information About Window

This command retrieves information about required window. After the command is processed, required information is saved in following system variables:

_vWinRectX1 - X position of upper left corner of the window in screen coordinates
_vWinRectY1 - Y position of upper left corner of the window in screen coordinates
_vWinRectX2 - X position of lower right corner of the window in screen coordinates
_vWinRectY2 - Y position of lower right corner of the window in screen coordinates
_vWinWdt - window’s width
_vWinHgt - window’s height
_vWinTitle - window title
_vWinClass - window class
_vWinState - window state (MIN, RESTORE, MAX, HIDDEN)
_vWinActive - YES, if window is active (on top receiving keyboard input), otherwise NO
 _vWinHWND - HWND of the window

Syntax:

<wininfo>("WIP or HWND", "Unused", WinMatch)

WIP or HWND
Window identifier in form of Window Identification Path or HWND. It identifies window the information is to be retrieved from.

Unused
Must be empty.

WinMatch
Takes effect only if a window is identified using WIP parameter. Can be one of these values:
0 - match substrings in WIP
1 - match exact strings in WIP

Example:

<#> This macro retrieves information about "Notepad" window
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<wininfo>("Notepad","",0)
<msg>(-100,-100,"Window information:

%_vWinTitle%

%_vWinClass%

%_vWinActive%

%_vWinState%","Message",1)

<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<win_enumerate> : Enumerate Windows

This command enumerates windows.

Syntax:

<win_enumerate>(VarWindows, VarNumberOfWindows, Options)

VarWindows
Variable (array) that receives window title of each visible window.

VarNumberOfWindows
Number of visible windows saved in VarWindows variable.

Options
0 - enumerate only visible windows and insert window titles to VarWindows variable
1 - enumerate both visible and hidden windows and insert window titles to VarWindows variable
2 - enumerate only visible windows and insert HWND to VarWindows variable
3 - enumerate both visible and hidden windows and insert HWND to VarWindows variable

Example:

<#> This macro enumerates opened windows
<#>
<cmds>

<win_enumerate>(vWin,vNum,0)
<begloop>(vNum)
<msg>(-100,-100,"vWin[_vLoopCounter0]","Message",1)
<endloop>


<varout> : Send Variable Value To Target Application

<win_findimage> : Find an Image in Specified Window

This command searches for defined image(s) within the given window. If the image is found in the window the command sets supplied coordinate variables. If multiple image files are defined using wildcards then [x,y] position variables for each image are created for each image file. For example, if image files are defined using "c:\find_images\*.bmp" and there are "Button.bmp" and "Title.bmp" image files in the "c:\find_images" folder then variables "button.bmp_x" and "button.bmp_y" variables that defines position of the "Button.bmp" image on the screen is created. The same for "title.bmp" file there are "title.bmp_x" and "title.bmp_y" variable created. Using such variables it is possible to determine what images were found and what are their position on the screen. Image file names are always converted to lowercase.

Syntax:

<win_findimage>("WinIdentPathOrHWND",WinMatch,"Image File(s)", StartSearchX, StartSearchY, VarResultX, VarResultY, ExactMatch, AreaWidth, AreaHeight)

WinIdentPathOrHWND
Window Identification Path or HWND of the window where the image is to be searched in. HWND is a unique handle Windows internally uses to identify each window. The HWND can be retrieved by some commands (<wininfo>, <win_enumerate>) or is provided by some system variables (_vKeybdFocusWindow_HWND, _vActiveWindow_HWND, _vActiveWindowPrev_HWND).

WinMatch
Takes effect only if a window title is used as WinTitleOrHWND parameter. Can be one of these values:
0 - WinTitle can be substring of a window title
1 - WinTitle must exactly match a window title

Image File
Full path to the image file. This is a bitmap image that is captured using "Capture..." feature in the <win_findimage> command editor. Multiple image files are supported using wildcards (* or ?).

StartSearchX
X-coordinate where to start searching in the window.

StartSearchY
Y-coordinate where to start searching in the window.

AreaWidth
It is possible to scope searching to an area smaller than the whole window. This attribute specifies the width of the searching area. If this parameter is set to "0" then the whole window width is being searched.

AreaHeight
It is possible to scope searching to an area smaller than the whole window. This attribute specifies the height of the searching area. If this parameter is set to "0" then the whole window height is being searched.

VarResultX
Name of the variable that receives X-coordinate of the position of the image in the window. If the image is not found then the variable receives "-1".

VarResultY
Name of the variable that receives Y-coordinate of the position of the image in the window. If the image is not found then the variable receives "-1".

ExactMatch
If 0 then the image does not has to exactly match, a certain level of tolerance is allowed.
If 1 then the image has to exactly match.

Example:

<#> This macro finds a "sin" button in Calculator window and clicks on it
<#>

<cmds>

<win_findimage>("[Calculator|CalcFrame|#25|#543]",0,"C:\Temp\sin.bmp",0,0,vSinBtnX,vSinBtnY,0,0,0)

<if>("vSinBtnX > -1")

<actwin>("[Calculator|CalcFrame|#0|#0]",0,0,"no")
<mousemove_relative_win>
<mm>(vSinBtnX,vSinBtnY)<mlbd><mlbu>

<endif>


<win_captureimage> : Capture an Image in Specified Window

This command captures an image in defined window.

Syntax:

<win_captureimage>("WIP or HWND", WinMatch, X, Y, Wdt, Hgt, "ImageFile")

WIP or HWND
Window identifier in form of Window Identification Path or HWND. It identifies the window where an image is to be captured.

WinMatch
Takes effect only if a window is identified using WIP parameter. Can be one of these values:
0 - match substrings in WIP
1 - match exact strings in WIP

X
X coordination of the upper left corner of the area to be captured.

Y
Y coordination of the upper left corner of the area to be captured.

Wdt
Width of the area to be captured. If it is set to "0" then whole window is captured.

Hgt
Height of the area to be captured.

Image File
Name (or full path) of the resulting image file.

Example:

<#> This macro shows how to capture picture of an active window
<cmds>

<win_captureimage>("_vActiveWindow_HWND",0,0,0,0,0,"%_vFolder_Personal%\WindowImage.bmp")

<msg>(-100,-100,"Do you want to see the captured image now?","Message",2,0,1)

<if>("_vMsgButton==YES")
<fileopen>("%_vFolder_Personal%\WindowImage.bmp",0)
<endif>


<winminall> : Minimizes All Windows

This command minimizes all windows.

Syntax:

<winminall>

Example:

<#> This macro minimizes all windows
<#>
<cmds>
<winminall>


<wintile_h> : Tile All Windows Horizontally

This command tiles all windows horizontally.

Syntax:

<wintile_h>

Example:

<#> This macro tiles all windows horizontally
<#>
<cmds>
<wintile_h>


<wintile_v> : Tile All Windows Vertically

This command tiles all windows vertically.

Syntax:

<wintile_v>

Example:

<#> This macro tiles all windows vertically
<#>
<cmds>
<wintile_v>


<wincascade> : Cascade All Windows

This command cascades all windows.

Syntax:

<wincascade>

Example:

<#> This macro cascades all windows
<#>
<cmds>
<wincascade>


<clp_copyselected> : Copy Selected (Object)

Copies selected data (text in a word processor, graphics in a graphics program, file in Windows Explorer, etc.) to clipboard. This command does much more then just pressing Ctrl+C (or Ctrl+Insert) key combination. The command also waits until the data are saved in the clipboard before macro execution continues.

Syntax:

<clp_copyselected>(CopyKeyCombination)

CopyKeyCombination
0 - Ctrl+C key combination is used to copy the data to clipboard.
1 - Ctrl+Insert key combination is used to copy the data to clipboard.

Example:

<#> This example copies selected data to clipboard
<#>
<cmds>
<me_error_nodisplay>
<clp_copyselected>(0)
<if_str>("_vErr != NO")
<msg>(-100,-100,"Cannot save data to clipboard - no text (or other object) is selected.","Message",1)
<endif>


<clpsave> : Save Clipboard Data To File

Saves clipboard content (all data in all the formats available) to file.

Syntax:

<clpsave>("File")

File
Full path to the file that receives clipboard data.

Example:

<#> This example saves clipboard data to file c:\clpdata.clx
<#>
<cmds>
<clpsave>("c:\clpdata.clx")


<clpload> : Load Clipboard Data From File

Loads clipboard content from file (previously created using <clpsave> command or by "Tools\Save Clipboard Data To File" menu item). This command changes clipboard content.

Syntax:

<clpload>("File")

File
Full path to the file that contains clipboard data (previously created using <clpsave> command or by "Tools\Save Clipboard Data To File" menu item).

Example:

<#> This example loads clipboard data from file "c:\clpdata.clx"
<#>
<cmds>

<if_file>("c:\clpdata.clx","EXIST","")
<clpload>("c:\clpdata.clx")
<else>
<msg>(100,100,"The file 'c:\clpdata.clx' doesn't exist.","Message",1)
<endif>


<clppastetext> : Paste Text

Pastes (inserts) text to destination application (document) through clipboard.

Syntax:

<clppastetext>("Text")

Text
Text (variable) to be pasted to destination application (document).

Example:

<#> This macro pastes "Hello!" into the Notepad
<#>
<cmds>

<if_win>("Notepad","OPEN",0)
<actwin>("Notepad",0,0,"no")
<clppastetext>("Hello!")
<else>
<msg>(100,100,"'Notepad' is not opened!","Message",1)
<endif>


<clpempty> : Removes Clipboard Content

Removes all the clipboard content.

Syntax:

<clpempty>

Example:

<#> This example removes all the content from clipboard
<#>
<cmds>
<clpempty>


<clpput> : Put Text To Clipboard

Puts text data or file shortcut to clipboard. This command changes clipboard content.

Syntax:

<clpput>("Text")

Text
Text to be put into the clipboard. It is also possible to put a file shortcut to the clipboard this way: FILE:file path. Example: <clpput>("FILE:c:\temp\file.txt") command puts shortcut to "c:\temp\file.txt" file to clipboard so that the file then can be copied using Windows Explorer "Paste" menu command.

Example:

<#> This macro puts data you type to clipboard
<#>
<cmds>
<varset>("vData=","Type text you want to put to clipboard")
<clpput>("vData")


<beep> : Play Sound

Play sound.

Syntax:

<beep>("SoundFile", Repeat)

SoundFile
Full path to the file (.wav) to play.

Repeat
How many times the sound should be repeated.

Example:

<#> This macro will play the sound file you select
<#>
<cmds>
<var_oper>(vSoundFile,"",SELECT_FILE,"Select File","", "0")
<beep>("vSoundFile",1)


<multimedia> : Multimedia Control

Multimedia control.

Syntax:

<multimedia>(Control, ControlValue)

Control
Must be VOLUME.

Control Value
One of these values: MUTE, UP, DOWN.

Example:

<#> This macro will mute player volume
<#>
<cmds>
<multimedia>(VOLUME,MUTE)


<me_macroenable> : Enable/Disable Macro

Enables or disables macro.

Syntax:

<me_macroenable>(“MacroName”, Enable, Reserved)

MacroName
Macro name (macro name field in “General” tab). The macro with this name must exist otherwise the command fails.

Enable
0 - disable
1 - enable

Reserved
Must be 0.

Example:

<#> This macro will disable 'TestMacro1' (if it exist)
<#>
<cmds>
<me_macroenable>("TestMacro1",0,0)


<me_macroenable_group> : Enable/Disable Macros From Group

Enables or disables specified macro group.

Syntax:

<me_macroenable_group>(“GroupName”, Enable, Reserved)

GroupName
Name of the macro group. The macro group with this name must exist otherwise the command fails.

Enable
0 - disable
1 - enable

Reserved
Must be 0.

Example:

<#> This macro will disable all macros from 'GRP1' group (if exists)
<#>
<cmds>
<me_macroenable_group>("GRP1",0,0)


<me_exit> : Exit/Restart This Program

Depending on the exit parameter, the command either exit or restart #THIS_PROGRAM#.

Syntax:

<me_exit>(ExitParam)

ExitParam
0 - exit the program
1 - restart the program

Example:

<#> This macro will restart program
<#>
<cmds>
<me_exit>(1)


<me_changeicon> : Change Macro Icon

This command changes a macro icon.

Syntax:

<me_changeicon>(“MacroName”, “IconFilePath”, IconIndex)

MacroName
Name of the macro. The macro with this name must exist otherwise the command fails.

IconFilePath
Full path to a file containing icon (exe, dll, ico, etc.).

IconIndex
Index of the icon within the IconFilePath.

Example:

<#> This macro will change icon of ‘TestMacro1’ macro.
<#>
<cmds>
<me_changeicon>(" TestMacro1","shell32.dll",2)


<me_stop_enable>, <me_stop_disable>

<me_stop_disable> : Disable Ability To Stop Macro Execution Using "Shift+Esc"
<me_stop_enable> : Enable Ability To Stop Macro Execution Using "Shift+Esc"

Macro execution (by default) can be stopped using "Shift+Esc" hotkey. If it is necessary, the macro developer can disable this using <me_stop_disable> command. After this command is processed, pressing "Shift+Esc" will have no effect. The <me_stop_enable> command enables "Shift+Esc" again.

Syntax:

<me_stop_disable>
<me_stop_enable>

No parameters.

Example:

<#> This macro shows how to enable/disable "Shift+Esc"
<#>
<cmds>
<me_stop_disable>
<#> Part of the macro that cannot be interrupted for integrity reasons comes here
<#> We will supply it by 5 seconds wait command in this example
<msg>(-100,-100,"You cannot stop macro execution using %_vQuoteChar%Shift+Esc%_vQuoteChar% hotkey now.
Wait for 5 seconds, please...","Message",0)
<wx>(5000)
<msgoff>
<me_stop_enable>
<#> The rest of the macro can be interrupted using "Shift+Esc"
<msg>(-100,-100,"Now you can stop macro execution using %_vQuoteChar%Shift+Esc%_vQuoteChar% hotkey.","Message",0)
<wx>(5000)
<msgoff>


<me_macroenable> : Enable/Disable Macro

<me_status_window> : Open/Close Macro Execution Status Window

For more complex macros, it is possible to display macro execution status so that user has a visual feedback of the running macro. This command either displays or closes the status (progress) window. Typically, the window is to be shown on the begin of the macro and closed in the end of the macro. There can be only one status window shown at the same time.
The window can contain multiple rows containing icon (none, "in progress", "OK" "Failed") and status text. The <me_status_set> command adds/modifies content of the status window - it either adds new row or modifies existing row.

Syntax:

<me_status_window>("Title", Operation, Always_on_top, X, Y, Wdt, Hgt)
Title:
 Title of the status window.

Operation:
 0 - the status window is to be opened
 1 - the status window is to be closed

Always_on_top:
 0 - normal window that can be overlapped by other windows
1 - always on top window that is never overlapped by other windows

X:
 X - position of the window on the screen (absolute screen coordinates).

Y:
 Y - position of the window on the screen (absolute screen coordinates).

Wdt:
 Width of the window.

Hgt:
 Height of the window.

Example:

<#> This sample shows how to us the status window
<cmds>

<me_status_window>("Macro in progres",0,1,100,100,350,150)
<me_status_set>(0,"Three steps needs to be done, please wait:",0)

<me_status_set>(1,"Step 1",1)
<wx>(2000)
<me_status_set>(1,"Step 1: OK",2)

<me_status_set>(2,"Step 2",1)
<wx>(2000)
<me_status_set>(2,"Step 2: Failed",3)

<me_status_set>(3,"Step 3",1)
<wx>(2000)
<me_status_set>(3,"Step 3: OK",2)

<wx>(2000)


<me_macroenable> : Enable/Disable Macro

<me_status_set> : Set Status In Status Window

This command adds or modifies row in the status window (<me_status_window>). Each row is identified using numeric ID. If there is not a row with the given ID in the window yet, then new row is added. If a row with the given ID exists, then it is updated using parameters passed (status and text - if the text is not supplied then old text remains displayed). Each row consists of status icon (none, "in progress", "OK", "Failed") and text.

Syntax:

<me_status_set>(ID, "Text", Status)
ID:
 Unique numeric identifier of the row in the status window.

Text:
 Text showing on the row.

Status:
 0 - none icon
1 - "in progress" icon
 2 - "OK" icon
 3 - "Failed" icon
4 - "Info" icon

Example:

<#> This sample shows how to us the status window
<cmds>

<me_status_window>("Macro in progres",0,1,100,100,350,150)
<me_status_set>(0,"Three steps needs to be done, please wait:",0)

<me_status_set>(1,"Step 1",1)
<wx>(2000)
<me_status_set>(1,"Step 1: OK",2)

<me_status_set>(2,"Step 2",1)
<wx>(2000)
<me_status_set>(2,"Step 2: Failed",3)

<me_status_set>(3,"Step 3",1)
<wx>(2000)
<me_status_set>(3,"Step 3: OK",2)

<wx>(2000)


<me_macroprogress_show> : Shows a Macro Execution Progress Window

This command shows macro progress execution window.

Syntax:

<me_macroprogress_show>

Example:

<#> This macro shows/hides macro progress execution window
<#>
<cmds>
<me_macroprogress_show>
<wx>(3000) <#> Wait 3 seconds
<me_macroprogress_hide>
<wx>(3000) <#> Wait 3 seconds
<me_macroprogress_show>
<wx>(3000) <#> Wait 3 seconds


<me_macroprogress_show> : Hides a Macro Execution Progress Window

<me_macroprogress_hide> : Hides a Macro Execution Progress Window

This command hides macro progress execution window.

Syntax:

<me_macroprogress_hide>

Example:

<#> This macro shows/hides macro progress execution window
<#>
<cmds>
<me_macroprogress_show>
<wx>(3000) <#> Wait 3 seconds
<me_macroprogress_hide>
<wx>(3000) <#> Wait 3 seconds
<me_macroprogress_show>
<wx>(3000) <#> Wait 3 seconds


<varout> : Send Variable Value To Target Application

 <display_findimage> : Find an Image on Computer Screen

This command searches for defined image(s) on computer screen. If the image is found on the screen the command sets supplied coordinate variables. If multiple image files are defined using wildcards then [x,y] position variables for each image are created for each image file. For example, if image files are defined using "c:\find_images\*.bmp" and there are "Button.bmp" and "Title.bmp" image files in the "c:\find_images" folder then variables "button.bmp_x" and "button.bmp_y" variables that defines position of the "Button.bmp" image on the screen is created. The same for "title.bmp" file there are "title.bmp_x" and "title.bmp_y" variable created. Using such variables it is possible to determine what images were found and what are their position on the screen. Image file names are always converted to lowercase.

Syntax:

<display_findimage>("Image File", StartSearchX, StartSearchY, VarResultX, VarResultY, ExactMatch, AreaWidth, AreaHeight)

Image File
Full path to the image file. This is a bitmap image that is captured using "Capture..." feature in the <display_findimage> command editor. In addition, multiple image files are supported by wildcards (* and ?).

StartSearchX
X-coordinate where to start searching on the computer screen.

StartSearchY
Y-coordinate where to start searching on the computer screen.

AreaWidth
It is possible to scope searching to an area smaller than the whole screen. This attribute specifies the width of the searching area. If this parameter is set to "0" then the whole screen width is being searched.

AreaHeight
It is possible to scope searching to an area smaller than the whole screen. This attribute specifies the height of the searching area. If this parameter is set to "0" then the whole screen height is being searched.

VarResultX
Name of the variable that receives X-coordinate of the position of the image on the screen. If the image is not found then the variable receives "-1".

VarResultY
Name of the variable that receives Y-coordinate of the position of the image on the screen. If the image is not found then the variable receives "-1".

ExactMatch
If 0 then the image does not has to exactly match, a certain level of tolerance is allowed.
If 1 then the image has to exactly match.

Example:

<#> This example shows how to find "Start" button on the screen and click on it
<cmds>

<display_findimage>("C:\PicturesForMacros\StartButton.bmp",0,0,vStartButtonX,vStartButtonY, 0)

<if>("%vStartButtonX% > -1")

<#> Start button found, move cursor on it...
<mm>(%vStartButtonX%,%vStartButtonY%)

<#> ...and click
<mlbd><mlbu>

<else>

<#> Start button not found, show message.
<msg>(-100,-100,"The Start button was not find on the screen. Possible reasons are:

1) The Task bar is hidden.
2) The Start button is overlapped by some window.
3) The StartButton.bmp file contains picture other than how Start button looks like.","Message",1,0,2)

<endif>


<display_captureimage> : Capture an Image on Computer Screen

This command captures an image on computer screen.

Syntax:

<display_captureimage>(X, Y, Wdt, Hgt, "ImageFile")

X
X coordination of the upper left corner of the area to be captured.

Y
Y coordination of the upper left corner of the area to be captured.

Wdt
Width of the area to be captured. If it is set to "0" then whole screen is captured.

Hgt
Height of the area to be captured.

Image File
Name (or full path) of the resulting image file.

Example:

<#> This macro shows how to capture display picture
<cmds>

<display_captureimage>(0,0,0,0,"%_vFolder_Personal%\ScreenImage.bmp")

<msg>(-100,-100,"Do you want to see the captured image now?","Message",2,0,1)

<if>("_vMsgButton==YES")
<fileopen>("%_vFolder_Personal%\ScreenImage.bmp",0)
<endif>


<display_getpixel> : Get Pixel Color

Retrieves color on the given position on screen.

Syntax:

<display_getpixel>(Xpos, Ypos, VarColor)

Xpos
X-coordinate (in screen coordinates) of the point.

Xpos
Y-coordinate (in screen coordinates) of the point.

VarColor
Variable that receives the color (as a number).

Example:

<#> This macro will show how to use 'get pixel' command:
<#>
<cmds>

<msg>(-100,-100,"Move mouse cursor to white color area and press 'Enter' key.","Message",1)

<display_getpixel>(_vMousePosX,_vMousePosY,vColor)

<if_num>("vColor==16777215")
<msg>(-100,-100,"Yes, mouse cursor is on white color area.","Message",1)
<else>
<msg>(-100,-100,"No, mouse cursor is not on white color area.","Message",1)
<endif>


<display_changewallpaper> : Change Wallpaper

This command changes wallpaper on Windows desktop.

Syntax:

<display_changewallpaper>(WallpaperFile)

WallpaperFile
Full path to file with wallpaper image.

Example:

<#> This macro changes wallpaper image
<#>
<cmds>

<var_oper>(vWallpaperFile,"c:\winnt\*.bmp",SELECT_FILE,"","", "0")

<if_str>("vWallpaperFile != _vEmptyStr")
<display_changewallpaper>(vWallpaperFile)
<msg>(-100,-100,"Wallpaper changed!","Message",1)
<endif>


<scrsavestart> : Start Screen saver

This command starts default screen saver.

Syntax:

<scrsavestart>

Example:

<#> This macro starts screen saver
<#>
<cmds>
<scrsavestart>


<scrsaver_enable> : Enables Screen saver

This command enables screen saver so that it can be started.

Syntax:

<scrsaver_enable>

Example:

<#> This macro enables screen saver
<#>
<cmds>
<scrsaver_enable>


<scrsaver_disable> : Disables Screen saver

This command disables screen saver so that it can not be started.

Syntax:

<scrsaver_disable>

Example:

<#> This macro disables screen saver
<#>
<cmds>
<scrsaver_disable>


<printer_setdefault> : Set Default Printer

Sets specified printer to be the default one.

Syntax:

<printer_setdefault>(PrinterName)

PrinterName
Name of the printer to be set as default.

Example:

<#> This macro changes default printer
<#>
<cmds>
<printer_setdefault>(PRN1)


<findfilesdlg> : Opens a File Search Window

Opens a file search window.

Syntax:

<findfilesdlg>

Example:

<#> This macro opens search files window
<#>
<cmds>
<findfilesdlg>


<findcompdlg> : Opens a Computer Search Window

Opens a computer search window.

Syntax:

<findcompdlg>

Example:

<#> This macro opens search computer window
<#>
<cmds>
<findcompdlg>


<rundlg> : Opens a "Run" Window

Opens a "Run" window.

Syntax:

<rundlg>

Example:

<#> This macro opens a "Run" window
<#>
<cmds>
<rundlg>


<contextmenu> : Shows Context Menu

Shows context menu.

Syntax:

<contextmenu>

Example:

<#> This macro shows context menu
<#>
<cmds>
<contextmenu>


<recbinempty> : Empties Recycle Bin

This command empties recycle bin.

Syntax:

<recbinempty>

Example:

<#> This macro empties recycle bin
<#>
<cmds>
<recbinempty>


<shutdown> : Shutdown/Reboot Computer

Exit Windows, shutdown computer, log off user.

Syntax:

<shutdown>("How", Force)

How
Can be one of these values:
"LOGOFF"
"REBOOT"
"SHUTDOWN"
"POWEROFF"

Force
If 1, the shutdown will proceed even if there is an application that refuses shutdown due unsaved data or other reason. In such the case there can be a data loss. If 0, the shutdown will proceed only if all the running applications accepts system shutdown query.

Example:

<#> This macro will reboot computer
<#>
<cmds>
<shutdown>("REBOOT",0)


<setsystime> : Set System Time

Sets system time.

Syntax:

<setsystime>(Hour, Minute, Second)

Hour
Hour of the newly set system time.

Minute
Minute of the newly set system time.

Second
Second of the newly set system time.

Example:

<#> This macro will set system time to 05:00:00
<#>
<cmds>
<setsystime>(5,0,0)


<setsysdate> : Set System Date

Sets system date.

Syntax:

<setsysdate>(Year, Month, Day)

Year
Year of the newly set date.

Month
Month of the newly set date.

Day
Day of the newly set date.

Example:

<#> This macro will set system date Feb 1, 2004
<#>
<cmds>
<setsysdate>(2004,2,1)


<post_win_msg> : Post Window Message

Posts Windows message (the same as PostMessage Windows API call).

Syntax:

<post_win_msg>(Win, Msg, WParam, LParam)

Win
Title of the window to activate or HWND. HWND is a unique handle Windows internally uses to identify each window. The HWND can be retrieved by some commands (<wininfo>, <win_enumerate>) or is provided by some system variables (_vKeybdFocusWindow_HWND, _vActiveWindow_HWND, _vActiveWindowPrev_HWND).

Msg
Windows message ID (decimal number).

WParam
WParam parameter of the Windows message (decimal number).

LParam
LParam parameter of the Windows message (decimal number).

Example:

<#> This macro controls WinAmp (if opened).
<#>
<cmds>
<varset>("vWin=WinAmp","")
<if_win>("vWin","OPEN",0)
<menu_additem>("Play")
<menu_additem>("Pause")
<menu_additem>("Stop")
<menu_additem>("Next")
<menu_additem>("Previous")
<menu_additem>("Next")
<menu_show>(-1,-1,vCommand,1,0)
<if_str>("vCommand == Play")
<post_win_msg>(vWin,273,40045,0)
<endif>
<if_str>("vCommand == Pause")
<post_win_msg>(vWin,273,40046,0)
<endif>
<if_str>("vCommand == Stop")
<post_win_msg>(vWin,273,40047,0)
<endif>
<if_str>("vCommand == Next")
<post_win_msg>(vWin,273,40048,0)
<endif>
<if_str>("vCommand == Previous")
<post_win_msg>(vWin,273,40044,0)
<endif>
<endif>


<reg_createkey> : Create Registry Key

This command creates required registry key.

Syntax:

<reg_createkey>("RegKey")

RegKey
Full path of registry key to be created. Example: "HKEY_CURRENT_USER\Software\MyCompany\NewKey"

Example:

<#> This command create new 'TestKey key
<#> in 'HKEY_CURRENT_USER\Software'
<cmds>
<reg_createkey>("HKEY_CURRENT_USER\Software\TestKey")


<reg_deletekey> : Delete Registry Key

This command deletes specified registry key.

Syntax:

<reg_deletekey>("RegKey")

RegKey
Full path of registry key to be deleted. Example: HKEY_CURRENT_USER\Software\MyCompany\NewKey

Example:

<#> This command deletes 'TestKey' key
<#> from 'HKEY_CURRENT_USER\Software'
<cmds>
<reg_deletekey>("HKEY_CURRENT_USER\Software\TestKey")


<reg_setvalue> : Set Registry Value

This command sets defined registry value.

Syntax:

<reg_setvalue>("RegKey", "ValueIdentifier", "Value", "ValueType" )

RegKey
Full path of registry key to be deleted. Example: HKEY_CURRENT_USER\Software\MyCompany\NewKey

ValueIdentifier
Name of the value. Example: ProductName.

Value
Value. Example: Macro Toolworks.

ValueType
0 - String value.
1 - Numeric value.

Example:

<#> This command sets ProductName value
<#> of 'HKEY_CURRENT_USER\Software\TestKey'
<#> to Something
<cmds>
<reg_setvalue>("HKEY_CURRENT_USER\Software\TestKey","ProductName","Something","0")


<reg_getvalue> : Get Registry Value

This command retrieves defined registry value.

Syntax:

<reg_getvalue>("RegKey", "ValueIdentifier", "Variable")

RegKey
Full path of registry key to be deleted. Example: HKEY_CURRENT_USER\Software\MyCompany\NewKey

ValueIdentifier
Name of the value. Example: ProductName.

Variable
Variable that receives value retrieved.

Example:

<#> This command retrieves ProductName value
<#> of 'HKEY_CURRENT_USER\Software\TestKey'
<cmds>
<reg_getvalue>("HKEY_CURRENT_USER\Software\TestKey","ProductName","v")
<msg>(-100,-100,"The retrieved value: %v%","Message",1)


<reg_deletevalue> : Delete Registry Value

This command deletes defined registry value.

Syntax:

<reg_deletevalue>("RegKey", "ValueIdentifier")

RegKey
Full path of registry key to be deleted. Example: HKEY_CURRENT_USER\Software\MyCompany\NewKey

ValueIdentifier
Name of the value. Example: ProductName.

Example:

<#> This command retrieves ProductName value
<#> of 'HKEY_CURRENT_USER\Software\TestKey'
<cmds>
<reg_deletevalue>("HKEY_CURRENT_USER\Software\TestKey","ProductName")


<reg_enumsubkeys> : Enumerate Registry Subkeys

This command enumerates all subkeys of the given key. The result (array of subkeys names) is saved in variable.

Syntax:

<reg_enumsubkeys>("RegKey", "VarSubkeys", "VarNumOfSubkeys")

RegKey
Full path of registry key to be deleted. Example: HKEY_CURRENT_USER\Software\MyCompany\NewKey

VarSubkeys
Variable (array) that receives subkeys found.

VarNumOfSubkeys
Variable that receives number of subkeys found.

Example:

<#> This example shows how to enumerate registry keys
<#>
<cmds>
<reg_enumsubkeys>("HKEY_CURRENT_USER\Software","vSubKey","vNumOfSubkeys")
<msg>(-100,-100,"There are %vNumOfSubkeys% registry subkeys of 'HKEY_CURRENT_USER\Software' registry key. Showing first three:
%vSubKey[0]%
%vSubKey[1]%
%vSubKey[2]%
","Message",1)


<reg_enumvalues> : Enumerate Registry Values

This command enumerates all values of the given key. The result (array of subkeys names) is saved in variable.

Syntax:

<reg_enumvalues> ("RegKey", "VarValues", "VarNumOfValues")

RegKey
Full path of registry key to be deleted. Example: HKEY_CURRENT_USER\Software\MyCompany\NewKey

VarValues
Variable (array) that receives values found.

VarNumOfValues
Variable that receives number of values found.

Example:

<#> This example shows how to enumerate registry values
<#>
<cmds>
<reg_enumvalues>("HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer","vValue","vNumOfValues")
<msg>(-100,-100,"There are %vNumOfValues% registry subkeys of 'HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer' registry key. Showing first three:

%vValue[0]%
%vValue[1]%
%vValue[2]%
","Message",1)


<process_enum> : Enumerate Processes

This command enumerate all running processes.

Syntax:

<process_enum> ("vProcesses", "vNumOfProcesses")

vProcesses
Variable (array) that receives running processes.

vNumOfProcesses
Variable that receives number of items added to vProcesses variable.

Example:

<#> This example enumerates running processes and lists them in Notepad
<#>
<cmds>
<process_enum>("vProcess","vNumOfProcesses")

<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","ACT","Notepad",5,0)
<if_win>("Notepad","ACT",0)
<keys>These processes are running:<newline><newline><cmds>
<begloop>(vNumOfProcesses)
<varout>("vProcess[_vLoopCounter0]",0)<keys><newline><cmds>
<endloop>

<endif>


<process_kill> : Kill Process

This command kills defined process. Killing process is different from closing application (window) using <winclose> command. Killing process may result to loosing unsaved data in the process.

Syntax:

<process_kill>(ExecutableName)

ExecutableName
Name of the executable file to kill. Example: notepad.exe

Example:

<#> This example kills Notepad
<#>
<cmds>
<process_kill>(notepad.exe)


<extmacro> : Run External Macro

 <extcmd> : Run External Command

Runs an external command. The external commands allow 3rd-parties to extend the #THIS_PROGRAM# macro language capability by adding own commands. The external command can be any (command line) executable file that takes parameters (optionally) and prints result to standard output. The #THIS_PROGRAM# takes the printed result from standard output and assigns it to user-defined macro language variable. This is big difference from <execappex> command that also allows to run executables with parameters but is not capable of getting the executable output.

The external command can be written in VBS, for example. However, the VBS engine outputs some copyright information at the start of the script execution. If the user does not want to have such the information as a part of own script result then the user can put this line at the begin of VBS script:

Wscript.StdOut.Write ">>>cmd_results>>>"

This line tells #THIS_PROGRAM# where actual results start and the #THIS_PROGRAM# ignores all the output printed before.

Syntax:

<extcmd>("ExtCommandFile", "Parameters", Timeout, VariableReceivingResult)

ExtCommandFile
This can be either full path to an executable file or just a name with ".ec...." extension (for example, "SimplePing.ec.vbs"). If the full path is not supplied then the executable file must be located in "ExternalCommands" folder in #THIS_PROGRAM# installation folder.

Parameters
Parameters that will be passed to the external command. The number of the parameters depends on the external command.

Timeout
Timeout in seconds. If the external command does not finishes its execution in the defined timeout then the command fails.

VariableReceivingResult
This is the user-defined variable that will receive the external command result.

Example 1:

<#> This command pings to the www.pitrinec.com web site
<cmds>
<extcmd>("SimplePing.ec.vbs","www.pitrinec.com",15,vResult)
<if_str>("vResult==1")
<msg>(-100,-100,"Ping OK.","Message",1,0,0)
<else>
<msg>(-100,-100,"Ping failed.","Message",1,0,0)
<endif>

Example 2:

<#> This command shows "Hello World" message
<cmds>
<extcmd>("HelloWorld.ec.exe","",2,v)
<msg>(-100,-100,"%v%","Message",1,0,0)


Examples

In this section, there are several examples that you can copy/paste and run immediately. The examples show how to use various commands, how to work with variables and how to write macros to be reliable.


Activate or run Notepad

<#>
<#> Sample: Activate Notepad window if Notepad is running or
<#> start it if it is not running yet.
<#>
<cmds>
<me_error_nodisplay>
<actwin>("mw[[ ]] mc[[ Notepad ]] cw[[ ]] cc[[ ]] ",0,0,"no")
<if_str>("_vErr!=NO")
   <me_error_clear>
   <execappex>("Notepad.exe","","",0,0)
<endif>
<me_error_display>


Add prefix and postfix text to each line in text file

<#>
<#> This sample adds prefix and postfix text to each line in a selected text file
<#>
<cmds>

<form_item>("f1","Input file:","EDIT_FILE","*.txt","vInputFile")
<form_item>("f1","Output file:","EDIT_FILE","%_vFolder_Temp%\output.txt","vOutputFile")
<form_item>("f1","Prefix:","EDIT",">>>","vPrefix")
<form_item>("f1","Postfix:","EDIT","<<<","vPostfix")
<form_show>("f1","Form","shell32.dll",0,,0)
<if_str>("_vCanceled==1")<exitmacro><endif>

<data_load>("vbTemp_FileText","vInputFile","")
<data_save>("","vOutputFile","")
<if_str>("_vErr==NO")
   <var_oper>(vbTemp_NumOfLines,"vbTemp_FileText",TEXT_GET_NUMOFLINES,"","", "0")
   <begloop>(vbTemp_NumOfLines)

      <var_oper>(vbTemp_LineText,"vbTemp_FileText",TEXT_GET_LINE,"_vLoopCounter","", "0")
      <-dbp->

      <var_oper>(vbTemp_LineText,"%vbTemp_LineText%",STR_INSERT,"0","%vPrefix%", "0")
      <var_oper>(vbTemp_LineText,"%vbTemp_LineText%",STR_APPEND,"%vPostfix%%_vKeyReturn%","", "0")

      <data_save>("vbTemp_LineText","vOutputFile","A")

   <endloop>

<else>
   <msg>(-100,-100,"_vError","File Error",1)
<endif>

<msg>(-100,-100,"Do you want to open output file now?","Message",2)
<if_str>("_vMsgButton==YES")
   <fileopen>("%vOutputFile%",0)
<endif>


Close all Notepad windows

<#>
<#> This sample Closes all Notepad windows
<#>
<cmds>
<me_error_nodisplay>

<label>("CloseNext")
<winclose>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",0)

<if_str>("_vErr==NO")
   <goto>("CloseNext")
<else>
   <me_error_clear>
<endif>

<me_error_display>


Convert clipboard text to uppercase

<#>
<#> This sample converts clipboard text to uppercase.
<#>
<cmds>
<var_oper>(vClipboardText,"",GET_TEXT_FROM_CLIPBOARD,"","", "0")
<if_str>("vClipboardText!=_vStrEmpty")

   <var_oper>(vClipboardText,"%vClipboardText%",STR_UPPER,"","", "0")
   <clpput>("vClipboardText")

<else>


Detects if notepad.exe is running and kills it on users request

<#>
<#> Sample: Detects if notepad.exe is running and kills it on users request.
<#>
<cmds>

<if_process>(notepad.exe,EXIST)

   <msg>(-100,-100,"Notepad.exe is running. Do you want to kill it?","Message",2)
   <if_str>("_vMsgButton==YES")
      <process_kill>(notepad.exe)
   <endif>
<else>
   <msg>(-100,-100,"Notepad.exe is not running.","Message",1)
<endif>


Filter formatted text out of clipboard - leave only unformatted text in clipboard

<#>
<#> Filter formatted text out of clipboard - leave only unformatted text in clipboard
<#>
<cmds>
<var_oper>(vClipboardText,"",GET_TEXT_FROM_CLIPBOARD,"","", "0")
<if_str>("vClipboardText==_vStrEmpty")
   <msg>(-100,-100,"There is NO text in clipboard. ","Message",1)
<else>
   <clpput>("%vClipboardText%")
<endif>


Generate file name containing current date

<#> This example shows how to generate a file name containing
<#> current date:
<cmds>
<form_item>("f1","Original file name:","EDIT","MyFileName","vOriginalFileName")
<form_item>("f1","File extension:","EDIT",".txt","vFileExtension")
<form_show>("f1","File Name","shell32.dll",0,0,0)
<if_str>("_vCanceled == 1") <exitmacro> <endif>

<varset>("vNewFileName=%vOriginalFileName%-%_vCurrDate_Year%-%_vCurrDate_MM%-%_vCurrDate_DD%%vFileExtension%","")

<msg>(-100,-100,"vNewFileName","Message",1)


Generate letter from information defined in form

<#>
<#> Sample: Start Notepad and generate cutomer's letter based on
<#> what is selected in form.
<#>
<cmds>

<#> Initialize and show form:

<form_item>("f1","Customer name:","EDIT","","vCustomerName")
<form_item>("f1","Service:","LIST","UNIX Virtual Server|NT Virtual Server|UNIX Dedicated Server|NT Dedicated Server","vService")
<form_item>("f1","Discount (in %):","LIST","0|5|10|20|30|50","vDiscount")
<form_item>("f1","Support staff:","LIST","John McSmith|Adrian Mane|Brigita Largo","vStaff")
<form_show>("f1","Customer Requests Information About Service","shell32.dll",0)
<if_str>("_vCanceled == 1") <exitmacro> <endif>

<#> Start Notepad and make it active window
<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","OPEN","mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",5,0)
<actwin>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",0,0,"no")
<if_win>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ","ACT",0)

<if_str>("vService==UNIX Virtual Server")
   <varset>("vPrice=99.95","")
<endif>
<if_str>("vService==NT Virtual Server")
   <varset>("vPrice=79.95","")
<endif>
<if_str>("vService==UNIX Dedicated Server")
   <varset>("vPrice=299.95","")
<endif>
<if_str>("vService==NT Dedicated Server")
   <varset>("vPrice=259.95","")
<endif>

<var_oper>(vDiscountedPrice,"%vPrice%-(%vPrice%*(%vDiscount%/100))",CALC_EXPRESSION,"2","", "0")

<#> Start writing letter here:
<keys>Dear <varout>("vCustomerName",0),

thank you very much for contacting us concerning our
web hosting services.  Find below some facts about
the service you are interested in.  We are glad we can
offer you discounted price!

-------------------------------------------------------
Customer: <varout>("vCustomerName",0)
Service: <varout>("vService",0)
Bandwith: Unlimited
Price: <varout>("vPrice",0)/month
Discount: <varout>("vDiscount",0)%
Price after discount:<varout>("vDiscountedPrice",0)/month
-------------------------------------------------------

Feel free to contact us with any question any time.

<varout>("vStaff",0)
The Service Company Support


Insert current date to file name (uses procedures)

<#>
<#> This sample inserts current date to name of the selected file
<#>
<#>
<cmds>

<proc_def_begin>(GetDateString, "&vDateString&"  )
   <varset>("vDateString=-%_vCurrDate_Year%-%_vCurrDate_MM%-%_vCurrDate_DD%","")
<proc_def_end>

<proc_def_begin>(InsertDateToFileName, "&vFileName&"  )
   <proc_call>(GetDateString,"vDateString")
   <var_oper>(vbLnt,"%vFileName%",STR_LENGTH,"","", "0")
   <begloop>(vbLnt)
      <var_oper>(vbInx,"%vbLnt%-%_vLoopCounter%",CALC_EXPRESSION,"0","", "0")
      <var_oper>(vbChar,"%vFileName%",STR_GET_CHAR,"vbInx","", "0")
      <if_str>("vbChar==.")
         <var_oper>(vFileName,"%vFileName%",STR_INSERT,"vbInx","%vDateString%", "0")
         <goto>("lbl_b_End")
      <endif>
   <endloop>
   <var_oper>(vFileName,"%vFileName%",STR_APPEND,"%vDateString%","", "0")
   <label>("lbl_b_End")
<proc_def_end>

<var_oper>(vFile,"",SELECT_FILE," ","", "0")
<if_str>("_vCanceled == 1") <exitmacro> <endif>
<proc_call>(InsertDateToFileName,"vFile")
<msg>(-100,-100,"vFile","Message",1)


Insert time & date to Notepad

<#>
<#> Sample: Start Notepad and insert time & date
<#>
<cmds>
<#> Start Notepad and make it active window
<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","OPEN","mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",5,0)
<actwin>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",0,0,"no")
<if_win>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ","ACT",0)

<#> Insert time & date here:
<keys>Current time:<time>(0,1,1,1,1)
Current date: <date>(9,"/",1,1,0)

Current date formatted a diferent way using a variable and system variables: <cmds>
<varset>("vDate=<%_vCurrDate_DD%><%_vCurrDate_MM%><%_vCurrDate_Year%>","")
<varout>("vDate",0)
<endif>


Is connected to internet

<#>
<#> This sample shows how to check if computer is connected to internet
<#>
<cmds>
<if_str>("_vIsConnectedToInternet==YES")
   <msg>(-100,-100,"Computer is connected to internet.","Message",1)
<else>
   <msg>(-100,-100,"Computer is NOT connected to internet.","Message",1)
<endif>


List files from selected directory

<#>
<#> Sample: List files from selected directory
<#>
<cmds>

<var_oper>(gm_vbiDirectory,"",SELECT_FOLDER,"","", "0")
<if_str>("_vCanceled==1")<exitmacro><endif>

<file_enum>("%gm_vbiDirectory%\*.*",2,vTemp_Files,vTemp_NumOfFiles)

<if_num>("vTemp_NumOfFiles==0")
   <msg>(-100,-100,"No files found in selected directory.","Message",1)
   <exitmacro>
<endif>

<#> Start Notepad and make it active window
<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","OPEN","mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",5,0)
<actwin>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",0,0,"no")

<if_win>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ","ACT",0)

<begloop>(vTemp_NumOfFiles)
   <varout>("vTemp_Files[_vLoopCounter0]",0)
   <newline>
<endloop>

<endif>


Math expressions calculator

<#>
<#> Sample: Mathematical expressions calculator
<#>
<cmds>

<form_item>("f1","Math. Expression:","EDIT","","vExpression")
<form_item>("f1","Example: 1+(3/2-3.212)^2","TEXT","","")

<label>("Show")

<form_show>("f1","Mathematical Expression Calculator","shell32.dll",12)
<if_str>("_vCanceled == 1") <exitmacro> <endif>

<var_oper>(vResult,"%vExpression%",CALC_EXPRESSION,"4","", "0")
<msg>(-100,-100,"vResult","Result:",1)

<goto>("Show")


Parse full file path to components

<#>
<#> Parse full file path to drive, directory and file name components
<#>
<cmds>

<var_oper>(vInputFile,"",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1")<exitmacro><endif>

<var_parse>("vInputFile",":\","",vFilePathComponents,vNumOfFilePathComponents)

<var_oper>(vNumOfFilePathComponents,"%vNumOfFilePathComponents%-1",CALC_EXPRESSION,"0","", "0")

<#> File Name:
<varset>("vOutput_FileName=vFilePathComponents[vNumOfFilePathComponents]","")

<var_oper>(vNumOfFilePathComponents,"%vNumOfFilePathComponents%-1",CALC_EXPRESSION,"0","", "0")

<#> Drive Letter:
<varset>("vOutput_Drive=vFilePathComponents[0]","")
<var_oper>(vTemp,"%vOutput_Drive%",STR_LENGTH,"","", "0")
<if_num>("vTemp>1")
   <#> This is network path like \\server\directory\,,,\
   <varset>("vOutput_Drive=\\%vOutput_Drive%\","")
<else>
   <#> This is local path like c:\directory\,,,\
   <varset>("vOutput_Drive=%vOutput_Drive%:\","")
<endif>

<#> Directory:
<varset>("vOutput_Directory=_vStrEmpty","")

<begloop>(vNumOfFilePathComponents)
   <var_oper>(vOutput_Directory,"%vOutput_Directory%",STR_APPEND,"%vFilePathComponents[_vLoopCounter]%\","", "0")
<endloop>

<msg>(-100,-100,"Original file: %vInputFile%

Drive: %vOutput_Drive%
Directory path: %vOutput_Directory%
File name: %vOutput_FileName%","Message",1)


Process lines in text file

<#>
<#> This sample process lines in text file
<#>
<cmds>

<var_oper>(vFile,"",SELECT_FILE,"Select File","", "0")
<if_str>("_vCanceled==1")<exitmacro><endif>

<data_load>("vbTemp_FileText","%vFile%","")
<if_str>("_vErr==NO")
   <var_oper>(vbTemp_NumOfLines,"vbTemp_FileText",TEXT_GET_NUMOFLINES,"","", "0")
   <begloop>(vbTemp_NumOfLines)
      <var_oper>(vbLine,"vbTemp_FileText",TEXT_GET_LINE,"_vLoopCounter","", "0")
      <msg>(-100,-100,"INSTEAD OF THIS MESSAGE, YOU CAN DO YOUR OWN FILE LINE PROCESSING.

Line number:
%_vLoopCounter%

Line content:
%vbLine%
","Message",1)
   <endloop>
<else>
   <msg>(100,100,"_vError","Error",1)
<endif>


Retrieve e-mail addresses from a text file

<#>
<#> Sample: Retrieve e-mail addresses from a text file
<#>
<cmds>

<msg>(100,100,"Select text file containing e-mail addresses to retrieve.","Message",0)
   <var_oper>(vbFilePath_Input,"*.txt",SELECT_FILE,"Select File","", "0")
   <if_str>("_vCanceled==1")<exitmacro><endif>
<msgoff>

<varset>("vNumOfEmailAddresses=0","")
<data_load>("vbTemp_FileText","vbFilePath_Input","")
<if_str>("_vErr==NO")

   <var_parse>("vbTemp_FileText","!#$^&*+=?';\~`<>:| %_vKeyReturn%()[]{},/%_vKeyTab%%_vQuoteChar%%_vKeyPercent%","",vbTemp_Word,vbTemp_NumOfWords)
   <begloop>(vbTemp_NumOfWords)

      <if_str>("vbTemp_Word[_vLoopCounter0]~=@")
         <if_str>("vbTemp_Word[_vLoopCounter0]~=.")
               <var_oper>(vNumOfEmailAddresses,"%vNumOfEmailAddresses%+1",CALC_EXPRESSION,"0","", "0")
               <msg>(-100,-100,"INSTEAD OF THIS MESSAGE, YOU CAN DO YOUR OWN E-MAIL ADDRESS PROCESSING HERE.

E-mail address found: %vbTemp_Word[_vLoopCounter0]%","E-mail Address Retrieved",1)

         <endif>
      <endif>
   <endloop>

<else>
   <msg>(-100,-100,"_vError","File Error",1)
<endif>
<if_num>("vNumOfEmailAddresses==0")
   <msg>(-100,-100,"No e-mail address found in the file.","File Error",1)
<endif>


Run context menu command

<#>
<#> Sample: Shows properties dialog box of "C:\" drive using "run context menu" command
<#>
<run_ctxcommand>("c:\",Properties,0,0)<wx>(5000)


Select file and open it in Notepad

<#>
<#> Sample: Select file and open it in Notepad
<#>
<cmds>
<var_oper>(vFile,"",SELECT_FILE,"","", "0")
<if_str>("_vCanceled==1")<exitmacro><endif>
<execappex>("notepad.exe","vFile","",0,0)


Show menu of opened window and activate selected

<#>
<#> Sample: Shows menu of all opened window and activates the selected one
<#>
<cmds>

<win_enumerate>(vWindow,vNumOfWindows,0)

<if_num>("vNumOfWindows>0")

   <begloop>(vNumOfWindows)

      <if_str>("vWindow[_vLoopCounter0]!=_vStrEmpty")
         <menu_additem>("vWindow[_vLoopCounter0]")
      <endif>

   <endloop>

   <menu_show>(-1,-1,vWindowSelected,1,1)
   <if_str>("vWindowSelected!=NO")

      <actwin>("vWindowSelected",0,0,"no")

   <endif>

<endif>


Show registry subkeys

<#>
<#> Sample: Shows all subkeys of  HKEY_CURRENT_USER\Software
<#>
<cmds>

<reg_enumsubkeys>("HKEY_CURRENT_USER\Software",vKey,vNumOfKeys)

<if_num>("vNumOfKeys==0")
   <msg>(-100,-100,"No keys found under HKEY_CURRENT_USER\Software.","Message",1)
   <exitmacro>
<endif>

<#> Start Notepad and make it active window
<execappex>("notepad.exe","","",0,0)
<waitfor>("WIN","OPEN","mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",5,0)
<actwin>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",0,0,"no")

<if_win>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ","ACT",0)

<begloop>(vNumOfKeys)
   <varout>("vKey[_vLoopCounter0]",0)
   <newline>
<endloop>

<endif>


Shows how to use menus

<#>
<#> Sample: Shows how to use menus
<#>
<cmds>

<msg>(100,100,"What color do you like?","Message",0)

<menu_additem>("Red")
<menu_additem>("Blue")
<menu_additem>("White")
<menu_additem>("---")
<menu_additem>(".Other")
<menu_additem>(".Green")
<menu_additem>(".Black")
<menu_additem>(".Yellow")
<menu_additem>("..Yet another")
<menu_additem>("..Tell me what?")
<menu_additem>(".")
<menu_additem>(".")
<menu_additem>("---")
<menu_additem>("I do not like colors")

<menu_show>(-1,-1,vSelectedItem,1,0)

<msgoff>

<#> Remove leading . characters in a case the selected item is from submenu
<var_oper>(vSelectedItem,"%vSelectedItem%",STR_TRIMLEFT,".","", "0")

<msg>(-100,-100,"You have selected: %vSelectedItem%","Message",1)


Simple form example

<#>
<#> Simple form example
<#>
<cmds>

<form_item>("f1","Items:","LIST","Item1|Item2|Item3|Item4|Item5","vItem")
<form_item>("f1","Your name:","EDIT","","vName")
<form_item>("f1","I like it!","CHECK","YES","vLikeIt")
<form_item>("f1","This is just a sample.","TEXT","","")

<form_show>("f1","Sample Form","shell32.dll",2)
<if_str>("_vCanceled == 1") <exitmacro> <endif>

<msg>(-100,-100,"In the form you have selected:

Item: %vItem%
Your name: %vName%
I like it: %vLikeIt%
","Form Results",1)


Simple FTP file download

<#>
<#> Sample: Simple FTP file download
<#>
<cmds>
<varset>("vLocalFile=%_vFolder_Temp%hello.txt","")
<ftp_getfile>("vLocalFile","ftp://pitrinec.com/pub/hello.txt","anonymous","")
<if_str>("_vErr==NO")

   <msg>(-100,-100,"The file was downloaded OK.  It will be shown now.","Message",1)
   <execappex>("notepad.exe","vLocalFile","",0,0)

<endif>


Start Notepad and type text in it - safe way

<#>
<#> Sample: Start Notepad and type text in it - safe way
<#>
<cmds>
<execappex>("notepad.exe","","",0,0)
<#> Wait until Notepad is loaded
<waitfor>("WIN","OPEN","mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",5,0)
<#> Make Notepad window active
<actwin>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ",0,0,"no")
<#> Make sure the Notepad window is active
<if_win>("mw[[  ]] mc[[ Notepad ]] cw[[  ]] cc[[  ]] ","ACT",0)

<keys>Hello Notepad!<cmds> <#> Send keys (text) to Notepad (active window)

<endif>


Tests if clipboard contains text

<#>
<#> This sample tests whether clipboard contains some text.
<#>
<cmds>
<var_oper>(vClipboardText,"",GET_TEXT_FROM_CLIPBOARD,"","", "0")
<if_str>("vClipboardText==_vStrEmpty")
   <msg>(-100,-100,"There is NO text in clipboard. ","Message",1)
<else>
   <msg>(-100,-100,"There is this text in clipboard:

%vClipboardText%","Message",1)
<endif>


Clipboard Manipulation

This section describes commands that can be used to manipulate with Windows clipboard:

<clp_copyselected> Copy Selected Data To Clipboard
<clpsave> Save Data From Clipboard To File
<clpload> Load Data From Clipboard File To Clipboard
<clppastetext> Paste Text
<clpput> Put Text To Clipboard
<clpempty> Empty Clipboard

See also "System Variables" section for this topic related system variables.


Dial Up Commands

This section contains dial up commands:

<dialup> Establish Dial-up Connection
<hangup> Hang up - Close Connection

See also "System Variables" section for this topic related system variables.


Display Commands

This section describes screen and display related commands:

<display_getpixel> Retrieve Color Of the Specified Screen Pixel
 <display_changewallpaper> Change Wallpaper
<scrsavestart> S tart Default Screen Saver
<scrsaver_enable> Enables Screen Saver
<scrsaver_disable> Disables Screen Saver


Files & Folders

This section contains commands for file and folder manipulation.

<fileopen> Open File
<filecreate> Create New File
<filecopy> Copy File(s)
<filemove> Move File(s)
<filerename> Rename File
 <filedel> Delete File(s)
<fileinfo> Retrieve File Information
<file_enum> Enumerate Files and/or Folders
<data_load> Load Data From File To Variable
<data_save> Save Data To File

<dircreate> Create Folder
<diropen> Open Folder
<dircopy> Copy Folder
<dirmove> Move Folder
 <dirrename> Rename Folder
<dirdel> Delete Folder

See also "System Variables" section for this topic related system variables.


Forms

This section describes how to create user-defined forms. The forms make it possible to define multiple parameters (variables) that can be further used in the macro.

<form_item> Define Form Item
<form_show> Show Form

See the "System Variables" section also for the system variables related to this topic.


HWND

HWND is a unique handle Windows internally uses to identify each window. The HWND can be retrieved by some commands (<wininfo>, <win_enumerate>) or is provided by some system variables (_vKeybdFocusWindow_HWND, _vActiveWindow_HWND, _vActiveWindowPrev_HWND). While some other window attributes like window title or window class are not unique (there can be other windows with the same title or class) the HWND is unique.


Internet

This section contains Internet related commands:

<wwwopen> Open Web Page
<download> Download File (Using HTTP)
<email> Create New Email
<email_send> Send Email

<ftp_getfile> Download File (Using FTP)
<ftp_putfile> Upload File
<ftp_delfile> Delete File
<ftp_renamefile> Rename File
 <ftp_filesize> Retrieve File Size
<ftp_filetime> Get Last Modification Time
<ftp_createdir> Create Directory
<ftp_deldir> Delete Directory


 Macro Flow Control

This section describes macro flow control commands: If - else - endif, go-to, loop, wait, procedures and others.

<proc_def_begin> Begin Of Procedure Definition
<proc_def_end> End Of Procedure Definition
<proc_call> Call Procedure
<-include-> Include File Or Macro

<if> If (Compare Strings or Numbers)
<if_str> If (Compare Strings)
<if_num> If (Compare Numbers)
<if_win> If Window...
<if_file> If File...
<if_dir> If Directory (Folder)...
<if_clp> If Clipboard...
<if_key> If Key Or Mouse Button...
<if_process> If Process...
<else> Else Branch Of "If" Command
<endif> Closes "If" or "If-Else" Command

<goto> Go To Label...
<label> Label To Jump To

<begloop> Begin Of Loop Section
<endloop> End Of Loop Section

<pause> Pause Macro Execution For User's Input
<wx> Wait X Milliseconds
<waitfor> Wait For Special Event

<cmds> Execute Commands Only
<keys> Execute Unrecognized Macro Commands As Keystrokes

<faston> Send Keystrokes Fast
<fastoff> Send Keystrokes Slow

<me_error_nodisplay> Disable Automatic Displaying Of Error Messages
<me_error_display> Enable Automatic Displaying Of Error Messages
<me_error_clear> Clear Error

<-dbp-> Debug Break Point

<exitmacro> Exit Macro
<exitmacro_soft> Exit Macro - Soft


Macros Manipulation

This section describes commands that allow to manipulate with this program and currently loaded macros (macro file).

<me_macroenable> Enable/Disable Macro
<me_macroenable_group> Enable/Disable Macro Group
<me_changeicon> Change macro Icon
<me_exit> Exit Macro Program

See also "System Variables" section for this topic related system variables.


Menus And Selection Box

These commands make it possible to create menus and selection box:

<macromenu> Macro Menu
<listbox> Macro Selection List Box
<menu_additem> Add Item To Menu
<menu_show> Show Defined Menu

See also "System Variables" section for this topic related system variables.


Messages

This section describes commands that allow user to show message box on the screen:

<msg> Show Message
<msgoff> Close Message

See also "System Variables" section for this topic related system variables.


 Mouse & Keyboard

This section contains commands that allows user to manipulate mouse and keyboard - move mouse cursor, invoke a mouse button click, send keyboard keystrokes...

Insert Text (Send Keystrokes)

<keys_block>
Blocks keyboard input. This command has no parameters.
<keys_unblock>
Unb locks keyboard input. This command has no parameters.

<mm>
Move mouse cursor to defined position.
 <mousemove_relative_win>
This command changes behavior of “mouse move” (<mm>) command so that mouse will be moved in coordinates relative to currently active window. This command has no parameters.
<mousemove_absolute>
This command changes behavior of “mouse move” (<mm>) command so that mouse will be moved in absolute (screen) coordinates. This is default behavior. This command has no parameters.
<mousemove_relative_pos>
This command changes behavior of “mouse move” (<mm>) command so that mouse will be moved in coordinates relative to current mouse position. This command has no parameters.
<mousemove_relative_definedwindow>
This command changes behavior of “mouse move” (<mm>) command so that mouse will be moved in coordinates relative to defined window.

<mlbd>
Mouse left button down. This command has no parameters.
<mlbu>
Mouse left button up. This command has no parameters.
<mmbd>
Mouse middle button down. This command has no parameters.
<mmbu>
Mouse middle button up. This command has no parameters.
<mrbd>
Mouse right button down. This command has no parameters.
<mrbu>
Mouse right button up. This command has no parameters.
<mx1bd>
Mouse X1 button down (five button mouse only). This command has no parameters.
<mx1bu>
Mouse X1 button up (five button mouse only). This command has no parameters.
<mx2bd>
Mouse X2 button down (five button mouse only). This command has no parameters.
<mx2bu>
Mouse X2 button up (five button mouse only). This command has no parameters.


Multimedia

This section describes multimedia commands:

<beep> Play Sound
<multimedia> Controll Multimedia


Network Drive

This section contains commands that allow a user to automatically connect/disconnect network drives:

<netcondrive> Connect (Map) Network Drive
<netdiscondrive> Disconnect Network Drive
<netcondrivedlg> Connect network drive dialog window
<netdiscondrivedlg> Disconnect network drive dialog window


Printer Commands

This section contains printer related commands:

<printer_setdefault> Set Default Printer
<file_print> Print File


Process Control

There is described commands that allow users to control processes:

<process_enum> Enumerate Processes
<process_kill> Kill Process

See also "System Variables" section for this topic related system variables.


Registry Commands

There are described commands that allow to manipulate with Windows registry:

<reg_createkey> Create Key
<reg_deletekey> Delete Key
<reg_setvalue> Set Value
<reg_getvalue> Get Value
 <reg_deletevalue> Delete Value
 <reg_enumsubkeys> Enumerate Sub keys
 <reg_enumvalues> Enumerate Values

See also "System Variables" section for this topic related system variables.


 Run Commands

This section describes commands that allow user to start specified application, run other macro or perform shell context menu command of the specified file.

<execappex> | Start Application or Open a File
<run> | Run Other Macro
<extmacro> | Run External Macro
<run_ctxcommand> | Run Context Menu Command
<remote_macro_call> | Run Macro on Remote Computer

See also "System Variables" section for this topic related system variables.


System Commands

System commands:

<findfilesdlg> Find file dialog window
<findcompdlg> Find computer dialog window
<rundlg> Run dialog window
<contextmenu> Show context menu
<recbinempty> Empty recycle bin
<shutdown> Shutdown/Reboot
<setsystime> Set Computer System Time
<setsysdate> Set Computer System Date
<post_win_msg> Posts An Application Windows Message

See also "System Variables" section for this topic related system variables.


 Inserting Time & Date

This section describes commands that can be used to insert user formatted time and date to currently active window (document, edit box, etc.). There are many time and date formats available plus user can create its own formatting by combining multiple time/date commands.

<date> Inset Date
<time> Insert Time

<td:d> Today's Day
<td:dlz> Today's Day (With Leading Zero)
<td:m> Today's Month
<td:mlz> Today's Month (With Leading Zero)
<td:y> Today's Year
<ct:h24> Current Time - Hour (24 Based)
<ct:h24lz> Current Time - Hour (24 Based, With Leading Zero)
<ct:h12> Current Time - Hour (12 Based)
<ct:h12lz> Current Time - Hour (12 Based, With Leading Zero)
<ct:m> Current Time - Minute
<ct:mlz> Current Time - Minute (With Leading Zero)
<ct:ampm> Current Time - am/pm
<ct:AMPM> Current Time - AM/PM

There are also several time/date system variables. The system variables can be used for building strings (variables) containing the time or date, for example, backup file names. See also "System Variables" section for this topic related system variables.


Variable & Text Manipulation

 Variable & Text Manipulation Commands

This section describes commands for text and variables manipulation. There are several commands that allow user to format text, performa arithmetical operations and manipulate strings and variables many other ways.

<var_set> Assign Variable Value
<var_oper> Modify Variable Value
<var_parse> Parse Text (Variable Value)
<varout> Send Variable Value To Target Application
<var_save> Save Variable To File
<var_load> Load Variable From File

See also "System Variables" section for this topic related system variables.


Window Manipulation

This chapter contains windows manipulation commands:

<actwin> Make Window Active
<winmove> Move Window To Given Position
<winresize> Resize Window
<winstate> Change Window State
<wininfo> Retrieve Window Info
<winclose> Close Window
<win_enumerate> Enumerate Windows

Desktop Windows:
<winminall> Minimize all windows
<wintile_h> Tile windows horizontally
<wintile_v> Tile windows vertically
<wincascade> C ascade windows

See also "System Variables" section for this topic related system variables.


Window Identification Path

Window Identification Path (WIP)

Window Identification Path (WIP) is a sequence of information that allows to uniquely identify Window. The WIP is used as a parameter for many windows commands such as <win_findimage>, <win_captureimage>, <winclose>, etc. The user does not has to enter the WIP manually when editing a window command in visual editor. The user rather put mouse cursor on the window he/she wants to use and the WIP is created automatically. The WIP contains a hierarchical structure (parent/child) of the windows. Each window is defined by window title, window class and X, Y position (X,Y position is used for window identification only if there are multiple windows with the same window title and window class).

It is possible to use wildcards (* and ?) within a WIP. There are examples how "Notepad" window is activated:

<actwin>("[A*.txt - Notepad|Notepad|#0|#0]",0,0,"no")
- this command activates Notepad windows with titles such as "Audrey.txt - Notepad", "Aaron.txt - Notepad", "Abbey.txt - Notepad"

<actwin>("[B*.txt - Notepad|Notepad|#0|#0]",0,0,"no")
- this command activates Notepad windows with titles such as "Bred.txt - Notepad", "Boris.txt - Notepad", "Bradley.txt - Notepad"

<actwin>("[*.txt - Notepad|Notepad|#0|#0]",0,0,"no")
- this command activates Notepad windows with titles such as "Audrey.txt - Notepad", "Bradley.txt - Notepad", "Jane.txt - Notepad"

<actwin>("[Untitled - Notepad|Notepad|#0|#0]",0,0,"no")
- this command activates only Notepad window with title "Untitled - Notepad"

<actwin>("[*Notepad|Notepad|#0|#0]",0,0,"no")
- this command activates Notepad windows with titles such as "Audrey.txt - Notepad", "Untitled - Notepad", "page.html - Notepad"


Files & Folders

ZIP Files

This section contains commands for file and folder manipulation.

<fileopen> Open File
<filecreate> Create New File
<filecopy> Copy File(s)
<filemove> Move File(s)
<filerename> Rename File
 <filedel> Delete File(s)
<fileinfo> Retrieve File Information
<file_enum> Enumerate Files and/or Folders
<data_load> Load Data From File To Variable
<data_save> Save Data To File

<dircreate> Create Folder
<diropen> Open Folder
<dircopy> Copy Folder
<dirmove> Move Folder
 <dirrename> Rename Folder
<dirdel> Delete Folder

See also "System Variables" section for this topic related system variables.