Database Search

If you can't find the information using the categories below, post a question over in our WinBatch Tech Support Forum.

TechHome

Dialog Editor version 6.X

	COMCONTROL
	Samples

Can't find the information you are looking for here? Then leave a message over on our WinBatch Tech Support Forum.

WIL Dialog Editor v6.1 and UDS Callbacks for Creating Dynamic Dialogs in Winbatch 2002F and later versions

Keywords: 	  WIL Dialog Editor v6.1 DefineSubroutine UDS Callback Dynamic Dialogs

NOTE: This is advanced Dialog programming for dynamic dialogs. You can use and create regular static Dialogs without this knowledge.

How to create dynamic dialogs with the WIL Dialog Editor:

With the release of version 6.1 of the WIL Dialog Editor, users can now create dynamic dialogs that update when a user clicks on an control, such as an itembox or pushbutton. This is a very nice feature because in the old days of Winbatch, one would have to save the value of a user's selection, and then redraw and redisplay a dialog with the new information. Now with the 2000F (or newer) versions of Winbatch, you can dynamically update this information on the dialog without the awkwardness of re-generating and re-displaying the dialog. Your script displays the dialog, the user picks one or more values from controls in the dialog, and right then and there, your dialog can modify the selected information in the original dialog box.

As a beginning dialog designer, you might ask, how do I make this work? Where do I start?

What follows is a brief outline of steps to take in order to generate and customize a dynamic dialog:

First, create the dialog using the WIL Dialog Editor. You can launch the WIL Dialog editor either from Winbatch Studio (by clicking on the icon with the hammer and red number 1), or via Explorer, by running the 'WIL Dialog Editor.exe', in your \WinBatch\System subdirectory.
Details on how to use the WIL Dialog Editor GUI (graphical user interface) is documented in the Winbatch.hlp file (search for Dialog in the index of Winbatch.HLP).
For the purposes of the discussion below, create a dialog with an itembox control, a static text control, and a couple of pushbuttons.
After you create your dialog with the Dialog Editor, you can copy the generated code to the clipboard by going to the File|SaveAs menu, and save as a file to later edit, or you can copy the code directly to the clipboard from the File|Save to Clipboard menu option.

Now, either paste the code into an open document in Winbatch Studio, or open the file you previously saved via the Dialog Editor. The code we will be discussing follows:

;=============================snip==================================================
#DEFINESUBROUTINE GetFruit(Handle,DialogMessage,DialogControlID,param4,param5)
switch  (DialogMessage)
   case 0
      DialogProcOptions(Handle, 7, 1)           ; Pass item listbox selection changes.
      break;
   case 7
      sSelection = DialogControlGet(Handle,2,6) ; Get selection for itembox control #2
      DialogControlSet(Handle,4,4,sSelection)   ; Set text for static text control #4
      break;
endswitch
return -1
#ENDSUBROUTINE

ItemList = "Apples|Cherries|Raspberries|Blueberries|Gooseberries|Quince|Plums|Apricots|Blackberries" ;create a delimited list
ItemList = StrReplace(ItemList,"|","%@tab%")    ;now convert it to a tab-delimited list

MyDialogFormat=`WWWDLGED,6.1`

MyDialogCaption=`Fruit Picker Example`
MyDialogX=049
MyDialogY=096
MyDialogWidth=212
MyDialogHeight=116
MyDialogNumControls=004
MyDialogProcedure=`GetFruit`                ;<=name of your callback procedure
MyDialogFont=`DEFAULT`
MyDialogTextColor=`DEFAULT`
MyDialogBackground=`DEFAULT,127|127|63` 

MyDialog001=`065,095,131,011,PUSHBUTTON,DEFAULT,"OK Already",1,1,DEFAULT,"Lucida Console|6963|70|49","0|0|0","127|127|0"`
MyDialog002=`014,009,057,075,ITEMBOX,ItemList,DEFAULT,DEFAULT,2,DEFAULT,"Lucida Console|6144|70|49","0|0|0","127|63|0"`
MyDialog003=`087,010,110,014,STATICTEXT,DEFAULT,"Your Selection:",DEFAULT,3,DEFAULT,"Lucida Console|8192|70|49","0|0|0",DEFAULT`
MyDialog004=`090,038,107,010,STATICTEXT,DEFAULT,"",DEFAULT,4,DEFAULT,"Lucida Console|8192|70|49","0|0|0",DEFAULT`

ButtonPushed=Dialog("MyDialog")
exit
;=============================snip==================================================

And the dialog looks like:

Take a moment to see what your generated code looks like. These formatting codes are described in great detail in the Windows Interface Language.HLP file under the 'Dialog' function. We're also including a subset of the documentation below for the purposes of this discussion.
Now that you are looking at your code and beginning to understand it, the next logical thing you might want to do is to edit the 'xxxProcedure=' line generated by the dialog editor. This line needs to contain the name of the #DEFINESUBROUTINE UserDefinedCallback (or #DEFINEFUNCTION UserDefinedCallback) procedure, the code of which you will be creating to handle the dynamic dialogs.
```
MyDialogProcedure=`GetFruit`                ;<=name of your callback procedure
```
To read about User Defined Subroutines, search for #DEFINESUBROUTINE in the Windows Interface Language.HLP file. The #DefineSubroutine UDF is similar, in most respects, to the #DefineFunction UDF, except that the variables are global. This means the it will be able to access and change variables in the main WIL script, and any variables it sets will not be destroyed when it returns.
You can find additional examples of how to set up this callback procedure by perusing the sample code in the Windows Interface Language.HLP file under the functions: DialogProcOptions, DialogControlSet and DialogControlGet.
For now, maybe call this Callback procedure 'GetFruit' as our example.
The #DEFINESUBROUTINE that you will be creating must be placed in your code before the Dialog code.
NOTE that when we are defining a subroutine to be used with a callback procedure used in a dialog, your user defined function/subroutine must have five parameters. Thus, in our example of the 'GetFruit' callback procedure, we are really using only the first three parameters (Handle, DialogMessage, and DialogControlID), but we must also specify empty placeholders (param4 and param5).
In general, in writing the code for your User Defined Callback routine, you will be setting up a switch statement to handle the default initialization case, case 0, and another case statement to handle the specific type of control from which the selection for the dynamic update is made.
In your switch statement, the switch variable will be the second parameter of the UserDefinedCallback procedure. So, in our example where we are defining our User Defined Callback procedure called 'GetFruit', the second parameter called 'DialogMessage' will be the variable used by the switch statement, i.e.,
```
#DEFINESUBROUTINE GetFruit(Handle,DialogMessage,DialogControlID,param4,param5)
   switch DialogMessage
```
After the switch statement, you will set up the Case statements.
Case 0 is the initialization code and varies depending on what type of control you are initializing and dynamically changing, be it an itembox, pushbutton, etc. Note that Event 0 only happens once.
In case 0, you will use the DialogProcOptions function to initialize the control and pass the item listbox selection changes. See the DialogProcOptions function in the Windows Interface Language.HLP file for details on what the parameters mean. The first parameter of the DialogProcOptions function will be the name of dialog-handle passed as the first parameter to your dialog procedure. The second parameter will be a 7 in our example, because we are working with an itembox control. We will set the third parameter to 1 so the event will cause a call to our dialog procedure when it next occurs.
```
switch  (DialogMessage)
   case 0
      DialogProcOptions(Handle, 7, 1)           ; Pass item listbox selection changes.
      break;
```
Note that you will always need to set up a case 0, to initialize the control. If you are working with an itembox control as in our example, you need to specify a case 0 and a case 7. Case 7 is for itembox/listbox-type controls (please see the Windows Interface Language help file and the documentation below, which further elaborates on what request codes correspond to types of controls).
Within case 7, you'll need to do a DialogControlGet, to get the handle of the listbox control. In our example, for DialogControlGet, the itembox control is control #2 and the third parameter is a request code #6 for itembox controls (see the Windows Interface Language.HLP file function 'DialogControlGet').
```
      sSelection = DialogControlGet(Handle,2,6) ; Get selection for itembox control #2
```
Then to set and update the itembox with the new selection value, use DialogControlSet. In our example, the control number to modify is 4, which is a "static text control," which will be dynamically updated after the selection is made.
```
     DialogControlSet(Handle,4,4,sSelection)   ; Set text for static text control #4
 
```
Copy the code above into Winbatch Studio, save the file with a *.WBT file extension, and run it, to see how a simple dynamic dialog works.

This article is a work-in-progress. Please let us know how we can improve it.

Below is the documentation from the Windows Interface Language.HLP file for the 'Dialog' function. Please see the help file for more details on how to use this function.

Dialog

Displays a user-defined dialog box.

Syntax:

Dialog (dialog-name)

Parameters:

(s) dialog-name name of the dialog box.

Returns:

(i) value of the pushbutton used to close the dialog box.

Note: The Dialog Editor has been included to help create your dialogs. The following information is for technical reference only.

The text which follows describes how to define a dialog box for use by the Dialog function. Please refer to your product-specific documentation (i.e., the user guide) for any additional information which may supplement or supersede that which is described here.

Before the Dialog function is called, you must include a section of code in your WIL program which will define the characteristics of the dialog box to be displayed. First of all, the dialog must be declared, and a name must be assigned to it. This is done with a line of the following format:

Format="WWWDLGED,6.1"

where is the dialog name. "WWWDLGED,6.1" is the hard coded format which identifies this dialog box as using the WIL Dialog Type 6.1. This should follow the standard rules for WIL variable names, and may not exceed 19 characters in length.

