|
|
| Line 1: |
Line 1: |
|
| |
| {{DISPLAYTITLE:{{SUBPAGENAME}}}} | | {{DISPLAYTITLE:{{SUBPAGENAME}}}} |
|
| |
| ==BUTIL==
| |
|
| |
| This macro implements a package of general purpose functions.
| |
|
| |
|
| |
| ==COPYFILE==
| |
|
| |
| Copy the source file to the target.
| |
|
| |
| =====Usage:=====
| |
|
| |
| <code>BUTIL COPYFILE source ; target</code>
| |
|
| |
| =====Parameters:=====
| |
|
| |
| ;<var>source</var>
| |
|
| |
| :The file name (and path) of the file being copied.
| |
|
| |
| ;<var>target</var>
| |
|
| |
| :The name of the target file or directory to copy to.
| |
|
| |
| =====Result:=====
| |
|
| |
| <code>0</code> for success or non-zero errorcode.
| |
|
| |
|
| |
| ==DELETEFILE==
| |
|
| |
| Delete the file <var>filename</var>.
| |
|
| |
| =====Usage:=====
| |
|
| |
| <code>BUTIL DELETEFILE <var>filename</var></code>
| |
|
| |
| =====Parameters:=====
| |
|
| |
| ;<var>filename</var>
| |
|
| |
| :The name of the file to be deleted (no wildcards are allowed).
| |
|
| |
| =====Result:=====
| |
|
| |
| 0 for success or non-zero errorcode
| |
|
| |
|
| |
| ==DIRECTORY==
| |
|
| |
| 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 {{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
| | ==<code>BUTIL MSGBOX read: <var>type</var> [<var>buttons</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> ]</code>== |
| | ==<code>BUTIL MSGBOXEX args: '<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>' ]</code>== |
| | {|class="einrahmen" |
| | !arg !description !default |
| | |- |
| | |<var>type</var> [<var>buttonlist</var>] |
| | |defines the type of the message box and the displayed buttons (see table below); the <var>buttonlist</var> is the blank seperated list of buttons for <var>type</var> <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;if a timeout is set, a progress bar is displayed and the message box is closed automatically after <var>timeout</var> seconds |
| | |no timeout |
| | |} |
