Dynamic Dialogs

 

Dynamic Dialogs allow you to modify the appearance of your WIL Dialog and execute WIL commands while your dialog remains on the screen. In order to take advantage of this feature, you will also need to create your own User Defined Callback Procedure.

Creating a Dialog Callback procedure

WinBatch Studio provides a right click context menu that helps generate a customized User Defined Callback Procedure template based on your WIL Dialog. To have WinBatch Studio generate the User Defined Callback Procedure template code, you simply highlight your Dialog code, top to bottom, starting with the line:

       

MyDialogFormat="WWWDLGED,6.2"

 

all the way down to and including the following line:      

 

ButtonPushed=Dialog( "MyDialog" )

 

Next, right-click anywhere in the WinBatch Studio edit window, then select the menu items:


Code Blocks | Create Dialog Callbacks in Clipboard | Function with Constants.

 

When it is complete, it copies the template code to the clipboard. Simply paste the generated template code into your script, usually above your Dialog code or at the beginning of your script.

Locate the Dialog code and modify the Dialog Definitions:  <dlg-variable>Procedure = <procedure-name>

Understanding the Dialog Callback procedure
Syntax:

{UserDefinedCallback}( dialog-handle, event-code, control-name, event-info, change-info)

Parameters:

(i) dialog-handle: handle to Dialog

(i) event-code: event code for event that produced call to UDC

(i) control-name: name of control associated with event

(i) event-info: event information object (valid only when event-code = 14)

(a/s) change-info: format depends on specified event-code.

Returns:

(i) The return value has special meaning:  

@retCancel (0) cancels dialog without updating control variables

@retDefault (-1) performs usual processing after return

@retNoExit (-2) will not terminate. (Note: control variables will not get updated until the Dialog exits.) Use DialogControlGet and DialogControlSet, to get and set values.

n (positive integer) performs usual processing and exits the dialog and the number n is the return value of the Dialog statement as it exits.

 

{UserDefinedCallback}

A placeholder for the name of a function 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 routine's 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-name

The third parameter indicates the name of the control associated with the event in parameter two. This is the same name that appears as the name attribute of the control in the control's definition (legacy dialog formats, i.e. earlier than 6.2, used the control's number in this parameter.)  

 

event-info

When the second parameter has the value COM-event (14), the fourth parameter contains a reference to an event information object. An event information object is a WinBatch generated COM object that contains information about the COM event that is calling to your user-defined function.

The event-info object has the following properties

Identifier

This is the user defined identification number originally passed as the fifth parameter to the DialogObject function.

Eventname

This is the name of the event you obtained from the controls documentation and passed as the fourth parameter to the DialogObject function.

Count

This property contains the number of parameters associated with the event. It also indicates the number of Parameter objects in the Parameters property. Count is zero (0) when the event does not have any parameters.

Parameters(index)

This indexed property returns one Parameter object for each parameter associated with the event. The index parameter indicates which event parameter you wish to access and should be a number between one (1) and Count. The parameter object has Value as its only property. You can use the value property to either access the information associated with the event parameter or return information to the control by assignment. To access an event parameter value you can do the following

 

; The "MSCAL.Calendar" control's "KeyPress" event had 1 

; parameter the code for the key pressed by the user. 

nKey = EventInfo.Parameters(1).value 

message("Key code", nKey) 

 

You can return information to a control too

 

; The "MSCAL.Calendar" control's "BeforeUpdate" event had 1 

; parameter. You can use it to cancel a control change. 

EventInfo.Parameters(1).value = @True 

 

 

change-info

The format of this parameter is dependant on the specified event code.

Event Code

Return Value

@deResize (17)

A space delimited list of items that represent the change in width and height of the dialog resulting from resizing activity is passed to the callback UDF/UDS in the callback's fifth parameter. The space delimited list items represent the delta (change in width and height) of the dialog that resulted from resizing activity and the client height and width that represents the internally maintained size of the dialog's client area.

{delta_width} {delta_height} {client_width} {client_height}

 

The delta width and height supplied are in dialog units and can be either negative or positive numbers.  The client area is the area of a window used to display controls and its size does not include the dialog window's borders, menu bar, nor title bar.

The dialog template must use the <dlg-variable>MinWidth and/or <dlg-variable>MinHeight variables in order to use this option. The last parameter is reserved for future development.

@deRvrSelect (18)

The text of  the first column of the selected row is passed to the callback UDF/UDS in the callback's fifth parameter.

@deRvrDblclick (19)

The text of the first column of the double-clicked row is passed to the callback UDF/UDS in the callback's fifth parameter.

@deRviCheck (20)

The text of the checked item is passed to the callback UDF/UDS in the callback's fifth parameter.

@deRviText (21)

The user modified text of the item is passed to the callback UDF/UDS in the callback's fifth parameter.

Note: that if more than one first column item of a control contains the same value, it is possible for the fifth parameter to contain a tab delimited list of multiple occurrences of the targeted item's text. The number items in the list indicates which instance of the item is the target of the event.

@deRvhClick (22)

User has used the mouse to click a column header of a REPORTVIEW control. The one based column number of the clicked column is passed to the callback UDF/UDS in the callback's fifth parameter. The event is fired before the indicated column is sorted so the sort direction can be controlled by setting or changing the sort direction style of the control during the callback. Sorting is effectively cancelled by removing both sorting related styles from the control.

    @deFocus (24)

Name of control that lost the focus or empty-string when no control lost the focus.

 

 

If you make the associations between your procedure and the Dialog via a dialog variable assignment, the procedure will always be called at least once to execute the initialization event.

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 or DialogObject function for each event you wish to handle in your procedure. After you make one or more calls to DialogProcOptions or DialogObject, each specified event will generate a call to your procedure with the event-code parameter set to the triggering event and the control-name 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.

Codes

Meaning

@deInit (0)

Initialization: Dialog has been created but not displayed. This event is only generated once per Dialog session.

@deTimer (1)

Timer: Set a Timer event

@dePbPush (2)

Pushbutton or Picturebutton Pushed: User has pressed a PUSHBUTTON or PICTUREBUTTON control.

@deRbPush (3)

Radiobutton Selected: User has selected a RADIOBUTTON.

@deCbCheck (4)

Checkbox Checked/Unchecked: User has checked or unchecked a CHECKBOX control.

@deEdText (5)

Changed text in Editbox or Multilinebox: User has changed the text in an EDITBOX or MULTILINEBOX control

@deFlSelect (6)

Filelistbox File Selected: User has selected a file in a FILELISTBOX control

@deIbSelect (7)

Itembox Item Selected: User has selected one or more items in a ITEMBOX control.

@deDlChange (8)

Droplistbox/Combobox Item Change: User has changed the text appearing at the top of a DROPLISTBOX. This event can be triggered by the user picking a new item from the list portion of the control or by the user typing new text into the control.

@deCaChange (9)

Calendar Date Change: User has selected a new date in a CALENDAR control.

@deSpChange (10)

Spinner Number Change: User has changed the value of a SPINNER control.

@deClose (11)

Close: 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 DialogProcOptions code 1002.

@deFlDblclick (12)

Filelistbox File Double-Clicked: the user has used the mouse to double-click an item in an FILELISTBOX.

@deIbDblclick (13)

Itembox Item Double-Clicked: the user has used the mouse to double-click an item in an ITEMBOX.

@deMiSelect (15)

Menu item selected:  The user has used the mouse, an access key or hot-key to select a MENUITEM.
Note: The user-defined callback is not called in response to the mouse selection of a menu item that has associated drop-down menus or sub-menus. The associated dropdown or sub-menu is displayed instead. Hot-keys should not be used with menu items that display a drop-down or sub-menu.

@deMiInit (16)

Menu Item Initialization: The user has selected a drop-down menu, sub-menu or context menu. The name of the menu hosting control or menu item is passed to the user-defined-callback as the value of its third parameter.

For example: This event be used to dynamically modify the menu itself.

@deResize (17)

Dialog Resize: The user has resized the dialog. When the user-defined-callback is called with this request, the fifth parameter to the user-defined-callback procedure contains a space delimited list of items that represent the change in width and height of the dialog that resulted from the resizing activity and the client width and height.

{delta_width} {delta_height} {client_width} {client_height}

 

The delta width and height supplied are in dialog units and can be either negative or positive numbers.  The client area is the area of a window used to display controls and its size does not include the dialog window's borders, menu bar, nor title bar.

The dialog template must use the <dlg-variable>MinWidth and/or <dlg-variable>MinHeight variables in order to use this option. The DialogProcOptions function will error, if this request code is used with a dialog template that does not contain at least one of these variables.

@deRvrSelect (18)

Item Select Row: User has selected row in the REPORTVIEW control. The text of the first column of the selected row is passed to the callback UDF/UDS in the callback's fifth parameter.

@deRvrDblclick (19)

Double-Clicked Row: User has used the mouse to double-click a row in the REPORTVIEW control. The text of the first column of the double-clicked row is passed to the callback UDF/UDS in the callback's fifth parameter.

@deRviCheck (20)

Checked/Unchecked Item: User has checked or unchecked an item in a REPORTVIEW control with the 'checkbox' style.  The text of the checked item is passed to the callback UDF/UDS in the callback's fifth parameter.

@deRviText (21)

Item Text: User has changed the text of a first column item in a REPORTVIEW control. The user modified text of the item is passed to the callback UDF/UDS in the callback's fifth parameter. Note that if more than one first column item of a control contains the same value, it is possible for the fifth parameter to contain a tab delimited list of multiple occurrences of the targeted item's text. The number items in the list indicates which instance of the item is the target of the event.

@deRvhClick (22)

Column Click: User has used the mouse to click a column header of a REPORTVIEW control. The one based column number of the clicked column is passed to the callback UDF/UDS  in the callback's fifth parameter. The event is fired before the indicated column is sorted so the sort direction can be controlled by setting or changing the sort direction style of the control during the callback. Sorting is effectively cancelled by removing both sorting related styles from the control.

 

Other events NOT supported by DialogProcOptions:

@deComEvent (14)

COM-Event: This event is not supported by DialogProcOptions. Use DialogObject to monitor for COM events.

 

Other non-events supported by DialogProcOptions:

@dpoDisable (1000)

Dialog Disable: Grey the dialog's title bar and redraw dialog as necessary. Optionally, display the system's "wait cursor". Note: If you have code that may take a long time to execute in a callback, you may need to temporarily disable the dialog. Don't forget to enable after the process is complete.

@dpoBkground (1001)

Change Background: Change the dialog's background bitmap or color.

@dpoSysMenu (1002)

Change System Menu: Change the dialogs title bar system menu. Note: this dialog option overrides the system menu settings established with IntControl 49.

@dpoTitle (1003)

Change Dialog Title: Change the dialogs title. Note: the maximum dialog title length is 254 characters.

@dpoCtlName (1004)

Get Control Name: Returns the name of the control associated with the number.

@dpoCtlNumber (1005)

Get Control Number: Returns the control number associated with the name.

@dpoClientSize (1007)

Get Client Area: Return internally maintained width and height of the dialog's client area in dialog-units as a space delimited list. The returned client area dimensions are the dialog's size not including the width and height of  borders, the height of the menu bar, nor the height of the title bar. The third parameter to DialogProcOptions must be set to -1 when using this request code.

 

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 @retnoexit (-2) in response to an event-code of 2 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 DialogProcOptions code 1002 or return @retdefault (-1) when one of the dialog's buttons is pressed.) The return value of @retcancel (0) will cancel the entire script, unless the cancel is handled with the :cancel label and/or with IntControl 72.

Dynamic Dialog Example:
#DefineSubRoutine ExampleProc(DialogHandle, EventCode, ControlName, EventInfo, ChangeInfo)
   Switch( EventCode)
      Case @deinit
         DialogProcOptions(DialogHandle, @depbpush, 1)
         break;
      Case @depbpush
         If ControlName == "Pushbutton_Hello"
            Display(2,"","Hello World")
            Return @retnoexit ; Don't termnate the dialog
         EndIf
         If ControlName == "Pushbutton_Bye"
            Display(2,"","Goodbye World")
            Return @retdefault
         EndIf
   EndSwitch
   Return @retdefault
#EndSubRoutine
ExampleOneFormat=`WWWDLGED,6.2`
ExampleOneCaption=`Simple Callback Example`

ExampleOneX=029 ExampleOneY=060 ExampleOneWidth=174 ExampleOneHeight=094 ExampleOneNumControls=002 ExampleOneProcedure=`ExampleProc` ExampleOneFont=`DEFAULT` ExampleOneTextColor=`DEFAULT` ExampleOneBackground=`DEFAULT,DEFAULT` ExampleOneConfig=0 ExampleOne001=`029,051,034,014,PUSHBUTTON,"Pushbutton_Hello",DEFAULT,"Hello",1,1,DEFAULT,DEFAULT,DEFAULT,DEFAULT` ExampleOne002=`093,051,034,014,PUSHBUTTON,"Pushbutton_Bye",DEFAULT,"Good Bye",0,2,DEFAULT,DEFAULT,DEFAULT,DEFAULT` ButtonPushed=Dialog("ExampleOne",1) Exit

 

§         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