BUTIL - Misc. Utility Functions

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.

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, deseclect all entries
RESULT	description
nsel	Number of selected table entries.

See also

TABLE items