Next, the format of the dialog box is defined, as follows:

<dlg-variable>Caption = "<box-caption>"
<dlg-variable>X = <x-origin>
<dlg-variable>Y = <y-origin>
<dlg-variable>Width = <box-width>
<dlg-variable>Height = <box-height>
<dlg-variable>NumControls = <ctrl-count>
<dlg-variable>Procedure = <procedure-name>
<dlg-variable>Font = <font>
<dlg-variable>TextColor = <textcolor>
<dlg-variable>Background = <bmp filename>

where:

<dlg-variable> is the internal name of the dialog box, as described above.
<box-caption> is the text which will appear in the title bar of the dialog box.
<x-origin> is the horizontal coordinate of the upper left corner of dialog box.
<y-origin> is the vertical coordinate of the upper left corner of the dialog box.
<box-width> is the width of the dialog box.
<box-height> is the height of the dialog box.
<ctrl-count> is the total number of controls in the dialog box (see below).

<procedure-name> a user defined subroutine or function name.
Use the same name you use as part of a #DEFINEFUNCTION or #DEFINESUBROUTINE statement.
Your user defined function/subroutine must have five parameters. You do not have to include
the parameters, commas or parentheses when you make the name assignment to this dialog definition
variable. However, the complete function/subroutine definition must appear in your script before
the WIL Dialog command that launches your dialog. The function/subroutine is called one or more
times while the dialog is displayed. This procedure is used to respond to user interactions with
the dialog without having to redisplay the dialog. The first call to the function/subroutine is
made just before the dialog is displayed. Use this initial call to specify events you wish to monitor.
You can find more information on the User Defined Dialog procedure in later sections of this document.

<font> is the default text font for all controls that accept a font. A control will use this font, if its font
attribute is not specified or set to DEFAULT. This font is not used on the dialog�s title text, however.
Dialog�s always use the system font in their titles. The font is specified as a string of vertical bar (|)
delimited fields. The four fields are:

name|size|style|{pitch,family and character set}

Name
If a blank string is specified for "name", the system will select the best available font based upon the
other parameters supplied. Some example font name would be: "Times Roman", "Helvetica", "Courier New",
"Brush Script MT", "Book Antiqua"

Size
Size of font, in virtual units.

Style
The following numbers may be added together:

0 Default.
1-99 Weight (40 = Normal, 70 = Bold)
100 Italics
1000 Underlined

A style of 1170 give you a bold, underlined, italic font.

Pitch and Family
Pitch and Family do not override the typeface supplied in the font name. If a match cannot be made,
(font name is mis-spelled, font not on system) they supply a general description for selecting a default font.
Combine (add) one pitch flag, one family flag, and one character set flag.

Pitch:
0 Default
1 Fixed pitch
2 Variable pitch

Family:
0 Default
16 Roman (Times Roman, Century Schoolbook, etc.)
32 Swiss (Helvetica, Swiss, etc.)
48 Modern (Pica, Elite, Courier, etc.)
64 Script
80 Decorative (Old English, etc.)

Character Set:

ANSI_CHARSET 0 (default)
DEFAULT_CHARSET 256
SYMBOL_CHARSET 512
SHIFTJIS_CHARSET 32768 (Kanji)
HANGEUL_CHARSET 33024
GB2312_CHARSET 34304
CHINESEBIG5_CHARSET 34816
OEM_CHARSET 65280
JOHAB_CHARSET 33280
HEBREW_CHARSET 45312
ARABIC_CHARSET 45568
GREEK_CHARSET 41216
TURKISH_CHARSET 41472
THAI_CHARSET 56832
EASTEUROPE_CHARSET 60928
RUSSIAN_CHARSET 52224
MAC_CHARSET 19712
BALTIC_CHARSET 47616

The character set flags will not override the typeface specified by the font "name".
If you would rather specify a character set than a specific typeface, specify a blank string ("")
for font "name". If you wish to use a Kanji (Japanese) font, you must specify the SHIFTJIS_CHARSET flag (32768).

WARNING: If a font is selected that doesn't exist on the users system, a substitution will be made.
We recommend using commonly available fonts.

<textcolor> This is the default text color for all controls that accept text color. A control will use this
color when its text color attribute is not specified or is set to DEFAULT. The text color is not used
by the dialog�s title. It is specified by three vertical bar (|) delimited numbers ranging from 0 to 255.
The numbers represent one of the RGB colors: red, green or blue in that order. The default is color black.
Here are some other sample colors:

BLACK="0,0,0"
WHITE="255,255,255"RED="255,0,0"
GREEN="0,255,0"
DKGRAY="128,128,128"
GRAY="192,192,192"
DKRED="128,0,0"
DKGREEN="0,128,0"
BLUE="0,0,255"
PURPLE="255,0,255"
YELLOW="255,255,0"
CYAN="0,255,255"
DKBLUE="0,0,128"
DKPURPLE="128,0,128"
DKYELLOW="128,128,0"
DKCYAN="0,128,128"

