Programmer Guide/Macro Library/BUTIL

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