WinParrot® 2.1.2

WinParrot.com

 

Main news

New functions :

FileListLoad, FileListGet, FileGetName, FileGetPath, FileGetExt, FileCopy, FileDelete, FileMove & Random

 

 

Version: 2.1.2

June 2012

Document  N°: A27062012
Summary

 

1.     Presentation. 6

2.     Install / Uninstall 8

3.     Start to record. 10

4.     Start the playback. 10

5.     Records. 11

6.     Command lines. 12

7.     Instructions. 12

8.     Locations. 13

9.     Events. 14

10.       Variables. 16

10.1.        System variables. 16

10.2.        Time variables. 16

10.3.        User variables. 17

11.       Operators. 18

11.1.        The assignment operator 18

11.2.        Logical operators. 18

11.3.        Operators of integers or floats. 19

11.4.        Operators of strings. 19

12.       Functions. 21

12.1.        Abs. 21

12.2.        AppForeground. 22

12.3.        AppResize. 23

12.4.        AppWait 24

12.5.        Ask. 24

12.6.        Ask3. 25

12.7.        Beep. 26

12.8.        Debug. 27

12.9.        FileCopy. 28

12.10.      FileDelete. 28

12.11.      FileGetExt 28

12.12.      FileGetName. 29

12.13.      FileGetPath. 29

12.14.      FileListGet 30

12.15.      FileListLoad. 30

12.16.      FileMove. 31

12.17.      GetChrono. 31

12.18.      GetClipboard. 32

12.19.      Goto. 32

12.20.      If. 34

12.21.      IfImage. 35

12.22.      IfProcess. 36

12.23.      IfShape. 37

12.24.      IfWindow.. 38

12.25.      Int 39

12.26.      Lpad. 40

12.27.      Ltrim.. 41

12.28.      Max. 42

12.29.      Min. 42

12.30.      MsgBox. 42

12.31.      NetSend. 43

12.32.      Random.. 44

12.33.      Repeat 45

12.34.      Replace. 46

12.35.      ResetChrono. 46

12.36.      Rpad. 47

12.37.      Rtrim.. 48

12.38.      Say. 49

12.39.      SetClipboard. 49

12.40.      SetColorTol 49

12.41.      SetEndKey. 51

12.42.      SetKeyMode. 51

12.43.      SetKeySpeed. 52

12.44.      SetMouseSpeed. 52

12.45.      SetPixelTol 53

12.46.      SetTitle. 55

12.47.      SetVar 55

12.48.      Sgn. 56

12.49.      Stop. 56

12.50.      StrLen. 56

12.51.      StrStr 57

12.52.      SubStr 57

12.53.      SystemCmd. 58

12.54.      SystemOpen. 58

12.55.      ToChar 59

12.56.      Trace. 60

12.57.      XlsAutoSave. 61

12.58.      XlsClose. 62

12.59.      XlsReadData. 62

12.60.      XlsSave. 63

12.61.      XlsWriteData. 64

12.62.      Verbose. 64

12.63.      Wait 66

12.64.      WprClose() 66

13.       The loops and the switches. 67

13.1.        The loops. 67

13.2.        The switches. 67

14.       Studio. 69

14.1.        Delete a record. 69

14.2.        Move a record. 69

14.3.        Copy a record. 70

15.       Debug your macros. 70

15.1.        Enable / Disable Debug mode. 70

15.2.        Debug window.. 71

16.       Trace your macros. 72

16.1.        Enable / Disable Trace mode. 72

16.2.        Customize the trace. 72

17.       Run playback from a command line. 74

17.1.        Run a macro from a command line. 74

17.2.        Schedule a macro. 75

17.3.        Run a macro with variables. 75

18.       Options. 75

19.       FAQ.. 76

19.1.        Navigation. 76

19.2.        Developing. 76

19.3.        Playback. 76

20.       Support 76

21.       Appendix. 76


 

 

 

 

Winparrot User Guide Release 2.1

 

 

 

The part number for this book is A20202012. To reorder this book, use set part number A20202012

Copyright , Winparrot. All rights reserved.

 

The Programs (which include both the software and documentation) are proprietary of Winparrot; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual property law. Reverse engineering of the Programs is prohibited.

 

Program Documentation is licensed for use solely to support the deployment of the Programs and not for any other purpose.

 

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing to Winparrot ( Support@WinParrot.com) . Winparrot does not warrant that this document is error free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Winparrot.

 

RESTRICTED RIGHTS LEGEND

 

Programs delivered subject to the DOD FAR Supplement are ’commercial computer software’ and use, duplication and disclosure of the Programs including documentation, shall be subject to the licensing restrictions set forth in the applicable Winparrot license agreement. Otherwise, Programs delivered subject to the Federal Acquisition. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be licensee’s responsibility to take all appropriate fail–safe, back up, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes and Winparrot disclaims liability for any damages caused by such use of the Programs.

To activate the software during the first execution, the software invites you to accept the general conditions of use:

 

1.   Presentation

 

WinParrot is the Windows parrot. If you perform repetitive tasks daily with no added value on Windows XP, Vista or Windows 7, it will save you much time.

To do this simply start recording, it generates a file with the extension 'wpr' containing all your actions. You can modify the saved document to include your control points, loops, sound effects, interactions...

 

Overview of the main window (with 3 documents opened)


 

Description of the main window.

(1)   Title: Display the full file name of the opened WinParrot file.
You can change this title with the function SetTitle()

(2)   Menus and buttons bar: For further information on a button you can move the mouse cursor over it.

(3)   List of Records: The record with blue background is the selected record (here the 11th record is edited).
Columns are:
-N°: It is the record number.
-Play: Click on the icon to enable or disable a record. If a line is disabled it will be ignored during the macro playback.
-Title: It is the title of the target application (here ‘Calculatrice’).
If the target application has a dynamic title you can modify this title and use wildcard character (‘*’ or ‘?’).
-Command: Command line (11) that contains the instructions separated by the character ‘ ;’. During the playback each instruction will be evaluated and it result will be send to the target application.

(4)   Screenshot, zoom, click and image selection: In this area you have a screenshot taken during the macro recording. You can also have an image selection or/and a point to click on.

(5)   Red rectangle: If the macro code (11) call a function that need an image selection (IfShape, IfImage,..) then a red rectangle is automatically added. You can resize or move the image selection with the yellow rectangles. Each line/record can have one rectangle/image selection if you need a second rectangle/image selection you must copy the line/record (see Studio chapter).

(6)   The red dotted line between the red rectangle (5) and the red arrow (7) shows that the click will be relative to the found image. Without this dotted line the click will be absolute (relative to the top left corner of the screenshot).

(7)   Red arrow that shows the pixel where WinParrot will click. This arrow appears automatically if the record (11) contains at least one mouse event (example ‘\[LBUTTON]’). Each line/record can have one arrow/click if you need a second arrow/click you must copy the line/record (see Studio chapter).

(8)   Zoom of the selected image or/and of the mouse event/click. You can move this zoom by clicking on it or by double clicking where you want to get it.

(9)   With the small yellow triangle you can resize the zoom area and zoom in.

(10)           WinParrot version.

(11)           Command line with 3 instructions :

:DEB                       => Tag/Label/location used by the

function GoTo().

IfImage(3,"V[LBUTTON]",)   => Find image function (5).

If the image is found within 3s then click (7) relative to it. Continue if the image is not found.

If($VAR1>2,Trace(,,),);    => Disable the trace mode if the variable $VAR is greater than 2.

 

 

2.   Install / Uninstall

 

The latest version of WinParrot does not need installation any more, simply download the latest version directly from the official site http://www.winparrot.com (the executable 'winparrot.exe') then copy it into a directory.

 

Note :

Choose the directory where you copy the executable 'winparrot.exe' because Windows will automatically assign all files '*. wpr' with this one.

 

If you copy 'winparrot.exe' under 'c:\temp', opening a file 'test.wpr' (by double clicking on it) will always call the Windows executable c:\temp\winparrot.exe.

 

WinParrot no longer needs its own directory, DLL ... it has several advantages:

·         Super simple installation

·         Uninstall: simply delete the executable, it will no longer let traces that pollute your computer.

·         Update fast and simple, by replacing the executable. WinParrot never attempts as some programs (eg Java ...) to go to the Internet without inform you.

·         WinParrot self checks. If a malicious user has modified the executable, WinParrot inform you that he has been corrupted and will prompt you to download a new version.

