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