<background> This is the dialog�s background bitmap. Specify the bitmap by file name and path enclosed
in single quotes. If this value is set to DEFAULT, the system dialog background color will be used.
Note: This variable can contain a three field color, a bitmap file path, or both. To specify both,
separate the bitmap and color attributes with a comma and make sure the bitmap�s file name and path
is enclosed in quotes. When both are specified WinBatch will always attempt to load the bitmap first.
If this fails, the color will be used as the dialog background. See the discussion under the heading
<textcolor> for more information about color specification.

Finally, you will need to define the objects, or controls, which will appear inside the dialog box.

Each control is defined with a line of the following format:

The following should all be on a single line:

<dlg-variable>nn=`x,y,width,height,type,var,"text/pre-selected item",value,tab-order,style,font,textcolor,backgroundcolor`

where:

dlg-variable is the name of the dialog box, as described above.
nn is the ordinal position of the control in the dialog box (starting with 1).
x is the horizontal coordinate of the upper left corner of the control.
y is the vertical coordinate of the upper left corner of the control.
width is the width of the control.
height is the height of the control. [This should be DEFAULT for all controls except file-list boxes and item boxes.]
type is the type of control, (see below).

var is the name of the variable affected by the control.

text/pre-selected item
text, if supported by the control, is the description which will be displayed with the control.
Use a null string ("") if the control should appear blank.]

pre-selected item, if supported by the control, is used to indicate which item in a list or
range is the default item for the control. Use this attribute with ITEMLIST and FILELIST controls
to have the control initially display selection coloring behind the pre-selected item. In order
for the Pre-selected Item to work properly it must one of the items listed in the controls variable.

Use this attribute with the new DROPLISTBOX control to have a pre-selected value appear in the text
box portion of the control. The pre-selected value does not have to be among the values listed in
the controls variable.

The SPINNER control accepts a pre-select item as its initial value. It will be the displayed value
in the text box when the dialog is displayed. Like with other controls it will be the value in the
Spinner�s variable, if the user does not make changes. In order for the Pre-selected Item to work
properly, it must fall within the range of values specified in the control�s variable

value is the value returned by the control. [Use only for pushbuttons, radiobuttons, and checkboxes.]
Note: should be within the range of 0 - 127.

tab-order allows you to specify a control's tab order independently of a control's position or name in the
dialog template. Tab order controls the order in which controls are accessed when the keyboard is used
to navigate the dialog. It also influences which control is on top when control have overlapping
positions in the dialog. It can be any positive integer, but each control should have a unique number.
When you navigate through a dialog using the tab key, lower number controls will be given the keyboard
focus before higher controls. Like wise, low numbered overlapping controls will appear on top of higher
numbers control. If you specify the DEFAULT key word for this attribute or if you give two controls
the same tab order, a tab order will be arbitrarily assigned to the control.

Note: The dialog function, under certain circumstances, may change the tab order you specify.
GROUPBOX controls tab order may be adjusted so that it is smaller than any of the controls it contains.
In addition, the tab order of the controls inside the GROUPBOX may be adjusted so that they are consecutive.

style allows you to control the initial appearance and behavior of your control. Numbers represent each
style and they can be combined, using the bit-wise OR (|) operator, to set multiple styles. Note: See the
Dialog function for a detailed table of the style numbers, their meaning and the controls that they have an effect on.

Note: Specifying 0 for this attribute is equivalent to using the DEFAULT key word and means that the control will
exhibit default behavior.

font is the font used to display a control's text. The font description should be delimited by double quote (")
marks unless the attribute is set to DEFAULT. If this attribute is set to DEFAULT, the font specified as the value
of the main dialog font will be used. If the main dialog font is set to DEFAULT the system font is used. You do
not need to provide any value for this attribute unless you are also specifying text or background color.

WARNING: If a font is selected that doesn't exist on the users system, a substitution will be made.
We recommend using commonly available fonts.

textcolor is the color of text associated with a control. Color is specified by three vertical bar (|) delimited
numbers ranging from 0 to 255. The numbers represent one of the RGB colors: red, green or blue, in that order.
The complete color specification must be surrounded by double quotes (�) unless the DEFAULT key word is used.
If this attribute is set to DEFAULT, the color listed in the main dialog's textcolor will be used. If a color
is not specified for the dialog, the system text color will be used.

backgroundcolor used to change the color displayed behind a control�s text or to specify the background bitmap for
controls that display them. Color is specified by three vertical bar (|) delimited numbers ranging from 0 to 255.
The numbers represent one of the RGB colors (red, green or blue, in that order). The complete color specification
must be surrounded by double quotes (�) unless the DEFAULT key word is used. If no color is specified or the
DEFAULT key word is used the system background color will be used. Specify a bitmap by file name and path enclosed
in single quotes. You can only place a bitmap in this attribute if the control supports bitmap display. If a
control displays a bitmap you cannot place a color specification in the attribute.

