BUTIL - Misc. Utility Functions

From STX Wiki
Jump to navigation Jump to search

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