Programmer Guide/Macro Library/BUTIL: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
No edit summary
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
*File: BUTIL.STX
*Title: Misc. utility functions
{|class="keinrahmen"
{|class="keinrahmen"
|[[#MsgBox|MsgBox]] ||—  
|[[#MsgBox|MsgBox]] ||—
|[[#EditBox|EditBox]]
|-
|[[#FileDialog|FileDialog]] ||—
|[[#FileDialog|FileDialog]] ||—
|[[#FileCommands|Copy/Move/DeleteFile]] ||—
|[[#DirectoryDialog|DirectoryDialog]] ||—
|[[#DirectoryDialog|DirectoryDialog]] ||—
|[[#GetDirectory|GetDirectory]] ||—
|[[#GetDirectory|GetDirectory]] ||—
|[[#Directory|Directory]]
|-
|[[#GetSwitch|GetSwitch]] ||—
|[[#GetSwitch|GetSwitch]] ||—
|[[#GetKeyWord|GetKeyWord]] ||—
|[[#GetKeyWord|GetKeyWord]] ||—
|[[#GetKeyIndex|GetKeyIndex]] ||—
|[[#GetKeyIndex|GetKeyIndex]]
|[[#Directory|Directory]] ||—
|-
|[[#FileCommands|Copy/Move/DeleteFile]] ||—
|[[#SelectTable|SelectTable]]
|[[#EditBox|EditBox]] ||—
|}
|}
==MsgBox==
==MsgBox==
;<code>BUTIL MSGBOX <var>type</var> [<var>buttonlist</var>] [ ; <var>text</var> ; <var>title</var> ; <var>maxtime</var> [<var>timestep</var> ; <var>xpos</var> ; <var>ypos</var> ; <var>monitor</var> ; <var>defaultbutton</var> ]</code>:
;<code>BUTIL MSGBOX <var>type</var> [<var>buttonlist</var>] [ ; <var>text</var> ; <var>title</var> ; <var>maxtime</var> [<var>timestep</var> ; <var>xpos</var> ; <var>ypos</var> ; <var>monitor</var> ; <var>defaultbutton</var> ]</code>:
Line 79: Line 84:
|}
|}
;See also:
;See also:
 
==EditBox==
 
;<code>BUTIL EDITBOX [<var>text</var> ; <var>edit</var> ; <var>title</var> <var>width</var> ]</code>: Simple input dialog.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>text</var> ||Text to display above the edit field. ||
|-
|<var>edit</var> ||The initial value for the edit field. ||
|-
|<var>title</var> ||Caption of the dialog window. ||<code>Edit Box</code>
|-
|<var>width</var> ||The width of the edigt field (in character units). ||17
|-
!RESULT !!description
|-
|<var>edit</var> ||Contents of the edit field if the dialog was closed with the <code>OK</code> button or the <code>[Enter]</code>-key.
|-
|''empty string'' ||If the dialog was cancelled.
|}
;See also:
==FileDialog==
==FileDialog==
;<code>BUTIL FILEDIALOG <var>type</var> [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]</code>: General file dialog.
;<code>BUTIL FILEDIALOG <var>type</var> [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]</code>: General file dialog.
Line 115: Line 138:
|}
|}
;See also:
;See also:
 
==FileCommands==
 
;<code>BUTIL COPYFILE <var>src</var> ; <var>dst</var></code>: Copy file.
;<code>BUTIL MOVEFILE <var>src</var> ; <var>dst</var></code>: Copy file.
;<code>BUTIL DELETEFILE <var>src</var></code>: Copy file.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>src</var>
|The file to copy, move (rename) or delete.
|
|-
|<var>dst</var>
|The target file or directory for copy or move (rename)
|
|-
!RESULT !!description
|-
|<code>0</code> ||success
|<var>rc</var> ||The non-zero error code if the command has failed.
|}
;See also:
==DirectoryDialog==
==DirectoryDialog==
;<code>BUTIL DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]</code>:
;<code>BUTIL DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]</code>:
Line 153: Line 195:
|''empty string'' ||If the dialog was canceled.
|''empty string'' ||If the dialog was canceled.
|}
|}
See also:
;See also:
 
 
==GetDirectory==
==GetDirectory==
;<code>BUTIL GETDIRECTORY <var>path</var></code>: Check if the directory exists.
;<code>BUTIL GETDIRECTORY <var>path</var></code>: Check if the directory exists.
Line 171: Line 211:
|<code>$@root</code> ||The {{STX}} installation directory if the specified directory was not found.
|<code>$@root</code> ||The {{STX}} installation directory if the specified directory was not found.
|}
|}
See also:
;See also:
 
==Directory==
 
;<code>BUTIL DIRECTORY [ <var>path</var></code> ]: Select directory and/or get full pathname of working directory.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>path</var>
|The directory to be selected.
|
|-
!RESULT !!description
|-
|<var>path</var> ||The fullpath of the selected/current {{STX}} working directory.
|}
;See also:
==GetSwitch==
==GetSwitch==
;<code>BUTIL GETSWITCH <var>val</var> ; <var>defval</var></code>: Verify and return boolean value.
;<code>BUTIL GETSWITCH <var>val</var> ; <var>defval</var></code>: Verify and return boolean value.
Line 192: Line 244:
|
|
|}
|}
See also:
;See also:
 
 
==GetKeyWord==
==GetKeyWord==
;<code>BUTIL GETKEYWORD <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>: Verify keyword and return keyword value.
;<code>BUTIL GETKEYWORD <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>: Verify keyword and return keyword value.
Line 218: Line 268:
|<var>defval</var> ||otherwise
|<var>defval</var> ||otherwise
|}
|}
See also:
;See also:
 
 
==GetKeyIndex==
==GetKeyIndex==
;<code>BUTIL GETKEYINDEX <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>: Verify keyword (or index) and return keyword index.
;<code>BUTIL GETKEYINDEX <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>: Verify keyword (or index) and return keyword index.
Line 244: Line 292:
|<var>defval</var> ||otherwise
|<var>defval</var> ||otherwise
|}
|}
See also:
;See also:
 
 
==Directory==
;<code>BUTIL DIRECTORY [ <var>path</var></code> ]: Select directory and/or get full pathname of working directory.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>path</var>
|The directory to be selected.
|
|-
!RESULT !!description
|-
|<var>path</var> ||The fullpath of the selected/current {{STX}} working directory.
|}
See also:
 
 
==SelectTable==
==SelectTable==
;<code>BUTIL SELECTTABLE <var>table</var> <var>sel</var></code>: Select table entries.
;<code>BUTIL SELECTTABLE <var>table</var> <var>sel</var></code>: Select table entries.
Line 283: Line 313:
|<var>nsel</var> ||Number of selected table entries.
|<var>nsel</var> ||Number of selected table entries.
|}
|}
See also:
;See also:
 
 
==FileCommands==
;<code>BUTIL COPYFILE <var>src</var> ; <var>dst</var></code>: Copy file.
;<code>BUTIL MOVEFILE <var>src</var> ; <var>dst</var></code>: Copy file.
;<code>BUTIL DELETEFILE <var>src</var></code>: Copy file.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>src</var>
|The file to copy, move (rename) or delete.
|
|-
|<var>dst</var>
|The target file or directory for copy or move (rename)
|
|-
!RESULT !!description
|-
|<code>0</code> ||success
|<var>rc</var> ||The non-zero error code if the command has failed.
|}
See also:
 
 
==EditBox==
;<code>BUTIL EDITBOX [<var>text</var> ; <var>edit</var> ; <var>title</var> <var>width</var> ]</code>: Simple input dialog.
{|class="einrahmen"
!argument !!description !!default
|-
|<var>text</var> ||Text to display above the edit field. ||
|-
|<var>edit</var> ||The initial value for the edit field. ||
|-
|<var>title</var> ||Caption of the dialog window. ||<code>Edit Box</code>
|-
|<var>width</var> ||The width of the edigt field (in character units). ||17
|-
!RESULT !!description
|-
|<var>edit</var> ||Contents of the edit field if the dialog was closed with the <code>OK</code> button or the <code>[Enter]</code>-key.
|-
|''empty string'' ||If the dialog was cancelled.
|}

Revision as of 14:04, 11 May 2011

  • File: BUTIL.STX
  • Title: Misc. utility functions
MsgBox — EditBox
FileDialog — Copy/Move/DeleteFile — DirectoryDialog — GetDirectory — Directory
GetSwitch — GetKeyWord — GetKeyIndex
SelectTable

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

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 COPYFILE src ; dst
Copy file.
BUTIL MOVEFILE src ; dst
Copy file.
BUTIL DELETEFILE src
Copy file.
argument description default
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

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

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 directory exists.
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 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.
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.
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.
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
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BUTIL&oldid=4919"

Navigation menu

Personal tools