Note: The numbers used for "x-origin", "y-origin", "box-width", "box-height", "x", "y", "width," and "height" are expressed in a unit of measure known as "Dialog Units." Basically speaking:

1 width unit		=   1/4 width of system font.
1 height unit 		=   1/8 height of system font.
4 units wide 		=   Average width of the system font.
8 units high		=   Average height of the system font.

There are eight types of controls available:

CALENDAR The Calendar control has a calendar-like user interface. This provides the user with a
very intuitive and recognizable method of entering or selecting a date. A user can select a day from the
current month and year by simply clicking on a day number. A user can scroll the months of the year by
clicking the arrow buttons in the top left or top right of the control. To select a non-adjacent month
the user can click the name of a displayed month, a pop-up menu appears that lists all months within the
year. The user can select a month on the list. If the user clicks the year displayed next to a month name,
a Spinner control appears in place of the year. The user can change the year with this control.

The Calendar control will return the user�s selection in the variable you supply as the Variable attribute
in the control�s definition. The date will be returned in the standard WIL YYYY:MM:DD:HH:MM:SS date time format.

You can also change the control�s font by providing a font string in the Font attribute. However, you cannot
change the text or background color of this control.

CHECKBOX A square box, in which an "X" appears when selected. A check box can have a value of 0 (unchecked) or
1 (checked). Each checkbox in a dialog should use a unique "var". Normally, when a dialog box opens, every
checkbox defaults to being unchecked. You can change this by assigning a value of 1 to "var" before calling
the Dialog function. Note for advanced users only: it is possible to define a group of checkboxes which have
the same "var". Each box in the group must have a unique value, which must be a power of 2 (1, 2, 4, etc.).
The user can check and uncheck individual checkboxes in the group, and when the Dialog function exits the
value of "var" will be equal to the values of all the checkboxes in the group, combined using the bitwise
OR operator (|).

DROPLISTBOX The DROPLISTBOX control is made up of two parts: an EDITBOX and a drop-down ITEMBOX. A user can
enter a value in the EDITBOX or select a suggested value from the drop-down items. The drop-down ITEMBOX
is displayed by clicking on the arrow next to the EDITBOX.

Generally, a DROPLISTBOX is appropriate when there is a list of suggested choices, and an ITEMBOX is
appropriate when you want to limit input to what is on the list. In addition, DROPLISTBOX save space on
your dialog. Because the full list is not displayed until, the user clicks the down arrow

You specify the items for the DROPLISTBOX list by placing a delimited list of values in the variable named
in the controls Variable attribute. You can give the EDITBOX portion of the control an initial value by
placing a string in the Text attribute of the control�s definition. The user�s choice is placed in the
variable named in the Variable attribute when the dialog is dismissed.

EDITBOX A box in which text can be typed. Whatever the user types in the editbox will be assigned to the
variable "var". Normally, when a dialog box opens, editboxes are empty. You can change this by assigning
a value to the string variable "var" before calling the Dialog function, in which case the value of "var"
will be displayed in the editbox.

Note: Variable names that begin with "PW_", will be treated as password fields causing asterisks to be
echoed for the actual characters that the user types.

FILELISTBOX A file selection list box. This will allow the user to select a file from any directory or drive
on the system. The value of "var" will be set to the selected filename; if you need to know what directory
the file is in, use the DirGet function after the Dialog function exits. Normally, when a dialog box opens,
filelist boxes display files matching a filemask of "*.*" (i.e., all files). You can change this by assigning
a different filemask value to the string variable "var" before calling the Dialog function. Normally, if a
dialog contains a FILELISTBOX, you must select a file from the list box before you can exit the dialog. You
can change this behavior by placing the statement IntControl(4, 0, 0, 0, 0) anywhere in your WIL program
prior to the Dialog statement. In combination with the FILELISTBOX, you can include an EDITBOX control
which has the same "var" name as the filelistbox. If you do, the user can type a filemask into the editbox
(e.g., "*.TXT"), which will cause the filelistbox to be redrawn to display only those files which match the
specified filemask. Also in combination with the filelistbox, you can include a VARYTEXT control which has
the same "var" name as the filelistbox. If you do, this control will show the name of the directory currently
displayed in the filelistbox. For FILELISTBOXes, "text" should be DEFAULT.

Note: You can have only one filelistbox in a dialog.

GROUPBOX The GROUPBOX control is a rectangle that surrounds a set of controls, such as check boxes or
radio buttons, with text in its upper left corner. The sole purpose of a Group control is to organize controls
related by a common purpose (usually indicated by the text).

