SAS Component Language: Reference

Events and Event Handlers

Events alert applications when there is a change of state. Events occur when a user action takes place (such as a mouse click), when an attribute value is changed, or when a user-defined condition occurs. Events are essentially generic messages that are sent to objects from the system or from SCL applications. These messages usually direct an object to perform some action such as running a method.

Event handlers are methods that listen for these messages and respond to the them. Essentially, an event handler is a method that determines which method to execute after the event occurs.

SCL supports both system events and user-defined events.

System Events

System events include user interface events (such as mouse clicks) as well as "attribute changed" events that occur when an attribute value is updated. SCL automatically defines system events for component attributes when those attributes are declared.

SCL can also automatically send system events for you when a component's attribute is changed. If you want "attribute changed" events to be sent automatically, specify SendEvent='Y' in the options list for the attribute.

If you want an action to be performed when the system event occurs, then you need to define the event handler that you want to be executed when the event occurs. You define event handlers for system events in the same way that you define them for user-defined events. See Defining Event Handlers for more information.

Defining and Sending Events

You can create user-defined events through the Properties window in the Class Editor or with event declaration statements in CLASS blocks.

EVENT event-name</(event-options)>;

Event names can be up to 256 characters long.

For the event options, you can specify the name of the method that handles the event and when an object should send the event. Events can be sent automatically either before (specify Send='Before') or after (Send='After') a method executes or they can be programmed manually ('Manual') with SCL. New events default to 'After'. You must specify a method name for events that are to be sent automatically.

After an event is defined, you can use the _sendEvent method to send the event:

object._sendEvent("event-name"<, event-handler-parameters>);
For a complete description of _sendEvent, refer to the SAS/AF online Help.

Defining Event Handlers

You can define event handlers with event handler declaration statements in CLASS blocks.

EVENTHANDLER event-handler-name</(event-handler-options)>;

As part of the event handler options, you can specify the name of the event, the name of the method that handles the event, and the name of the object that generates the event (the sender). As the sender, you can specify '_SELF_' or '_ALL_'. When Sender='_SELF_', the event handler listens only to events from the class itself. When Sender='_ALL_', the event handler listens to events from any other class.

Using the _addEventHandler method, you can dynamically add a sender to trigger the event. For a complete description of _addEventHandler, refer to the SAS/AF online Help.

For more information about defining event handlers, see CLASS.

Example

The following class defines one user-defined event, myEvent, and the event handler for this event, M2. When this class is created, SCL also assigns the system event name "n Changed" for the attribute n and registers the event name with the component.

class EHclass;
  public num n;   /* system event */
  event 'myEvent' / (method='M2');
  eventhandler M1 / (sender = '_SELF_',
                     event = 'n Changed');
  eventhandler M2 / (sender = '_SELF_',
                     event = 'myEvent');
  
  M1: method a:list;
    put "Event is triggered by attribute n";
  endmethod;

  M2: method a:string n1:num n2:num;
    put "Event is triggered by _sendEvent";
    put a= n1= n2=;
  endmethod;
endclass;

When the value of the attribute n is changed, the system automatically sends the "n Changed" event, and method M1 is executed. Method M2 is not executed until myEvent is sent with the _sendEvent method.

The next class, EHclass1, defines a second event handler, M3, that is also executed when myEvent is sent.

class EHclass1;
  /* Sender='*' means that the sender */
  /* is determined at run time.       */
  eventhandler M3 / (sender = '*', event='myEvent');
  M3: method a:string n1:num n2:num;
    put "Event myEvent is defined in another class";
    put "that is triggered by _sendEvent.";
    put a= n1= n2=;
  endmethod;
endclass;

In the following program, the system event "n Changed" is triggered when the value of the n attribute is modified. The user-defined event myEvent is triggered with the _sendEvent method.

import work.a.EHclass.class;
import work.a.EHclass1.class;
init:
  dcl EHclass obj = _new_ EHclass();
  dcl EHclass1 obj1 = _new_ EHclass1();
  
  /* Trigger the system event. */
  obj.n = 3;

  /* Trigger the user-defined event. */
  obj._sendEvent("myEvent", 'abc', 3, 4);
return;

The order in which the two classes are instantiated determines the order in which the event handlers for myEvent are executed. EHclass is instantiated first, so when myEvent is sent, event handler M2 is executed first, followed by the event handler defined in EHclass1, M3.

The output from this test program is

Event is triggered by attribute n
Event is triggered by _sendEvent
a=abc n1=3 n2=4
Event myEvent is defined in another class
that is triggered by _sendEvent.
a=abc n1=3 n2=4

Event and Event Handler Metadata

Events and event handlers are implemented and maintained with metadata. This metadata exists as a list that is stored with the class. You can query a class (or an event within a class) to view the event and event handler metadata. To list the metadata for the an event, execute code similar to the following:

init:
   DCL num rc;
   DCL list metadata; 
   DCL object obj;
   
   obj=loadclass('class-name');
    
   rc=obj._getEvent('event-name',metadata);
   call putlist(metadata,'',3);
   rc=obj._getEventHandler('_self_','event-handler-name',
                            '_refresh',metadata);
   call putlist(metadata,'',3);
return;

Chapter Contents
Previous
Next
Top of Page