dlg -- load and manage Windows dialog boxes

SYNOPSIS

dlg keyword [option...] [result...]

dlg is a built-in function of the MKS KornShell which allows you to load and manage standard Windows dialog boxes. dlg does not have the capability to create dialogs, but rather works with pre-existing dialogs designed either specifically for use with dlg or in other non-related programs.

dlg lets you load a dialog box from any valid module containing a standard resource. module can be any executable containing a resource (for example, a .exe or .dll file), the output from a resource compiler (a .res file), or a .ksh file with resources bound into it. For more information on binding resources to .ksh files, see the bindres reference page.

dlg commands are most effective running from a shell script to emulate Windows programs (see autorun and ugrep for examples). To manage a dialog box

First load the dialog box from an available module.

Enter a loop to read events from the dialog box's controls with the event keyword.

Use various keywords to manage controls, and change, add, or delete information.

Close the loop and close the dialog box.

Controls

dlg commands often operate on dialog box controls, specified with the -c control option (where control is the unique identifier for an individual control). Most standard Windows dialog box control types are supported: ListBox, ComboBox, EditBox, ListView, CheckBox, RadioButton, and Static. If the resource you specify has non-standard control types, dlg fails and returns an error.

Keywords

dlg uses keywords to manage the operation of dialog boxes and their controls. Most of the keywords to dlg are specific to certain control types, though some generic keywords (like load, list, busy, and close) are meant to function with dialog boxes in general.

Keywords and many of their options take arguments as input or store their results in output variables. Input arguments such as control, string, dialogid, index, value, xpos, and ypos are all values which the user supplies to specify various functions or actions. When working with input arguments, you simply enter the necessary value; for example, whenever you encounter the module input argument you are expected to specify the name of a valid 32-bit file containing standard Windows dialogs. Similarly, the xpos argument to load is, by necessity, an integer that specifies the X position of a new dialog.

Output variables, conversely, are the receptacles of information generated by dlg commands. To read the contents of an output variable you must treat it as you would an environment variable. For example, to read the contents of result from the command

dlg gettext -c 102 result

you would enter a command such as

echo $result

The output variables msg, control, value, xpos, ypos, width, height, and result all act similarly: they store the result of a command and, therefore, must be referenced with a preceding $ when you want to use their value.

If -d dlg is not specified for any of these keywords, dlg operates on the most recently used or created dialog.

dlg accepts the following keywords.

addcontrol [-d dlg] -t type [-C controlid] [-s style] [-n name] [-x xpos] [-y ypos] [-w width] [-h height]

dynamically adds a control to a dialog box.

The -t option specifies the type of control to add (such as Button, Edit, ComboBox, ListBox, Static, or SysListView32). The -C controlid option specifies the control ID for the new control. The -s style option specifies the style bits for the control (as described in the appropriate windows header files).

The -x xpos and -y ypos options specify the X/Y position of the control while the -w width and -h height option specify its width and height.

With this keyword, you can simply load a dummy dialog (for example, 102 in sh.exe), use this keyword to add controls, and then use layout to lay them out.

addtext [-d dlg] -c control [-i index] string...

adds string at the end of the list or specified index in a ListBox, ComboBox, or ListView control.

To add text to the end of the current list in a ListBox or ComboBox, specify the control identifier and text to be added. For example, the command

dlg addtext -c 101 thomas.txt richard.exe harrison.res

