Programmer Guide/Macro Library/BUTIL: Difference between revisions

From STX Wiki
Jump to navigationJump to search
 
(38 intermediate revisions by 2 users not shown)
Line 35: Line 35:
|<var>rc</var> ||The non-zero error code if the command has failed.
|<var>rc</var> ||The non-zero error code if the command has failed.
|}
|}
;See also: [[Programmer_Guide/Macro_Library/FILETOOLBOX|FileToolBox]]
;See also: [[Programmer_Guide/Macro_Library/Kernal/StdLib#FileToolBox|FileToolBox]]


==EditBox==
==EditBox==
  BUTIL EDITBOX [<var>text</var> ; <var>value</var> ; <var>title</var> <var>width</var> ]
  BUTIL EDITBOX [<var>text</var> ; <var>value</var> ; <var>title</var> ; <var>width</var> ]
:Display a simple dialog with one input field.
:Display a simple dialog with one input field.
{|class="einrahmen"
{|class="einrahmen"
Line 57: Line 57:
|''empty string'' ||If the dialog was cancelled.
|''empty string'' ||If the dialog was cancelled.
|}
|}
;See also: [[Programmer_Guide/Macro_Library/DOMODALDIALOG|DoModalDialog]], [[Programmer_Guide/Macro_Library/CDLGMAP|CDLGMAP]]
;See also: [[Programmer_Guide/Macro_Library/DOMODALDIALOG|DoModalDialog]], [[Programmer_Guide/Macro_Library/CDLGMAP|CDlgMap]]


==GetDirectory==
==GetDirectory==
Line 75: Line 75:
|<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: [[#DirectoryDialog|DirectoryDialog]], [[#Directory|Directory]], [[Programmer_Guide/Command_Reference/PWD|PWD]]


==GetKeyWord, GetKeyIndex==
==GetKeyWord, GetKeyIndex==
 
BUTIL GETKEYWORD <var>val</var> ; <var>defval</var> ; <var>keyword1 keyword2</var> ...
==GetSwitch==
:Return the '''keyword value''' if <var>val</var> is a valid index or abbreviation of one of the keywords, otherwise return the default value <var>defval</var>.
 
BUTIL GETKEYINDEX <var>val</var> ; <var>defval</var> ; <var>keyword1 keyword2</var> ...
==Directory==
:Return the '''keyword index''' if <var>val</var> is a valid index or abbreviation of one of the keywords, otherwise return the default value <var>defval</var>.
 
:Both functions are normally used to check/verify arguments passed to macro.
==DirectoryDialog==
 
==FileDialog, FileNewDialog, FileOpenDialog==
 
==MsgBox, MsgBoxEx==
 
==SelectTable==
 
 
 
 
 
 
 
==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 MSGBOXEX '<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>====
:Display a message box dialog.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!argument !!description !!default
|-
|-
|<var>type</var> [<var>buttonlist</var>]
|<var>val</var>
|Defines the type of the message box and the displayed buttons (see table below).<BR>The <var>buttonlist</var> is the blank seperated list of buttons, if <var>type</var> is set to <code>USERDEFINED</code>.
|The value to check.
|
|
|-
|-
|<var>text</var>
|<var>defval</var>
|The text to be displayed in the message box.
|The default value to be returned if <var>val</var> is neighter an abbreviation nor an index of a keyword.
|
|
|-
|-
|<var>title</var>
|<var>keyword1</var> ...
|Caption of the message box.
|Blank seperated list of keywords (not case sensitive).
|name of the {{STX}} application
|
|-
|<var>maxtime</var> [<var>timestep</var>]
|If this argument is a number, it is used as timeout value in seconds.<BR>If a timeout is set, a progress bar is displayed and the message box is closed automatically after <var>timeout</var> seconds. The <var>timestep</var> is the time for the progress bar update in seconds (if &lt;1) or milli-seconds (if &ge;1). The default <var>timestep</var> is set to 50ms.
|no timeout
|-
|<var>xpos</var>
|Horizontal position in pixels or keyword <code>LEFT, RIGHT, CENTER</code>.<BR>If <var>xpos</var> is a number it specifies, the offset to the left (&ge;0) or the right (&lt;0) side of the desktop.
|depends on parent window
|-
|<var>ypos</var>
|Vertical position in pixels or keyword <code>TOP, BOTTOM, CENTER</code>.<BR>If <var>ypos</var> is a number it specifies, the offset to the top (&ge;0) or the bottom (&lt;0) of the desktop.
|depends on parent window
|-
|<var>monitor</var>
|The index (1, 2, ..) of the monitor to display the message box on.
|monitor the mouse is on
|-
|<var>defaultbutton</var>
|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
!RESULT !!description
|-
|-
|<code>CANCEL</code> ||If the message box was closed using the close button or the <code>[Escape]</code>-key.
|<var>keyword/index</var> ||If <var>val</var> is a an abbreviation or an index of a keyword.
|-
|-
|<code>TIMEOUT</code> ||If a timeout was set and the maximum timout value was reached before a user input.
|<var>defval</var> ||otherwise
|-
|<var>button</var> ||The name of the pressed button.<BR>Note that <code>USERDEFINED</code> buttons using the ampersand &amp; to underline a letter (e.g. &amp;Segment) return the keyword including the ampersand.
|}
|}
;See also: [[#GetSwitch|GetSwitch]], [[Programmer_Guide/Command_Reference/KEYWORD|KeyWord]]


 
==GetSwitch==
BUTIL GETSWITCH <var>val</var> ; <var>defval</var>
:Verify and return boolean value. This function is normally used to check/get argument values.
{|class="einrahmen"
{|class="einrahmen"
!<var>type</var> !!buttons (return values are specified in brackets)
!argument !!description !!default
|-
|-
|<code>NONE</code> || no buttons, message box must be closed with the <code>[Escape]</code>-key or by using a timeout
|<var>val</var>
|The value to check.<BR>Valid values are: <code>0=no=false=off, 1=yes=true=on</code>
|
|-
|-
|<code>Msg</code> or <code>Message</code> || <code>OK</code> (okay)
|<var>defval</var>
|The default value to be used if <var>val</var> is invalid. The same values as for <var>val</var> can be specified.
|0
|-
|-
|<code>OkayCancel</code> || <code>OK</code> (okay), <code>Cancel</code> (cancel)
!RESULT !!description
|-
|-
|<code>OkayRetryCancel</code> || <code>OK</code> (okay), <code>Retry</code> (retry) <code>Cancel</code> (cancel)
|<code>0</code> or <code>1</code>
|-
|
|<code>YesNo</code> || <code>Yes</code> (yes), <code>No</code> (no)
|-
|<code>YesNoCancel</code> || <code>Yes</code> (yes), <code>No</code> (no) <code>Cancel</code> (cancel)
|-
|<code>UserDefined</code> || buttons are defined by the argument <var>buttonlist</var>
|}
|}
;See also:
;See also: [[#GetKeyWord, GetKeyIndex|GetKeyWord and GetKeyIndex]]
==EditBox==


==FileDialog==
==Directory==
====<code>BUTIL FILEDIALOG <var>type</var> [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]</code>====
BUTIL DIRECTORY [ <var>dir</var> ]
:General file dialog.
:Select specified directory <var>dir</var> and/or get full pathname of current directory. This function never returns an error. If no directory is specified or the specified directory <var>dir</var> do not exist, the full path of the current directory is returned.
====<code>FILEOPENDIALOG [ '<var>title</var>' '<var>path</var>' '<var>ftype1</var>' ... ]</code>====
:Dialog to open an existing file
====<code>FILENEWDIALOG [ '<var>title</var>' '<var>path</var>' '<var>ftype1</var>' ... ]</code>====
:Dialog to create a new file.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!argument !!description !!default
|-
|-
|<var>type</var>
|<var>dir</var>
|Selects the action to perform:<BR>
|The directory to be selected.
<code>LOAD</code> or <code>OPEN</code> &rarr; open existing file<BR>
|
<code>SAVE</code> or <code>NEW</code> &rarr; create new file
|<code>OPEN</code>
|-
|<var>title</var>
|The caption of the dialog window.
|<code>Select File</code>
|-
|<var>file</var>
|The default file or directory.
|current directory
|-
|<var>ftype1</var> ...
|Each <var>ftype</var> argument defines one entry of the filetype-combobox of the dialog.<BR>
Each filetype is defined by the string <code><var>extension</var>=<var>description</var></code>.<BR>
Example: <code>WAV=wave files</code><BR>
If a <var>ftype</var> argument is the name of a (simple) table item, each entry of the table defines a filetype.
|-
|-
!RESULT !!description
!RESULT !!description
|-
|-
|<var>path</var> ||The full pathname of the file to be opened or created.
|<var>pwd</var> ||The fullpath of the selected/current {{STX}} working directory.
|-
|''empty string'' ||If the dialog was canceled.
|}
|}
;See also:
;See also: [[Programmer_Guide/Command_Reference/PWD|PWD]], [#Directory|Directory]], [[#DirectoryDialog|DirectoryDialog]]
 


==DirectoryDialog==
==DirectoryDialog==
====<code>BUTIL DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]</code>====
BUTIL DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]
====<code>DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]</code>====
DIRECTORYDIALOG [ <var>title</var> ; <var>path</var> ; <var>restore</var> ; <var>sdmode</var> ; <var>sdvalue</var> ]
:Dialog to select a directory.
: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.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!argument !!description !!default
Line 241: Line 180:
|''empty string'' ||If the dialog was canceled.
|''empty string'' ||If the dialog was canceled.
|}
|}
;See also:
;See also: [[#GetDirectory|GetDirectory]], [[#Directory|Directory]], [[Programmer_Guide/Command_Reference/PWD|PWD]]


==Directory==
==FileDialog, FileNewDialog, FileOpenDialog==
====<code>BUTIL DIRECTORY [ <var>path</var></code> ]====
BUTIL FILEDIALOG OPEN|LOAD [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
:Select specified directory and/or get full pathname of working directory.
FILEOPENDIALOG [ <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
:Display the {{STX}} standard dialog to open or load a file. Only existing files can be selected. If the function <code>BUTIL FILEDIALOG</code> is called without an argument, the '''open''' style is assumed.
BUTIL FILEDIALOG NEW|SAVE [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
FILENEWDIALOG [ ; <var>title</var> ; <var>path</var> ; <var>ftype1</var> ; ... ]
: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.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!argument !!description !!default
|-
|<var>title</var>
|The caption of the dialog window.
|<code>Select File</code>
|-
|-
|<var>path</var>
|<var>path</var>
|The directory to be selected.
|The default file or directory.
|
|current directory
|-
|<var>ftype1</var> ...
|Each <var>ftype</var> argument defines one entry of the filetype-combobox of the dialog.<BR>
Each filetype is defined by the string <code><var>extension</var>=<var>description</var></code>.<BR>
Example: <code>WAV=wave files</code><BR>
If a <var>ftype</var> argument is the name of a (simple) table item, each entry of the table defines a filetype.
|-
|-
!RESULT !!description
!RESULT !!description
|-
|-
|<var>path</var> ||The fullpath of the selected/current {{STX}} working directory.
|<var>path</var> ||The full pathname of the file to be opened or created.
|-
|''empty string'' ||If the dialog was canceled.
|}
|}
;See also:
 
==GetSwitch==
==MsgBox==
====<code>BUTIL GETSWITCH <var>val</var> ; <var>defval</var></code>====
 
:Verify and return boolean value. This function is normally used to check/get argument values.
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> ]
BUTIL MSGBOXEX '<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>' ]
MSGBOXEX '<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>' ]
:Display a message box dialog with a set of pre-defined (depending on <var>type</var>) or user-defined (<var>type</var> = <code>USERDEFINED</code>) buttons.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!argument !!description !!default
|-
|-
|<var>val</var>
|<var>type</var> [<var>buttonlist</var>]
|The value to check.<BR>Valid values are: <code>0=no=false=off, 1=yes=true=on</code>
|Defines the type of the message box and the displayed buttons (see table below).<BR>The <var>buttonlist</var> is the blank seperated list of buttons, if <var>type</var> is set to <code>USERDEFINED</code>.
|
|-
|<var>text</var>
|The text to be displayed in the message box.
|
|
|-
|-
|<var>defval</var>
|<var>title</var>
|The default value to be used if <var>val</var> is invalid. The same values as for <var>val</var> can be specified.
|Caption of the message box.
|0
|name of the {{STX}} application
|-
|-
!RESULT !!description
|<var>maxtime</var> [<var>timestep</var>]
|If this argument is a number, it is used as timeout value in seconds.<BR>If a timeout is set, a progress bar is displayed and the message box is closed automatically after <var>timeout</var> seconds. The <var>timestep</var> is the time for the progress bar update in seconds (if &lt;1) or milli-seconds (if &ge;1). The default <var>timestep</var> is set to 50ms.
|no timeout
|-
|-
|<code>0</code> or <code>1</code>
|<var>xpos</var>  
|
|Horizontal position in pixels or keyword <code>LEFT, RIGHT, CENTER</code>.<BR>If <var>xpos</var> is a number it specifies, the offset to the left (&ge;0) or the right (&lt;0) side of the desktop.
|}
|depends on parent window
;See also:
==GetKeyWord==
====<code>BUTIL GETKEYWORD <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>====
:Verify keyword and return keyword value. This function is normally used to check/get argument values.
{|class="einrahmen"
!argument !!description !!default
|-
|-
|<var>val</var>
|<var>ypos</var>  
|The value to check.
|Vertical position in pixels or keyword <code>TOP, BOTTOM, CENTER</code>.<BR>If <var>ypos</var> is a number it specifies, the offset to the top (&ge;0) or the bottom (&lt;0) of the desktop.
|
|depends on parent window
|-
|-
|<var>defval</var>
|<var>monitor</var>
|The default value to be returned if <var>val</var> is not a keyword.
|The index (1, 2, ..) of the monitor to display the message box on.
|
|monitor the mouse is on
|-
|-
|<var>keyword1</var> ...
|<var>defaultbutton</var>
|Blank seperated list of keywords.
|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
!RESULT !!description
|-
|-
|<var>keyword</var> ||If <var>val</var> is a keyword or an abbreviation of a keyword.
|<code>CANCEL</code> ||If the message box was closed using the close button or the <code>[Escape]</code>-key.
|-
|<code>TIMEOUT</code> ||If a timeout was set and the maximum timout value was reached before a user input.
|-
|-
|<var>defval</var> ||otherwise
|<var>button</var> ||The name of the pressed button.<BR>Note that <code>USERDEFINED</code> buttons using the ampersand &amp; to underline a letter (e.g. &amp;Segment) return the keyword including the ampersand.
|}
|}
;See also:
 
