Defining the Dialog

 

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:

 

<dlg-variable>Format="WWWDLGED,6.2"

 

where <dlg-variable> is the dialog name. "WWWDLGED,6.2" is the hard coded format which identifies this dialog box as using the WIL Dialog Type 6.2.

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>MinWidth = <min-box-width>  [optional]

<dlg-variable>MinHeight = <min-box-height>[optional]

<dlg-variable>NumControls = <ctrl-count>

<dlg-variable>Procedure = <procedure-name>

<dlg-variable>Font = <font>

<dlg-variable>TextColor = <textcolor>

<dlg-variable>Background = <background>

<dlg-variable>Config = <config>

<dlg-variable>DPI = <dpi,x-units,y-units>

 

where:

<dlg-variable>

The internal name of the dialog box, as described above. The WIL Dialog Editor uses the dialog variable name 'MyDialog' by default.

<box-caption>

The text which will appear in the title bar of the dialog box.

<x-origin>

The horizontal coordinate of the upper left corner of dialog box Dialog Units. Note: specify 9999 to always force the dialog to center, or specify -1 to center but remember user placement for re-display.

<y-origin> 

The vertical coordinate of the upper left corner of the dialog box Dialog Units. Note: specify 9999 to always force the dialog to center, or specify -1 to center but remember user placement for re-display.

<box-width>

The width of the dialog box in Dialog Units.

<box-height>

The height of the dialog box in Dialog Units.

<min-box-width>

[optional] Indicates the approximate minimum width of the dialog window that can be set by dragging the dialog's boarders. The value is assumed to be in dialog units. When this variable is present in a dialog template, the dialog becomes re-sizable by either directly dragging the dialog's boarder or by using the 'Size' system menu.

<min-box-height>

[optional] Indicates the approximate minimum height of the dialog window that can be set by dragging the dialog's boarders. The value is assumed to be in dialog units and to not include the height of the title and menu bars. When this variable is present in a dialog template, the dialog becomes re-sizable by either directly dragging the dialog's boarder or by using the 'Size' system menu.

<ctrl-count>

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> 

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 dialogs title text, however. Dialogs always use the system font in their titles. The font is specified as a string of vertical bar (|) delimited fields. The field values need to be set in such a way that the font will display properly on many different systems. You should use the WIL Dialog Editor to create values for this dialog attribute. For details see the Fonts section. 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 dialogs 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"

Note: A single hexadecimal number can be used instead of a vertical delimited list to indicate color.  The hexadecimal number must be preceded by the letter "h" or "H". For exemple, "hFFFFF" is equivalent to "255|255|255"    

<background>

This is the dialogs 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 (or a hexadecimal representation of a color in the for hXXXXXX where each  represents a hexadecimal digit), a bitmap file path, or both. To specify both, separate the bitmap and color attributes with a comma and make sure the bitmaps 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.

 

<config>

This controls how the WIL Dialog Editor creates the WIL Dialog command in your template. If the variable is given a value of one (1), the editor will create a return variable name that includes the dialog name (<dlg-variable>). For example, if your dialog name is MyDialog, the dialog statement would be:

MyDialogPushbutton=Dialog("MyDialog", 1)

 

Without this setting the dialog statement would be:

Pushbutton=Dialog("MyDialog", 1)

 

If the variable is given a value of two (2), the WIL Dialog Editor will place a zero (0) in the optional second parameter of the Dialog statement when it creates your dialog template. This optional parameter tells WinBatch to ignore the Dialog statement when it processes a script containing the dialog template. The WIL Dialog Editor, on the other hand, will not ignore the dialog statement so that you can reload the template into the editor at any time. If you do not specify this configuration option, the WIL Dialog Editor will create a dialog statement with the second parameter set to one (1). This tells WinBatch to process the Dialog statement by loading and displaying the dialog template.

You can combine the values 1 and 2 using the binary OR(|) operator to enable both features.

<DPI>

When present this attribute adjusts the size of the dialog and its controls to the scaling of current system's default display when that scaling differs from the default display of the system used to originally create the dialog template.  The three comma separated numbers that make up this attribute reflect the dots-per-inch, and horizontal and vertical dialog base units of the default display of the system used to create the dialog template. These values do not affect sizes when the current  system's displaying settings match the values of this attribute. You are strongly encouraged to use  the WIL Dialog Editor to create this attribute.  

When this attribute is present display scaling  ignores the horizontal and vertical dialog units of the current system. This should be taken into consideration when deciding whether or not to add this attribute to dialogs that will be deployed on systems with vastly different aspect ratios.  

<dlg-variable>nn

Defines each control in the dialog.

 

§         Dialog

§         Dialog Overview

§         Defining the Dialog

§         Defining the Dialog Controls

§         Dialog Control Types

§         Dynamic Dialogs

§         InternetExplorer Controls

§         Dialog Units

§         Dialog Fonts

 

Control Types

§         Calendar

§         Checkbox

§         ComControl

§         DropListbox

§         Editbox

§         FileListbox

§         Groupbox

§         Itembox

§         MenuBar

§         MenuItem

§         MultiLinebox

§         Picture

§         PictureButton

§         PushButton

§         RadioButton

§         ReportView

§         Spinner

§         StaticText

§         VaryText