puts the three new list items at the end of the current list (or, if no list currently exists, they become the list). Note that the three file names are separated by spaces, indicating that they are three individual list items; to include any space separated string as a single list item the string must be enclosed in quotation marks (").

For Listview controls, the first string is added to the first column, the second string is added to the second column, and so on. If you do not specify the appropriate number of text items for the current number of columns, extraneous text items are ignored. For example, if your ListView has only two columns and you specify

dlg addtext -c 102 thomas.txt richard.exe harrison.res

the first two items are added, and harrison.res is ignored. If not enough text items are specified, the first item is placed in the first column (you cannot leave the first column of a ListView control empty), with any extra columns remaining empty. If the end user clicks on a column heading of a Listview control, the list is automatically sorted in ascending order by the text found in that column.

busy [-d dlg] value

makes the current or specified dialog inactive. value can be either 1 for disabled, or 0 for enabled. If you specify dlg busy 1, the dialog box becomes completely disabled and an hourglass icon is displayed until you re-enable the dialog with the dlg busy 0 command. It is recommended that you use the dlg cursor command instead unless you really understand what you are doing; this command completely freezes the thread handling the dialog box. When the dialog is made busy, do not attempt any dlg command on it except to unbusy it.

checkbutton [-d dlg] -c control value

sets a RadioButton or CheckBox control to checked or unchecked. A value of 1 checks the buttons, and a value of 0 unchecks the button.

clear [-d dlg] -c control

deletes all current list items from a ListBox, ComboBox, or ListView control.

close [-d dlg]

closes the current or specified dialog. To close the current dialog, use the dlg close command with no options. If more than one dialog is loaded, you can specify the dialog to be closed with the -d dlg option, where dlg is the handle determined with the dlg load -r handle command.

columns [-d dlg] -c control name width [-n] [name width]...

defines column size and titles in a ListView control. For example, the command

dlg columns -c 102 File 130 "Directory Name" 240

defines two columns: File, and Directory Name. For more than two columns, simply include another title and width definition on the command line. Normally, this appends to any existing columns already present; use the -n option to cause the columns to be cleared prior to adding the new columns.

cursor [-a] [-p variable] (-h variable | cursor-keyword)

changes the mouse cursor shown in the dialog box. Use -a to always show the cursor specified by cursor-keyword even on top of the border or any control; normally child controls provide their own cursors. The old cursor handle is stored in the variable specified with the -p option.

The new cursor is specified with either the -h variable option where variable is a variable containing a cursor handle or a cursor keyword. Cursor keywords are the cursor names builtin to the operating system. Normally, you would use WAIT to get an hourglass while performing a slow operation.

# Set cursor to hourglass
dlg cursor -a -p ocur WAIT
... perform slow operation ... 
# Set cursor back to previous cursor
dlg cursor -h $ocur

debug

displays dialog control and usage information on standard output. This keyword is intended for internal MKS usage only, and is provided with the stipulation that the type of information returned may change at any time without notice.

delete [-d dlg] -i index -c control

removes list items (specified with the -i index option) from ListBox, ComboBox, or ListView controls. index is an integer relative to the current list in the specified control, with 0 signifying the first list item, 1 signifying the next, and so on.

When you use delete to remove an index item, that index number represents the entire row of information in the specified list position. For example, if a ListView control has two columns with information in each column, specifying an index of 0 deletes all information in the first row of both columns.

enabled [-d dlg] -c control value

enables or disables a control. A value of 0 disables the control, and a value of 1 enables it.

event [-d dlg] flush

deletes all events from the current or specified dialog box queue.

event [-d dlg] [-t timeout] [-P] [-W]

checks the queue for pending events if msg and control are not specified. An exit status of 0 is returned if there are pending events, and a status of 1 is returned if there are no pending events.

event [-d dlg] [-t timeout] [-P] [-W] msg control

reads events from the current or specified dialog and store the results in msg (for returned message) and control (for control number). dlg event reads from the dialog box for a specified time (with the -t timeout option, measured in milliseconds), and stores event information in the output variables msg and control. If an event times out, msg returns the value of timeout and the exit code of dlg is 1. If -t timeout is not specified, event defaults to an indefinite wait for an event.

Events read from the queue are stored in one of the shell variables msg or control. The return value stored in control is the unique control number of the control causing the event, for events that cause an action. The return value of msg is one of the following, depending upon the event that occurred:

break--a console interrupt occurred

child-exit--the -W option was specified and a child process exited

close--the dialog box was closed with a system menu selection. Dialogs invoked with the dlg load command must still be closed with the dlg close command; the close return value to msg offers the opportunity to issue a dlg close command or to prompt the user for confirmation. dlg has an exit status of 1 when it receives a close message.

command--a command button was pressed

coprocess--the -P option was specified and data is available from the shell coprocess

double--an item in a listbox or combobox control was double clicked

help--the F1 key was pressed. The focus is on the current control number in control.

edit--an edit control or combobox edit field was edited

maxtext--an edit field reached the maximum number of characters

select--an item in a listbox or combobox control was selected

timeout--the specified timeout duration was reached

The -P option specifies that dlg event should wake-up on a dialog event, or when a shell coprocess has data available. The -W option specifies that dlg event should wake-up on a dialog event, or when a shell child process terminates.

font [-h Height] [-w Width] [-e Escapement] [-o Orientation] [-W Weight] [-IUS] [-c Charset] [-p OutputPrecision] [-C ClipPrecision] [-q Quality] [-P Pitch] [-F Family] [-f Face] fontvariable

creates a font and stores a font value which identifies it in the variable specified by fontvariable. The other options are described in the Windows SDK documentation.

font -d -- font_value

deletes the font with the font value given by font_value. Normally, this value is returned by a dlg font command. The -- is used to separate the option from the font value since font values can be negative and could be misinterpreted as an option.

getcursel [-d dlg] -c control result

gets the current list selection index from a ListBox, ComboBox, or ListView control, storing the return value in result. All list indexes are numbered according to their ordinal position starting with 0; for example, if the third list item is currently selected, result is 2, and so on. If no items are currently selected, getcursel returns a value of -1 to result. For information on how to set the current selection, see the setcursel command.

gethorizontalextent [-d dlg] -c control result

determines the current maximum scroll width of the specified ListBox control, and store the value in result.

getline [-d dlg] -c control -i index result

gets the list item specified by index from a multi-line EditBox control, and store the resulting line in result.

getpos [-d dlg] [-c control] [-x xpos] [-y ypos] [-w width] [-h height]

gets the X/Y position, height, or width of a dialog box or control. getpos reads the specified (with the -d dlg option) or current dialog, and returns the position value of the dialog box or control to an output variable. For example, to determine the X position of the current dialog, use the command

dlg getpos -x xpos

where the output variable xpos would contain the integer value of X. To read xpos, use a command such as

echo $xpos

Similarly, you would use -y ypos to get the Y position, -w width to get the width, and -h for the height. For information on how to set the position of a dialog or control, see the setpos command.

gettext [-d dlg] [-c control] [-i index] result

reads text from a dialog box or a specified control (with the -c control option) and store it in result. If you do not specify a control, gettext returns the title text of the current or specified (with -d dlg) dialog box. For information on changing the text in dialog boxes and controls, see settext, addtext, and inserttext.

gettext works in different ways depending on what type of control you are using it on:

When used on a PushButton, RadioButton, CheckBox, or Static control, gettext returns the heading or label text associated with the control.

When used on an EditBox control, gettext returns all text currently residing in the edit box.

When used on a ListBox or ListView control, you must specify an index number (with the -i index option), where 0 signifies the first item in the list, 1 signifies the second, and so on. You can specify a separate result variable for each each column in the list item. For example, in the command
```
dlg gettext -c 103 -i 3 result1 [result2 ...]
```
In this case, the variable result1 contains the text from the first column of the fourth list item in control 103 of the current dialog, while if the variables result2, result3 and so on are specified, they would contain the text from the second, third, etc. columns of that item.

When used on a ComboBox control, gettext can work two ways: if you do not specify an index to the ComboBox control, gettext reads the current contents of the edit field; otherwise, if you specify an index, gettext reads the specified index.

help

displays a list of all dlg keywords and options on standard output.

inserttext [-d dlg] -c control [-i index] string...

inserts string before the specified index position in any ListBox, ComboBox, or ListView control. If index is not specified, string is inserted in the first position of any list. For Listview controls, the first string is inserted before the specified index in the first column, the second string is inserted in the second column, and so on.

isbuttonchecked [-d dlg] -c control result

determines whether a CheckBox or RadioButton control is checked. result is one of 0 (unchecked), 1 (checked), or 2 (indeterminate).

layout rule...

specifies layout rules. As many rules as are required may be given, each as a separate argument. The format of each rule is:

action-keyword metric-to-act-on relative-to-metric [[-+offset]

where both metric-to-act-on and relative-to-metric have the syntax

metric-name-keyword(number [number])

Delimiters may be commas or spaces. The layout rules specify control positions immediately and when the dialog is resized. When a size event occurs, the new layout has already been computed. Each control is described by six metrics: left, top, right, bottom, width and height. Given some of these, the others can be derived. For example, given left and width, the right is known. The metrics of the parent dialog are always known. layout makes multiple passes over the rules to determine the metrics of each control. Thus, invalid actions may be reported several times.

Possible action-keywords are:

move stretch hcenter vcenter

move is used to set the position of one side of a control relative to some metric of another control. stretch is used stretch a metric of a control based on some other metric of another control. hcenter and vcenter are used to center a group of controls with respect to a single control. Note that this doesn't require a control residing within another control, it may be used for example to vertically position a button beside an edit control. The possible metric-name-keywords are:

left top right bottom width height widthof heightof child group

The first six of these directly refer the the six metrics which are being computed. They all take in parenthesis after them, either a control id number, or the keyword parent to indicate the dialog itself. Thus, for example:

move right(1) right(parent) -8

Fixes the right hand side of control number 1, eight dialog units from the right of the parent dialog box. widthof and heightof are used in the relative-to-metric to specify a percentage of the width or height; for example,

stretch width(1) widthof(parent, 80)

sets the width of control number 1, to 80% of the width of the parent dialog box. child and group are used to specify a control, or a set of controls for action-keywords which set several metrics of a control at once; for example,

hcenter group(1, 5) child(6)

Horizontally centers the group of controls with id numbers from 1 to 5 inclusive; within the control number 6. This example can be used to center a group of radio buttons in an enclosing group box. Illegal actions are possible; for example,

stretch widthof(100, 22) left(101)

It is invalid to act on widthof. To see the dlg layout command in action, see some of the layout commands found in the various .ksh scripts distributed with the MKS Toolkit. The implementation of this command uses code from the book Windows 95, A Developer's Guide by Jeffrey Richter and Jonathan Locke; it is Copyright (c) 1995 Jeffrey Richter.

list [-a] module [dialogid]

displays all dialog identifiers present in the resources of module on standard output. The list module command (without a dialogid) lists each dialog identifier in the specified module, one per line. With the -a option, all resource identifiers are printed.

If you specify a dialogid with the list module command, the specified resource is disassembled and printed to standard output in a format dictated by the resource compiler; for more information on the exact meaning of printed dialog control fields, see the Statement Reference in the Compiling Resources section of Microsoft's Tool's User Guide.

load [-m parent] [-x xpos -y ypos] [-r handle] module dialogid

loads and positions the specified dialog box from module. Dialogs must be loaded before most dlg commands can operate on them.

When you are loading more than one dialog in a single session, you can use use the load -r handle option to store the return value of each loaded dialog.

The -m option creates a modal dialog, where parent is the dialog identifier of the parent dialog. Once a modal dialog is created with the -m option, the parent dialog box does not accept any user input (or dlg commands) until the modal dialog box has been closed.

The -x xpos and -y ypos options can be specified to position the dialog box while loading. If you specify a value of -1 for xpos and ypos, the dialog box is centered either on the screen or on top of the parent dialog.

msg [-d dlg] [-c control] msg wParam lParam result

sends an arbitrary message to any specified control. dlg msg is useful for sending calls to the Windows API that are not currently supported by dlg. Issuing the dlg msg command results in the following Windows API call:

Result: SendMessage(window/control, msg, wParam, lParam)

Warning:: MKS cannot be responsible for the results of using the msg keyword. Since many messages have either lParam or wParam pointing at strings or other structures for input or output, passing random numbers with msg can cause the shell to crash or behave unpredictably.

No error status is returned by msg; the return value from SendMessage is stored in result.

readonly [-d dlg] -c control yes|no

defines an Edit control as read-only (with the yes), or writable (with no).

replacerow [-d dlg] -c control -i index string...

replaces the specified index item in the list of ComboBox, ListBox, or ListView control. For Listview controls, the first string replaces the string in the first column, the next string replaces the string in the second column, and so on.

setcursel [-d dlg] -i index -c control

sets the current selection in a ComboBox, ListBox, or ListView control. index is the position number (starting at 0) of the list item that you want set as the current selection; for example, if you want to set the third list item as the current selection, index would be defined as 2. An index of -1 ensures that no items are currently selected.

sethorizontalextent [-d dlg] -c control value

sets the width of the horizontal scroll for a specific ListBox control to value.

setfocus [-d dlg] -c control

sets the current focus to be on the specified control.

setfont [-d dlg] -c control -- font_value

sets the font in the specified control to the one indicated by font_value. Normally, this value is returned by a dlg font command. The -- is used to separate the options from the font value since font values can be negative and could be misinterpreted as an option.

setpos [-d dlg] [-c control] [-x xpos -y ypos] [-w width -h height]

sets the X/Y position or height and width of a dialog box or specified control. A value of -1 for either xpos or ypos centers the dialog control in the specified direction. If -d dlg and -c control are not specified, setpos operates on the most recently loaded dialog.

settext [-d dlg] -c control string

overwrites existing text. If no control is specified, settext replaces the dialog box title.

On PushButton, RadioButton, CheckBox, or Static controls, settext overwrites the associated label or title.

On an EditBox control, settext overwrites the entire contents of the EditBox with string.

On a ComboBox control, settext only replaces the current edit field. settext is not valid with the list text in a ComboBox control, or in ListBox or ListView controls.

winhelp [-d dlg] [-q] [-C context-id] help_file

loads a Windows Help file. If you specify a context-id to the help_file, the help file is opened to that page location. The winhelp keyword allows you to run the help file independently of the dialog box from which it is invoked.

EXAMPLES

The following example shows how to create a dialog box using a resource that is already bound into the shell, thus, eliminating the need to bind any resources to script.

ResFile=$(whence "sh.exe")
#dlg load "$ResFile" 101        # Resizable dialog box.
dlg load "$ResFile" 102         # Fixed size dialog box.
while :; do
	dlg event msg control
	case $msg in
        close)  break;;
        esac
done
dlg close

The following code is an example of how to load a dialog box, read events, and cancel a slow running process. This sample uses the $(whence "$0") construct as an example of how to reference a resource that is bound into the KornShell script. For more information on binding resource files, see bindres.

# Start the slow command going; sleep is simply an example
sleep 10&

set -o guierror
if ! dlg load -x -1 -y -1 $(whence "$0") CANCEL
then
	exit	# dlg has given an error in a msgbox!
fi

while dlg event -W msg control
do
	case "$msg" in
	child-exit)
		break
		;;
	command)
		# Only one control it can be: the cancel button!
		kill %1
		wait %1
		break
		;;
	esac