Along with text, you can specify font, text color and a background color for the control. The background color
applies to the area immediately behind the text in the upper left corner. It does not change the background in
the majority of the control.

ITEMBOX A selection list box. The variable "var" is assumed to contain a tab delimited list. The list is loaded
into the list box in the original order (Use the ItemSort function if a sorted list is desired.). The user may
choose none, one, or more items in the list. When the dialog box is closed, the selected items are returned via
the "var" variable as a tab delimited list. If the user selects more than 99 items, an error will occur.

MULTILINEBOX As the name suggests, the MULTILINEBOX control allows a user to enter multiple lines of text.
In all other respects, it behaves like an EDITBOX control.

PICTURE The PICTURE control is a simple control you use to display a bitmap. You indicate the bitmap to display
by placing the bitmap file name and, optionally, the file path in the Background attribute parameter of the
control�s definition. If you supply a file path, WinBatch will check in the indicated path for the bitmap file
before checking other locations. If it does not find the file there or if you do not supply a path, WinBatch
will search the current directory, the windows directory and the WinBatch directory for the bitmap file.

Your bitmap does not need to be the same size as your PICTURE control. The appropriate stretch or compress
is applied to the bitmap so that the entire image is displayed. However, if the aspect ratio of your control
is significantly different from the bitmap�s aspect ratio, your image may appear distorted.

Although the control does not normally display text, you can still place text in the Text attribute.
WinBatch will display the text when it cannot find the bitmap indicated in the Background attribute while
loading the dialog template.

PICTUREBUTTTON The Picture Button control is a push button that displays a bitmap on its face instead of text and
a background color. Dialog Editor places your indicated bitmap file name and path in the Background parameter.
This parameter is used for background color in most other controls. Although the control does not normally
display text, you can place a text string in Text attribute. WinBatch will display the text when it cannot
find the bitmap indicated in the Background attribute while loading the dialog template. Also, if you include
the an ampersand in the text, your users will be able to use an accelerator key to navigate to button just like
they can with regular push buttons.

PUSHBUTTON A button, which can be labeled and used as desired. When the user presses a pushbutton, the Dialog
function will exit and will return the "value" assigned to the button which was pressed. Therefore, you should
assign a unique "value" to each pushbutton in a dialog. Pushbuttons with values of 0 and 1 have special meaning.
If the user presses a pushbutton which has a value of 0, the WIL program will be terminated (or will go to the
label marked ":CANCEL", if one is defined); this corresponds to the behavior of the familiar Cancel button. A
pushbutton with a value of 1 is the default pushbutton, and will be selected if the user presses the Enter key;
this corresponds to the behavior of the familiar OK button. For pushbuttons, "var" should be DEFAULT.
Note: Every dialog box must contain at least one pushbutton.

RADIOBUTTON One of a group of circular buttons, only one of which can be "pressed" (filled in) at any given time.
You can have more than one group of radiobuttons in a dialog box, but each group must use a different "var".
When the Dialog function exits, the value of "var" will be equal to the "value" assigned to the radiobutton
which is pressed. Therefore, you should assign a unique "value" to each radiobutton in a group. Normally,
when a dialog box opens, the default radiobutton in each group (i.e., the one which is pressed) is the first
radiobutton, 'called' in each group. You can change this by assigning a default "value" to the "var" before
calling the Dialog function.

SPINNER The SPINNER control has a pair of arrow buttons which the user can click to increment or decrement
a value displayed in a small edit box connect to the arrow buttons.

Use the control�s variable attribute to set the range of values that the control will display. The variable
should contain a vertical bar (|) delimited list with two or three items. Make the first item the minimum
value and the second the maximum value. The minimum value can be greater than the maximum value but both
values must be in the range of �32768 to 32767 and the difference between the values cannot exceed 32767.
The third value indicates the amount to add or subtract from the displayed number each time the user clicks
an up or down arrow (or presses the arrow keys when the control has the input focus.) The control adds or
subtracts one (1) each time, if you do not supply the third value. The final value selected by the user is
placed in the Variable when the dialog function returns.

You can indicate the initial value for your control by placing a number in the in the text attribute of the
control definition. The control will default to the minimum value if you do not indicate an initial value
or if your initial value does not fall within the range you have selected in the Variable attribute.

STATICTEXT Descriptive text, which does not change. This can be used to display titles, instructions, etc.
For static text controls, "var" should be DEFAULT.

VARYTEXT Variable text. The current value of "var" is displayed. If "var" is not assigned a value in the
WIL program before calling the Dialog function, the "text" field of the control definition will be used.

See Table 1 under the Dialog function for a complete list of both new and previously existing controls.

Notes:

You can have a maximum of 200 controls in a dialog.

The Dialog function has a debugging feature to help you quickly identify problem lines in your dialog templates. When the Dialog function encounters a template line that it can not parse, it copies the offending line to the wwwbatch.ini file located in your computer�s WINDOWS or WINNT directory. The template line is located in the [Dialog Template] section of the file, along with the number of the error. The keyname for the line and error number is LastError.

