Partager via

BINDEVENT() Function

  • Article

You can use BINDEVENT() to bind events, properties, or methods from native Visual FoxPro objects to other Visual FoxPro objects. To bind events from Component Object Model (COM) objects, use the EVENTHANDLER() function.

**Note   **The ActivePage property is not supported when using BINDEVENT( ).

BINDEVENT(oEventSource, cEvent, oEventHandler, cDelegate [, nFlags])

Parameters

  • oEventSource
    Specifies the event source, which must be a valid Visual FoxPro object.

  • cEvent
    Specifies the name of the event, method, or property you want to bind.

  • oEventHandler
    Specifies the object, which must be a valid Visual FoxPro object, handling the event.

  • cDelegate
    Specifies the method, or "delegate", that handles the event for oEventHandler.

    The delegate method must have the same parameters as the event specified in cEvent. You can call the AEVENTS() function to retrieve an object reference to the event source. If the delegate method does not have enough parameters to handle those passed by the event, Visual FoxPro generates an error.

  • nFlags
    Specifies an additive bit flag you can set for the event binding operation.

    nFlags Bits Description
    0 00 Call delegate code before event code. (Default)
    1 01 Call event code before delegate code.
    2 10 Do not trigger event (call delegate code) when a simple method call occurs.
    31 11 Call event code before delegate code. Do not trigger event (call delegate code) when simple method calls occur.

    1If you use an nFlags value of 1, the value returned by a method call to the event is not that of the event, rather that of the last delegate invoked. The event gets called before any of the delegates, so the return value of the delegate is the remaining value on the stack. Therefore, it is recommended that the delegate method contain the same return value as that of the event itself. In Visual FoxPro, a procedure that has no explicit RETURN statement returns an implicit value of True (.T.). This is an issue only if the event was triggered by method call and not via normal interactive mode or RAISEEVENT() call.

    The following table shows whether an event is raised when Bit 1 is off or on.

    Event type OFF (Default) ON
    Interactive YES YES
    Programmatic YES NO
    RAISEEVENT( ) YES YES

Return Values

Numeric data type. BINDEVENT() returns the number of bindings for the object's event.

Remarks

You can bind to any valid Visual FoxPro object event, property, or method, including the Access and Assign methods. However, the event and delegate methods must be public, not protected or hidden, members of the class.

You cannot bind to an event with parameters that are passed by reference. Though calling BINDEVENT( ) succeeds, raising the event, for example, using RAISEEVENT( ), fails.

When you bind to a property, you should bind to it directly and not to the Assign method. If you bind directly to the Assign method, be aware that Access and Assign methods are marked as Protected and are not visible except within the class.

Note   If you bind to a property that has an Assign method, the delegate method might trigger twice. The first time is when the property assignment call is made. The second time is when the property is actually set, within the Assign method, to the parameter that is passed. The delegate method should be aware of this possibility.

Normal rules of inheritance apply. If the delegate method does not contain any code, Visual FoxPro traverses up the parent hierarchy.

An event handler is called when an event occurs or if it is called as a method. Calling the event as a method triggers the event unless you specify a nFlags value of 2 or 3.

By default, Visual FoxPro calls the delegate method before the event. However, you can change the default behavior by using an nFlags setting.

If you specify a property as the event you want to bind, Visual FoxPro binds that property to an implicit Assign method. When the value of the property changes, Visual FoxPro triggers an event.

If an invalid parameter is passed, Visual FoxPro generates the error, "Function argument value, type, or count is invalid." However, if a problem occurs during the binding operation, Visual FoxPro does not generate an error. You can retrieve the return value of BINDEVENT( ) to check the number of bindings.

Certain control events such as GotFocus, LostFocus, InteractiveChange, and ProgrammaticChange do not work if the second bit of the nFlags parameter is set, for example, nFlags set to 2. These events are treated as method calls internally by Visual FoxPro, even though they are considered events. The same behavior applies to the Refresh method of an object on a form that is called when the form's Refresh method is called. Certain events such as When and Valid require code in the event for it to occur.

BINDEVENT( ) does not directly support the Value property because it is handled by Visual FoxPro in a special way. You should use the InteractiveChange and ProgrammaticChange events instead.

If the original event contains a NODEFAULT command, Visual FoxPro still processes the event because it is possible that the delegate method is called before the event. NODEFAULT applies only to native Visual FoxPro events.

If you make an exact duplicate BINDEVENT() call, Visual FoxPro disregards the call but still returns the number of bindings for the object's event. If you change the nFlags setting, you can call BINDEVENT( ) to rebind the event.

Example

The following example shows how you can keep the Class Browser positioned to the right side of the Visual FoxPro desktop, regardless of how the desktop is resized. BINDEVENT( ) associates the Resize event of the _SCREEN system variable, or Visual FoxPro desktop, with oHandler, which uses myresize as its delegate. The code for myresize runs when the Resize event is triggered.

PUBLIC oHandler
oHandler=NEWOBJECT("myhandler")
DO (_browser)
BINDEVENT(_SCREEN,"Resize",oHandler,"myresize")

DEFINE CLASS myhandler AS Session
   PROCEDURE myresize
      IF ISNULL(_obrowser) THEN
         UNBINDEVENT(THIS)
      ELSE
         _obrowser.left = _SCREEN.Width - _obrowser.width
      ENDIF
   RETURN
ENDDEFINE

See Also

Functions | Event Binding for Visual FoxPro Objects | UNBINDEVENTS() Function | RAISEEVENT() Function | AEVENTS() Function