Programmer Guide/Macro Library/BUTIL: Difference between revisions

From STX Wiki
Jump to navigationJump to search
(initial import)
 
 
(87 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}} - Misc. Utility Functions}}
'''File''': BUTIL.STX, linked to library STX.LIB


{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==CopyFile, DeleteFile, RenameFile, OpenFile==

BUTIL COPYFILE <var>src</var> ; <var>dst</var>
==BUTIL==
:Copy file <var>src</var> to file or directory <var>dst</var>.
BUTIL RENAMEFILE <var>src</var> ; <var>dst</var>
:Rename or move file <var>src</var> to file or directory <var>dst</var>.
BUTIL DELETEFILE <var>src</var>
:Delete the file <var>src</var>
BUTIL OPENFILE [*] ; <var>src</var>
:Open the file <var>src</var> with the default application.
BUTIL OPENFILE <var>app</var> ; <var>src</var>
:Open the file <var>src</var> with the specified application <var>app</var>.


This macro implements a package of general purpose functions.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>app</var>
|The name of the application to open the file. If empty or *, the default application is used.
|*
|-
|<var>src</var>
|The file to copy, delete, rename (move) or open.
|
|-
|<var>dst</var>
|The target file or directory for copy or rename (move).
|
|-
!RESULT !!description
|-
|<code>0</code> ||success
|-
|<var>rc</var> ||The non-zero error code if the command has failed.
|}
;See also: [[Programmer_Guide/Macro_Library/Kernal/StdLib#FileToolBox|FileToolBox]]



==EditBox==
==COPYFILE==
BUTIL EDITBOX [<var>text</var> ; <var>value</var> ; <var>title</var> ; <var>width</var> ]
:Display a simple dialog with one input field.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>text</var> ||Text to display above the edit field. ||
|-
|<var>value</var> ||The initial (default) value for the edit field. ||
|-
|<var>title</var> ||The caption of the dialog window. ||<code>Edit Box</code>
|-
|<var>width</var> ||The width of the edit field (in character units). ||17
|-
!RESULT !!description
|-
|<var>value</var> ||The content of the edit field if the dialog was closed with the <code>OK</code> button or the <code>[Enter]</code>-key.
|-
|''empty string'' ||If the dialog was cancelled.
|}
;See also: [[Programmer_Guide/Macro_Library/DOMODALDIALOG|DoModalDialog]], [[Programmer_Guide/Macro_Library/CDLGMAP|CDlgMap]]


Copy the source file to the target.
==GetDirectory==
BUTIL GETDIRECTORY <var>path</var>
:Check if the specified directory <var>path</var> exists. The current directory is not changed.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>path</var>
|The directory to be checked.
|
|-
!RESULT !!description
|-
|<var>path</var> ||The fullpath of the specified directory.
|-
|<code>$@root</code> ||The {{STX}} installation directory if the specified directory was not found.
|}
;See also: [[#DirectoryDialog|DirectoryDialog]], [[#Directory|Directory]], [[Programmer_Guide/Command_Reference/PWD|PWD]]


=====Usage:=====
==GetKeyWord, GetKeyIndex==
BUTIL GETKEYWORD <var>val</var> ; <var>defval</var> ; <var>keyword1 keyword2</var> ...
:Return the '''keyword value''' if <var>val</var> is a valid index or abbreviation of one of the keywords, otherwise return the default value <var>defval</var>.
BUTIL GETKEYINDEX <var>val</var> ; <var>defval</var> ; <var>keyword1 keyword2</var> ...
:Return the '''keyword index''' if <var>val</var> is a valid index or abbreviation of one of the keywords, otherwise return the default value <var>defval</var>.
:Both functions are normally used to check/verify arguments passed to macro.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>val</var>
|The value to check.
|
|-
|<var>defval</var>
|The default value to be returned if <var>val</var> is neighter an abbreviation nor an index of a keyword.
|
|-
|<var>keyword1</var> ...
|Blank seperated list of keywords (not case sensitive).
|
|-
!RESULT !!description
|-
|<var>keyword/index</var> ||If <var>val</var> is a an abbreviation or an index of a keyword.
|-
|<var>defval</var> ||otherwise
|}
;See also: [[#GetSwitch|GetSwitch]], [[Programmer_Guide/Command_Reference/KEYWORD|KeyWord]]


<code>BUTIL COPYFILE source ; target</code>
==GetSwitch==
BUTIL GETSWITCH <var>val</var> ; <var>defval</var>
:Verify and return boolean value. This function is normally used to check/get argument values.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>val</var>
|The value to check.<BR>Valid values are: <code>0=no=false=off, 1=yes=true=on</code>
|
|-
|<var>defval</var>
|The default value to be used if <var>val</var> is invalid. The same values as for <var>val</var> can be specified.
|0
|-
!RESULT !!description
|-
|<code>0</code> or <code>1</code>
|
|}
;See also: [[#GetKeyWord, GetKeyIndex|GetKeyWord and GetKeyIndex]]


=====Parameters:=====
==Directory==
BUTIL DIRECTORY [ <var>dir</var> ]
:Select specified directory <var>dir</var> and/or get full pathname of current directory. This function never returns an error. If no directory is specified or the specified directory <var>dir</var> do not exist, the full path of the current directory is returned.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>dir</var>
|The directory to be selected.
|
|-
!RESULT !!description
|-
|<var>pwd</var> ||The fullpath of the selected/current {{STX}} working directory.
|}
;See also: [[Programmer_Guide/Command_Reference/PWD|PWD]], [#Directory|Directory]], [[#DirectoryDialog|DirectoryDialog]]


;<var>source</var>
==DirectoryDialog==
BUTIL DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]
DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]
:Display the {{STX}} standard dialog for directory selection. This dialog allows the user to select a directory and to perform some special file/directory operations.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>title</var>
|The caption of the dialog window.
|<code>Select Directory</code>
|-
|<var>path</var>
|The default directory.
|current directory
|-
|<var>restore</var>
|<code>no</code> or <code>0</code> &rarr; do not restore current directory<BR>
<code>yes</code> or <code>1</code> &rarr; restore current directory
|<code>no</code>
|-
|<var>sdmode</var>
|<code>no</code> or <code>0</code> &rarr; do not display the '''subdirectories''' checkbox<BR>
<code>yes</code> or <code>1</code> &rarr; display the '''subdirectories''' checkbox
|<code>no</code>
|-
|<var>sdvalue</var>
|Initial state of the '''subdirectories''' checkbox: <code>off</code> (=<code>0</code>) or <code>on</code> (=<code>1</code>)
|<code>off</code>
|-
!RESULT !!description
|-
|<var>path</var> ||If <var>sdmode</var> equals <code>no</code> &rarr; The full pathname of the selected directory.
|-
|<var>path;sdvalue</var> ||If <var>sdmode</var> equals <code>yes</code> &rarr; The full pathname of the selected directory and the value of the '''subdirectories''' checkbox (<code>0</code> or <code>1</code>).
|-
|''empty string'' ||If the dialog was canceled.
|}
;See also: [[#GetDirectory|GetDirectory]], [[#Directory|Directory]], [[Programmer_Guide/Command_Reference/PWD|PWD]]


:The file name (and path) of the file being copied.
==FileDialog, FileNewDialog, FileOpenDialog==
BUTIL FILEDIALOG OPEN|LOAD [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
FILEOPENDIALOG [ <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
:Display the {{STX}} standard dialog to open or load a file. Only existing files can be selected. If the function <code>BUTIL FILEDIALOG</code> is called without an argument, the '''open''' style is assumed.
BUTIL FILEDIALOG NEW|SAVE [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
FILENEWDIALOG [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
:Display the {{STX}} standard dialog to create a new file or to save (save as) a file. If an existing file is selected, the user is asked if the file should be replaced.
:The displayed dialog allows the user to select/enter a filename and to perform some special file/directory operations.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>title</var>
|The caption of the dialog window.
|<code>Select File</code>
|-
|<var>path</var>
|The default file or directory.
|current directory
|-
|<var>ftype1</var> ...
|Each <var>ftype</var> argument defines one entry of the filetype-combobox of the dialog.<BR>
Each filetype is defined by the string <code><var>extension</var>=<var>description</var></code>.<BR>
Example: <code>WAV=wave files</code><BR>
If a <var>ftype</var> argument is the name of a (simple) table item, each entry of the table defines a filetype.
|-
!RESULT !!description
|-
|<var>path</var> ||The full pathname of the file to be opened or created.
|-
|''empty string'' ||If the dialog was canceled.
|}


;<var>target</var>
==MsgBox==


:The name of the target file or directory to copy to.
BUTIL MSGBOX <var>type</var> [<var>buttonlist</var>] [ ; <var>text</var> ; <var>title</var> ; <var>maxtime</var> [<var>timestep</var>] ; <var>xpos</var> ; <var>ypos</var> ; <var>monitor</var> ; <var>defaultbutton</var> ]
BUTIL MSGBOXEX '<var>type</var> [<var>buttonlist</var>]' '<var>text</var>' [ '<var>title</var>' '<var>maxtime</var> [<var>timestep</var>]' '<var>xpos</var>' '<var>ypos</var>' '<var>monitor</var>' '<var>defaultbutton</var>' ]
MSGBOXEX '<var>type</var> [<var>buttonlist</var>]' '<var>text</var>' [ '<var>title</var>' '<var>maxtime</var> [<var>timestep</var>]' '<var>xpos</var>' '<var>ypos</var>' '<var>monitor</var>' '<var>defaultbutton</var>' ]
:Display a message box dialog with a set of pre-defined (depending on <var>type</var>) or user-defined (<var>type</var> = <code>USERDEFINED</code>) buttons.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>type</var> [<var>buttonlist</var>]
|Defines the type of the message box and the displayed buttons (see table below).<BR>The <var>buttonlist</var> is the blank seperated list of buttons, if <var>type</var> is set to <code>USERDEFINED</code>.
|
|-
|<var>text</var>
|The text to be displayed in the message box.
|
|-
|<var>title</var>
|Caption of the message box.
|name of the {{STX}} application
|-
|<var>maxtime</var> [<var>timestep</var>]
|If this argument is a number, it is used as timeout value in seconds.<BR>If a timeout is set, a progress bar is displayed and the message box is closed automatically after <var>timeout</var> seconds. The <var>timestep</var> is the time for the progress bar update in seconds (if &lt;1) or milli-seconds (if &ge;1). The default <var>timestep</var> is set to 50ms.
|no timeout
|-
|<var>xpos</var>
|Horizontal position in pixels or keyword <code>LEFT, RIGHT, CENTER</code>.<BR>If <var>xpos</var> is a number it specifies, the offset to the left (&ge;0) or the right (&lt;0) side of the desktop.
|depends on parent window
|-
|<var>ypos</var>
|Vertical position in pixels or keyword <code>TOP, BOTTOM, CENTER</code>.<BR>If <var>ypos</var> is a number it specifies, the offset to the top (&ge;0) or the bottom (&lt;0) of the desktop.
|depends on parent window
|-
|<var>monitor</var>
|The index (1, 2, ..) of the monitor to display the message box on.
|monitor the mouse is on
|-
|<var>defaultbutton</var>
|The index (1, 2, ..) of the default button, which will initially be receiving the focus. Buttons are numbered from left to right, starting with index 1.
|1
|-
!RESULT !!description
|-
|<code>CANCEL</code> ||If the message box was closed using the close button or the <code>[Escape]</code>-key.
|-
|<code>TIMEOUT</code> ||If a timeout was set and the maximum timout value was reached before a user input.
|-
|<var>button</var> ||The name of the pressed button.<BR>Note that <code>USERDEFINED</code> buttons using the ampersand &amp; to underline a letter (e.g. &amp;Segment) return the keyword including the ampersand.
|}


=====Result:=====


<code>0</code> for success or non-zero errorcode.
{|class="einrahmen"
!<var>type</var> !!buttons (return values are specified in brackets)
|-
|<code>NONE</code> || no buttons, message box must be closed with the <code>[Escape]</code>-key or by using a timeout
|-
|<code>Msg</code> or <code>Message</code> || <code>OK</code> (okay)
|-
|<code>OkayCancel</code> || <code>OK</code> (okay) or <code>Cancel</code> (cancel)
|-
|<code>OkayRetryCancel</code> || <code>OK</code> (okay), <code>Retry</code> (retry) or <code>Cancel</code> (cancel)
|-
|<code>YesNo</code> || <code>Yes</code> (yes) or <code>No</code> (no)
|-
|<code>YesNoCancel</code> || <code>Yes</code> (yes), <code>No</code> (no) or <code>Cancel</code> (cancel)
|-
|<code>UserDefined</code> || buttons are defined by the argument <var>buttonlist</var>
|}
;See also: [[Programmer_Guide/Macro_Library/UM|UM or EM]], [[Programmer_Guide/Macro_Library/CONLOG|ConLog]]



==SelectTable==
==DELETEFILE==
BUTIL SELECTTABLE <var>tab</var> <var>sel</var>
 
:Select entries of the table item <var>tab</var> according to keyword <var>sel</var> and return the number of selected entries.
Delete the file <var>filename</var>.
{|class="einrahmen"
 
!argument !!description !!default
=====Usage:=====
|-
 
|<var>tab</var>
<code>BUTIL DELETEFILE <var>filename</var></code>
|Name of a table item.
 
|
=====Parameters:=====
|-
 
|<var>sel</var>
;<var>filename</var>
|The selection keyword:<BR>
 
<code>ALL</code> &rarr; select all entries<BR>
:The name of the file to be deleted (no wildcards are allowed).
<code>TOGGLE</code> &rarr; toggle (invert) selection<BR>
 
<code>NONE</code> &rarr; clear selection, deselect all entries
=====Result:=====
|
 
|-
0 for success or non-zero errorcode
!RESULT !!description
 
|-

|<var>nsel</var> ||Number of selected table entries.
==DIRECTORY==
|}
 
;See also: [[Programmer_Guide/Shell_Items/Table|TABLE items]]
Selects a new working working directory (if <var>dir</var> is supplied) and returns the full path of the working directory.
 
=====Usage:=====
 
<code>BUTIL DIRECTORY [ <var>dir</var> ]</code>
 
=====Parameters:=====
 
;<var>dir</var>
 
:The new working directory.
 
=====Result:=====
 
The full path of the current or selected working directory.
 

==DIRECTORYDIALOG==
 
Display a directory selection dialog and return the selected directory path. If <var>subdirs</var> is set to Yes (<code>1</code>) a check-box for sub-directory processing is displayed.
 
=====Usage:=====
 
<code>BUTIL DIRECTORYDIALOG <var>caption</var> [; <var>path</var> ; <var>restore</var> ; <var>subdirs</var> ; <var>subflag</var> ]</code>
 
=====Parameters:=====
 
;<var>caption</var>
 
:The dialog window caption.
 
;<var>path</var>
 
:The default directory or <code>*</code> for the current working directory.
 
;<var>restore</var>
 
:Restore the current working directory (<code>No</code>|<code>Yes</code>). If <code>No</code>, the current working directory is set to the selected directory. The default is <code>No</code>.
 
;<var>subdirs</var>
 
:Show the sub-directory checkbox (<code>No</code>|<code>Yes</code>). The default is <code>No</code>.
 
;<var>subflag</var>
 
:The state to initialize the sub-directory checkbox to (<code>Off</code>|<code>On</code>). The default is <code>Off</code>.
 
=====Result:=====
 
An empty string (if the dialog was cancelled), the selected directory (if <var>subdirs</var>=<code>No</code>) or the selected directory and the subflag ('directory;subflag'), if <var>subdirs</var>=<code>Yes</code>. The value of subflag equals <code>0</code> or <code>1</code>.
 

==FILEDIALOG==
 
A dialog to open (mode = <code>OPEN</code>|<code>LOAD</code>) or create (mode = <code>NEW</code>|<code>SAVE</code>) a file is displayed. All '<code>type=text</code>' assignments are added to the filetype combo-box. The type "<code>*=all files</code>" is always appended to the type list. If the function returns a file path, all checks for opening and/or creating the file are performed, but the file is not opened or created! If a file is opened or loaded (type = <code>OPEN</code> | <code>LOAD</code>) only existing files can be used. It must be possible to open the selected file for read access. If a file is created (type = <code>NEW</code>|<code>SAVE</code>) it is tested to see if it exists already (an overwrite dialog is displayed) and if it is possible to open the file for write access.
 
=====Usage:=====
 
<code>BUTIL FILEDIALOG <var>mode</var> [; <var>caption</var> ; <var>defFile</var> ; <var>type</var>=<var>typetext</var> ; <var>type</var>=...]</code>
 
=====Parameters:=====
 
;<var>mode</var>
 
:The file dialog mode <code>OPEN</code> (=<code>LOAD</code>) or <code>NEW</code> (=<code>SAVE</code>).
 
;<var>caption</var>
 
:The file dialog window caption.
 
;<var>defFile</var>
 
:The default file name. The default file is selected when the dialog is displayed (if it exists). If no default file is specified, the dialog is initialised with the present working directory (<code>PWD</code>).
 
;<var>type</var>
 
:The file extension.
 
;<var>typetext</var>
 
:The description of files with extension type.
 
=====Result:=====
 
The full path of file or empty string for cancel.
 
=====Examples:=====
 
<pre>
butil filedialog open ; Select a settings file ; J:\data\settings.xml ; xml=xml settings file
</pre>

==GETDIRECTORY==
 
Call this macro to verify if a directory exists and to get a valid path (always).
 
=====Usage:=====
 
<code>BUTIL GETDIRECTORY <var>path</var></code>
 
=====Parameters:=====
 
;<var>path</var>
 
:The directory to be checked.
 
=====Result:=====
 
The full path of the directory (if path exists and is a directory) or the S_TOOLS-STx installation directory.
 

==GETKEYINDEX==
 
If value is a valid keyword index (0 .. number of keywords – 1) or a keyword abbreviation, the corresponding keyword index is returned, otherwise the default value is returned.
 
=====Usage:=====
 
<code>BUTIL GETKEYINDEX <var>value</var> ; <var>default</var> ; <var>keywords</var></code>
 
=====Parameters:=====
 
;<var>value</var>
 
:The argument value (an index or a keyword).
 
;<var>default</var>
 
:The default value.
 
;<var>keywords</var>
 
:A blank separated list of keywords.
 
=====Result:=====
 
The index of the keyword (if value is included in the keyword list) or the default value.
 

==GETKEYWORD==
 
If value is a valid keyword index (0 .. number of keywords – 1) or a keyword abbreviation the corresponding keyword is returned, otherwise the default value is returned.
 
=====Usage:=====
 
<code>BUTIL GETKEYWORD <var>value</var> ; <var>default</var> ; <var>keywords</var></code>
 
=====Parameters:=====
 
;<var>value</var>
 
:The argument value (an index or a keyword).
 
;<var>default</var>
 
:The default value.
 
;<var>keywords</var>
 
:A blank separated list of keywords.
 
=====Result:=====
 
The keyword (if the value is included in the keyword list) or the default value.
 

==GETSWITCH==
 
Get a logical switch value. If value is a valid switch-value the value index (<code>0</code>|<code>1</code>) is returned, otherwise the index of the default value is returned. If both values are invalid, the function returns <code>0</code>.
 
=====Usage:=====
 
<code>BUTIL GETSWITCH <var>value</var> ; <var>default</var></code>
 
=====Parameters:=====
 
;<var>value</var>
 
:The switch argument value (<code>0</code>|<code>NO</code>|<code>OFF</code>|<code>FALSE</code> or <code>1</code>|<code>YES</code>|<code>ON</code>|<code>TRUE</code>).
 
;<var>default</var>
 
:The default value, used if value is not a valid switch.
 
=====Result:=====
 
<code>0</code> for false and <code>1</code> for true
 

==LOGMSG==
 
Write a message line into the log-window. The message line consists of the name of the calling macro (script) and the specified text.
 
=====Usage:=====
 
<code>BUTIL LOGMSG <var>text</var></code>
 
=====Parameters:=====
 
;<var>text</var>
 
:The text to write to the log window.
 
=====Result:=====
 
None.
 

==MSGBOX==
 
Display a message box with specified title and text-line. The buttons can be selected from a couple of pre-defined sets, or define by the user.
 
If the timeout mode is used (<var>maxtime</var> > 0), a progress bar for the elapsed time is included in the message box. For the timeout-mode the default timer step is 50ms. The timer step can be specified with the argument <var>maxtime</var> in the format '<var>maxtime</var> , <var>step</var>'.
 
To specify the x/y window position in pixels, a positive or negative number can be used. If x/y is greater/equal zero it is the offset from the left/top side of the desktop, otherwise (<0) it is the offset from the right/bottom side.
 
=====Usage:=====
 
<code>BUTIL MSGBOX [ <var>type</var> [ <var>buttons</var> ]]; <var>text</var> [; <var>caption</var> ; <var>maxtime</var> ; <var>xpos</var> ; <var>ypos</var> ; <var>monitor</var> ]</code>
 
=====Parameters:=====
 
;<var>type</var>
 
:The type of message box to display. The following values are supported:
 
:<code>MSG</code> - An 'OK' button.
 
:<code>YESNO</code> - A 'Yes' and a 'No' button.
 
:<code>YESNOCANCEL</code> - A 'Yes', 'No' and 'Cancel' button.
 
:<code>OKAYCANCEL</code> - An 'OK' and a 'Cancel' button.
 
:<code>OKAYRETRYCANCEL</code> - An 'OK', a 'Retry' and a 'Cancel' button.
 
:<code>USERDEFINED</code> - The argument <var>buttons</var> contains a blank separated list of buttons. See example below.
 
:If <var>type</var> is not specified (the default), then no buttons are displayed. The message box can be closed withe the Escape key.
 
;<var>buttons</var>
 
:A list of user-defined buttons (blank separated).
 
;<var>text</var>
 
:The message text.
 
;<var>caption</var>
 
:The message box caption.
 
;<var>maxtime</var>
 
:The maximum time for which the message box should be displayed; set to <code>0</code> or less (default) to disable timeout handling.
 
;<var>xpos, ypos</var>
 
:The x-position in pixels or keyword <code>LEFT</code>, <code>RIGHT</code> or <code>CENTER</code> and the y-position in pixels or keyword <code>TOP</code>, <code>BOTTOM</code>, <code>CENTER</code>. If the <var>xpos</var> and <var>ypos</var> are not specified, the window is centered.
 
;<var>monitor</var>
 
:The monitor the dialog should appear on (from left to right - 1..x) or blank, if all monitors should be treated as one monitor.
 
=====Result:=====
 
Name of button or one of the keywords <code>CANCEL</code> (if the window was closed) or <code>TIMEOUT</code> (if the maximum timeout value was reached). Note that user-defined buttons using the ampersand '&' to underline a letter (e.g. &Segment) return the keyword including the ampersand.
 
=====Examples:=====
 
<pre>
<code>BUTIL 'MSGBOX USERDEFINED Open Run Cancel ; User-defined Message Box Example'</code>
</pre>

==OPENFILE==
 
Opens a file with the specified application (<var>app</var> is an application name or an exe-file path) or with the default windows application for the type of the specified file (<var>app</var> = <code>*</code>).
 
=====Usage:=====
 
<code>BUTIL OPENFILE <var>app</var> ; <var>file</var></code>
 
=====Parameters:=====
 
;<var>app</var>
 
:The name of the application or <code>*</code> for the default application.
 
;<var>file</var>
 
:The name of the file to be opened.
 
=====Result:=====
 
none (void)
 

==RENAMEFILE==
 
Rename or move the source file to the target. If the target is a directory or a file in an other directory or on an other disk, the source file is moved, otherwise it is renamed.
 
=====Usage:=====
 
<code>BUTIL RENAMEFILE <var>source</var> ; <var>target</var></code>
 
=====Parameters:=====
 
;<var>source</var>
 
:The name of the source file.
 
;<var>target</var>
 
:The name of the target file or directory.
 
=====Result:=====
 
<code>0</code> for success or non-zero errorcode
 

==SELECTTABLE==
 
=====Usage:=====
 
<code>BUTIL SELECTTABLE <var>table</var> <var>selection</var></code>
 
=====Parameters:=====
 
;<var>table</var>
 
:The name of a table item.
 
;<var>selection</var>
 
:A selection keyword: <code>ALL</code>|<code>TOGGLE</code>|<code>NONE</code>
 
=====Result:=====
 
The number of selected entries
 
=====Description:=====
 
Select all entries (<code>ALL</code>), clear selection (<code>NONE</code>) or invert selection (<code>TOGGLE</code>) of a table.
 

==TRACE==
 
Set trace mode or turn trace mode off.
 
=====Usage:=====
 
<code>BUTIL TRACE <var>mode</var> [ <var>logfile</var> ]</code>
 
=====Parameters:=====
 
;<var>mode</var>
 
:The following modes are supported:
 
:<code>OFF</code> - turn trace mode off
<code>ON</code> - standard trace mode (write to log window)
<code>DEBUG</code> - debug mode (show debug window on error)
 
;<var>logfile</var>
 
:The logfile path for standard trace mode; def.: workdir\TRACE.LST
 
=====Result:=====
 
none
 
=====see also:=====
 
COBJ::TRACE, global variables @TRACEON and @TRACEOFF
 

==ONERROR==
 
Write a message line into the log-window. The message line consists of the name of the calling macro (script) and the specified text.
 
=====Usage:=====
 
<code>BUTIL ONERROR <var>text</var></code>
 
=====Parameters:=====
 
;<var>text</var>
 
:The text to log.
 
=====Result:=====
 
none
 

==TREE2TREE==
 
Copies the whole source directory tree to the target directory. Information, progress and errors are written to the script console.
 
=====Usage:=====
 
<code>BUTIL TREE2TREE <var>source</var> ; <var>target</var></code>
 
=====Parameters:=====
 
sourceThe source directory to copy files and directories from.targetThe target directory to copy the source directory to.=====Result:=====
 
Returns the number of failed directories and/or files.
 

==TREE2DATASET==
 
Import all soundfiles from the source directory tree into a linked DataSet. If the dataset file already exists it is overwritten.
 
=====Usage:=====
 
<code>BUTIL TREE2DATASET <var>source</var> ; <var>datasetfilename</var> ; <var>createsets</var></code>
 
=====Parameters:=====
 
sourceThe source directory to import soundfiles from.datasetfilenameThe name of the dataset file to import soundfiles into.createsetsSet to 1 if a set should be created in the DataSet for each subdirectory (0|1).=====Result:=====
 
There are no messages or return values.
 

==EDITBOX==
 
Display an edit box to retrieve basic user input
 
=====Usage:=====
 
<code>BUTIL EDITBOX [ [ <var>caption</var> ] ; [ <var>edit</var> ] ; [ <var>title</var> ] ; [ <var>width</var> ]]</code>
 
=====Parameters:=====
 
;<var>caption</var>
 
:The caption to display above the edit box. If left blank, no caption is used.
 
;<var>edit</var>
 
:The value to initialize the edit box with. If left blank, the edit box is left blank.
 
;<var>title</var>
 
:The title to use for the dialog box. If left blank, the default '<code>Edit Box</code>' is used.
 
;<var>width</var>
 
:The edit box width in characters. The default is <code>17</code>.
 
=====Result:=====
 
The content of the edit box on OK, and an empty string on Cancel.
 
Array

Latest revision as of 08:14, 7 August 2018

File: BUTIL.STX, linked to library STX.LIB

CopyFile, DeleteFile, RenameFile, OpenFile

BUTIL COPYFILE src ; dst
Copy file src to file or directory dst.
BUTIL RENAMEFILE src ; dst
Rename or move file src to file or directory dst.
BUTIL DELETEFILE src
Delete the file src
BUTIL OPENFILE [*] ; src
Open the file src with the default application.
BUTIL OPENFILE app ; src
Open the file src with the specified application app.
argument description default
app The name of the application to open the file. If empty or *, the default application is used. *
src The file to copy, delete, rename (move) or open.
dst The target file or directory for copy or rename (move).
RESULT description
0 success
rc The non-zero error code if the command has failed.
See also
FileToolBox

EditBox

BUTIL EDITBOX [text ; value ; title ; width ]
Display a simple dialog with one input field.
argument description default
text Text to display above the edit field.
value The initial (default) value for the edit field.
title The caption of the dialog window. Edit Box
width The width of the edit field (in character units). 17
RESULT description
value The content of the edit field if the dialog was closed with the OK button or the [Enter]-key.
empty string If the dialog was cancelled.
See also
DoModalDialog, CDlgMap

GetDirectory

BUTIL GETDIRECTORY path
Check if the specified directory path exists. The current directory is not changed.
argument description default
path The directory to be checked.
RESULT description
path The fullpath of the specified directory.
$@root The STx installation directory if the specified directory was not found.
See also
DirectoryDialog, Directory, PWD

GetKeyWord, GetKeyIndex

BUTIL GETKEYWORD val ; defval ; keyword1 keyword2 ...
Return the keyword value if val is a valid index or abbreviation of one of the keywords, otherwise return the default value defval.
BUTIL GETKEYINDEX val ; defval ; keyword1 keyword2 ...
Return the keyword index if val is a valid index or abbreviation of one of the keywords, otherwise return the default value defval.
Both functions are normally used to check/verify arguments passed to macro.
argument description default
val The value to check.
defval The default value to be returned if val is neighter an abbreviation nor an index of a keyword.
keyword1 ... Blank seperated list of keywords (not case sensitive).
RESULT description
keyword/index If val is a an abbreviation or an index of a keyword.
defval otherwise
See also
GetSwitch, KeyWord

GetSwitch

BUTIL GETSWITCH val ; defval
Verify and return boolean value. This function is normally used to check/get argument values.
argument description default
val The value to check.
Valid values are: 0=no=false=off, 1=yes=true=on
defval The default value to be used if val is invalid. The same values as for val can be specified. 0
RESULT description
0 or 1
See also
GetKeyWord and GetKeyIndex

Directory

BUTIL DIRECTORY [ dir ]
Select specified directory dir and/or get full pathname of current directory. This function never returns an error. If no directory is specified or the specified directory dir do not exist, the full path of the current directory is returned.
argument description default
dir The directory to be selected.
RESULT description
pwd The fullpath of the selected/current STx working directory.
See also
PWD, [#Directory|Directory]], DirectoryDialog

DirectoryDialog

BUTIL DIRECTORYDIALOG [ title ; path ; restore ; sdmode ; sdvalue ]
DIRECTORYDIALOG [ title ; path ; restore ; sdmode ; sdvalue ]
Display the STx standard dialog for directory selection. This dialog allows the user to select a directory and to perform some special file/directory operations.
argument description default
title The caption of the dialog window. Select Directory
path The default directory. current directory
restore no or 0 → do not restore current directory

yes or 1 → restore current directory

no
sdmode no or 0 → do not display the subdirectories checkbox

yes or 1 → display the subdirectories checkbox

no
sdvalue Initial state of the subdirectories checkbox: off (=0) or on (=1) off
RESULT description
path If sdmode equals no → The full pathname of the selected directory.
path;sdvalue If sdmode equals yes → The full pathname of the selected directory and the value of the subdirectories checkbox (0 or 1).
empty string If the dialog was canceled.
See also
GetDirectory, Directory, PWD

FileDialog, FileNewDialog, FileOpenDialog

BUTIL FILEDIALOG OPEN|LOAD [ ; title ; path ; ftype1 ; ... ]
FILEOPENDIALOG [ title ; path ; ftype1 ; ... ]
Display the STx standard dialog to open or load a file. Only existing files can be selected. If the function BUTIL FILEDIALOG is called without an argument, the open style is assumed.
BUTIL FILEDIALOG NEW|SAVE [ ; title ; path ; ftype1 ; ... ]
FILENEWDIALOG [ ; title ; path ; ftype1 ; ... ]
Display the STx standard dialog to create a new file or to save (save as) a file. If an existing file is selected, the user is asked if the file should be replaced.
The displayed dialog allows the user to select/enter a filename and to perform some special file/directory operations.
argument description default
title The caption of the dialog window. Select File
path The default file or directory. current directory
ftype1 ... Each ftype argument defines one entry of the filetype-combobox of the dialog.

Each filetype is defined by the string extension=description.
Example: WAV=wave files
If a ftype argument is the name of a (simple) table item, each entry of the table defines a filetype.

RESULT description
path The full pathname of the file to be opened or created.
empty string If the dialog was canceled.

MsgBox

BUTIL MSGBOX type [buttonlist] [ ; text ; title ; maxtime [timestep] ; xpos ; ypos ; monitor ; defaultbutton ]
BUTIL MSGBOXEX 'type [buttonlist]' 'text' [ 'title' 'maxtime [timestep]' 'xpos' 'ypos' 'monitor' 'defaultbutton' ]
MSGBOXEX 'type [buttonlist]' 'text' [ 'title' 'maxtime [timestep]' 'xpos' 'ypos' 'monitor' 'defaultbutton' ]
Display a message box dialog with a set of pre-defined (depending on type) or user-defined (type = USERDEFINED) buttons.
argument description default
type [buttonlist] Defines the type of the message box and the displayed buttons (see table below).
The buttonlist is the blank seperated list of buttons, if type is set to USERDEFINED.
text The text to be displayed in the message box.
title Caption of the message box. name of the STx application
maxtime [timestep] If this argument is a number, it is used as timeout value in seconds.
If a timeout is set, a progress bar is displayed and the message box is closed automatically after timeout seconds. The timestep is the time for the progress bar update in seconds (if <1) or milli-seconds (if ≥1). The default timestep is set to 50ms. 		no timeout
xpos Horizontal position in pixels or keyword LEFT, RIGHT, CENTER.
If xpos is a number it specifies, the offset to the left (≥0) or the right (<0) side of the desktop. 		depends on parent window
ypos Vertical position in pixels or keyword TOP, BOTTOM, CENTER.
If ypos is a number it specifies, the offset to the top (≥0) or the bottom (<0) of the desktop. 		depends on parent window
monitor The index (1, 2, ..) of the monitor to display the message box on. monitor the mouse is on
defaultbutton The index (1, 2, ..) of the default button, which will initially be receiving the focus. Buttons are numbered from left to right, starting with index 1. 1
RESULT description
CANCEL If the message box was closed using the close button or the [Escape]-key.
TIMEOUT If a timeout was set and the maximum timout value was reached before a user input.
button The name of the pressed button.
Note that USERDEFINED buttons using the ampersand & to underline a letter (e.g. &Segment) return the keyword including the ampersand.


type buttons (return values are specified in brackets)
NONE no buttons, message box must be closed with the [Escape]-key or by using a timeout
Msg or Message OK (okay)
OkayCancel OK (okay) or Cancel (cancel)
OkayRetryCancel OK (okay), Retry (retry) or Cancel (cancel)
YesNo Yes (yes) or No (no)
YesNoCancel Yes (yes), No (no) or Cancel (cancel)
UserDefined buttons are defined by the argument buttonlist
See also
UM or EM, ConLog

SelectTable

BUTIL SELECTTABLE tab sel
Select entries of the table item tab according to keyword sel and return the number of selected entries.
argument description default
tab Name of a table item.
sel The selection keyword:

ALL → select all entries
TOGGLE → toggle (invert) selection
NONE → clear selection, deselect all entries

RESULT description
nsel Number of selected table entries.
See also
TABLE items
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BUTIL&oldid=10172"

Navigation menu

Personal tools