Programmer Guide/Macro Library/BUTIL

• File: BUTIL.STX, linked to library STX.LIB
• Title: misc. utility functions

---

Content

MsgBox · EditBox · FileDialog · Open/Copy/Move/DeleteFile · DirectoryDialog · GetDirectory · Directory · GetSwitch · GetKeyWord · GetKeyIndex · SelectTable

MsgBox

BUTIL MSGBOXEX 'type [buttonlist]' 'text' [ 'title' 'maxtime [timestep]' 'xpos' 'ypos' 'monitor' 'defaultbutton' ]

Display a message box dialog.

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), Cancel (cancel)
OkayRetryCancel	OK (okay), Retry (retry) Cancel (cancel)
YesNo	Yes (yes), No (no)
YesNoCancel	Yes (yes), No (no) Cancel (cancel)
UserDefined	buttons are defined by the argument buttonlist

See also

EditBox

BUTIL EDITBOX [text ; edit ; title width ]

Simple input dialog.

argument	description	default
text	Text to display above the edit field.
edit	The initial value for the edit field.
title	Caption of the dialog window.	Edit Box
width	The width of the edigt field (in character units).	17
RESULT	description
edit	Contents 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

FileDialog

BUTIL FILEDIALOG type [ ; title ; path ; ftype1 ; ... ]

General file dialog.

FILEOPENDIALOG [ 'title' 'path' 'ftype1' ... ]

Dialog to open an existing file

FILENEWDIALOG [ 'title' 'path' 'ftype1' ... ]

Dialog to create a new file.

argument	description	default
type	Selects the action to perform: LOAD or OPEN → open existing file SAVE or NEW → create new file	OPEN
title	The caption of the dialog window.	Select File
file	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.

See also

FileCommands

BUTIL OPENFILE app ; src

Open file.

BUTIL COPYFILE src ; dst

Copy file.

BUTIL MOVEFILE src ; dst

Move or rename file.

BUTIL DELETEFILE src

Delete file.

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, move (rename) or delete.
dst	The target file or directory for copy or move (rename)
RESULT	description
0	success
rc	The non-zero error code if the command has failed.

See also

DirectoryDialog

DIRECTORYDIALOG [ title ; path ; restore ; sdmode ; sdvalue ]

Dialog to select a directory.

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

BUTIL GETDIRECTORY path

Check if the specified directory 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

Directory

BUTIL DIRECTORY [ path ]

Select specified directory and/or get full pathname of working directory.

argument	description	default
path	The directory to be selected.
RESULT	description
path	The fullpath of the selected/current STx working directory.

See also

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

BUTIL GETKEYWORD val ; defval ; keyword1 ...

Verify keyword and return keyword value. This function is normally used to check/get argument values.

argument	description	default
val	The value to check.
defval	The default value to be returned if val is not a keyword.
keyword1 ...	Blank seperated list of keywords.
RESULT	description
keyword	If val is a keyword or an abbreviation of a keyword.
defval	otherwise

See also

GetKeyIndex

BUTIL GETKEYINDEX val ; defval ; keyword1 ...

Verify keyword (or index) and return keyword index. This function is normally used to check/get argument values.

argument	description	default
val	The value to check.
defval	The default value to be returned if val is not a keyword.
keyword1 ...	Blank seperated list of keywords.
RESULT	description
keyindex	The zero based index of the matching keyword, if val is a keyword or an abbreviation of a keyword.
defval	otherwise

See also

SelectTable

BUTIL SELECTTABLE table sel

Select table entries.

argument	description	default
table	Name of a table item.
sel	The select command: ALL → select all entries TOGGLE → toggle (invert) selection NONE → clear selection, deseclect all entries
RESULT	description
nsel	Number of selected table entries.

See also