Scripit 1.20 Command Reference ============================== Introduction: ------------- Scripit is a not a language in the normal sense of computer languages. It is, instead, a script language that allows the user to automate actions he/she would normally have to do manually. (although Scripit goes far beyond that) Scripit can do anything the user can do manually by either the mouse or keyboard by using a set of commands that instruct Scripit to simulate specific mouse or keyboard actions. The major concept in Scripit is that of a 'selected window.' As you know, the Amiga's user interface consists of windows (which reside on one or more screens.) These windows can be moved or resized, pushed to the front or back, and are used to get user input via the keyboard or mouse in the form of menu selections, boolean gadgets (clicks), string gadgets (text input), proportional gadgets (slider moves), mouse movements, mouse clicks, and keyboard actions. Scripit can simulate all of those in order to automate actions. The first step in any Scripit script is to select the 'selected window' which may or may not be the currently active window. Once a window is selected, all (well, actually most) Scripit commands will act upon that window and will send simulated actions to it. This allows Scripit to 'drive' programs that are in the background while you are working on something else. Next, commands are issued in the script to do things to the selected window. For example: select window "MyProgram" menu "MenuName" "MenuItem" This script will select the window named "MyProgram" (this is the window title displayed in its title bar) and will then simulate the user selecting the menu "MenuName" item "MenuItem". The select window command will search for the window title specified in all of the screens in the Amiga's system at the time the script was run. There are several select commands in Scripit that control how the window is selected. Scripit will never allow the user to do something that the program doesn't expect. For example, if a menu item was disabled (ghosted) Scripit will not send the simulated menu selection. This is a safety feature that makes it more reliable since the program that disabled the menu item probably did it for a very good reason. Menu selections are just a drop in the ocean of what Scripit can do, but this should give you a taste of its power. Scripit can also output text and graphics onto the selected window (without the program owning the window even knowing what is happening) or output text to a console (a text-based window) that it was run from or it has opened using special Scripit console control commands. The easiest way of starting with Scripit is to use the provided 'Recorder' to record user actions as a script that can be executed again to repeat those actions. The generated script is a valid Scripit script and can be edited and modified. However, the Recorder does not use any of the more powerful Scripit facilities such as variables, graphics and text output, console control, or logic flow commands (such as if/else, while, goto, etc.) Scripit can also be driven from ARexx allowing ARexx control over programs that do not have ARexx ports... but that is a different story entirely. ---------------------------------------------------------------------------- The following is the full reference to all Scripit commands. ---------------------------------------------------------------------------- Scripit Select Commands ======================= The SELECT commands are used to select the window Scripit will work with. For example, 'SELECT WINDOW Test' will tell Scripit to select the window titled 'Test' (actually the first window starting with 'Test') for further control. Normally, if no SELECT command was issued, the first command that tries to do anything to a window will automatically select the currently active window. If you issued a SELECT command and it couldn't find the window you requested, it will continue from there without aborting. So, the next command will select the active window automatically. The SELECT WAIT command controls the operation of all the SELECT commands. If you issue a 'SELECT WAIT 1000' command, all the SELECT commands afterwards will wait for 1000 jiffies (i.e. 1000/50 = 20 seconds) before failing and continuing with the script. (Scripit will check for the window once every 10 jiffies.) Also, if you specify the 'ABORT' keyword in the SELECT WAIT command, e.g. 'SELECT WAIT 1000 ABORT' all the SELECT commands will wait for the specified time, but will abort the script if the time runs out and Scripit couldn't find the requested window yet. So, the SELECT WAIT command actually controls the operation of the 'SELECT WINDOW Test' command. There are cases when the window you are trying to select has no title. In that case, you can use one of the other SELECT commands for that. They are: SELECT SCREEN, which selects the first window in the specified screen. SELECT MENU, which selects the window by the name of one of its menus. SELECT GADGET, which selects the window by the name of one of its gadgets. SELECT ACTIVE, which selects the active window. Command Summary: ---------------- SELECT screenname windowname Select the Screen (and window) all the other commands will work on. If no SELECT command was used, the currently active window will be selected. (In all cases, the first match will be used.) S SCREEN screenname Select the first window in the specified screen. S WINDOW windowname Select the specified window. (Searches through all the screens in the system.) S ACTIVE Select the currently active window. S MENU menuname This will force the screen/window search to look for the specified menu as the search criterion for the SELECT command. This should only be used with programs that have no screen or window name. (e.g. to select DPaint: SELECT MENU Picture) Make sure you select a menu name that is unique to the program you're looking for. S GADGET gadgetname This will force the screen/window search to look for the specified gadget name as the search criterion for the SELECT command. This should be used only when the program has no no screen or window name, or any menus. Make sure you select a gadget name unique to the window you're looking for. S WAIT [MaxDelay] [ABORT] This sets the time all the SELECT commands will keep trying to find the requested screen, window, menu, or gadget. The MaxDelay is specified in ticks, (50 per second). The ABORT keyword, when specified, tells Scripit to abort the script if the requested window, etc. could not be found in the specified time, otherwise, if the ABORT keyword was not specified, the script will just continue. Example: SELECT WAIT 500 ABORT This means: Wait for 10 seconds (500/50) and if nothing found then abort the script. The S WAIT command doesn't do anything by itself, it only modifies the operation of the other SELECT commands (except for SELECT ACTIVE.) To turn the wait off, just type 'S WAIT' alone. Return Codes: ------------- All select commands (except SELECT WAIT) will fill in #result with 1 for success or 0 for failure. If #result is true, then #result2 will have the actual window's address, and #result3 will have the actual screen's address. $window will contain the window's title and $screen will contain the screen's title. Note: In all SELECT commands, SELECT can be replaced with an 'S'. ----- e.g. 'S ACTIVE' is the same as 'SELECT ACTIVE'. ---------------------------------------------------------------------------- Main Commands ============= The following commands mostly simulate user actions. (i.e. menus, gadgets, mousemoves, keyboard keys, etc.) MENU menu menuitem Simulate a menu selection from the selected window's menu. The input is 'menu' 'menuitem' and if needed 'subitem'. This command needs at least the first two to work. Note 1 explains naming conventions. (If the window has the MENUVERIFY flag set Scripit will send a MENUVERIFY msg and wait for a reply to it before sending the actual menu select message.) Return Codes: #result : 1 for success, 0 for failure. $result : Menu name $result2 : Item name $result3 : Subitem name (if exists) if #result == 0, then: #result2 : 0 for menu not found, 10 for menu disabled. GADGET gadgetname ID NUM X Y This controls the gadgets of the selected window. It needs a gadgetname (or number) to identify the gadget and, depending on the gadget type needs more arguments to modify that gadget's contents. It will send both a GadgetUp and a GadgetDown message if the window's flags request that. (See Note 3 for more info.) Return Codes: ------------- ALL gadget commands (GADGET, GADGETDOWN, GADGETUP & GETGADGET) fill in the following return codes: $result : full text name of gadget (if exists) #result : 0 = failure (gadget not found), 1 = bool gadget, 2 = prop gadget, 3 = string gadget if #result == 1 : (bool gadget) #result2 : 0 = gadget not selected, 1 = gadget selected if #result == 2 : (prop gadget) #result2 : prop gadget horizontal position (0-65536) #result3 : prop gadget vertical position (0-65536) if #result == 3 : (string gadget) $result2 : current contents of string gadget $result3 : contents of string gadget undo buffer GADGET boolgadgetname ID NUM X Y Triggers a selected bool gadget from the selected window. GADGET stringgadgetname ID NUM X Y newstring Replaces the string in a string gadget with a new string and simulates a 'return' on the gadget. [opt1] is the new string. GADGET propgadgetname ID NUM X Y horz,vert Changes the position of a proportional gadget. The input values reflect the horizontal and vertical prop position of the gadget. (Values allowed: 0-65535) [horz] is the horizontal position, and [vert] is the vertical position. GADGETDOWN Does the same job as 'GADGET' except that it will only send GadgetDown messages and not GadgetUp messages. (For use with Recorder scripts.) GADGETUP Does the same job as 'GADGET' except that it will only send GadgetUp messages and not GadgetDown messages. (For use with Recorder scripts.) GETGADGET gadgetname ID NUM This is identical to the GADGET command, except that it doesn't actually trigger or do anything to the gadget. It will just check the gadget's status and fill in the corresponding result variables as per the GADGET command's return results. WAIT Suspends script execution for delay * 1/50th seconds. Default delay time is 25, i.e. 1/2 second. LMB x,y Simulate clicking the left mouse button while the pointer is at position x,y. Related : SELECTUP Sends only LMBUp message. Commands : SELECTDOWN Sends only LMBDown message. RMB x,y Simulate clicking the right mouse button while the pointer is at position x,y. Related : MENUUP Sends only RMBUp message. Commands : MENUDOWN Sends only RMBDown message. DOUBLECLICK Simulate a double click. This can be one of the following: DOUBLECLICK GADGET boolgadget DOUBLECLICK RMB DOUBLECLICK LMB The delay between the two clicks is controlled by the double- click setting in Preferences. VERBOSE [ON] or [FULL] or [OFF] Turns on debug text printout to the console window. Default mode is off. VERBOSE ON will turn it on, any keyword other than 'ON' will turn it off except VERBOSE FULL which will turn on full debug display. DRAG x,y,x2,y2,[steps] This is intended for use with WorkBench. It will click on an icon at x,y (if it exists) and will keep holding down the button while moving the icon to x2,y2 where it will release the button. It is the equivalent of: (RMBDOWN x,y + MOUSEMOVE x2,y2 + RMBUP x2,y2). Steps, if specified, will make the drag into an actual drag by inserting interim MOUSEMOVE commands between the RMBDOWN and RMBUP. The number of interim moves is the number of steps specified. MOUSEMOVE x,y Simulates mouse movement to x,y. (Sends a MOUSEMOVE message.) DELTAMOVE x,y Simulate mouse movement by x,y. (Sends a DELTAMOVE message.) RAWKEY code,qualifier Sends a RAWKEY event to the program owning the selected window. This command is only intended for script generated by the auto- script generator, Recorder. ITICK x,y Sends an INTUITICKS event to the program. This is only intended for scripts generated by the Recorder. POINTER x,y [l] [L] [r] [R] Pointer will move the mouse pointer to position x,y on the current screen. This will _really_ move the pointer not just simulate it. The qualifier (one of the following l,L,r,R) simulates left mouse button down, left mouse button up, right mouse button down, right mouse button up. DRAW x,y x2,y2 x3,y3 ..... xn,yn A specialized command used for drawing on DeluxePaint's screen. It simulates the following: POINTER x,y l POINTER x2,y2 L POINTER x2,y2 l POINTER x2,y2 L .... POINTER xn,yn l POINTER xn,yn L WAITFOR screen window [ABORT] This command is obsolete. You should use the SELECT WAIT command instead. This was left in here for compatibility with older scripts only. RUN Simply runs another program. Control returns immediately to the script which continues executing. If you want to include any command line switches, then RUN "programname switches.." Read note 4. RUNBACK Simply runs another program. Control returns immediately to the script which continues executing. The program will not have any input or output streams. Read note 4. EXECUTE Executes another program. Script processing will wait until the program exits. You can also use the shorthand version of this command: 'X'. (e.g. X list) Read note 4. REQUEST [requester title] [default dir] [default file] [left edge] [top edge] [req width] [req height] This brings up the Scripit file requester and allows the user to select a file. The return value of the requester is stored in system variable $request. (see 'System Variables') The arguments provided to REQUEST are not necessary, but they override the defaults. The requester's title is "Please Select A File:" unless you supply one. The default dir and default file are whatever was in the File Requester the last time it was run. The left edge, top edge, width and height control the size and placement of the requester when it comes up. (The requester itself is totally resizable and moveable by the user.) If none of those was specified, the requester will come up where it was the last time it was used. NOTE: The requester will always show up on the selected screen! (or on the Workbench screen if none was selected.) Important: This function is not available in 'Xit' only in the 'Scripit' program itself. ABORT [ON] or [PAUSE] or [OFF] ABORT controls whether the abort and pause/restart facilities work or not. ABORT OFF disables both the abort and the pause/ restart facilities. ABORT PAUSE only allows the pause/restart but not the abort facility. And ABORT ON, which is the default mode, allows both. Abort facility: You can break out of a script that is currently executing by holding down both the left mouse button and the control key on the keyboard. Pause/restart facility: You can stop the execution of a script at any time by pressing the left mouse button and the left shift key at the same time. To resume the script press the left mouse button and then right shift key. (you can also use the abort facility even when a script is paused.) FORMAT formatstring arg1 arg2 ... argn FORMAT is a text formatting function that does the same function that sprintf() does in the C language. It uses the same format as sprintf(). The following is the full explanation of it: The formatting result string is stored in $result. The format string contains two types of items: normal text characters and 'coversion specifications', each of which causes the conversion and output of the next successive argument. The conversion specification always starts with a % and continues with some optional characters, then the conversion type characters, which can be any of the following: d, o, x, u, c, or s. For example: $name = "Khalid Aldoseri" #age = 24 FORMAT "Name : %s Age : %d" $name #age After this, $result will contain: "Name : Khalid Aldoseri Age : 24" Conversion Characters: ---------------------- d, o, or x The integer in the corresponding argument is converted to decimal, octal, or hexadecimal notation, respectively, and output to the result string. u Converts an unsigned integer. c Converts the integer to a single character based on the standard ASCII tables. s The characters in the corresponding argument are output. Optional specifications: ------------------------ These come in between the % and the conversion character. a. An optional minus sign (-) which specifies left adjustment of the converted integer or string. b. An optional digit string specifying the 'field width' for the conversion. If the resulting string has fewer characters than this, enough blank characters are output to make the total number of characters output equal the field width. If the field width digits have a leading 0, 0 is used as a pad character rather than a blank. The minus sign controls whether the blanks are output before or after the string. For example: FORMAT "Hex: %08x Decimal: %8d" 10 10 Then, $result will contain "Hex: 0000000a Decimal: 10" PRINTF formatstring arg1 arg2 ... argn PRINTF does exactly the same job as FORMAT, except that it will print out the result string to the current console. The result will still be available in $result. PRINTF also allows for the special character codes as listed in the next command. PRINT arg1 arg2 ... argn Prints out the strings provided to the current console. The is not terminated after each string. You can also use any of the following special codes in the strings: \n Return + Line feed \e Return (no line feed) \r Same as \e \t Tab \b Backspace E.g.: PRINT "Test\n" These codes are only translated into actual returns, etc. when the string is about to be printed, so if you store such codes in a string variable, the code is stored, not the actual ASCII character. These codes are also supported by the PRINTF, CON ECHO, and CON TEXT commands. Note 1: Argument format for Screen, Window, Menu and Gadget Selection: ------- The required item can be selected by specifying: a. The item's name. This is NOT case-sensitive. Abbreviations are allowed. (i.e. 'Pro' will match the first item that starts with 'Pro' e.g. 'Project'.) Leading spaces are ignored. b. The item's number. This is the sequential number of the item in its list. This must always start with '^' and a number. (e.g. 'MENU ^1 ^4 ^3' will select the first menu, the fourth menuitem, and the 3rd subitem.) Note 2: Arguments can be separated by one or more spaces, tabs, or a ------- comma. Any string argument can be surrounded with double-quotes to include spaces in its text. (e.g. "Text string") All numeric arguments are integer. (i.e. no fractions allowed) Any argument can be substituted by a string or integer variable. (Read section on 'Variables.') Note 3: Gadgets are selected by one of the following methods: ------- a. Gadget Name: This is the text that is normally attached to a gadget. Few programs attach text to gadgets. (Also use Lister for gadget names.) b. Gadget ID: This is the gadget's ID number. Most programs have unique ID numbers for each gadget. You can find out a gadget's ID by using the 'Lister' program. c. Serial Number: This is just a serial number of the gadget. It is reliable in some programs, and unreliable in others. Scripit will search for the gadget based on the following logic: 1. Search for gadget name, first gadget that matches the name will be selected. If no matching gadget found, or gadget name was a null (""), then: 2. Search for ID. If found ID, then gadget found, unless more than more gadget with the same ID was found. 3. As a last resort, scan for the gadget by its serial number. Examples: a. Bool Gadget: GADGET "gadname" 323,6,10,34 This will search for "gadname" first, then ID 323, then #6. The X (10) and Y (34) settings are fed into the message sent to the program because some programs need to know where the pointer is when the gadget was clicked on. b. String Gadget: GADGET "gadname" 323,6,10,34 "newstring" c. Prop Gadget: GADGET "gadname" 323,6,10,34 horz,vert Note 4: The EXECUTE, RUN, and RUNBACK commands will interpret any ------- arguments added after the command and these arguments are correctly passed to the command being executed/run. For example: RUN list df0: To give null arguments to a program, just use "". e.g.: X Lister "" workbench Of course, any program name or argument that contains spaces or commas needs to be in double quotes. Note 5: The following commands return #result = 1 if successful, 0 if ------- failed: (success is if the message was delivered correctly to the program.) LMB, RMB, DOUBLECLICK, DRAG, MOUSEMOVE, DELTAMOVE, RAWKEY, ITICK, POINTER, DRAW. ---------------------------------------------------------------------------- Scripit Graphics Commands ========================= These commands draw directly on the specified window (i.e. into its RastPort, if you understand what that means) The program owning the window will not know if you changed the contents of the window. To use those, just SELECT the window you want, and start drawing! (Note: To select DPaint's window, use SELECT MENU PICTURE) GFX PEN front_pen,back_pen,drawmode This sets the current front pen, back pen, and draw mode. The pen number can range from 0 to the number of colors on the screen. The draw mode can be one of the following: JAM1 (the background color, 0, does not overwrite what is underneath it.) JAM2 (color 0 clears whatever is underneath it.) COMP (the complement mode reverse the color of the original pixel.) and INVR (which is the same as JAM2, only with the front and back pen reversed.) GFX MOVE x,y Moves the windows 'cursor' to the specified x,y coords. This affects where drawing will start. GFX TEXT "string" Prints the specified string in the current font to the position selected by MOVE. (using the current front pen, back pen, and drawing mode.) GFX LINE x1,y1 x2,y2 .... xn,yn Draws connected straight lines. GFX CIRCLE x,y,radius Draws a circle at x,y using the specified radius GFX ELLIPSE x,y,x_radius,y_radius Draws an ellipse at x,y using the specified x_radius and y_radius. GFX BOX x,y,x2,y2 Draws a rectangle. x,y and x2,y2 are any two opposite corners. GFX RECT x,y,x2,y2 Draws a filled-in rectangular. x,y and x2,y2 are any two opposite corners. GFX CLEAR x,y Clears the current window. The x,y are optional and select the start position for clearing. GFX CLEARLINE x,y Clear to the end of the current line starting at x,y. GFX FILL x,y,fillmode Does a flood-fill at the selected x,y using the current front pen. Fillmode can be either 0 or 1. (Note: This is currently not working very well, but I opted to keep it in here.) GFX PIXEL x,y Draws a single pixel at x,y using the current frontpen and drawmode. GFX SAVEMODE modenumber This saves the current settings (front pen, back pen, draw mode, and current x,y) to a temporary storage. The modenumber selects the storage slot number. (from 0 to 3) You should always use the GFX SAVEMODE command before changing anything in the window, and restore them using the next command as soon as possible. GFX RESTOREMODE modenumber Restores the current settings to those stored in the selected location. (0 to 3) Example: -------- select window "Workbench" gfx savemode gfx move 10,10 gfx pen 1,0,JAM2 gfx text "Some text on the Workbench Window!" gfx restoremode This script will select the Workbench window, save its current settings, move the draw cursor to 10,10, set the front pen to 1, back pen to 0, and draw mode to JAM2, then type some text there and finally restore the window's settings to what they were. ---------------------------------------------------------------------------- Scripit Console Commands ======================== Scripit can output text to any text console using its console commands. These allow both output of text and ANSI console control commands. These Commands work with a CLI console only: -------------------------------------------- CON CLS Clears all the text in the console and moves the cursor to the top left-hand corner. CON ECHO [string_1] [string_2] [string_3] ... [string_n] Prints out the specified strings onto the console. Each string is printed on its own line. Please refer to the description of the PRINT command for more details on print codes. CON TEXT [string_1] [string_2] [string_3] ... [string_n] Prints out the specified strings onto the console. The line is not terminated after each string. Note: To terminate a line use \n code E.g. CON TEXT "test " $test "\n" Please refer to the description of the PRINT command for more details on print codes. CON MOVE x,y Moves the cursor to position x,y. If no x,y were given, the cursor will be moved to the top left of the screen. CON UP [n] CON DOWN [n] CON LEFT [n] CON RIGHT [n] Move the cursor up/down/left/right n times. (default is 1) CON SCROLLUP [n] CON SCROLLDOWN [n] Scroll the console lines up/down n lines. (default is 1) CON INSLINE CON DELLINE Insert/Delete a line at the current cursor position. CON INSCHAR [n] CON DELCHAR [n] Insert/delete [n] chars at the current cursor position. CON CURSORON CON CURSOROFF Turn cursor display on/off. CON CLREOL Erase to end of line. CON CLREOD Erase to end of display. CON STYLE