DEFINE EVENT statement

Defines an ABL class event, declares a class event prototype in an ABL interface, or overrides an abstract class event inherited from an ABL or .NET abstract super class. A class event is a member of the class in which it is defined. You can publish a non-abstract event from within the defining class definition using the built-in Publish( ) event method in response to a condition that you determine. You can subscribe a class method or internal procedure as a handler for any accessible event (abstract or non-abstract) using the built-in Subscribe( ) event method. This handler executes whenever the event is published. You can also unsubscribe any handler using the built-in Unsubscribe( ) event method. The following description begins with general syntax for defining a class event.

Note: This statement is applicable only when used in a class or interface definition (.cls) file. For more information on class events, see the "Class Events Reference" section.

Syntax


DEFINE [ PRIVATE \| PROTECTED \| PUBLIC ] [ STATIC \| ABSTRACT ] [ OVERRIDE ] EVENT `event-name` `signature-spec`

Use the following syntax to declare a class event prototype in an interface:


DEFINE [ PUBLIC ] EVENT `event-name` `signature-spec`

Use the following syntax to declare an abstract class event prototype:


DEFINE [ PROTECTED \| PUBLIC ] [ OVERRIDE ] ABSTRACT EVENT `event-name` `signature-spec`

[ PRIVATE | PROTECTED | PUBLIC ]

Specifies the access mode for this event. For a class event, the access mode indicates what code can call the Subscribe( ) event method on the event.

Note: You can only directly publish an event from within the class where it is defined, regardless of its access mode.

A PRIVATE event can have a handler subscribed to it only by the defining class. A PROTECTED event can have a handler subscribed to it by the defining class and any of its derived classes. A PUBLIC event can have a handler subscribed to it by:

The defining class

Any of its derived classes

Any class or procedure that has access to a class instance that defines or inherits the event

Any piece of code can subscribe a handler to a PUBLIC static event. The default access mode is PUBLIC.

When declaring an interface event prototype, the access mode for the event must be PUBLIC (the default).

When defining an abstract event, the access mode for the event cannot be PRIVATE.