You can access the template line and error number from within scripts by using the IniReadPvt function. For example, the following script fragment will display the offending template line:

line = IniReadPvt ("Dialog Template", "LastError", "No errors", "wwwbatch.ini")
Message("Last Dialog Function Error", line)

Some WIL functions have been added to support the new Dynamic Dialog feature of the Dialog function. In order take advantage of this new feature, you will also need to create your own user defined callback procedure. This procedure allows you to modify the appearance of your dialog and execute WIL commands all while your dialog remains on the screen.

User-Defined-Callback Function or Subroutine

Syntax: 

UserDefinedCallback(dialog-handle,  event-code, control-number, rsvd, rsvd) 

Parameters: 

(i) dialog-handle           handle to dialog 
(i) event-code              event code for event that produced call to UDC
(i) control-number          number of control associated with event
(i) rsvd                    reserved
(i) rsvd                    reserved

Returns:  

(i)                         0 cancels dialog without updating control variables
                            -1 dialog performs usual processing after return
                            -2 dialog will not terminate or update control variables
                            n (positive integer) performs usual processing and exits dialog
                              and the number n is the return value of the Dialog statement as it exits.

�UserDefinedCallback� is a placeholder for the name of a functions or subroutine you place after the 
 #DEFINEFUNCTION or #DEFINESUBROUTINE reserved words in your WIL scripts.  Your implementation must 
 accept five (5) parameters as shown.

dialog-handle

The first parameter is a handle to the dialog associated with the procedure by assigning the routines 
name to the <dlg-variable>Procedure variable.

event-code

The second parameter is an event code that tells your procedure which event triggered the latest call. 

control-number 

The third parameter indicates the number of the control associated with the event in parameter two.  This is the same number 
that appears as part of each controls definition variable. 

The last two parameters are reserved for future development.

If you make the associations between your procedure and the dialog via a dialog variable assignment, your procedure will 
always be called at least one time.  This initial call occurs after your dialog has been created but just before it is 
displayed.  This initial call (event-code = 0) is good place to inform the dialog about other events you would like to 
handle.  You can do this by making one call to the DialogProcOptions functions for each event you wish to handle in your 
procedure.  After you make one or more calls to DialogProcOptions, each specified event will generate a call to your 
procedure with the event-code parameter set to the triggering event and the control-number parameter set to the control 
associated with the event. 

This table provides the list of dialog event codes that your dialog procedure can receive through the event-code parameter 
(parameter two).   Conveniently, these event-codes can also be used in calls to the DialogProcOptions function to indicate 
that you want to process the event.

Event-Codes	Meaning 
0	Initialization: dialog has been created but not displayed.  This event is only generated once pre dialog session.
1	Timer Expired: a previously specified amount of time has passed.  
2	Push: the user has pressed a PUSHBUTTON or PICTUREBUTTON control.
3	Radio: the user has selected a RADIOBUTTON.
4	Check/Uncheck: the user has checked or unchecked a CHECKBOX control.
5	Edit: the user has changed the text in an EDITBOX or MULTILINEBOX control
6	File Select� the user has selected a file in a FILELISTBOX control
7	Item Select: the user has selected one or more items in a ITEMBOX control.
8	Item Change: the user has change the text appearing at the top of a DROPLISTBOX.  
        This event can be trigger by the user picking a new item from the list portion of the control or by the user 
        typing new text into the control.
9	Date Change: the user has selected a new date in a CALENDAR control.
10	Number Change � the user has changed the value of a SPINNER control.
11	Close: the user has selected the Close command from the system menu.  This event only applies 
        to dialog's with system menus enabled by a call to IntControl 49.

