All,
I've added some new (or better) functionality to the way OLEObject
handles event connections. I'm looking for any feedback on method
names, critiques, or really any comment any one has.
To first give this some context: COM has the concept of connectable
objects. This is a way for a COM object to notify a client of events.
We've always supported this in OLEObject, to a degree. But, it was
only possible to connect events when the user directly created an
OLEObject using a class ID or program ID. To recieve the events the
user had to subclass OLEObject and in the subclass provide the the
event methods.
This works okay for some instances, like a Word.Application object.
But, when you start writing real applications using OLEObject, you
soon hit the problem that most OLEObjects are created indirectly and
there is no way to connect events with those object, even though many
of them support events. Take this example:
wordApp = .OLEObject~new("Word.Application")
document = wordApp~documents~Add
Now, the Document object supports events, but there was no way in
ooRexx to take advantage of that, because there is no way for the
programmer to directly create a Document object. The Document object
can only be created by one of the Word COM objects.
This has always bugged me, so I have now fixed this. Plus, the
connectable object architecture in COM is designed around the idea of
being able to connect and disconnect from the connectable object.
There used to be no way to do this in OLEObject.
With the following extensions, the programmer can connect or
disconnect the OLEObject at any point in the object's life cycle.
Plus, this works with objects created indirectly like the Document
object above.
These new methods are added to OLEObject to support this functionality:
connectEvents
isConnectable
isConnected
disconnectEvents
addEventMethod(methodName, methodObj)
removeEventMethod(methodName)
removeEventHandler
getKnownEvents() is now enhanced.
connectEvents()
===============
Used to tell the OLEObject to make the event connection. This can be
done at any time in the life cycle of an OLEObject object. Prior to
this, event connections could *only* be done at the time of object
instantiation.
Returns true if no errors are detected, and false if errors prevent the
connection from being made.
isConnectable()
===============
Used to determine if the OLEObject object supports connections, or not.
If connections are not supported, trying to connect event methods will
not succeed.
Returns true or false.
isConnected()
=============
Used to determine if the OLEObject object is currently connected, if
it is currently set up to receive event notifications.
Returns true or false.
disconnectEvents()
==================
Used to tell the OLEObject to drop the event connection. Likewise, this
can be done at any time in the life cycle of an OLEObject object. Prior
to this, event connections could never be dropped.
Returns true if no errors are detected, and false if errors prevent the
connection from being dropped.
addEventMethod()
================
used to add an event method to an existing OLEObject.
removeEventMethod()
===================
used to remove an event method that was previously added to an existing
OLEObject.
removeEventHandler()
====================
disconnects (if connected) the OLEObject from event notifications and
also destroys the underlying object that takes care of receiving event
notifications and routing the notifications to the ooRexx object (the
OLEObject.) After this handler is destroyed, connectEvents() and
getKnownEvents() will still work. They will then first recreate an
event handler and then proceed as normal.
Returns true if no errors are detected, and false if errors are
detected.
getKnownEvents()
================
This existing method is now enhanced to always return the event methods
for a connectable object. Prior to this, only OLEObjects created
directly, and created with the 'event' flag (WITHEVENTS or NOEVENTS)
would return any known events. This little known fact was never really
documented correctly. So, if the user did not create the OLEObject
correctly, .nil would be returned for objects that actually would
support event connections.
--
Mark Miesfeld
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Oorexx-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