done
dlg close
#[]mks internal resource : dialog : CANCEL
#[ ]begin : size 220
#[  ]MP   D      "      "Z $(         " !- %, ( !3 &$ ;@!S "  4P!E
#[  ]M '( :0!F          %0     $, )P R  X  @#__X  0P!A &X 8P!E &P
#[  ]M         0 "4      0 !  F0 + /____^" %, ; !O '< ( !/ '  90!R
#[  ]M &$ = !I & ;@ @ &D ;@ @ '  <@!O &< <@!E ', <P Z "  ( !# &$
#[  ]H;@!C &4 ;  @ '0 ;P @ '0 90!R &T :0!N &$ = !E "X
#[ ]end

The next example demonstrates how to intercept a system close message, and display a message prompting users for confirmation. Note that while the dlg load command refers to a bound resource file, the resource code has been omitted here for the sake of brevity.

IDOK=1
IDCANCEL=2
EDIT=1000

set -o guierror
if ! dlg load -x -1 -y -1 $(whence "$0") CLOSE
then
	exit	# dlg has given an error in a msgbox!
fi

# Note the loop does not terminate on failure status from dlg
while :
do
	dlg event msg control
	case "$msg $control" in
	"command $IDCANCEL")
		break
		;;
	"command $IDOK")
		dlg gettext -c $EDIT s
		# Save the contents of the edit box...
		break
		;;
	"close ")
		msgbox -b yesno -d 1 -f -i question -q "Close"
		    "Information has changed.  Do you really want to close?"
		if [ $? -eq 7 ]		# 7 is no
		then
			continue
		fi
		break	# Discarding contents
		;;
	esac
done
dlg close

DIAGNOSTICS

Possible exit status values are:

0: Successful completion.
>0: An error occurred.

PORTABILITY

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
PTC Windchill Requirements and Validation

dlg
load and manage Windows dialog boxes

KornShell Built-in