Function SetAppEvent() | Xbase++

Associates a code block with an event.

SetAppEvent( <nEvent>, [<bNewBlock>] ) --> bOldBlock

<nEvent> is the numeric event code for the event to link to the code block. Symbolic constants are defined in the #include file Appevent.ch for the event codes.

<bNewBlock> is a code block which is attached to the event with the code <nEvent>. The code block should have three parameters for receiving the message parameters from AppEvent():

{|mp1, mp2, oXbp| ...Code... }

The association between the event and the code block is removed when the value NIL is explicitly specified for <bNewBlock>.

If SetAppEvent() is called without the argument <bNewBlock>, the function returns the code block currently linked to the event. If the event with the code <nEvent> is not currently linked to a code block, NIL is returned. If <bNewBlock> is specified, the new code block is attached to the event and the old code block or NIL is returned.

The function SetAppEvent() associates a code block with a specific event or returns the code block currently associated with the event. The code block is then automatically executed by certain functions and commands which independently process events. These include input commands like ACCEPT and READ as well as the dialog functions like MemoEdit(). If code blocks are associated with the same key using SetKey() and SetAppEvent(), both code blocks are automatically executed one at a time.

Most functions or commands do not provide automatic event processing. In this case a code block which is associated with an event must be retrieved with SetAppEvent() and evaluated with Eval().

Suppressing default event handling in text-mode functions

The return value of the SetAppEvent() code block influences the default event handling of all functions and commands that evaluate this code block automatically on their own. This applies only to text-mode commands and functions such as Achoice() or Memoedit(). If the code block returns 0 or a non-numeric value, the event associated with the code block is not processed further, i.e. a default event processing can be disabled in this way. If the code block returns a valid event code, this event will be processed. This way, a default bahavior for a given event can be mapped to a different behavior.

SetAppEvent()

// In the example, a code block is linked with the event "left 
// mouse click". A click of the left button displays the message 
// parameters of AppEvent(). 

#include "Appevent.ch" 

PROCEDURE Main 
   LOCAL mp1, mp2, oXbp, nEvent, bBlock 
   SetMouse(.T.) 

   CLS 
   ? "Left mouse click tests SetAppEvent()" 
   ? "Exit with right mouse button" 

   SetAppEvent( xbeM_LbClick, ; 
               {|mp1,mp2,obj| CheckEvent(mp1,mp2,obj) } ) 

   DO WHILE .T. 
      nEvent := AppEvent( @mp1, @mp2, @oXbp, 0 ) 

      IF (bBlock := SetAppEvent(nEvent)) <> NIL 
          Eval( bBlock, mp1, mp2, oXbp ) 

      ELSEIF nEvent < xbeB_Event 
          ?? Chr( nEvent ) 

      ELSEIF nEvent == xbeM_RbClick 
         QUIT 

      ENDIF 
   ENDDO 

RETURN 

************************************** 
PROCEDURE CheckEvent( mp1, mp2, oXbp ) 

   ? "First message parameter:", mp1 
   ? "Second message parameter:", mp2 

   IF Valtype( oXbp ) == "O" 
      ? "Xbase-Part:", oXbp:className() 
   ENDIF 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function SetAppEvent() Foundation