[Dev] CPIA Events now return results

[Donn Denman]

John and I reconciled our different approaches to return values on  
CPIA events, and we now have the best of both:
* The API is essentially unchanged (see below for minor differences)
* Internally the results are propagated as before, using the  
event.arguments dictionary
    - event dispatching is simpler and probably faster than the way I  
was doing it

Details
-------
* Reconciled my changes from rev 6385 with John's previous  
implementation
* The return value from post() is now simply the result returned by  
the handler
    (no more True/False to tell you if a handler was executed or not)
* If the event was broadcast, the result is what the last handler  
returned
* If no handler executed, you get back None (as one would expect)
* Event handlers that want to continue a bubble up dispatch do so  
differently:
    - this had been done by the handler returning False
    - now this is done using event.arguments['continueBubbleUp'] = True
    - this is rare -- only four handlers do this
    - most handlers just return a value if it's appropriate, or don't  
return anything

- Donn

On Aug 7, 2005, at 6:48 PM, John Anderson wrote:

> Hi Donn:
>
> Maybe we can talk tomorrow morning. Currently it looks like only  
> SendToBlockByReference and SendToBlockByName work with your return  
> result whereas BroadcastInsideMyEventBoundary,  
> BroadcastInsideActiveViewEventBoundary, BroadcastEverywhere,  
> FocusBubbleUp, ActiveViewBubbleUp don't work or use the result for  
> something different. I'm thinking it might more sense to have the  
> return result assigned to an argument by the caller in dispatch,  
> then passed up the call chain and returned to whoever dispatched  
> the event, so it can be available to everyone, no matter how the  
> event was dispatched. Then move the continuation return result a  
> different item in arguments so as not to conflict with the return  
> result.
>
> John
>
> Donn Denman wrote:
>
>
>> John,
>>
>> I think using the return value has a lot of advantages over using  
>> event.arguments, but it does limit the return values so as to be  
>> compatible with the bubble-up dispatch continuation flag, since  
>> None, True and False have a predefined meaning in this context.   
>> Maybe a hybrid approach is best, where we use the return values in  
>> the client API but use event.arguments internally for efficiency.   
>> Lets meet soon to figure out the best way to reconcile the two  
>> approaches and then we can post an update on Dev.
>>
>> - Donn
>>
>> John Anderson wrote:
>>
>>
>>> Hi Donn:
>>>
>>> In the current design I return results from events by passing the  
>>> result back in event.arguments -- which seemed simpler than  
>>> bubbling the result back up the call chain. Also, in the current  
>>> design I use the return result of the handler to control whether  
>>> or not to continue further dispatch in the bubble up dispatch  
>>> case. It seems like your mechanism for returning results might  
>>> conflich with this design, so I thought we might want to discuss  
>>> reconciling the designs before converting more code.
>>>
>>> John
>>>
>>> Donn Denman wrote:
>>>
>>>
>>>> I just made a change to allow CPIA's event-posting mechanism to   
>>>> return results.   This feature was motivated by CPIA Script to  
>>>> allow  the commands that create new items to return the list of  
>>>> items  created.  In general, this seemed like a nice enhancement  
>>>> to CPIA,  because it allows event handlers to simply return a  
>>>> value that they  want passed back to the sender of the event.  I  
>>>> think that having a  convenient return value will be handy for  
>>>> future events that expect  replies.   I have already updated a  
>>>> lot of the event handlers in the  system to return reasonable  
>>>> results.
>>>>
>>>> POSTING EVENTS: When you call Block.post() or  
>>>> Block.postEventByName()  you will get back a meaningful  
>>>> result.   These methods return:
>>>>     * False when there was a problem with the event dispatch
>>>>     * True when there was no value passed back by the event  
>>>> handler,  or when the event was broadcast (since there is no  
>>>> single event  handler in these cases).
>>>>     * Some other result value determined by the event handler
>>>> Note: these results have already been used internally to  
>>>> determine  when bubble-up method dispatch should terminate.
>>>> Block.post() now lists the above information in ePyDoc.
>>>>
>>>> WRITING EVENT HANDLERS: When you write an event handler,  
>>>> consider if  there is a logical result to return.  Handlers that  
>>>> create new items  by convention return the list of items  
>>>> created.  Handlers that don't  want to handle the event (in  
>>>> bubble up dispatch cases) should return  False to allow the  
>>>> event dispatch to continue.  If you return None or  leave off  
>>>> the return statement all together it's considered that you  have  
>>>> handled the event (so post will return True).  The "UpdateUI"   
>>>> event handlers usually to do the latter.
>>>>
>>>> WRITING CPIA SCRIPTS: Now a lot of CPIA BlockEvent commands  
>>>> return a  result.  So you can say:
>>>> myNote = NewNote()
>>>> to capture the list of items created - in this case the list  
>>>> contains  a single Note.  Cut() and Copy() return the value(s)  
>>>> placed in the  clipboard.  All the commands that create  
>>>> Collections, including the  ones from example parcels, should  
>>>> return a list with the new  collection(s) in it.   
>>>> GenerateContentItems returns the list of items  created (and I  
>>>> changed the default to 4 -- 100 was just too much!)   In  
>>>> general, your script will get back the result from Block.post 
>>>> (),  which tells you if the event was successfully dispatched,  
>>>> or whatever  the event handler returned.
>>>>
>>>>
>>>> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>>>>
>>>> Open Source Applications Foundation "Dev" mailing list
>>>> http://lists.osafoundation.org/mailman/listinfo/dev
>>>>
>>>
>>>
>>>
>>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osafoundation.org/pipermail/chandler-dev/attachments/20050810/23f2b9b3/attachment.htm