==GetKeyIndex==
 
====<code>BUTIL GETKEYINDEX <var>val</var> ; <var>defval</var> ; <var>keyword1</var> ...</code>====
:Verify keyword (or index) and return keyword index. This function is normally used to check/get argument values.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!<var>type</var> !!buttons (return values are specified in brackets)
|-
|<code>NONE</code> || no buttons, message box must be closed with the <code>[Escape]</code>-key or by using a timeout
|-
|-
|<var>val</var>
|<code>Msg</code> or <code>Message</code> || <code>OK</code> (okay)
|The value to check.
|
|-
|-
|<var>defval</var>
|<code>OkayCancel</code> || <code>OK</code> (okay) or <code>Cancel</code> (cancel)
|The default value to be returned if <var>val</var> is not a keyword.
|
|-
|-
|<var>keyword1</var> ...
|<code>OkayRetryCancel</code> || <code>OK</code> (okay), <code>Retry</code> (retry) or <code>Cancel</code> (cancel)
|Blank seperated list of keywords.
|
|-
|-
!RESULT !!description
|<code>YesNo</code> || <code>Yes</code> (yes) or <code>No</code> (no)
|-
|-
|<var>keyindex</var> ||The zero based index of the matching keyword, if <var>val</var> is a keyword or an abbreviation of a keyword.
|<code>YesNoCancel</code> || <code>Yes</code> (yes), <code>No</code> (no) or <code>Cancel</code> (cancel)
|-
|-
|<var>defval</var> ||otherwise
|<code>UserDefined</code> || buttons are defined by the argument <var>buttonlist</var>
|}
|}
;See also:
;See also: [[Programmer_Guide/Macro_Library/UM|UM or EM]], [[Programmer_Guide/Macro_Library/CONLOG|ConLog]]
 
