[Wnd-commit] wnd/wnd_doc/doc/api/ole/dataobject dataobject.dtpl,NONE,1.1

[jürgen u. <cer...@us...>]

Update of /cvsroot/wnd/wnd/wnd_doc/doc/api/ole/dataobject
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11778

Added Files:
	dataobject.dtpl 
Log Message:
bit of this and a bit of that

--- NEW FILE: dataobject.dtpl ---

::site:: DataObject
	
	<code class=import>defined in: wnd.api.ole.dataobject</code><br><br>
	<code>DataObjec(*formats, **kwargs)</code><br>

	<br><br>

	DataObject is a python inplementation of the IDataObject interface.
	DataObject are used mainly in clipboard and drag-and-drop 
	related operations to share data cross process boundaries.
	<br><br>
	For example a clipboard for operation is done roughly like this:
	<OL>
		<LI>create a data object, feed it with one ore more data descriptors, 
			providing access to one ore more aspects of the data you provide.
		<LI>place the data object on the clipboard, where it will remain 
			untill either someother object is taking your data objects place on the
			clipboard, or the clipboard is cleared, or you pass ownership of the
			data to the clipboard
		<LI>if someone wants to get some of the data you placed on the clipboard,
			he will ask your data object if it provides data of a certain type and
			if so request a copy of it.
	</OL>
	<br>
	The key to this way of sharing data are the format descriptors.
	Each format you provide should either match a predefined
	clipboard format or should be a format you registered on the fly.
	The system has quite a few predefined formats for example
	strings come in shapes of CF_TEXT, CF_UNICODETEXT, other
	formats cover gdi handles , riff's tiff's wav's and god knows what else.
	<br><br>
	I'm not planning to go into details here. The framework provides
	wrapper classes managing the packing and unpacking of the data. You
	simply pass the data to the data object, letting ole and python do their thing,
	while you have the hands free to do another. These format wrappers are not
	intended to be imported directly. This module provides the same stub classs
	<b>cf</b> (sorry no link yet) to handle the import from the clipformats library
	module.
	<br><br>
	This implementation of the DataObject currently can only handle
	mediums of type TYMED_HGLOBAL, streams, storages and gdi objects
	are yet to come.
	
	
	<br><br>
	You use this class if you want to implement your own data object wich can
	be called by any language capable of interfacing with ole objects. 
	<br><br>

	To setup a DataObject you should feed it with one or more formats.
	<br><br>
	<b>**kwords</b><br>
	the only keyword recognised currently is <b>allowset</b>, wich should be
	a list of formats any consumer is allowed to set to or change in the
	DataObject.


<pre>
cf.text('my text here')
do= DataObject(text, allowset= (text, ))
</pre>

This sets up a Dataobject containing text, and allowing any consumer to 
alter the text conained.


<pre>
cf.text('my text here')
cf.unicodetext(u'my text here')
do= DataObject(text, unicodetext,  allowset= (cf.oemtext, ))
</pre>

This sets up a Dataobject containing text and unicodetext, and allowing any
consumer to add oemtext to the object.


::site:: DataObjectFromPointer
	
	<code class=import>defined in: wnd.api.ole.dataobject</code><br><br>
	<code>DataObjecFromPointer(pDataObject)</code><br>
	<P>This class creates a DataObjectPointer you can pass to any api
		querying a pointer to a DtataObject. 
	<br><br>
	You use this class if to wrap DataObject methods around a DataObject pointer
	<br><br>
	
	In difference to a <a HREF="DataObject.html">DataObject</a> you set up as 
	a data provider this class does not define the 
	<a HREF="DataObject methods.Close.html">Close</a>.
	<br><br>
	As an additional method the __nonzero__ method is defined, to let you check
	if the underlaying IDataObject pointer is alive.
	
	<br><br>
	


::site:: DataObjectPointer
	
	<code class=import>defined in: wnd.api.ole.dataobject</code><br><br>
	<code>DataObjecPointer()</code><br>
	<P>This class creates a DataObjectPointer you can pass to any api
		querying a pointer to a DtataObject. 
	<br><br>
	You use this class if you want to want to retrieve a DataObject interface.
	The instance will define two attributes 'refiid' and 'ptr' you may find usefull
	to pass along to an interface retrieving method.
	Here is a non real world example to demonstrate:
	<br><br>

<pre>	
do = DataObjectPointer()
print not do
\# >> True
SomeInterfaceRetrievingMethod(do.refiid, do.ptr)

\# ...instead of the more lengthy
\# dataobj= POINTER(IDataObject)
\# SomeInterfaceRetrievingMethod(REFIID(IDataObject._iid_), byref(dataobj))
\# dataobj= DataObjectFromPointer(dataobj)

if do:
	print "sucessfully retrieved the interface"
else:
	print "something went wrong, interface could not be retrieved"

</pre>	

	<br><br>
	
	In difference to a <a HREF="DataObject.html">DataObject</a> you set up as 
	a data provider this class does not define the 
	<a HREF="DataObject methods.Close.html">Close</a>.
	<br><br>
	As an additional method the __nonzero__ method is defined, to let you check
	if the underlaying IDataObject pointer is alive.
	
	<br><br>
	
	
	</p>





::folder:: DataObject methods
	DataObject instances support the following (python) methods:

	

	::item:: GetComPointer
		<code>GetComPointer()</code><br>	
		<P>Returns the com pointer of the Dataobject as parameter you can pass
		directly to any api expecting a ppIDtataObject as parameter
		</P>

	::item:: GetData
		<code>GetData(format)</code><br>	
		<P>Retrieves data of the specified format from the dataObject.
		<br><br>
		<b>Return value</b><br>
		True if succesfull, False otherwise
		</P>

	::item:: HasFormat
		<code>HasFormat(self, format)</code><br>	
		<P>Returns True if the DataObject contains data of the specified format,
		False otherwise
		</P>

	::item:: CanSet
		<code>CanSet(format)</code><br>	
		<P>Returns true if data of the specified format can be set to the
		dataqObject, False otherwise
		</P>

		::item:: SetData
		<code>SetData(format, release=True)</code><br>	
		<P>Setsdata of the specified format to the DataObject
		<br><br>
		The release flag instructs the DataObject how to handle the data.
		If release is True, the DataObject assumes that is should take over
		emidiate ownership of the data, taking care of freeing it. In this case
		you should not free the data anyhow. If release is False the DataObject
		copies the data to take ownership of a unique copy of the data.
		In this case freeing the data is up to you.
		
		<br><br>
		<b>Return value</b><br>
		True if succesfull, False otherwise
		</P>

		::item:: Close
		<code>Close()</code><br>	
		<P>Closes the DataObject. 
		<br><br>
		All data associates to the DataObject is freed in this call

		</P>

		::item:: ListFormats
		<code>ListFormats(self, get=True)</code><br>	
		<P>Returns a list of all formats the Dataobject contains.
			<br><br>
			The formats returned have no data assigned to them.
			Use <a HREF="GetData.html">GetData</a> to actually retrieve
			data from the Dataobject
			<br><br>
			If get is True all formats that can be retrieved from the DataObject
			are returned, if False all formats that can be set are returned.

		</P>