QUALIFYWINMSG Method (GUI)

Enables or disables the processing of a specified Windows message for a form or control. When enabled the object will trigger it's WINMSG event when the message is received.

PrevQualInfo = Exec_Method( CtrlEntID, "QUALIFYWINMSG", MsgNum, NewQualInfo )

The previous event qualifier information before any adjustments are made. This can be used with a subsequent call to QUALIFYWINMSG to reset the default processing.

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 – the script may be written once and then other control 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.

Eg.

3*SYSPROG*CLOSE.WINDOW.OIWIN*
   ^ ^                         ^
    -------------------------
             OIEventExeID
   ArgCount

Setting the "Event Name" allows the system to fire a specific named event when the message is received rather than simply calling the WINMSG event. This may help to structure application code in a more meaningful fashion.

For example, when tracking the WM_SETFOCUS message, the Event Configuration dialog may be used to define a custom event called "MYSETFOCUS". If this same name is used with the QUALIFYWINMSG method then the new MYSETFOCUS event is triggered rather than the normal WINMSG event when the object receives the WM_SETFOCUS message.

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, this can be a problem with handling Windows messages as many of them can pass a pointer to extra data: By the time the event is executed in the PS any pointers will likely be invalid as the code triggering the Windows message will have finished and cleaned up memory. To avoid this problem this event should be handled in one of the following synchronous ("Basic Sync" or "Callback Sync") manners instead because any pointers passed will still be valid.

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 actually 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 Basic synchronous mode.

Equates for the core Window messages can be found in the MSWIN_WINDOWMESSAGE_EQUATES insert record. Equates for the control-specific message like ComboBoxes and EditLines can be found in their respective MSWIN_<controltype>_EQUATES records.

 
//// Example : Track the WM_CAPTURECHANGED message//
   
   $Insert MsWin_WindowMessge_Equates
   $Insert Logical
   
   NewQualInfo  = TRUE$
   PrevQualInfo = Exec_Method( CtrlEntID, "QUALIFYWINMSG", 
                               WM_CAPTURECHANGED$,         
                               NewQualInfo )
                               
   ////  Do some processing...//
   
   //// Stop tracking and reset the event to it's defaults.//
   Call Exec_Method( CtrlEntID, "QUALIFYWINMSG", 
                     WM_CAPTURECHANGED$,         
                     PrevQualInfo )
 
 
 

Common QUALIFYEVENT method, OLECONTROL QUALIFYOLEEVENT method, Common GUI WINMSG event, Appendix XXX – Event handling, Appendix XXX - Event Configuration.