[Dev] CPIA Events now return results

[Donn Denman]

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.