If this event is defined with the OVERRIDE option, the access mode cannot be more restrictive than the access mode defined for the overridden abstract ABL or .NET class event. ABL access modes correspond to the access levels of inherited .NET abstract events (in C#) as follows:

PROTECTED matches either the .NET protected or protected internal access level.

PUBLIC matches the .NET public access level.

[ STATIC ]

Defines an event that is a static member of the class type for which it is defined and that is scoped to the ABL session where it is referenced. ABL creates one copy of the specified class static event on first reference to the class type, and ABL creates only one such copy for any number of instances of the class that you create. You can subscribe a handler for an accessible static event in any piece of code. You can publish a static event only in an instance or static method that is defined within the same class definition where the static event is defined.

Without this option, ABL defines an instance event that is scoped to a single instance of the class where it is defined. ABL creates one copy of the specified instance event for each such class instance that you create. You can subscribe a handler for any public instance event (abstract or non-abstract) in any procedure, or in any instance or static method defined inside or outside of the class where the instance event is defined. Any static method can publish the public instance event only using an object reference to a class instance that defines the event as a member. If the referencing static method is defined in the same class as the public instance event, the class must instantiate itself in order to have access to an instance reference.

You can subscribe a handler for a private or protected instance event only in instance methods that are defined inside the same class or class hierarchy.

You can publish a non-abstract instance event only in a method that is defined within the same class definition where the instance event is defined. If the method is static, the instance event must also be public and you can only publish it using an object reference to an instance of the class. An instance method defined in the same class can also publish a public instance event using an object reference to an instance of the class.

Note: You cannot use a class instance that is not equal to the THIS-OBJECT system reference to subscribe a handler for a private or protected instance event, or to publish a private or protected instance event that is defined in the same class, because PRIVATE and PROTECTED access modes are instance based in ABL. Thus, private and protected instance members are accessible only to other members of the same class instance, where as public instance members can be accessed from other instances of the same class, including the session “static instance” of the class.

For more information on the mechanism for subscribing handlers to static and instance class events, see the Subscribe( ) event method reference entry. Note that the same constraints on subscribing handlers for static and instance class events applies to unsubscribing the handlers. For more information, see the Unsubscribe( ) event method. For more information on the mechanism for publishing instance and static class events, see the Publish( ) event method reference entry.

The STATIC option is not valid when you:

Define or implement an abstract event

Declare an interface event prototype

Implement an interface event

[ ABSTRACT ]

Defines the event as an abstract instance member of the class type for which it is defined. The defining class type must also be abstract. If you define an abstract event, it has the following requirements:

You must specify the OVERRIDE option if an inherited abstract event has the same name and signature.

Note: Class events cannot be overloaded. If you want to define an event with a different signature, it must also have a different name than any other event inherited by or defined in the same class.

You can specify either a PROTECTED or a PUBLIC access mode, depending on any inherited abstract event you might be overriding.

The abstract event must be overridden and implemented in a derived class.

Any class definition for an instance event that includes the OVERRIDE option and does not include the ABSTRACT option defines an event implementation. If it also includes the ABSTRACT option, the inherited abstract event remains abstract.

Note: You cannot publish an event that is defined as ABSTRACT.

This option is not valid either when you define a static event or when you declare an interface event prototype.

[ OVERRIDE ]

Specifies that this instance event overrides an abstract event inherited from an ABL or .NET class.

Note: A .NET abstract event or class is defined in C# with the abstract keyword.

When you specify OVERRIDE, event-name must be identical to the name of the overridden abstract event, and signature-spec must specify a signature that is identical to the signature defined for the overridden event. In addition, the access mode must not be more restrictive than the access mode defined for the overridden event. When overriding a .NET event, the signature-spec must specify the same delegate that is defined for the .NET event. For more information, see the description of the signature-spec option.

If you specify the ABSTRACT option, your overriding event is also defined as abstract, and it must be implemented in a class derived from the defining class. Note that you do not have to override an inherited abstract event that you want to remain abstract as long as the inheriting class is also abstract. However, doing so allows you to specify a less restrictive access mode for the abstract event.

If you do not specify the ABSTRACT option, your overriding event implements the inherited abstract event.

This option is not valid:

When you define a static event

When you declare an interface event prototype

To override an inherited event that is implemented (not abstract)

EVENT event-name

Specifies the event name. This event name must be unique among all events, properties, and variable data members defined in the class hierarchy of the defining class, unless you specify the OVERRIDE option to override an inherited abstract event.

Note: Members of a class are grouped into six namespaces, including buffers/temp-tables, methods, variables/properties/events, ProDataSets, queries, and data-sources. Variables, properties, and events defined as members of a class share the same namespace. There can be only one class member in this namespace with a given name (not counting abstract member overrides).

signature-spec

Specifies the signature for the Publish( ) event method and for any class method or internal procedure that executes as a handler when the event is published. You can define this signature using one of the two options in the following syntax:

Syntax
{ [ SIGNATURE ] VOID ( [ `parameter` [ , `parameter` ] ... ] ) \| [ DELEGATE ] [ CLASS ] `dotNet-delegate-type` }

[ SIGNATURE ] VOID ( [ parameter [ , parameter ] ... ] )

Defines an ABL method signature for the event, including the return value and zero or more parameters. The return value is always VOID. No associated internal procedure or method event handler can return a value. The SIGNATURE keyword is optional for readability.

If this event implements an ABL interface event or overrides an inherited ABL abstract event (using the OVERRIDE option), the interface or inherited abstract event must also be defined with an ABL method signature that matches this signature. If the ABL interface or inherited ABL abstract event is defined with a .NET signature (dotNet-delegate-type), you must use the .NET signature option to define this event instead.

For more information on the syntax of parameter and on matching parameters to implement or override ABL class events, see the Parameter definition syntax reference entry.

[ DELEGATE ] [ CLASS ] dotNet-delegate-type

Defines a .NET signature for the event as specified by a .NET delegate type (dotNet-delegate-type), for example, System.EventHandler. You can specify the delegate class name without a namespace (for example, EventHandler) with the presence of an appropriate USING statement. The DELEGATE or CLASS keyword is optional for readability. However the CLASS keyword, only, also disambiguates a delegate type name that might be identical to an ABL primitive type name. Note that ABL only supports .NET delegate types that conform to the .NET Framework convention for event handlers. This convention defines an event handler signature with a VOID return type and two input parameters, where the first parameter is a System.Object and the second parameter is a System.EventArgs or a .NET class derived from System.EventArgs. The .NET delegate type can also be a constructed generic type. For more information on .NET generic types, see the Data types reference entry.

You must use this option to define the ABL class event signature if the ABL event implements a .NET interface event or overrides an inherited .NET abstract event (using the OVERRIDE option). Also, the dotNet-delegate-type for the ABL event must be identical to the .NET delegate type used to define the .NET interface or abstract event.

You can use this option to define the signature for an ABL class event even if the event does not implement or override a .NET event. However, if this event implements an ABL interface event or overrides (using the OVERRIDE option) an inherited ABL abstract event that is, itself, defined with a .NET delegate, you must also define the signature for this event using an identical dotNet-delegate-type.

Note that you can identify the data types of .NET event parameters by looking up the delegate type defined for the event in the appropriate .NET event documentation.

Examples

The following sample class and procedure files define, publish, subscribe an event handler to, and unsubscribe an event handler from an ABL class event. The r-EventPublish sample class defines the public NewCustomer event and a PubNewCustomer( ) method to publish it.

r-EventPublish.cls
CLASS r-EventPublish: /* Define an event / `DEFINE PUBLIC EVENT NewCustomer` `SIGNATURE VOID ( INPUT pcCustName AS CHARACTER ).` / Code that publishes the event. */ `METHOD PUBLIC VOID PubNewCustomer( ):` DEFINE VARIABLE cCustName AS CHARACTER INITIAL "A Customer Name" NO-UNDO. `NewCustomer:Publish( INPUT cCustName ) NO-ERROR.` `END METHOD.` END CLASS.

CLASS r-EventPublish:  
   
  /* Define an event */ 
  DEFINE PUBLIC EVENT NewCustomer  
    SIGNATURE VOID ( INPUT pcCustName AS CHARACTER ). 
       
  /* Code that publishes the event. */ 
  METHOD PUBLIC VOID PubNewCustomer( ): 
     
    DEFINE VARIABLE cCustName AS CHARACTER INITIAL "A Customer Name" NO-UNDO. 
                     
    NewCustomer:Publish( INPUT cCustName ) NO-ERROR. 
     
  END METHOD.  
END CLASS.

The r-EventSubscribe sample class defines and subscribes a NewCustomer( ) method as a handler for the event when it is instantiated, based on the object reference to the r-EventPublish class that is passed to the constructor. Note that the event handler also unsubscribes itself to the event after it executes.

r-EventSubscribe.cls
CLASS r-EventSubscribe: DEFINE VARIABLE rPubObj AS CLASS r-EventPublish NO-UNDO. CONSTRUCTOR PUBLIC r-EventSubscribe ( INPUT prPubObj AS CLASS r-EventPublish): ASSIGN rPubObj = prPubObj. `rPubObj:NewCustomer:Subscribe( NewCustomer_Handler ) NO-ERROR.` END CONSTRUCTOR. /* Method used as event handler */ `METHOD PUBLIC VOID NewCustomer_Handler ( INPUT pcCustName AS CHARACTER ):` MESSAGE "Subscriber received event NewCustomer" SKIP "CustName =" pcCustName VIEW-AS ALERT-BOX. `rPubObj:NewCustomer:Unsubscribe( NewCustomer_Handler ) NO-ERROR.` `END METHOD.` END CLASS.

CLASS r-EventSubscribe: 
   
  DEFINE VARIABLE rPubObj AS CLASS r-EventPublish NO-UNDO. 
     
  CONSTRUCTOR PUBLIC r-EventSubscribe  
    ( INPUT prPubObj AS CLASS r-EventPublish):  
        
    ASSIGN rPubObj = prPubObj. 
    rPubObj:NewCustomer:Subscribe( NewCustomer_Handler ) NO-ERROR. 
     
  END CONSTRUCTOR. 
  /* Method used as event handler */ 
  METHOD PUBLIC VOID NewCustomer_Handler ( INPUT pcCustName AS CHARACTER ): 
     
    MESSAGE "Subscriber received event NewCustomer" SKIP 
            "CustName =" pcCustName VIEW-AS ALERT-BOX. 
    rPubObj:NewCustomer:Unsubscribe( NewCustomer_Handler ) NO-ERROR. 
  END METHOD.  
END CLASS.

The r-EventPubSub.p sample procedure instantiates these classes. The procedure then displays a frame that includes a bNewCust button that when clicked runs an internal procedure, which in turn invokes the PubNewCustomer( ) method on the r-EventPublish object to publish the event. This demonstrates how the class defining an event can allow a client class or procedure to publish it by providing a public method for the purpose. Note that any subsequent attempt to click the button does not run the event handler, because the handler has unsubscribed itself.

r-EventPubSub.p
DEFINE VARIABLE rPubObj AS CLASS r-EventPublish NO-UNDO. DEFINE VARIABLE rSubObj AS CLASS r-EventSubScribe NO-UNDO. DEFINE `BUTTON` `bNewCust` LABEL "New Customer". DEFINE BUTTON bQuit LABEL "Quit". FORM bNewCust bQuit WITH FRAME aFrame. `ON CHOOSE OF bNewCust RUN CallNewCust NO-ERROR.` `rPubObj = NEW r-EventPublish( ).` `rSubObj = NEW r-EventSubScribe( rPubObj ).` ENABLE ALL WITH FRAME aFrame. WAIT-FOR CHOOSE OF bQuit OR WINDOW-CLOSE OF CURRENT-WINDOW. PROCEDURE CallNewCust: /* Call to publish */ `rPubObj:PubNewCustomer( ) NO-ERROR.` END PROCEDURE.

DEFINE VARIABLE rPubObj AS CLASS r-EventPublish NO-UNDO. 
DEFINE VARIABLE rSubObj AS CLASS r-EventSubScribe NO-UNDO. 
DEFINE BUTTON bNewCust LABEL "New Customer". 
DEFINE BUTTON bQuit    LABEL "Quit". 
FORM bNewCust bQuit WITH FRAME aFrame. 
ON CHOOSE OF bNewCust RUN CallNewCust NO-ERROR. 
rPubObj = NEW r-EventPublish( ). 
rSubObj = NEW r-EventSubScribe( rPubObj ). 
ENABLE ALL WITH FRAME aFrame. 
WAIT-FOR CHOOSE OF bQuit OR WINDOW-CLOSE OF CURRENT-WINDOW. 
PROCEDURE CallNewCust: 
   
  /* Call to publish */ 
  rPubObj:PubNewCustomer( ) NO-ERROR. 
END PROCEDURE.

For more examples of class event definitions, including static and abstract events, see the descriptions of r-CustObj.cls, r-CustObjStatic.cls, and r-CustObjAbstract.cls in the CLASS statement reference entry.

Notes

For information on using class event handlers and the built-in event methods, including Publish( ), Subscribe( ), and Unsubscribe( ), and on .NET see the "Class Events Reference" section.

If you define an ABL event using a .NET delegate, .NET can only subscribe to this event if its definition implements or overrides an event defined in a .NET interface or abstract class.