= Raise = 

Raises an event which will directly notify any [wiki:Listen 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 [wiki:Delegate 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 [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 ==

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 ==

 * [wiki:Listen]
 * [wiki:Ignore]
 * [wiki:AllStatements]
 * [wiki:LanguageTopics]