Function GetHandleEvent() | Xbase++

Applies events to the active Get object.

GetHandleEvent( <oGet>, <nEvent>, [<mp1>], [<mp2>], [<oXbp>]) --> NIL

<oGet>

<oGet> is the active Get object that receives events.

<nEvent> is the event code returned from AppEvent().

<mp1>

<mp1> is the first message parameter of AppEvent().

<mp2>

<mp2> is the second message parameter of AppEvent().

<oXbp>

<oXbp> is an Xbase Part to which the event should apply instead of the active Get object. This parameter is only relevant when Xbase Parts are used in a program. This parameter is provided by AppEvent() (see AppEvent()).

The return value of GetHandleEvent() is always NIL.

GetHandleEvent() implements the standard behavior of Get objects when using AppEvent(). It is to be used in place of the compatibility function GetApplyKey() when events are handled by the Get system. Switching between keyboard input using Inkey(), and event handling using AppEvent() can be done by calling GetEnableEvents(.T.|.F.).

GetHandleEvent() is usually not needed when programming Get objects, and is called automatically within the Xbase++ Get system as soon as an event occurs.

The standard input behavior for Get objects can be changed by a user- defined Get reader. A reader is a function in the form of a code block that is assigned to the Get object's :reader instance variable. For example, the reader can redefine several input keys, while the remaining keys are handled by GetHandleEvent() (see example).

Data validation after mouse click

When the parameter <oXbp> is an Xbase++ Part (for example, a pushbutton), the event is applied to it instead of to the Get object. This occurs only with mouse events. Before an Xbase++ Part can handle the event, the actual Get object must lose input focus, which is accomplished with GetKillActive(). This causes the Get object to complete a data validation before it is allowed to lose focus (-> VALID Option in @...GET). If, for example, a pushbutton was clicked on and the active Get object has invalid data in its edit buffer, the changed data is discarded and the previous buffer contents are restored before the Get object loses input focus (see the source code for GetHandleEvent() and GetKillActive() in the file GETSYS.PRG).

If the event is associated with a code block, the event is not applied to the Get object. Instead, the code block is executed (see GetDoSetkey()).

GetHandleEvent() usage

// An extensive example of changing the default Get system behavior 
// with GetHandleEvent() is found in the function 
// GetEventReader(). It shows a user-defined Get reader using 
// AppEvent().

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 GetHandleEvent() Foundation