{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.

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.

@deComEvent (14)

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

@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.