User Guide/The Script Controller: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
No edit summary
 
(18 intermediate revisions by the same user not shown)
Line 2: Line 2:
[[File:ws_sc.png]]
[[File:ws_sc.png]]


The Script Controller provides a convenient way to run {{STx}} scripts from the {{STx}} Workspace. You can also open the {{STx}} Console, a command line interface to an {{STX}} macro shell.
The '''Script Controller''' is a part of the [[User_Guide/Workspace|Workspace]] GUI, displayed in the upper right part of the window, and provides a convenient way to develop and run {{STx}} scripts.


===Hiding and showing Script Controller===
To hide or show the {{STx}} Script Controller, use the Workspace menu item "Scripts > Show Scripts".


To hide or show the {{STx}} Script Controller, use the Workspace menu item "Scripts > Show Scripts".
Note: The [[User_Guide/Workspace_/Detail_Find_Select|Find / Select dialog]] of the detail view is displayed in the same part of the GUI as the Script Controller. Only one of both dialogs can be visible.
 
===Dialog Elements to Select and Run a Script===


===Running a script===
;Script File (button): Press this button to open the standard open-file dialog to select a script file. The full path of the selected file is displayed as caption of the button.
:* Note: To select a script file, you can also drop a file with the standard {{STX}} script file type '''.sts''' on the workspace window, and than press the button '''Select''' in the displayed popup dialog box.


To run an {{STx}} script from the mighty {{STx}} Script Controller, do the following:
;Macro (combo box): This combo box contains a list of all visible macros (or executeable code sections) of a script file. Use this list to select the macro to be executed when the '''Run''' button is pressed.


# Select a script file by clicking the "Script File" button. {{STx}} will provide you with a file selection dialog labelled "Select script file" allowing you to tell {{STx}} which script file to use.
;Arguments (combo box): In this field you can provide the arguments for the selected macro. The arguments entered here, are stored in a history.
# Choose the macro to be run from the "Macro" combobox. In this comobox, {{STx}} lists all macros available in your script file.
# If your macro expects arguments, provide them in the "Arguments" field.
# To finally execute the macro, ''either'' press the [[File:resource_script_run.png]] button, ''or'' choose the menu item "Scripts > Run", ''or'' just press the Enter key while in the "Arguments" combobox.


You can also add scripts and store their arguments in the "Application & Setup Tree" under the entry [[User Guide/Workspace/Scripts|Scripts]].
;Run - [[File:Resource_script_run.png]] (button): The script file is loaded into the BScript runtime environment and the macro selected by the combobox '''Macro''' is executed. See the options '''Debug''' and '''Console''' for the selection of special run modes of a script.


===Debugging a script===
;Console (button): Press this button to start the [[User_Guide/STX_Console|{{STX}} Console application]], which provides a command line interface to an {{STX}} shell.


Just check the "Debug" checkbox. Now when you execute the script, the {{STX}} debugger will automatically open.
<u>'''Four steps to run a script'''</u>:
:# Select a script file by clicking the "Script File" button.
:# Choose the macro to be run from the "Macro" combobox.
:# If your macro expects arguments, provide them in the "Arguments" field.
:# To finally execute the macro, ''either'' press the '''Run''' button, ''or'' choose the menu item "Scripts > Run", ''or'' press the Enter key while in the "Arguments" combo box.


===Command History===
Note: The most functions of the Script Controller dialog are also available in the menu "Script" of the workspace, but they are actived only when the Script Controller dialog is visible.


A history of arguments passed to the script is stored and can be retrieved by selecting an entry from the "Arguments" combobox.
===Dialog Elements for Script Development===


===The Console===
;New (button): Press this button to create a new script file via the standard new-file dialog. If a new file is created, it is also selected and opened in the external text editor.


