DialogObject

Interacts with COM controls in a dialog callback procedure.

Syntax:

DialogObject( dialog-handle, control-name, request-code, event-name/image-file, event-id )

Parameters

(i) dialog-handle: handle to dialog.

(2) control-name: name of a COM control or 0 (depends on request-code.)

(i) request-code: number of task to perform

(s) event-name: (optional) name of control event, image file or do not specify (depends on request-code)

(i) event-id: (optional) number to associate with an event or do not specify (depends on request-code)

Returns:

(i) object-reference 1 or object reference on success (depends on request-code), 0 on failure

DialogObject is a multi-purpose function that you can call from within your dialog callback procedure to interact with COM controls embedded in your dialog. The function’s main purpose is to allow you to instruct a COM control to call your dialog callback procedure when a supported event occurs within the control. But you can also use the function to obtain a COM object reference to a control and you can even use it to create Picture objects that some COM controls display as part of their user interface.

dialog-handle

The first parameter must be the dialog-handle passed as the first parameter to your dialog procedure.

control-name

Name of the COM control from which you wish to receive events or obtain an object reference. This parameter should be set to zero (0) when request-code 4 is used in the third parameter.(for legacy dialog formats, i.e. earlier than 6.2, use the control's number in this parameter.)

request-code

The third parameter determines the action taken by the function. Currently, there are four possible values

event-name

Almost all COM controls provide events. Events are usually fired in response to a user action, like a mouse button click on the control, but they can also be fired as the result of some action taken by your script. When an event is fired by the control, you can instruct the control to make a call to your dialog callback procedure so that you can do additional processing. In order to have your dialog procedure called by the control, you need to call DialogObject with a request code of one (1) and specify the name of the event in the fourth parameter. To stop a control calling your dialog procedure for an event, specify the event name in this parameter and set the request-code to two (2).

This parameter is also used with request-code 3 to obtain a reference to a picture object. When you use request code 3 the parameter must contain the file name and path to a file that contains a BMP (bitmap), JPEG, WMF (metafile), ICO (icon) or GIF format image. Some COM controls accept picture objects for use as part of the control’s on screen appearance.

Here is a summary of the event-name parameter’s usage

event-id

You can associate a number with a particular control event with this parameter. The number can later be used inside the dialog callback procedure to uniquely identify which control event is currently calling your procedure. This is because it becomes the Identifier property of the EventInfo object passed to your procedure each time an event is fired. The number should be unique for each event in the control and can be made unique for all control events monitored by your procedure.

Only specify this parameter for request code 1.

Example:

 
;This example uses the DialogObject function To cause a Dialog To Receive mouse button
;click events from a Microsoft calendar COM control. DialogObject is also used To
;obtain a reference To the calendar control. The reference is Then used To obtain
;and set properties of the control before and during control event processing. To
;use this example, the Microsoft calendar control and the Microsoft concatenated speech
;synthesis (or text-To-speech) engine must be installed and registered ON the computer
;running this script. The computer must also have appropriate sound hardware and drivers.
#DefineSubRoutine DlgObjExamProc(Dlg_Handle, Dlg_Message, Dlg_ID, Dlg_EventInfo, Dlg_ChangeInfo)
Switch Dlg_Message
Case @deInit
   MSCAL_CLICK = 1 ; User specified identifier for "click" event.
   DialogProcOptions( Dlg_handle, @dePbPush, 1 )
   ; Handle mouse click events.
   DialogObject(Dlg_Handle, "ComControl_1", @doAddEvent, "Click", MSCAL_CLICK )
   ; Get an object reference to the calendar control.
   objCal = DialogObject(Dlg_Handle, "ComControl_1", @doGetObject)
   ; Create a voice object
   objVoice = ObjectOpen("Sapi.SpVoice.1")
   objVoice.volume = 100 ; Loud!
   Break
Case @deComEvent
   ; Correct COM control and event?
   If (Dlg_ID == "ComControl_1") && (Dlg_EventInfo.identifier == MSCAL_CLICK)
      ; Speak the date.
      sSpeach = StrCat('<context ID ="date_mdy">',objCal.month)
      sSpeach = StrCat(sSpeach,'/',objCal.day,'/',objCal.year,'</context>')
      sSpeach = StrCat('<voice required="Gender=Female;Name=Microsoft Anna">',sSpeach,'</voice>')
      objVoice.Speak(sSpeach, 9) ; 9 = SPF_ASYNC|SPF_IS_XML
   EndIf
   Break
Case @dePbPush
   ; Release Objects.
   Dlg_EventInfo = 0
   objVoice = 0
   objCal = 0
   Break
EndSwitch
Return(@retDefault) ; Do default processing.
#EndSubRoutine ; End of Dialog Callback.
DlgObjExFormat=`WWWDLGED,6.2`
DlgObjExCaption=`Dialog Object Example`
DlgObjExX=035
DlgObjExY=105
DlgObjExWidth=200
DlgObjExHeight=181
DlgObjExNumControls=002
DlgObjExProcedure=`DlgObjExamProc`
DlgObjExFont=`DEFAULT`
DlgObjExTextColor=`DEFAULT`
DlgObjExBackground=`DEFAULT,DEFAULT`
DlgObjExConfig=0
DlgObjDPI=`96,8,16`
DlgObjEx001=`031,161,133,011,PUSHBUTTON,"PushButton_1",DEFAULT,"Enough Already",1,1,@csDefButton,DEFAULT,DEFAULT,DEFAULT`
DlgObjEx002=`015,015,168,126,COMCONTROL,"ComControl_1",DEFAULT,"MSCAL.Calendar",DEFAULT,3,DEFAULT,DEFAULT,DEFAULT,DEFAULT`
ButtonPushed=Dialog("DlgObjEx")
Exit
 

See Also:

Dialog