Changes between Initial Version and Version 1 of Listen

Timestamp:

05/02/10 13:37:37 (15 years ago)

Author:

hopscc

Comment:

--

Listen

@@ +1 @@
+= Listen = 
+
+Connect an event to some particular handling code by giving an event 
+handler (method reference) for a particular Event instance.[[BR]]
+When the event is raised (or fired) the method (event handler) is
+invoked with the args given to raise the event.
+
+An event is specified as a name typed to a sig (signature/delegate).[[BR]] 
+Any method given as an eventhandler/listener must conform to the same sig.
+
+For disconnecting an event from its handling code see  [wiki:Ignore].[[BR]]
+For firing an event see [wiki:Raise].
+
+== Grammar ==
+{{{
+listen <event>, <method-reference>
+}}}
+
+
+== Examples ==
+{{{
+use System.Windows.Forms
+
+...
+        button = Button(parent=p, autoSize=true, text='One', tag=1)
+        listen button.click, ref .clickHandler
+...
+def clickHandler(source as Object, args as EventArgs)
+    pass
+}}}
+
+Full example showing sig and event declaration and method to raise the event.
+{{{
+
+# delegate for ActionEvent  <eventName>EventHandler
+sig ActionEventHandler(sender as Object, args as EventArgs)
+
+class Generator
+        # event declaration for an 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
+
+class Listener
+        # the event handler method do<eventName>
+        def doAction(source as Object, args as EventArgs)
+                print 'Event received from [source]'
+
+...
+        def driver
+                g = Generator()
+                l = Listener()
+                
+                #tie the generator event to the Listener method
+                listen g.actionEvent, ref l.doAction
+}}}
+
+{{{
+# Todo example using closure/anonymous method
+}}}
+
+== Notes ==
+
+The event handler method must be a reference to a method not a 
+method invocation.[[BR]]
+In practice this means that most listen statements will have their second
+argument as a method name prefixed with '''ref'''.