[[File:Console dialog.png|thumb]]
<u>Content of a new script file created via the '''New'''-button</u>:
//{{4.2.14 (8805)}{2016.01.19  10.32.20} - automatically created version information - do not change or delete this line}
[Macro testfile read: #arg1 #arg2 #arg3 #arg4 #arg5 #rest]
//>> begin of script - enter your source code below this line
//<< end of script
// AutoCloseSF  := 0 // close all used sound files automatically on exit
// ShowLogOnExit := 0 // close bscript log-window automatically (no wait)
exit 1 int 0


If you press the Console button, the Console application is started. The Console is a command line interface to an {{STX}} shell.
;Edit - [[File:Resource_script_edit.png]] (button): Open the selected script file in the text editor.


The Console can:
;Test - [[File:Resource_script_test.png]] (button): Use this button to test if the script file can be loaded (syntax check) and if it is compatible with your {{STX}} release. Note: If the script file can not be loaded, a short error message is displayed in a dialog box and detailed error messages are written to the [[User_Guide/Log_Window|{{STX}} log window]].
# process commands on a line by line basis
# process multiple commands pasted from the clipboard
# maintain a command history (up/down keys)


The Console cannot:
;[[User_Guide/STX_Debugger|Debug]] (check box): Check this option to run the selected macro in the [[User_Guide/STX_Debugger|debug mode]] and uncheck it, to execute the macro without debugging. If the dubug mode is enabled, the Break-mode of the debugger is entered before the execution of the macro begins.
# process IF or WHILE control statements


The Console implements the following additional commands:
;[[User_Guide/STX_Console|Console]] (check box): Check this option to run the script file in the [[User_Guide/STX_Console|console mode]]. If the '''Run''' button is pressed, the script file is loaded and the console application is started. This mode can be useful, e.g. to test some macros during the development of a complex script package or to load a script file that implements a set of special functions intended to be used in the command line.


: exit
===Other ways to select / run Scripts===
: cls|clear
: cd
: pwd
: ls
: log
: list
: setcon
: stx
: sts
: use


Other ways to select / run {{STX Scripts}}
* You can add scripts and store their configuration and arguments in the [[User_Guide/Workspace/Application_and_Setup_Tree|Application & Setup Tree]] under the entry '''Scripts'''. If a script is linked to the workspace, it can be started easily with a double-click.
* Script files can be added to the Script section of the [[User_Guide/Workspace/Application_and_Setup_Tree|The Application & Setup Tree]] of the [[User_Guide/Workspace|Workspace]].
* Start the [[User_Guide/BScript_Console|{{STx}} Console]] to load and run scripts via the command line.
* If a script file ''filename''.'''sts''' is dropped on the workspace, a dialog comes up to select a function for the script file:
** Add the file to the [[User_Guide/Workspace/Application_and_Setup_Tree|The Application & Setup Tree]
** Run the macro ''filename'' defined in the script file
** Select the script file as the current file of the Script Controller
** Edit the file ''filename''.'''sts'''




The Console was added to {{STX}} in version 3.9. It is currently in its baby shoes, so please be nice to it, and report any misbehaviour.
;See also:
[[Programmer_Guide|Programmer Guide]], [[User_Guide/Toolboxes|Toolboxes]]


[[Category:User Guide]][[Category:Workspace]]
[[Category:User Guide]][[Category:Workspace]][[Category:Scripts]]

Latest revision as of 10:37, 20 January 2016

Ws sc.png

The Script Controller is a part of the Workspace GUI, displayed in the upper right part of the window, and provides a convenient way to develop and run STx scripts.

To hide or show the STx Script Controller, use the Workspace menu item "Scripts > Show Scripts".

Note: The Find / Select dialog of the detail view is displayed in the same part of the GUI as the Script Controller. Only one of both dialogs can be visible.

Dialog Elements to Select and Run a Script

Script File (button)
Press this button to open the standard open-file dialog to select a script file. The full path of the selected file is displayed as caption of the button.
  • Note: To select a script file, you can also drop a file with the standard STx script file type .sts on the workspace window, and than press the button Select in the displayed popup dialog box.
Macro (combo box)
This combo box contains a list of all visible macros (or executeable code sections) of a script file. Use this list to select the macro to be executed when the Run button is pressed.
Arguments (combo box)
In this field you can provide the arguments for the selected macro. The arguments entered here, are stored in a history.
Run - Resource script run.png (button)
The script file is loaded into the BScript runtime environment and the macro selected by the combobox Macro is executed. See the options Debug and Console for the selection of special run modes of a script.
Console (button)
Press this button to start the STx Console application, which provides a command line interface to an STx shell.

Four steps to run a script:

  1. Select a script file by clicking the "Script File" button.
  2. Choose the macro to be run from the "Macro" combobox.
  3. If your macro expects arguments, provide them in the "Arguments" field.
  4. To finally execute the macro, either press the Run button, or choose the menu item "Scripts > Run", or press the Enter key while in the "Arguments" combo box.

Note: The most functions of the Script Controller dialog are also available in the menu "Script" of the workspace, but they are actived only when the Script Controller dialog is visible.

Dialog Elements for Script Development

New (button)
Press this button to create a new script file via the standard new-file dialog. If a new file is created, it is also selected and opened in the external text editor.

Content of a new script file created via the New-button: 

//{{4.2.14 (8805)}{2016.01.19  10.32.20} - automatically created version information - do not change or delete this line}

[Macro testfile read: #arg1 #arg2 #arg3 #arg4 #arg5 #rest]
//>> begin of script - enter your source code below this line

//<< end of script
// AutoCloseSF   := 0 // close all used sound files automatically on exit
// ShowLogOnExit := 0 // close bscript log-window automatically (no wait)
exit 1 int 0
Edit - Resource script edit.png (button)
Open the selected script file in the text editor.
Test - Resource script test.png (button)
Use this button to test if the script file can be loaded (syntax check) and if it is compatible with your STx release. Note: If the script file can not be loaded, a short error message is displayed in a dialog box and detailed error messages are written to the STx log window.
Debug (check box)
Check this option to run the selected macro in the debug mode and uncheck it, to execute the macro without debugging. If the dubug mode is enabled, the Break-mode of the debugger is entered before the execution of the macro begins.
Console (check box)
Check this option to run the script file in the console mode. If the Run button is pressed, the script file is loaded and the console application is started. This mode can be useful, e.g. to test some macros during the development of a complex script package or to load a script file that implements a set of special functions intended to be used in the command line.

Other ways to select / run Scripts

  • You can add scripts and store their configuration and arguments in the Application & Setup Tree under the entry Scripts. If a script is linked to the workspace, it can be started easily with a double-click.
  • Start the STx Console to load and run scripts via the command line.
  • If a script file filename.sts is dropped on the workspace, a dialog comes up to select a function for the script file:
    • Add the file to the [[User_Guide/Workspace/Application_and_Setup_Tree|The Application & Setup Tree]
    • Run the macro filename defined in the script file
    • Select the script file as the current file of the Script Controller
    • Edit the file filename.sts


See also

Programmer Guide, Toolboxes

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=User_Guide/The_Script_Controller&oldid=8661"

Navigation menu

Personal tools