Procedure return values
In addition to the processing you perform in response to events, your procedure's return value has an important impact on 
the behavior of your dialog.  For example, usually any button process will terminate a dialog, but by returning a �2 in 
response to an event-code of 2 (button push) you can force the dialog to stay on the screen.  (Of course, you still need 
to provide a way for the user to dismiss the dialog so you may want to turn on system menus with IntControl 49 or return �1 
when one of the dialog's buttons is pressed.)

The return value of zero will cancel the entire script, unless the cancel is handled with the :cancel label and/or with 
IntControl 72.

Dynamic Dialog Example:

PROCOPT_INIT    = 0   ; Dialog created .
PROCOPT_PUSH    = 2   ; Pass push/picture button presses.

#DEFINESUBROUTINE ExampleProc(DialogHandle, EventCode, ControlNum, Res4, Res5)
switch( EventCode)

   case PROCOPT_INIT
   DialogProcOptions(DialogHandle, PROCOPT_PUSH, 1)
   break;

   case PROCOPT_PUSH
      if  ControlNum == 1
         Display(2,"","Hello World")
         return -2 ; Don't termnate the dialog
      endif

      if ControlNum == 2
         Display(2,"","Goodbye World")

         return -1
      endif
endswitch

return -1
#ENDSUBROUTINE

ExampleOneFormat=`WWWDLGED,6.1`

ExampleOneCaption=`Simple Example`
ExampleOneX=029
ExampleOneY=060
ExampleOneWidth=174
ExampleOneHeight=094
ExampleOneNumControls=002
ExampleOneProcedure=`ExampleProc`
ExampleOneFont=`DEFAULT`
ExampleOneTextColor=`DEFAULT`
ExampleOneBackground=`DEFAULT,DEFAULT`

ExampleOne001=`029,051,034,014,PUSHBUTTON,DEFAULT,"Hello",1,1,DEFAULT,DEFAULT,DEFAULT,DEFAULT`

ExampleOne002=`093,051,034,014,PUSHBUTTON,DEFAULT,"Good Bye",0,2,DEFAULT,DEFAULT,DEFAULT,DEFAULT`

ButtonPushed=Dialog("ExampleOne")

Simple Example:

MyDialogFormat=`WWWDLGED,6.1`

MyDialogCaption=`Edit INI file`
MyDialogX=069
MyDialogY=124
MyDialogWidth=176
MyDialogHeight=184
MyDialogNumControls=014
MyDialogProcedure = `DEFAULT`
MyDialogFont=`DEFAULT`
MyDialogTextColor=`DEFAULT`
MyDialogBackground=`DEFAULT`


MyDialog001=`109,157,58,14,PUSHBUTTON,DEFAULT,"&Cancel",0,1,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog002=`111,77,60,14,PUSHBUTTON,DEFAULT,"&Notepad",1,2,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog003=`111,95,60,14,PUSHBUTTON,DEFAULT,"&WinBatch Studio",2,3,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog004=`111,113,60,14,PUSHBUTTON,DEFAULT,"Wri&te",3,4,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog005=`111,131,60,14,PUSHBUTTON,DEFAULT,"WinW&ord",4,5,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog006=`111,35,58,14,RADIOBUTTON,state,"No&rmal",1,6,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog007=`111,49,58,14,RADIOBUTTON,state,"&Zoomed",2,7,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog008=`111,63,58,14,RADIOBUTTON,state,"&Iconized",3,8,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog009=`111,21,58,14,CHECKBOX,backup,"Make &BAK",1,9,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog010=`5,3,34,14,STATICTEXT,DEFAULT,"&Directory:",DEFAULT,10,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog011=`41,3,130,20,VARYTEXT,editfile,"*EMPTY*",DEFAULT,11,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog012=`5,15,18,12,STATICTEXT,DEFAULT,"&File:",DEFAULT,12,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog013=`5,35,100,140,FILELISTBOX,editfile,DEFAULT,DEFAULT,13,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
MyDialog014=`5,25,100,10,EDITBOX,editfile,"None Selected",DEFAULT,14,DEFAULT,DEFAULT,DEFAULT,DEFAULT`


DirChange(DirWindows(0))
editfile = "*.INI"        ; Set default mask for filelistbox
backup = 1                ; Set the checkbox to be on by default
state = 2                 ; Set the 2nd radio button as the default

; Display the dialog, and wait for the user to press one of the
; pushbuttons.  The variable "ButtonPushed" will be equal to the value of
; whichever pushbutton is pressed.
while @TRUE
    ButtonPushed = Dialog("MyDialog")
    ; If the user didn't select a valid file, re-display the dialog
    If FileExist(editfile) Then break
endwhile        

; Find out if the checkbox was checked, and proceed accordingly
If backup == 1
    bakfile = StrCat(FileRoot(editfile), ".BAK")
    FileCopy(editfile, bakfile, @TRUE)
endif        

; Find out which radio button was pressed, and set the variable
; "runcmd" to the name of the appropriate member of the Run "family"
Switch state
    case 1
        runcmd = "Run"
        break
    case 2
        runcmd = "RunZoom"
        break
    case 3
        runcmd = "RunIcon"
        break
endswitch

; Set the variable "editor", based on the pushbutton that was pressed
Switch ButtonPushed
    case 1
        editor = FileLocate("notepad.exe")
        break
    case 2
        editor = FileLocate("WinBatch Studio.exe")
        break
    case 3
        editor = FileLocate("write.exe")
        break
    case 4
        editor = FileLocate("winword.exe")
        break
endswitch

; Execute the appropriate command (using variable substitution)
%runcmd%(editor, editfile)
Exit

:cancel
; If we got here, it means the user pressed the Cancel pushbutton
Message(MyDialogCaption, "Operation cancelled")

Article ID:   W15126

File Created: 2002:09:05:13:49:50

Last Updated: 2002:09:05:13:49:50