==SelectTable==
==SelectTable==
====<code>BUTIL SELECTTABLE <var>table</var> <var>sel</var></code>====
BUTIL SELECTTABLE <var>tab</var> <var>sel</var>
:Select table entries.
:Select entries of the table item <var>tab</var> according to keyword <var>sel</var> and return the number of selected entries.
{|class="einrahmen"
{|class="einrahmen"
!argument !!description !!default
!argument !!description !!default
|-
|-
|<var>table</var>
|<var>tab</var>
|Name of a table item.
|Name of a table item.
|
|
|-
|-
|<var>sel</var>
|<var>sel</var>
|The select command:<BR>
|The selection keyword:<BR>
<code>ALL</code> &rarr; select all entries<BR>
<code>ALL</code> &rarr; select all entries<BR>
<code>TOGGLE</code> &rarr; toggle (invert) selection<BR>
<code>TOGGLE</code> &rarr; toggle (invert) selection<BR>
<code>NONE</code> &rarr; clear selection, deseclect all entries
<code>NONE</code> &rarr; clear selection, deselect all entries
|
|
|-
|-
Line 349: Line 305:
|<var>nsel</var> ||Number of selected table entries.
|<var>nsel</var> ||Number of selected table entries.
|}
|}
;See also:
;See also: [[Programmer_Guide/Shell_Items/Table|TABLE items]]

Latest revision as of 09:14, 7 August 2018

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

Navigation menu

Personal tools