·         WinParrot integrates its own antivirus. WinParrot detects any foreign code, so if a virus or spyware try to infect the executable, WinParrot will inform you that he has been corrupted and will prompt you to download a new version (if the problem persists please install or update your antivirus and scan all your drives).
If it is infected Winparrot reports it with this screen:

 

 

·         Verify that there is no virus

·         Downloaded WinParrot again

If this message still appears, you can launch the executable WinParrot.exe from the zip file (viruses seldom enter into compressed files).

3.   Start to record

To start the recording you must click on the button .

If this is a new document WinParrot will ask you to specify a folder and a file name.
If you open an existing document, new records will be placed at the end of it.
While recording your actions, WinParrot’s icon in the taskbar changes from green to red.
You can stop the recording at any time with the button  or with the key [END] (Key End is the default key, you can change it in ‘Options’).

Important notes:

To get a recording efficient: 

·         Resize the main window of the target application the smallest possible (that will reduces the wpr file size) before you start recording.

·         Do not key too fast because WinParrot must have time enough to save all your actions while making screenshots.

·         Click on messages that validate your transactions (WinParrot will creates a record. Then you can change the record in order to insert a check point with the functions IfImage / IfShape and stop if the expected message is not displayed). 

Watch the video 'How to record a Windows macro with the freeware WinParrot' on  or download the AVI video .

 

4.   Start the playback

 

To start the playback you must click on the button . The playback begins at the first record and at the 1st instruction.
When WinParrot is starting playback, the small icon in the taskbar changes from green to blue.
It read only records that 'Play' is activated (symbolized by
and not  ). You can enable / disable the playback of one record by clicking on the icons /).
You can stop the playback at any time by pressing [END] (End key by default, you can change it with the function SetEndKey())
To restart the playback you have to click again on the button
, then WinParrot will ask you to choose one alternatives:

 

 

 

 

 

5.   Records

A record is mainly composed of an image taken during recording and a command line. When you are recording, WinParrot takes pictures at each event depending on the options selected. It also records the text you have entered as a command line consisting of a simple statement (eg "My textV[RETURN]", overview). You can modify this record in order to:

·         Change one instruction (Change the text and / or add functions.).

·         Add instructions (separated by the character ';')

·         Resize, move the rectangle of the image to find.

·         Change the position of the arrow/mouse (to change the position of the point where you want to click for example).

·         Disable the record (by clicking on the icon  )

·         Change the title of the target application (you can use wildcards ‘*’ or ‘?’)

 


 

6.   Command lines

A command line consists of zero to n instruction(s) separated by the character ";" (overview). When WinParrot reads a command line it starts with the first instruction from left to right, it ends the execution and only after it sends the text and events to the target application.
Thus the command line 'A' consists of 2 instructions:

"My text" ; Wait(1000


Is not equivalent to the command line 'B' consists of a single instruction:
"My text"&Wait(1000)


The command 'A' sends to the target application the text "My text", then it waits while the command 'B' waits the return of function Wait (1000) and then sends the text "My text".

  

7.   Instructions

An instruction is composed of texts, integers, floats, variables, functions and operators (overview).
An instruction is used to:

·         Send text or events to an application.

-"My text"

-"My textV[RETURN]"

-"My text "&Ask("What else ? Coffee ?", "Yes",

     "Y", "No", "N")&"."

-1+2 (sends 3 to the target application)

 

·         To assign a value to a variable.

-$MY_VARIABLE=1

-$MY_TEXTE="Toto"

 

·         Perform a calculation, a concatenation

-$MY_VARIABLE=$MY_VARIABLE+1

-$MY_TEXTE="Toto "&Ask("What else ? Coffee ?","Yes","Y","No","N")&"."

 

 

·         Insert a location (that can be use by the function GoTo).
-:LOCATION

 

·         To perform a test and/or a redirection, pause, stop the playback.

 

-If($I>3, "Ok", "Not Ok")

-IfImage(5, "V[RETURN]", Stop()),

-Goto($MY_VARIABLE,1)  

-Wait(200)

-Stop()

 

When you start the playback:

·         Each statement is evaluated and only after its result (if any) is send to the target application.

·         Any instruction started is ended. You cannot stop within an instruction whatever stop is caused by the stop() function or by the [End] key.

 

8.   Locations

Locations are tags that are inserted between instructions.

You can redirect the current playback to that point with the function GoTo (). The same location name may be used multiple times in a document because the function GoTo () takes in second argument the number of the searched location. Locations starts with the character ":" and may contain letters, numbers or the character "_".

Example : :MY_LOCATION  

9.   Events 

Events such as pressing, releasing of a key are stored within strings with the format X[Key]:

 

 

Command ‘X’

Description

 

 

\

Press a key

/

Releases a key

V

Press and Releases a key

 

The following keys are recognized automatically as events:

‘[Key]’

Description

[ALT]

Key Alt

[ALT]

Alt Key

[APPS]

Apps Key

[BACK]

Suppr Key

[CAP]

Maj Key

[CLR]

Del Key

[CTRL]

Ctrl Key

[DEL]

Suppr Key

[DOWN]

Bas Key

[END]

End Key. Note this key is the default key to stop recording or playback.

[ESC]

Echap Key

[EXECUTE]

Execution Key

[F1] to [F12]

Function Keys

[HELP]

Help Key

[HOME]

Home Key

[INSERT]

Inser Key

[INSERT]

Inser Key

[LBUTTON] 

Left mouse button

[LEFT]

Left Key

[LWIN]

Left Windows Key

[NEXT]

Next Page Key

[PAGEUP]

Previous Page Key

[PAUSE]

Pause Key

[PRINT]

Print Key

[RBUTTON] 

Right mouse button

[RETURN]

Return Key

[RIGHT]

Right Key

[RWIN]

Right Windows Key

[SELECT]

Select Key

[SHIFT]

Shift Key

[SNAPSHOT]

Print snapshot Key

[UP]

Up Key

 

 

Note :

 Double click is stored as V[LBUTTON]V[LBUTTON]

 

 

Depending on the options selected (currently not available) you can request not to create new record for a given event.

In order to generate files *. wpr not too large you can also specify to merge certain events (eg \[LBUTTON] and /[LBUTTON] as V [LBUTTON]). When the command line contains [LBUTTON] or [RBUTTON] WinParrot displays on the capture screen a red cross that represents the position of the mouse (you can move this cross).

Tip: To find the code for a particular key start recording, switch to an application other than WinParrot Press the key and stop recording.

 

.


 

10.         Variables


Variables are used to store strings, integers or floats. They are related to the opened document. If two or more WinParrot documents are open each document has its own variables.

10.1.            System variables

System variables are initialized when you start the playback.
The main variables are :

·         $WPR_LINE_NB : It contains the number of records.

·         $WPR_LINE : It contains the number of the current record.

·         $WPR_INST_NB : It contains the number of instructions in the current record.

·         $WPR_INST : It contains the number of the current instruction in the current record.

·         $WPR_PATH : It contains the wpr file path (with the ‘/’ character at the end.

 

10.2.            Time variables

Time variables contain in a defined format, current date and time.

The two time variables are:

·         $DATE : It contains the current date with the default format ‘YYYY/MM/DD’ where  YYYY is the year, MM is the month and DD is the day.

·         $TIME : It contains the current time with the default format ‘HH:MM:SS’ for HH hours, MM minutes and SS seconds.

 

These two variables are alterable, you can change them in order to set the output format.
Examples :

MsgBox($DATE&"-"&$TIME);

=> Open a popup with ‘2011/05/16-16:33:56’

$DATE="YYMMDD"; $TIME="HHMMSS"; $V=$DATE&"-"&$TIME  

=> Set the variable $V  with the string value ‘110516-163356’.

$TIME="HHMMSS"; If($TIME>160000,Stop(),)

=> Stop the playback if it is 4 PM past.

 

10.3.            User variables

User variables are implicitly declared during their first assignment. You can change their type of content at any time. Variable's names begin with the character '$' and are followed from 1 to 29 characters in [AZ] [0-9] and '_'.

To assign a value to a variable you must add an instruction in a command line and use the assignment operator '='

Syntax:  $VARIABLE_NAME=<instruction> or you can use the function SetVar() : SetVar($MY_VARIABLE, "Toto").

            Examples:

$MY_VARIABLE=1

$MY_VARIABLE="Test"

            $MY_VARIABLE=Ask("One or Two ?","One","1",

"Two","2")&"."

11.         Operators

 

11.1.            The assignment operator

The assignment operator ‘=’ has the following syntax:

$<Variable>=<instruction>

 <instruction> is an instruction that return an integer or a string.

 

If the variable does not exist it is automatically declared and contains the results of the instruction. If the variable already exists it content is replaced by the result of the instruction.

To assign a value to a variable inside a function you must use the function SetVar ().

11.2.            Logical operators

Logical operators are used with the following Syntax:

 

<instruction2><Operator><instruction2>

 

<instruction1> and <instruction2> are instructions that return integers (except for operators ‘== ‘and ‘!= ‘ because they can compare strings).

 

  • ==       
    Return 1 if
    <instruction1> is equal to <instruction2>, 0 otherwise.
  • !=
    Return 1 if
    <instruction1> is different from <instruction2>, 0 otherwise.
  • <
    Return 1 if
    <instruction1> is equal or less than <instruction2>, 0 otherwise.
  • <=
    Return 1 if
    <instruction1> is equal or smaller than <instruction2>, 0 otherwise.
  • >
    Return 1 if
    <instruction1>> is greater than <instruction2>, 0 otherwise.
  • >=
    Return 1 if
    <instruction1> is equal or greater than <instruction2>, 0 otherwise.

 

11.3.            Operators of integers or floats

Operators of integers or float are used with the following Syntax:

 

<instruction1><Operator><instruction2>

 

<instruction1> and <instruction2> are instructions that return integers or floats.

  • +
    Return the addition of <instruction1> and <instruction2>.
  • -
    Return the subtraction of <instruction1> by <instruction2>.
  • *
    Return the multiplication of <instruction1> by <instruction2>.
  • /
    Return the division of <instruction1> by <instruction2>.
  • %
    Return the mod of <instruction1> by <instruction2>.

 

Examples

$MY_VARIABLE=$MY_VARIABLE+2

$V=(($I-1.1)*5)%3

 

11.4.            Operators of strings

Operators of strings are used with the following Syntax:

 

<instruction1><Operator><instruction2>

 

<instruction1> and <instruction2> are instructions that return strings.

 

  • &
    Return the concatenation of <instruction1> and <instruction2>.

 

Example

$MY_VARIABLE="["&$MY_VARIABLE&"]"

 

Note :

This operator is often used in order to merge instructions that may not return strings. (Example MsgBox("Unknown error ")&Stop())


 

12.         Functions


The functions allow WinParrot to interact with:

  • The driven program through the search functions (IfImage(), IfShape..).
  • The user with popup functions.
  • The operating system Windows, through the system functions.
  • Itself through redirection functions (Goto(), Pause()).

You can call a function without arguments values.

Each function can set its defaults values nevertheless if it is not the case a general default value is zero if an integer or a float is expected and an empty string if a string is expected.

For example if an instruction in a macro ‘c:\demo.wpr’ contains:

Trace(,,)ó Trace(0, "TFORMAT","c:\demo.html")

-          The 1rst argument expected is an integer, it will be set to zero.

-          The 2nd argument expected is a string with the trace format. The default trace format TFORMAT will be used.

-          The 3rd argument expected is a string that contains the partial or the full file name. The function Trace will use the default folder, the default file name and the default file type : « <wpr folder>\<wpr filename>.<default type =.html> »

 

Note :

Each function argument must be only one instruction, therefore if you want to execute two or more instructions you must merge them with the operator '&'.

Example : MsgBox("Unknown error ")&Stop()

 

12.1.            Abs

Description 

Function that return an integer or a float absolute value.

 

Syntax   Abs(<Instruction>)

 

Arguments 

<Instruction>: Instruction that must return an integer or a float.

 

Return :

An integer or a float greater or equal to zero.

 

Examples

Abs(30) will send  ‘30’ to the target application.

MsgBox("Abs(-10.15*2)="&ToChar("%0.3f",Abs(-10.15*2))) will open a popup with ‘Abs(-10.15*2)=20.300’.

 

12.2.            AppForeground

Description 

This function sets the switch mode of changing the foreground application (Target application that is defined on each record line).

 

Syntax   AppForeground(<Inst switch_mode>,<Inst select_mode>)

 

Arguments 

<Inst switch_mode> : Instruction that must return an integer between 0 and 2.

<Inst select_mode> : Instruction that must return an integer between 0 and 3.

 

 

If <Inst switch_mode>=0 then the target application will never be put by WinParrot at the foreground. It is the current foreground window that will receive the keys and mouse events. Search functions (IfImage, IfShape) will search only in the foreground window.

If <Inst switch_mode>=1 then the target application will be put at the foreground before the execution of each instruction.

If <Inst switch_mode>=2 then the target application will be put at the foreground before the excution of each instruction and as soon as WinParrot need it (for example during the execution of the function IfImage()). With this value you cannot manually change the foreground application during the playback.

 

If <Inst switch_mode>=1 or 2 and <Inst select_mode>=0 the target application is selected according to its title or its name.

If <Inst switch_mode>=1 or 2 and <Inst select_mode>=1 the target application is selected according to its title and its name.

If <Inst switch_mode>=1 or 2 and <Inst select_mode>=2 the target application is selected according to its title.

If <Inst switch_mode>=1 or 2 and <Inst select_mode>=3 the target application is selected according to its name.

 

 

Return string 

None.

 

Notes 

This function doesn’t suspend the current playback.

The change will be effective before the execution of all the following instructions.

If switch_mode = 1 or 2, the target application will be put at foreground as soon as it is available. If the target application is not available within the maximum time specified by the function AppWait() a popup error message will stop the playback.

If switch_mode = 0 the agument <Inst select_mode> is not used.

If you do not call this function WinParrot set switch_mode to 2 and  select_mode> to 0.

 

Example

After the execution of this instruction:

AppForeground (1,0)

WinParrot will put the target application at the foreground before the execution of all following instructions. If you manually change the foreground application it will not force the target application to be at the foreground even if for example it is searching an image with the IfImage function.

 

 

12.3.            AppResize

Description 

Function that set the mode of resizing the target application.

 

Syntax   AppResize (<Inst mode>,<Inst Width>,<Inst Heigth>,<Inst X>,<Inst Y>)

 

Arguments 

<Inst mode> : Instruction that must return an integer between 0 and 3 :

If 0 then WinParrot will not resize the target application.

If 1 then WinParrot will resize the target application as it was during the recording.

If 2 then WinParrot will resize the target application according to <Inst Width> and <Inst Heigth>.

Si 3 then WinParrot will resize and move the target application according to <Inst Width> and <Inst Heigth>,<Inst Heigth>,<Inst X> et <Inst Y>.

 

<Inst Width> : Instruction that must return an integer, that will be the width in pixel.

<Inst Height> : Instruction that must return an integer, that will be the height in pixel.

<Inst X> : Instruction that must return an integer, that will be the position X in pixel.

<Inst Y> : Instruction that must return an integer, that will be the position Y in pixel.

 

 

Return string 

None.

 

Note 

The change will be effective before the execution of all the following instructions.

 

Examples

After the execution of this instruction:

AppResize (3,200, 200, 200, 200)

Before the execution of all the following instructions WinParrot will resize the target application to 200 x 200 pixels and move it to the position (200,200).

 

After the execution of this instruction:

AppResize (1,,,,)

Before the execution of all the following instructions WinParrot will resize the target application to the size it was during the recording.

 

12.4.            AppWait

Description 

Function that set the maximum time to wait for the target application.

If the target application is available it will be put at the foreground.

If the application is not available WinParrot will stop the playback and display an error message.

 

Syntax   AppWait(<Inst time>)

 

Arguments 

<<Inst time > : Instruction that must return an integer, that will be the maximum time in seconds  that WinParrot will wait for the target application.

 

Return string 

None.

 

Note 

The change will be effective before the execution of all the following instructions.

If the function AppForeground(<Inst switch_mode>,<Inst select_mode>) has  been called before with <Inst switch_mode>=0 the call to the function AppWait will have no effect. If the target application is not available during the maximum time specified WinParrot stops the playback.

 

Example

After the execution of this instruction:

AppWait(30)

WinParrot will wait for the target application a maximum of 30 seconds.

 

12.5.            Ask

Description 

Function that asks the user to choose between two alternatives and performs one of two specified instructions depending on the user's choice.

 

Syntax   Ask(<Inst 1>,<Inst 2>,<Inst 3>,<Inst 4>,<Inst 5>)

 

Arguments 

<Inst 1> : Instruction that must return a string containing the question.

<Inst 2> : Instruction that must return a string containing the label of the button 1

<Inst 3> : Instruction to be executed if the user press the button 1.

<Inst 4> : Instruction that must return a string containing the label of the button 2

<Inst 5> : Instruction to be executed if the user press the button 2.

 

Return string 

Result of  <Inst 3> if the user press the button 1.

Result of  <Inst 5> if the user press the button 2.

 

Note 

This function suspends the current playback and waits for the user’s response.

During the playback the user can record his answer in the INI file by selecting the check box 'Do not ask again'.

 

 

Example

This instruction :

Ask("Continue ? ","Yes",Say("Ok"),"No",Stop())

Open this dialog box :

 

 

 

12.6.            Ask3

Description 

Function that asks the user to choose between three alternatives and performs one of three specified instructions depending on the user's choice.

 

Syntax   Ask3(<Inst 1>,<Inst 2>,<Inst 3>,<Inst 4>,<Inst 5>,<Inst 6>,<Inst 7>)

 

Arguments 

<Inst 1> : Instruction that must return a string containing the question.

<Inst 2> : Instruction that must return a string containing the label of the button 1

<Inst 3> : Instruction to be executed if the user press the button 1.

<Inst 4> : Instruction that must return a string containing the label of the button 2

<Inst 5> : Instruction to be executed if the user press the button 2.

<Inst 6> : Instruction that must return a string containing the label of the button 3

<Inst 7> : Instruction to be executed if the user press the button 3.

 

Return string 

Result of  <Inst 3> if the user press the button 1.

Result of  <Inst 5> if the user press the button 2.

Result of  <Inst 7> if the user press the button 3.

 

Note 

This function suspends the current playback and it waits for the user’s response.

During the playback the user can record his answer in the INI file by selecting the check box 'Do not ask again'.

 

Example

This instruction :

Ask3("Continue ? ","Yes",Say("Ok"),"No",Stop(),"Wait 1mn",Wait(60000))

 

Open this dialog box :

 

12.7.            Beep

Description:

Function that emits a sound at a given frequency and during a given period.

Syntax:  Beep(<Integer 1>,<Integer 2>)

 

Arguments:

<Integer 1> : Instruction that must return an Integer >0. This will be the frequency in Hz.

<Integer 2> : Instruction that must return an Integer >0. This will be the duration of the sound in milliseconds.

 

Return string: None

 

Note : This function suspends the current playback durring the time of the sound.

 

Examples: Sound with a frequency of  3000Hz during 0,1s : Beep(3000,100)

 

 

 

12.8.            Debug

Description: 

Function that enable or disable the debug mode.

For further information see chapter ‘Debug your macros’ .

 

Syntax:   Debug(<Inst Level>)

 

Arguments 

<Inst Level>: Instruction that must return an integer between 0 and 7.

With Level=0 it disable the debug mode and with Level=7 it will stop a least 3 times per instruction (Instruction selection, instruction execution and instruction result).

 

Return string:

None.

 

Note:

The change will be effective for all the following instructions.

You can change the debug level at any moment by clicking in the checkboxes of the debug window.

 

Examples:

After the execution of this instruction: Debug(7)

The debug mode is enabled with a maximum of check points.

After the execution of this instruction: Debug(0)

The debug mode is disabled.

 

 

Watch the video 'How to use the Debug & Trace functions' on  or download the AVI video .

 

12.9.            FileCopy

Description:

Function FileCopy, Copies an existing file to a new file.

 

Syntax:  FileCopy(<Txt1:String=source file name, Txt2:String=target file name>)

 

Arguments:

(<Txt1> : Instruction that must return a text containing the source file name.

(<Txt2> : Instruction that must return a text containing the target file name.

 

Return string:  None.

 

Note : This function set the variable $LAST_ERROR and $LAST_ERROR_NUM if the function run with no error $LAST_ERROR="" and $LAST_ERROR_NUM=0.

 

Example:             

FileCopy("C:\temp_dpc\WinParrot.ini","C:\temp_dpc\WinParrot2.ini"); If($LAST_ERROR!="",MsgBox($LAST_ERROR&":"&$LAST_ERROR_NUM)&Stop(),)

 

12.10.      FileDelete

Description:

Function FileDelete, Deletes an existing file.

 

Syntax:  FileDelete(<Txt1:String=file name>)

 

Arguments:

(<Txt1> : Instruction that must return a text containing the file name to delete.

 

Return string:  None.

 

Note : This function set the variable $LAST_ERROR and $LAST_ERROR_NUM if the function run with no error $LAST_ERROR="" and $LAST_ERROR_NUM=0.

 

Example:             

FileDelete("C:\temp_dpc\WinParrot.ini")

If($LAST_ERROR!="",MsgBox($LAST_ERROR&":"&$LAST_ERROR_NUM)&Stop(),)

 

 

12.11.      FileGetExt

Description:

Function FileGetExt, Returns the extension of a file (ex 'exe').

 

Syntax:  FileGetExt(<String: Full file name>)

 

Argument:

<Inst 1> : Instruction that must return a text containing the name of the file.

 

Return string:   The extension of the file.

 

Example:             

FileGetExt("C:\folder\file.exe") ó "exe"

 

12.12.      FileGetName

Description:

Function FileGetName, Returns the name of the file without it extension.

 

Syntax:  FileGetName(<String: Full file name>)

 

Argument:

<Inst 1> : Instruction that must return a text containing the name of the file.

 

Return string:   The name of the file.

 

Example:             

FileGetName ("C:\folder\file.exe") ó "file"

 

 

 

12.13.      FileGetPath

Description:

Function FileGetPath, Returns the path of the file (ex 'C:\tmp').

 

Syntax:  FileGetPath(<String: Full file name>)

 

Argument:

<Inst 1> : Instruction that must return a text containing the name of the file.

 

Return string:   The path of the file.

 

Example:             

FileGetPath ("C:\folder\file.exe") ó " C:\folder"

 

12.14.      FileListGet

Description:

Function FileListGet, Returns the full name of a file from a list of files loaded with the function FileListLoad.

 

Syntax:  FileListGet(<Variable name>, <Int: file index in list>)

 

Arguments:

<Variable name> : This variable name must be the name of the list previously given.

<Int: file index in list> : Index of the file in the list..

 

 

Return string:   The full name of the file.

 

Note : The variable <Variable name> contains the number of files in the list.

 

Examples:           

       FileListLoad($Z,"\\xp250g\c$\WinParrot\*.zip");

       $I=1;

       :D; If($I<=$Z,MsgBox(FileGetName(FileListGet($Z,$I))),Stop());

       $I=$I+1; GoTo(:D,1)

 

 

 

12.15.      FileListLoad

Description:

This function loads a list containing the full names of files that match a specified search string.

 

Syntax:  FileLisLoad(<Variable name>, <Txt=search string>)

 

Arguments:

<Variable name> : This variable will contain the number of files found.

<Txt=search string> : Search string.

 

 

Return string:   None.

 

Note : The variable <Variable name> contains the number of files found.

 

Examples:           

       FileListLoad($Z,"\\xp250g\c$\WinParrot\*.zip");

       $I=1;

       :D; If($I<=$Z,MsgBox(FileGetName(FileListGet($Z,$I))),Stop());

       $I=$I+1; GoTo(:D,1)

 

 

12.16.      FileMove

Description:

Function FileMove, Moves an existing file or a directory, including its children.

 

Syntax:  FileMove(<Txt1:String=source file/directory name, Txt2:String=target file/directory name>)

 

Arguments:

(<Txt1> : Instruction that must return a text containing the source file/directory name.

(<Txt2> : Instruction that must return a text containing the target file/directory name.

 

Return string:  None.

 

Note : This function set the variable $LAST_ERROR and $LAST_ERROR_NUM if the function run with no error $LAST_ERROR="" and $LAST_ERROR_NUM=0.

 

Example:             

FileMove ("C:\temp_dpc\WinParrot.ini","C:\temp_dpc\WinParrot2.ini"); If($LAST_ERROR!="",MsgBox($LAST_ERROR&":"&$LAST_ERROR_NUM)&Stop(),)

 

12.17.      GetChrono

Description:

Function that returns the time elapsed since the last call to the function ResetChrono ().

 

Syntax:  GetChrono(<Inst>)

 

Arguments:

<Inst 1> : Instruction that must return a text string containing the output text format. The format can contain the following tags:

"%H"  to display hours.

"%M"  to display minutes.

"%S"  to display seconds.

"%MS" to display milliseconds.

 

Return string:  

A text containing the time elapsed since the last call to the function ResetChrono ().

 

Note : 

If <Inst> is emplty the folowing format is used : "%H:%M:%S.%MS"

 

Examples:

ResetChrono(; Wait(1300) ; GetChrono(ó  "00:00:01.300"

ResetChrono(; Wait(1300) ; GetChrono("%S%MS"ó  "01300"

 

12.18.      GetClipboard

Description:

Function that return the content of the clipboard.

 

Syntax:  GetClipboard()

 

Arguments: None

 

Return string: The string in the clipboard.

 

Note : This function removes the newline characters that some applications add (like Excel). To change the content of the clipboard use the function ‘SetClipboard’.

 

Examples:

Copy the content of the clipboard into the variable $PP : $PP=GetClipboard()

Send the content of the clipboard to the target application, stop if any :

If(GetClipboard()=="",Stop(),"\[CTRL]v/[CTRL]")
ó If(GetClipboard()=="",Stop(),GetClipboard())

      

 

 

 

12.19.      Goto

Description:

Function that specifies to WinParrot the next instruction to execute (after it has finished the execution of the current instruction and it has sent to the target application the result thereof). There are two syntaxes for this function.

 

Syntax 1:  Goto(:LOCATION,<Integer 1>)

:LOCATION : Location that must  be present in the document opened.

<Integer 1> : Instruction that must return an integer >0 that will be the number of occurrence of the location.

 

Syntax 2:  Goto(<Integer 1>,<Integer 2>)

<Integer 1> : Instruction that must return an integer >0 that will be the line number of the next instruction to be executed.

<Integer 2> : : Instruction that must return an integer >0 that will be the instruction number of the next instruction to be executed.

 

Return string: None

 

Note : This function doesn’t suspend the current playback. The two instructions below are equivalent:

Goto(2,1)&Wait(200) ó Wait(200)&Goto(2,1)

This instruction wait 2s and only thereafter WinParrot will execute the first instruction at the 2nd line. 

The first syntax using one location is more convenient, especially if you delete or add records.

 

Examples:

Goto 2nd instruction, command line 5 : 

Goto(5, 2)

Go to the second occurrence of the location :MY_LOCATION

Goto(:MY_LOCATION,2)

 

Watch the video 'How to add a loop in a WinParrot macro' on  or download the AVI video .

 


 

12.20.      If

Description:

Function that will execute one of two instructions depending on a logical test.

 

Syntax: If(<Inst 1>,<Inst 2>,<Inst 3>)

 

Arguments:

<Inst 1> : Instruction that must return an integer.

<Inst 2> : Instruction to be executed if the result of  the instruction 1 is different from zero.

<Inst 3> : Instruction to be executed if the result of  the instruction 1 is equal to zero.

 

Return string:

String generated by the 2nd instruction if the result of the first instruction differs from zero or string generated by the 3rd instruction if the result of the first instruction equals to zero.

 

 

Note : This function doesn’t suspend the current playback.

 

 

 

Examples:

Go to command line 5, instruction 2 if $I<5, otherwise continue:

If($I<5,GoTo(5,2),)

 

Go to command line 5, instruction 2 if $I<5, otherwise ask if WinPArrot should continue:

 

If($I<5,GoTo(5,2),Ask("Continue ?","Yes","","No",Stop()))

 

 

Past if the clipboard isn’t empty:

If(GetClipboard()=="",Stop(),"\[CTRL]v/[CTRL] ")


 

12.21.      IfImage

Description:

Function that executes one of two instructions. The 1st instruction is executed if the requested image has been found during a maximum specified time.

IfImage can have three usages:

·         Find an image, a button, a text to click on it or relatively to it.

·         Check that the application has received and treated the previous commands (only if it displays notifications).

·         Check that the target application is ready to receive new entries.

This function looks for an exact image in shape and in color.

For a search for shape without taking into account colors use rather the function IfShape().

WinParrot will search the image in the target application (according to the window title specified in the 3rd column 'Title'). 

 

New since version 2.1.0 : With the version 2.1.0 and above if the first character of the 'Title' is the character '-' WinParrot will search in all the screen (You will avoid the message 'Cannot find Window...').

 

Syntax:  IfImage(<Inst 1>,<Inst 2>,<Inst 3>)

 

Arguments:

<Inst 1> : Instruction that must return an integer, it is the maximum time in seconds to find the image .

<Inst 2> : Instruction to be executed if the image was found during the specified time.

<Inst 3> : Instruction to be executed if the image was not found during the specified time.

 

Return string:

If the image was found during the specified time, string generated by the 2nd instruction or string generated by the 3rd otherwise.

 

 

Note : The execution of the current instruction is interrupted by this function for the maximum time defined by the 1st parameter. If the image is found before the specified time, playback restarts immediately.

Once you enter the name of this function within a command line WinParrot automatically adds a search area image (red rectangle). You must move or/and resize it in order to have a reliable search area.

Check :

·         Do not over expand the area searched, the result would be to slow the search while running the playback.

·         Do not select an area containing the cursor blinking or such other useless objects, the search function will not be able to find the image without them.
 

 You can cancel at any time the search with the V[END] key (Key set by default is [End]). Nevertheless, note that the search function will run the 3rd instruction and send the result to the target application (WinParrot will stop only after the current instruction is finished).

 

While the search function is running if you change the foreground application WinParrot cannot find the image if the target application is not the active windows and in foreground.

 

Examples:

 

·         Search the text ‘coucou’ during a maximum time of 5s, stop if the image cannot be found :

IfImage(5,"",Stop())

      

 

 

 

·         Search a button for a maximum time of 5s, click on the left of it if the image was found and stop otherwise.

IfImage(5,"V[LBUTTON]",Stop())

 

 (The dotted line shows that the click is relative to the found image. In order to click with an absolute position (x,y) you must put the text "V[LBUTTON]" outside of the function :  IfImage(5,,Stop()); "V[LBUTTON]")

    

During the search if the specified maximum time is greater than 1s Winparrot display in the application title the message: [Elapse time /Maximum time] eq ‘IfImage 2/5’

If the button changes it appearance  when you move the mouse over, you must use the IfShape() function and/or combine it with percentages of tolerance (using SetPixelTol and SetColorTol functions).

 

Watch the video 'How to use the IfImage function in a WinParrot macro' on  or download the AVI video .

 

12.22.      IfProcess

Description:

Function that will wait a specified time for a process and it will execute one of two instructions.

 

Syntax:

IfProcess(<Inst 1 = Process name>,<Inst 2 = max time to wait>,<Inst 3>, <Inst_4>)

 

Arguments:

<Inst 1> : Instruction that must return a string, it is the process name.

<Inst 2> : Instruction that must return an integer, it is the maximum time (seconds) WinParrot will wait for the process.

<Inst 3> : Instruction to be executed if the process starts within the given time

                  in <Inst_2>.

<Inst 4> : Instruction to be executed if the process do not starts within the given time.

 

Return string:

String generated by the 3rd instruction if the process starts within the given time or string generated by the 4th instruction if the process do not starts within the given time.

 

Notes : This function suspend the current playback.

If you stop the playback the 4th instruction is executed and it result is send to the target application.

You can find the name of a process with the Windows Task Manager.

 

Examples:

Go to command line 5, instruction 2 if the processus 'notepad' starts within 5s, otherwise continue:

SystemCmd("notepad&"); IfProcess("notepad",5,GoTo(5,2),)

 

Go to command line 5, instruction 2 if the processus 'notepad' starts within 5s, otherwise ask if WinParrot must stop the playback:

IfProcess("notepad",5,GoTo(5,2),Ask("Do you want to continue ?","Oui","","Non",Stop()))

 

12.23.      IfShape

 

Description:

This function is identical to the function IfImage. The unique difference is on the search engine which does not take into account colors, so the following 3 'Test' images will be accepted:

 

Syntax: IfShape (<Inst 1>,<Inst 2>,<Inst 3>)

 

 

Arguments:

<Inst 1> : Instruction that must return an integer, it is the maximum time in seconds to find the shape .

<Inst 2> : Instruction to run if the shape was found during the specified time.

<Inst 3> : Instruction to run if the shape was not found during the specified time.

 

Return string:

If the shape was found during the specified time, string generated by the 2nd instruction or string generated by the 3rd otherwise.

 

 

Note :

Use the function IfImage() for an exact recognition of an image.

 You can cancel at any time the search with the V[END] key (Key set by default is [End]). Nevertheless, note that the search function will run the 3rd instruction and send the result to the target application (WinParrot will stop only after the current instruction is finished).

 

Examples:

 

·         Search for a shape during a maximum time of 5s, click relative to this one if the shape has been found and stop otherwise.

IfShape(5,"V[LBUTTON]",Stop())

 

During the search if the specified maximum time is greater than 1s Winparrot display in the application title the message: [Elapse time /Maximum time] eq ‘IfShape 2/5’

 

Watch the video 'How to use the IfImage function in a WinParrot macro' on  or download the AVI video .

 

 

12.24.      IfWindow

Description:

Function that will wait a specified time for a window and it will execute one of two instructions.

 

Syntax:

IfWindow(<Inst 1 = Window title>,<Inst 2 = max time to wait>,<Inst 3>,<Inst 4>)

 

Arguments:

<Inst 1> : Instruction that must return a string, it is the window title.

This string can have wildcards '*' and '?'

<Inst 2> : Instruction that must return an integer, it is the maximum time (seconds) WinParrot will wait for the windows.

<Inst 3> : Instruction to be executed if the window starts within the given time in <Inst_2>.

<Inst 4> : Instruction to be executed if the window do not starts within the given time.

 

Return string:

String generated by the 3rd instruction if the window starts within the given time or string generated by the 4th instruction if the window do not starts within the given time.

 

Notes : This function suspend the current playback.

If you stop the playback the 4th instruction is executed and it result is send to the target application.

The window title is displayed in the top horizontal bar of the window.

 

Examples:

Go to command line 5, instruction 2 if the window 'Calculator' starts within 5s, otherwise continue:

SystemCmd("calc&"); IfWindow("Calculat*", 5,GoTo(5,2),)

 

Go to command line 5, instruction 2 if the window 'Calculator' starts within 5s, otherwise ask if WinParrot must stop the playback:

SystemCmd("calc&"); IfWindow("Calculat*",5,GoTo(5,2),Ask("Do you want to continue ?","Oui","","Non",Stop()))

 

 

12.25.      Int

Description 

Function that returns the integer value of a float.

 

Syntax   Int(<Instruction>)

 

Arguments 

<Instruction>: Instruction that must return a float.

 

Return :

An integer.

 

Examples

Int(30.30) will send  ‘30’ to the target application.

MsgBox("Int(-10.15*2)="&ToChar("%0.3f",Int(-10.15*2)))will open a popup with ‘Int(-10.15*2)=-20’.

 

12.26.      Lpad

Description:

Function that left pad a string with an other string. The returned string will have a specified length.

Syntax:  Lpad(<Inst 1>, <Inst 2>, <Inst 3>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string to transform.

<Inst 2> : Instruction that must return a text containing the string to append.

<Inst 3> : Instruction that must return an integer containing the length of the returned string.

Return string:   The result of the string <Inst 1> padded with as many result of the string  <Inst 2> needed  in order that the returned string has the length specified in <Inst 3>.

 

Notes: If the length of the result of the string <Inst 1> is greater than <Inst 3> the returned string is truncated. This function is key sensitive.

 

Examples:           

Lpad("ABCDE", " ", 10) ó "     ABCDE"

$STR="ABCDE" ; Lpad($STR, " ", 10) ó "     ABCDE"


 

12.27.      Ltrim

Description:

Function that delete any specified string at the beginning of an other.

 

Syntax:  Ltrim(<Inst 1>, <Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string to transform.

<Inst 2> : Instruction that must return a text containing the string to delete.

 

 

Return string: The result of the string <Inst 1> without at the beginning any occurrence of  the  result of the string <Inst 2>.

 

Notes: This function is key sensitive.

 

Examples:           

Rtrim("    ABCDE", " ") ó "ABCDE"

$STR="  ABCDE" ; Rtrim($STR, " ") ó "ABCDE"

 


 

 

12.28.      Max

Description:

Function that returns the maximum between two floats.

 

Syntax:  Max(<Inst 1>, <Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a float.

<Inst 2> : Instruction that must return a float.

 

 

Return string:   The greatest float.

 

Examples:           

Max(1, 10) ó 10

$STR=-30.50; Max($STR, -10.50) ó -10.5

 

12.29.      Min

Description:

Function that returns the minimum between two floats.

 

Syntax:  Min(<Inst 1>, <Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a float.

<Inst 2> : Instruction that must return a float.

 

Return string:   The smallest float.

 

Examples:           

Min(1, 10) ó 1

$STR=-30.50; Min($STR, 10) ó -30.5

 

 

12.30.      MsgBox

Description:

Function which displays a message to the user in a popup window.

 

Syntax:  MsgBox(<Inst 1>)

 

Arguments:

<Inst 1> : Instruction that must return a string containing the message to display.

 

Return string: None

 

Note : The execution of the current instruction is interrupted by this function and continue as soon as the user clicks on the button 'OK'.

During the playback the user can record his answer in the INI file by selecting the check box 'No longer report'.

 

 

Examples:       $I=" Click "; MsgBox($I&" to continue.");

 

 

12.31.      NetSend

Description:

Function that send a message to a specified PC or to all PCs on which a given Windows user is logon.

 

Syntax:  NetSend(<Inst 1>,<Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the message to send.

<Inst 1> : Instruction that must return a text containing the PC’s name or the Windows login.

 

Return string:  

None.

 

Note : This function is certified only on Windows XP. (Vista and 7 do not have the required service ‘Windows Messages’.

 

Examples:           

Send the message "Please help!" to the PC "PC007": 

NetSend ("Please help!","PC007");

Send the message "Please help!" to any PCs on which M. BEAN is logon. 

$NB="Please help!"; NetSend($NB,"BEAN");

 

 

12.32.      Random

Description:

Function Random, returns a random integer

 

Syntax:  Random(<Integer = maximum returned by the random function>)

 

Arguments:

<Inst 1> : Instruction that must return an integer.

 

Return :   An integer between 0 and the result of the instruction <Inst 1> .

 

Example:             

This instruction returns an integer between 0 and 6:

Random(7)

 

 


12.33.      Repeat

Description:

Function that repeat a string.

 

Syntax:  Repeat(<Inst 1>, <Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a text.

<Inst 2> : Instruction that must return an integer.

 

 

Return string:   <Inst 2> times the string  <Inst 1>

 

Note : This function is useful for example in order to select the nth value in a list box by sending nth time the key "V[DOWN]".

 

Examples:           

Repeat("V[DOWN]", 0) ó ""

$NB=4 ; Repeat("V[DOWN]", $NB) ó "V[DOWN]V[DOWN]V[DOWN]V[DOWN]"

  

 

 


12.34.      Replace

Description:

Function that replaces a text in a string by another an other text.

 

Syntax:  Replace(<Inst 1>, <Inst 2>, <Inst 3>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string to transform.

<Inst 2> : Instruction that must return a text containing the old string.

<Inst 3> : Instruction that must return a text containing the new string.

 

 

Return string:   The result of the string <Inst 1> on which the result of  <Inst 2> has been  replaced by the result of  <Inst 3>.

 

Remarque : This function is key sensitive.

 

Examples:           

Replace("ABCDE", "BC","xy") ó "AxyDE"

$STR="ABCDE" ; Replace($STR, "BC","xy") ó "AxyDE"

 

12.35.      ResetChrono

Description:

Function that initialize the chrono counter. This function should be called before the function GetChrono() which give the time elapsed between the called to the function ResetChrono() and the call to the function GetChrono().

 

Syntax:  ResetChrono()

 

Arguments:

None.

 

Return string:  

None.

 

Note : This function is automatically called when you start the playback.

 

Examples:           

ResetChrono(; Wait(1300) ; GetChrono(ó  "00:00:01.300"

ResetChrono(; Wait(1300) ; GetChrono("%S%MS"ó  "01300"

 

 

12.36.      Rpad

Description:

Function that right pad a string with an other string. The returned string will have a specified length.

Syntax:  Rpad(<Inst 1>, <Inst 2>, <Inst 3>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string to transform.

<Inst 2> : Instruction that must return a text containing the string to append.

<Inst 3> : Instruction that must return an integer containing the length of the returned string.

Return string:   The result of the string <Inst 1> padded with as many result of the string  <Inst 2> needed  in order that the returned string has the length specified in <Inst 3>.

 

Notes: If the length of the result of the string <Inst 1> is greater than <Inst 3> the returned string is truncated. This function is key sensitive.

 

Examples:           

Rpad("ABCDE", " ", 10) ó "ABCDE     "

$STR="ABCDE" ; Rpad($STR, " ", 10) ó "ABCDE     "


 

12.37.      Rtrim

Description:

Function that delete any specified string at the end of an other.

 

Syntax:  Rtrim(<Inst 1>, <Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string to transform.

<Inst 2> : Instruction that must return a text containing the string to delete.

 

 

Return string: The result of the string <Inst 1> without at the end any occurrence of  the  result of the string <Inst 2>.

 

Notes: This function is key sensitive.

 

Examples:           

Rtrim("ABCDE   ", " ") ó "ABCDE"

$STR="ABCDE  " ; Rtrim($STR, " ") ó "ABCDE"

 


 

12.38.      Say

Description:

Function which uses the sound card of the computer to read a text.

 

Syntax:  Say(<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which has to return a string containing the message to be read. (at present only Hello, Help and Ok are implemented).

 

Return string: None

 

Note : This function suspend the playback while speaking.

 

Examples:            Say("Hello");

Say("Help");

Say("Ok");

 

 

12.39.      SetClipboard

Description:

Function which changes the text in the clipboard.

 

Syntax:  SetClipboard(<Inst 1>)

 

Arguments:

<Inst 1> : Instruction that must return the string to copy to the clipboard.

 

Return string: None

 

Note : To obtain the contents of the clipboard use the function GetClipboard().

 

Example:

Copy the contents of the variable $PP in the clipboard : SetClipboard($PP)

 

 

12.40.      SetColorTol

Description:

Function which changes the tolerance of the search functions IfImage() and IfShape() only with regard to colors.

 

Syntax:  SetColorTol (<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which has to return an integer between 0 and 100%.

The value '0' indicates to the search functions that there is no tolerance for colors, a grey point even very very clear (invisible) will not be confused with a white point. 

 

Return string: None

 

Note : For a tolerance on a percentage of pixels not corresponding use rather / also the function SetPixelTol().

Changes of tolerance are taken into account by the search functions SetColorTol() and SetPixelTol() only if they are called before. They have to be placed before the search functions.

It is recommended that the functions SetColorTol() or/and SetPixelTol() are added with the operator '&' before the search function, so during the playback if WinParrot stop on this instruction (by the function Stop()) you can increase the tolerances and restart the playback from this instruction.

Example:

SetColorTol(20)&SetPixelTol(20)&IfShape(5,"V[LBUTTON]",Stop())


 

 

12.41.      SetEndKey

Description:

Function that set the playback end key.

 

 Syntax:  SetEndKey(<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which must return a text string containing the end key.

You can use any known key (See the list of known keys in chapter ‘Events’).

 

Return string:   None

 

Note : The default end key is V[END]. If you stop the playback (with the end key) and if you restart the playback, you must remember the new end key. If you specify an unknown key, the end key V[END] will be set as the default end key.

 

Examples:           

Set F12 as the end key:

SetEndKey("V[F12]")

Set escape as the end key:

SetEndKey("V[ESC]")

 

12.42.      SetKeyMode

Description:

Function that change the way WinParrot send data to the target application.

 

Syntax:  SetKeyMode(<Inst 1>)

 

Argument:

<Inst 1> : Instruction that must return an integer containing the send mode number. The default value is 0.

 

 If  <Inst 1>  = 0 WinParrot will send character by character.

 The string ‘Text1V[RETURN]Text2’  will be send :

T,e,x,t,1,V[RETURN],T,e,x,t, then 2  (10 operations)

Advantage:

Always works (even if the target application does not have access to the contents of the clipboard)

 

If  <Inst 1>  = 1 WinParrot will send characters by lots of characters.

The string ‘Text1V[RETURN]Text2’  will be send :

Text1, V[RETURN], then Text2 (3 operations)

Advantage:

Fast (especially if we send texts).

 

Return string: None

 

Note : If this function is called multiple times in one instruction, only the last execution is taken into account.

 

Examples:            SetKeyMode(1)

SetKeyMode(0)

 

 

12.43.      SetKeySpeed

Description:

Function which changes the speed of sending keys.

 

Syntax:  SetKeySpeed (<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which has to return an integer between 0 and 100.

The value 100 changes the typing speed to the fastest possible. With the value 0 typing is extremely slow (useful for a demonstration or debugging). If this function is not called during the playback, the default value is used (value specified in the playback options, unavailable at present).

 

Return string: None

 

Note : To control the speed of the mouse use the function SetMouseSpeed(). If the specified value is close to 0 and if you realized a loop, it is recommended that you insert into this loop controls with the search functions IfImage() or IfShape() to make sure that the target application follows well and that it is not overflowed.

 

Examples:

SetMouseSpeed(20)& SetKeySpeed(20)&IfShape(5,"testV[LBUTTON]",Stop())

 

 

12.44.      SetMouseSpeed

Description:

Function which changes the mouse speed during the playback.

 

Syntax:  SetMouseSpeed (<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which has to return an integer between 0 and 100.

The value 100 changes the mouse speed to the fastest possible. With the value 0 the mouse is extremely slow (useful for a demonstration or debugging). If this function is not called during the playback, the default value is used (value specified in the playback options, unavailable at present).

 

 

Return string: None

 

Note : To control the speed of the typing use the function SetKeySpeed(). If the specified value is close to 0 and if you realized a loop, it is recommended that you insert into this loop controls with the search functions IfImage() or IfShape() to make sure that the target application follows well and that it is not overflowed.

 

Examples:

SetMouseSpeed(20)& SetKeySpeed(20)&IfShape(5,"testV[LBUTTON]",Stop())

 

 

 

12.45.      SetPixelTol

Description:

Function which changes the tolerance of the functions of search IfImage() and IfShape() only with regard to pixels.

 

Syntax:  SetPixelTol (<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which has to return an integer between 0 and 100%.

The value '0' indicates to the search functions that there is no tolerance for pixels, one different pixel is enough to consider the two image are different.

 

Return string: None

 

Note : For a tolerance of matching colour, use rather / also the function SetColorTol().

Changes of tolerance are taken into account by the search functions SetColorTol() and SetPixelTol() only if they are called before. They have to be placed before the search functions.

It is recommended that the functions SetColorTol() or/and SetPixelTol() are added with the operator '&' before the search function, so during the playback if WinParrot stop on this instruction (by the function Stop()) you can increase the tolerances and restart the playback from this instruction.

 

Examples:

SetColorTol(20)& SetPixTol(20)&IfShape(5,"V[LBUTTON]",Stop())


 

12.46.      SetTitle

Description:

Function which displays a message in the title of the WinParrot application. So in a loop you can use this function to follow the playback while minimizing this application (Title visible in the taskbar)

 

Syntax:  SetTitle(<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which has to return a string containing the message to be displayed.

 

Return string: None

 

Note : This function doesn’t suspend the playback.

 

Examples:  SetTitle("i="&$I&"/"&$TOTAL);

 

                                         

 

12.47.      SetVar

Description:

Function which set the value of a variable.

 

Syntax:  SetVar($MY_VARIABLE ,<Inst 1>)

 

Arguments:

$MY_VARIABLE : Variable name.

<Inst 1> : Instruction that will return the value for the variable.

 

Return string: None

 

Note : To set a variable you can also use the operator ‘=’.

 

Examples:

Set the variable $PP with the value 100:

SetVar($PP, 100)

 

Beep and copy the contents of the clipboard in the variable $PP:

Beep(3000,100)&SetVar($PP, GetClipboard())


12.48.      Sgn

Description 

Function that return the sign of an integer or a float.

 

Syntax   Sgn(<Instruction>)

 

Arguments 

<Instruction>: Instruction that must return an integer or a float.

 

Return :

The integer -1 if the argument is negative.

The integer 0 if the argument is equal to zero.

The integer 1 if the argument is positive.

 

Examples

Sgn(123) will send  ‘1’ to the target application.

MsgBox(Sgn(-123)) will open a popup with ‘-1’.

 

12.49.      Stop

Description:

Function which stop the playback after having ended the execution of the current instruction and having sent to the target application the output text.

 

Syntax: Stop()

 

Arguments: None

 

Return string: None

 

Note :

When you restart the playback WinParrot will suggest you to resume it from the instruction containing this function 'Stop', the following one or since the beginning (and resetting all the variables of the document).

 

Examples:   Stop()

 

12.50.      StrLen

Description:

Function that return the length of a string.

 

Syntax:  StrLen (<Inst 1>)

 

Arguments:

<Inst 1>: Instruction that must return a string.

 

Return :   The length of the string <Inst 2> .

 

Examples:           

StrLen ("ABCDE") ó  5

$STR="ABCDE"; StrLen ($STR&"Z") ó  6

 

12.51.      StrStr

Description:

Function that searches a string in another string.

 

Syntax:  StrStr(<Inst 1>, <Inst 2>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string to parse.

<Inst 2> : Instruction that must return a text containing the string to find.

 

Return string:   If the text string resulting from the execution of the instruction

<Inst 2>  was found in the text string resulting from the execution of the instruction <Inst 1>, the function strstr () returns the character number where it has been found.

 

Notes: This function is key sensitive. It return zero if the string has not been found.

 

Examples:           

StrStr("ABCDE", "BC") ó  2

$STR="ABCDE" ; StrStr($STR, "Z") ó  0

 

12.52.      SubStr

Description:

Function that extracts a substring from a string.

 

Syntax:  SubStr(<Inst 1>, <Inst 2>, <Inst 3>)

 

Arguments:

<Inst 1> : Instruction that must return a text containing the string.

<Inst 2> : Instruction that must return an integer, it is the first character of the substring.

<Inst 3> : Instruction that must return an integer, it is the last character of the substring.

 

Return string:   The substring from the string resulting from the execution of the instruction <Inst 1>.

 

 

Examples:           

SubStr("123456",3,5) ó  "345"

SubStr("123456",3,50) ó  "3456"

12.53.      SystemCmd

Description:

Function that execute a system command.

 

Syntax:  SystemCmd(<Inst 1>)

 

Argument:

<Inst 1> : Instruction which must return a text string containing the command line to execute. If the command line is ended by the character ‘&’ the command is executed asynchronously.

 

Return string:   None.

 

Notes : If the command line is ended by the character ‘&’ WinParrot will not wait the end of the execution of the command line and it will end the execution of the current instruction.

To open a file use the function SystemOpen() (Windows will use the associated program).

.

Examples:           

-Delete a file, and wait it is deleted (‘&’ is not added at the end of the command line):

SystemCmd("cmd /C del c:\test.txt")

Note that in order to execute a DOS command you must prefix it by "cmd /C ". (For further information key in a DOS window ‘cmd /?‘ )

 

-Open a web site with a specified browser and continue the playback without waiting (‘&’ is added at the end of the command line):

$STR="iexplore " ; SystemCmd($STR&" http://www.winparrot.com&")

12.54.      SystemOpen

Description:

Function that instructs Windows to open a file or a link with the associated program.

 

 Syntax:  SystemOpen(<Inst 1>)

 

Arguments:

<Inst 1> : Instruction which should return a text containing the file or the link to open.

 

Return string:   None

 

Note : WinParrot does not waits the end of the execution of the command line it ends the execution of the current instruction.

 

Examples:           

Open the file test.txt :

SystemOpen("c:\test.txt")

Open WinParrot web site using the default browser:

$STR="http://www.winparrot.com" ; SystemOpen($STR)

 

12.55.      ToChar

Description 

Function that format in a string an integer, a float or a string according to a specified format string.

The format string is identical to that of the C language fprintf function.

(see fprintf format for further information)

 

Syntax   ToChar((<Inst 1 = format>,<Inst 2 = value>)

 

Arguments 

<Inst 1>: Instruction which has to return the format string.

<Inst 2>: Instruction which has to return the value to format (an integer, a float or a string).

 

Return :

The string formatted.

 

Example:

ToChar("%.2f",1.2) will send  ‘1.20’ to the target application.

 

Note : Below are the most used formats. The character X represents the space character.

(‘d’,’f’ for integers and floats, ‘s’ for strings).

Value

Format

Result

Comment

12

%-5d

12XXX

Right padded

12

%5d

XXX12

Left padded

12.4

%-5d

12XXX

Right padded

12.4

%5d

XXX12

Left padded

123456

%5d

123456

 

12

%05d

00012

zero-fill option

123456

%05d

123456

zero-fill option

12.345

%.2f

12.35

Two position after the decimal

12

%8.2f

XXX12.00

Eight-wide, two positions after the decimal

12

%08.2f

00012.00

Eight-wide, two positions after the decimal, zero-filled

12.345

%-8.2f

12.35XXX

Eight-wide, two positions after the decimal, left padded

12.345

%s

12.345

A simple string

12.345

%8s

XX12.345

A string with a minimum length

12.345

%-8s

12.345XX

Minimum length, left-justified

 

 

12.56.      Trace

Description:

Enable or disable the trace mode.

For further information see chapter ‘Trace your macro’.

 

Syntax: Trace(<Inst 1>,<Inst 2>,<Inst 3>)

 

Arguments:

<Inst 1>: Instruction that must return an integer between 0 and 2.
                  Value 0 disable trace mode.

Value 2 is the highest trace level.

<Inst 2>: Instruction that must return a string with the trace format (Columns to display separated by the character ‘;’).

<Inst 3>: Instruction that must return a string with the trace file name.
                  The extension of this file specify the file type (.csv, .xls or .html)

 

Return:

None.

 

Remarque: Default parameters are:

<Inst 1> : 0 (disable trace mode).

<Inst 2> :  The default format $TFORMAT contains the following columns :

"LNUM.INUM;INSTRUCTION;DESC1;DESC2;OUTPUT;ISELECTED;IFOUND":

LNUM is the line number of the instruction executed.

INUM is the n° of the instruction executed in the record.

INSTRUCTION is the instruction executed.
DESC1;DESC2 are the descriptions of the execution of the instruction.

OUTPUT is the string result of the execution of the instruction. It is also the string that will be send (by keystrokes) to the target application/window.

ISELECTED image selected (in the red rectangle) to search and / or the image centred on a point (red arrow) on which to click.

IFOUND is the image found (in the red rectangle) and / or the image centred on the point (red arrow) on which WinParrot will click .

<Inst 3> : If the full path to the trace file is not specified the folder will be the wpr folder.

If the trace file name is not specified the name of the trace file will the same as the wpr file.

If the trace file extension is not specified it will be '. html '

 

You can add extra columns to the default format $TFORMAT. You can also add variables names into the format : <Inst 2> =  "$DATE;$TIME;”&$TFORMAT&”;$MY_VARIABLE"

 

Examples:

-Enable trace with the level 2, default format and file name TraceTmpHHMMSS.html:

$TIME="HHMMSS"; Trace(2,,"TraceTmp"&$TIME&"")

-Enable trace with the level 1, add columns date, time (HHMMSS) and my variable $MY_VARIABLE, file name =TraceTmp.xls (Excel file):

$TIME="HHMMSS";

Trace(1, "$DATE;$TIME;”&$TFORMAT&”;$MY_VARIABLE","TraceTmp.xls")

Warning:

$TIME="HHMMSS";

Trace(1, "$DATE;”&$TIME&”;”&$TFORMAT&”;”&$MY_VARIABLE,"TraceTmp.xls")

Will not generate a useful trace because $TIME and $MY_VARIABLE will be constant in the trace file.

-Disable trace mode: Trace(,,)

 

 

Watch the video 'How to use the Debug & Trace functions' on  or download the AVI video .

 

 

12.57.      XlsAutoSave

Description 

Function that enable or disable the Excel auto save mode.

 

Syntax   XlsAutoSave(<Instruction>)

 

Arguments 

<Instruction>: Instruction that must return an integer N.

If N=0 auto save mode is disabled, otherwise it is enabled.

 

 

Return :

None.

 

Note : Use this function if you want an Excel spreadsheet to be saved each time you call the XlsWriteData() function. 

 

Examples

XlsAutoSave(1) : Enable the auto save mode.

XlsAutoSave(0) : Disable the auto save mode.

 

12.58.      XlsClose

Description:

Function which close an Excel workbook.

 

Syntax:  XlsClose (<Inst 1>)

 

Arguments:

<Inst 1>: Instruction which has to return the name of the Excel file to close.

 

Return string:

None.

 

Note : This function should be called at the end of a macro which open an Excel file.

 

Example:

 

·         Write «Ok » on the cell B1, save and close the workbook :

$I=1; $F="c:\x1.xls"; XlsWriteData($F,1,"B"&$I,"Ok");

XlsSave($F); XlsClose($F)

12.59.      XlsReadData

Description:

Function which reads the contents of a cell of an Excel sheet.

This function opens the Excel file if this one is not already opened.

 

Syntax:  XlsReadData(<Inst 1>,<Inst 2>,<Inst 3>)

 

Arguments: