Developer Guide and Reference

ID 767251
Date 10/31/2024
Public
Document Table of Contents

DLGSETCTRLEVENTHANDLER

Dialog Subroutine: Lets you assign your own event handlers to ActiveX controls in a dialog box. This routine is only available for Windows.

Module

Dialog Function: Assigns user-written event handlers to ActiveX controls in a dialog box.

USE IFLOGM

result = DLGSETCTRLEVENTHANDLER (dlg,controlid,handler,dispid[,iid])

dlg

(Input) Derived type dialog. Contains dialog box parameters. The components of the type dialog are defined with the PRIVATE attribute, and cannot be changed or individually accessed by the user.

controlid

(Input) Integer. Specifies the identifier of a control within the dialog box. Can be the symbolic name for the control or the identifier number, both listed in the include (with extension .FD) file.

handler

(Input) Name of the routine to be called when the event occurs. It must be declared EXTERNAL.

dispid

(Input) Integer. Specifies the member id of the method in the event interface that identifies the event.

iid

(Input; optional) Derived type GUID, which is defined in the IFWINTY module. Specifies the interface identifier of the source (event) interface. If omitted, the default source interface of the ActiveX control is used.

Results

The result type is INTEGER(4). The result is an HRESULT describing the status of the operation.

When the ActiveX control event occurs, the handler associated with the event is called. You call DLGSETCTRLEVENTHANDLER to specify the handler to be called.

The events supported by an ActiveX control and the interfaces of the handlers are determined by the ActiveX control.

You can find this information in one of the following ways:

  • By reading the documentation of the ActiveX control.

  • By using a tool that lets you examine the type information of the ActiveX control;, such as the OLE-COM Object Viewer.

  • By using the Fortran Module Wizard to generate a module that contains Fortran interfaces to the ActiveX control, and examining the generated module.

The handler that you define in your application must have the interface that the ActiveX control expects, including calling convention and parameter passing mechanisms. Otherwise, your application will likely crash in unexpected ways because of the application's stack getting corrupted.

Note that an object is always the first parameter in an event handler. This object value is a pointer to the control's source (event) interface, not the IDispatch pointer of the control. You can use DLGGET with the DLG_IDISPATCH index to retrieve the control's IDispatch pointer.

Example

USE IFLOGM
ret = DlgSetCtrlEventHandler(            &
      dlg,                         &
      IDC_ACTIVEMOVIECONTROL1,     & ! Identifies the control
      ReadyStateChange,            & ! Name of the event handling routine
      -609,                        & ! Member id of the ActiveMovie's
                                   & !   control ReadyStateChange event.
      IID_DActiveMovieEvents2 )          ! Identifer of the source (event)
                                         !    interface.