BUTIL - Misc. Utility Functions
From STX Wiki
Jump to navigationJump to search
File: BUTIL.STX, linked to library STX.LIB
Contents
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. |
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.
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 |
GetSwitch
Directory
DirectoryDialog
FileDialog, FileNewDialog, FileOpenDialog
MsgBox, MsgBoxEx
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:
|
|
RESULT | description | |
nsel | Number of selected table entries. |
- See also
- TABLE items
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' ]
- 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
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:
|
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 | |
RESULT | description | |
path | The full pathname of the file to be opened or created. | |
empty string | If the dialog was canceled. |
- See also
DirectoryDialog
BUTIL DIRECTORYDIALOG [ title ; path ; restore ; sdmode ; sdvalue ]
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
|
no
|
sdmode | no or 0 → do not 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
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