Enables or disables the processing of a specified event for an object.
PrevQualInfo = Exec_Method( CtrlEntID, "QUALIFYEVENT", EventID, NewQualInfo )
| Name | Required | Description |
|---|---|---|
| EventID | Yes | Name of the event to update. If this is numeric then it is assumed to be a Windows message ID instead – refer to the Common GUI QUALIFYWINMSG method for more details. |
| NewQualInfo | No | An @fm delimited array that specifies how to update the event processing. <1> Enable Flag – TRUE$ to process the event, FALSE$ to disable it. This field is required. If set to TRUE$ then the following fields are also valid: <2> Qualifier String. Can contain the name of an event qualifier to execute rather than the default (See Remarks below for more details). This field is optional. <3> Event Name - Can contain the name of a different event to execute (See Remarks below for more details). This field is optional. <4> SyncFlags – specifies the priority of the event. Can be one of the following values: 0 : Asynchronous – the event is queued and executed as the queue is processed. This is the default. 1 : Basic Sync – the event is executed as soon as it is received. If this is not possible the event will be discarded. 2 : Callback – similar to Synchronous, except that the event will also be executed if the PS is in a "wait state". (See Remarks below for more details) |
The previous event qualifier information before any adjustments are made. This can be used with a subsequent call to QUALIFYEVENT to reset the default processing.
If the EventID is numeric then it is assumed that we are qualifying a Windows Message – refer to the Common GUI QUALIFYWINMSG method for more details.
Setting the "Qualifier String" allows the system to use a different event script at runtime rather than the default one. This can be useful when centralizing code – a script may be written once and then other controls can be "redirected" to use it. A qualifier string is defined by two parts, delimited by a "*" character. These are:
1. The number of arguments the event expects (including the object name and class), and
2. The ID of a SYSREPOSEVENTEXES object code record to execute when the event is fired.
E.g.
3*SYSPROG*CLOSE.WINDOW.OIWIN*
Setting the "Event Name" allows the system to fire a specific named event when the message is received rather than simply calling the same event. This is mainly for use with OLE and WINMSG events (see the QUALIFYWINMSG and QUALIFYOLEEVENT methods for more details).
Setting the "SyncFlags": Normal PS event processing is executed in an asynchronous fashion, which means it is placed in a queue and run when the PS checks its message queue. However, events can also be executed synchronously using one of two methods: "Basic Sync" or "Callback Sync".
In Basic Sync mode the PS attempts to execute the event as soon as it is notified. However, if it is busy processing a previously executed event then the new one cannot be processed and will be discarded.
In Callback Sync mode the PS attempts to execute the event as soon as it is notified. However, if it is busy processing a previously executed event then it checks to see if that one is in a "wait-state", i.e. it Basic+ has called back into the PS through use of something like a Set_Property call and is waiting for the PS to respond. This can happen if setting the property generates a Windows notification message which triggers a PS event – the event can be raised before the Set_Property call returns. Using the Callback mode is generally a better idea than the simple Synchronous mode.
In previous versions of OpenInsight this method was called QUALIFY_EVENT. That name may still be used to preserve backwards compatibility.
//// Example : Redirect the CHAR event of EDL_DATA2 to use the CHAR event script // //// : of EDL_DATA1// QualInfo = Exec_Method( @Window : ".EDL_DATA1", "QUALIFYEVENT", "CHAR" ) Call Exec_Method( @Window : ".EDL_DATA2", "QUALIFYEVENT", "CHAR", QualInfo ) //// Example : Turn off the CHANGED event processing of EDL_DATA3 and restore it // //// : again.// QualInfo = Exec_Method( @Window : ".EDL_DATA3", "QUALIFYEVENT", "CHANGED", FALSE$ ) ////// //// .. Do some processing ...// //// // Call Exec_Method( @Window : ".EDL_DATA3", "QUALIFYEVENT", "CHANGED", QualInfo )
Common GUI QUALIFYWINMSG method, OLECONTROL QUALIFYOLEEVENT method, Appendix XXX – Event handling, Appendix XXX - Event Configuration.