Wiki

Raise

Raises an event which will directly notify any listeners for that event. An event can only be raised for the same class and the same instance.

The number and types of args given in the raise statement must match those declared in the sig used as the type for the event being raised with two exceptions:

  1. The sender which is always this should not be specified.
  2. The event arguments object can be left out if you are happy with a default instantiation.

This will become more clear in the examples below.

See also Listen and Ignore.

Grammar

raise <event> [ [,<source>] ,<arg> [,<arg> ...]]

In an attempt to default the most common case, if the number of arg parameters is one less than the number in the sig
and the first arg is not this
then this will be implicitly passed as the source (first arg).

If an event has been declared with a no param signature then neither <source> nor <event-args> can or need be given as args to the raise call.

sig NoArgEventHandler                    # no parameters
event notifyEvent as NoArgEventHandler   # is public
...
raise .notifyEvent

Examples

use System.Windows.Forms

...
        button = Button(parent=p, autoSize=true, text='One', tag=1)
        # connect event and handling code
        listen button.click, ref .clickHandler
        ...
        # trigger the button programatically
        raise button.click, EventArgs()
        ...
        # disconnect event and its handling code
        ignore button.click, ref .clickHandler
...
def clickHandler(source as Object, args as EventArgs)
    pass

Full example with augmented EventArg, signature and event declarations, convenience method to raise the event, event handlers/listeners


# EventArgs subclass to pass additional info in args
class BEventArgs inherits EventArgs
    var _value as int

    get value from var
    
    def init(val as int)
        base.init
        _value = val

# delegate for ActionEvent  <eventName>EventHandler
sig ActionEventHandler(sender as Object, args as EventArgs)

class Generator
    var _count = 0 
        """local state"""
    
    # event dcl for event called Action
    # event <eventName>Event as <sigName> (<eventName>EventHandler)    
    event actionEvent as ActionEventHandler

    # (protected) method to raise/fire the event for this class 
    # {on,fire}<eventName>Event
    def _onActionEvent(args as EventArgs)      # fireActionEvent
        raise .actionEvent, args

    def bump
        _count += 1 
        if _count % 20 == 0
            ev = BEventArgs(_count)
            _onActionEvent(ev)

class Listener
    # the event handler method do<eventName>
    def doAction(source as Object, args as BEventArgs)
        print 'Event from [source] - argCount is [args.count]'
            
...
class RaiseDriver
    def main is shared
        g = Generator()
        l = Listener()
        
        #tie the generator event to the Listener method
        listen g.actionEvent, ref l.doAction

        for i in 100
            g.bump    

        #untie the event and listener
        ignore g.actionEvent, ref l.doAction

No Arg event, No args passed to raise.

# delegate with no args for notifyActionEvent  <eventName>EventHandler
sig NoArgEventHandler

class Generator
    var _count = 0 
        """local state"""
    
    # event dcl for event called Action
    # event <eventName>Event as <sigName> (<eventName>EventHandler)    
    event notifyActionEvent as NoArgEventHandler

    # (protected) method to raise/fire the event for this class 
    # {on,fire}<eventName>Event
    def _onNotifyActionEvent
        raise .notifyActionEvent

    def bump
        _count += 1 
        if _count % 20 == 0, _onNotifyActionEvent

class Listener
    # the event handler method do<eventName>
    def doNotifyAction
        print 'NotifyAction Event received'
            
...
class RaiseDriver
    def main is shared
        g = Generator()
        l = Listener()
        
        #tie the generator event to the Listener method
        listen g.notifyActionEvent, ref l.doNotifyAction

        for i in 100
            g.bump    

        #untie the event and listener
        ignore g.notifyActionEvent, ref l.doNotifyAction

Notes

In C#, the programmer must first check if the event is null before invoking it. This is not necessary in Cobra where raise .someEvent ... is all that is required.

See Also