= Raise = 

Trigger an event to fire with the specified args.

If the event is not null and  any handlers are listening (registered with) [[BR]]
the event they will be invoked after the event has been raised.

The number and types of args given in the raise statement must match those declared [[BR]]
in the sig used as the Type for the event being raised.

See also [wiki:Listen] and [wiki: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 [[BR]]
and the first arg is not '''this'''  [[BR]]
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.
{{{
#!cobra
sig NoArgEventHandler                    # no parameters
event notifyEvent as NoArgEventHandler	 # is public
...
raise .notifyEvent
}}}

== Examples ==
{{{
#!cobra
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
{{{
#!cobra

# 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
		listen g.actionEvent, ref l.doAction
}}}

No Arg event, No args passed to raise.
{{{
#!cobra
# 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
		listen g.notifyActionEvent, ref l.doNotifyAction
}}}


== Notes ==