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

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

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

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

--- NEW FILE: clipboard.dtpl ---



::site:: clipboard
	
	this module contains several clipboard related functions and datatypes
	<br>

	<code class=import>defined in: wnd.api</code><br><br>
	<br><br>


Sample code. Set/Get clipboard the ole way. The data will be set to the clipboard,
provifing three different aspects of a string: plain text, unicode text and oem text.
This gives any application the oportuenty to retrieve the data in the format
suiting its needs best.


<pre>
from wnd.api import clipboard

\# set the text you want to have on the clipboard to the wrappers
\# and use them to init a DataObject
myText= 'abcdefg'
text= clipboard.cf.text(myText)
utext= clipboard.cf.unicodetext(unicode(myText))
otext= clipboard.cf.oemtext(myText)
do= clipboard.DataObject(text, utext, otext)
clipboard.SetDataObject(do)

\# to check if it worked, print the formats now available on the clipboard
for i in ListFormats():
	print i
\#>> &lt;wnd.cf.null at 10f4fd0 {format=text} {aspect=content} {tymed=hglobal}&gt;
\#>> &lt;wnd.cf.null at 10fa090 {format=unicodetext} {aspect=content} {tymed=hglobal}&gt
\#>> &lt;wnd.cf.null at 10fa0d0 {format=oemtext} {aspect=content} {tymed=hglobal}&gt	

clipboard.Flush()
do.Close()


\# retrieve thei data from clipboard again
do= clipboard.GetDataObject()
if do:
	if do.HasFormat(text):
		if do.GetData(text):
			print text.value
			text.Close()
	if do.HasFormat(utext):
		if do.GetData(utext):
			print untext.value
			utext.Close()
	if do.HasFormat(otext):
		if do.GetData(otext):
			print ontext.value
			otext.Close()

	\#>> abcdefg
	\#>> u'abcdefg'
	\#>> abcdefg

</pre>

<br><br>
The required DataObject (and DataObjectFromPointer) are imported
by the clipboard module <code class="import">from wnd.api.ole.dataobject</code> and are intended too be used from this module.



::folder:: clipboard functions
	the clipboard module defines the following functions

	
	::item:: GetDataObject
		<code>GetDataObject()</code><br>	
		<P>Returns a pointer to the data object that is currently on the clipboard
		<br><br>
		<b>Return value</b><br>
		a DataObjectFromPointer instance
		
		</P>
	
	::item:: SetDataObject
		<code>SetDataObject(dataobject)</code><br>	
		<P>Sets the data object to the clipboard
		</P>
	
	::item:: Clear
		<code>Clear()</code><br>	
		<P>Empties the clipboard
		<br><br>
		<b>Return value</b><br>
		True if successfull, False otherwise
		</P>
	
	::item:: IsFormatAvailable
		<code>IsFormatAvailable(format)</code><br>	
		<P>returns True if the format is available on the clipboard, False otherwise.
		<br><br>
		format can be a format class or a format instance
		<br><br>
		See 
		<a HREF="../clipboard format wrappers/contents.html">clipboard format wrappers</a>
		for dtails
		</P>
	
	::item:: Flush
		<code>Flush()</code><br>	
		<P>Flushes the contents of a data object to the clipboard.  
		<br><br>
		When you set a DataObject to the clipboard, its contents are not 
		rendered unless calling Flush. After caling Flush the clipboard has
		taken over ownership of the data of the DataObject. As long as
		Flush is not called all changes in the dataObject are reflected
		directly by the dataObject.
	

<pre>
MyFormat= text('blah here')
do= DataObject(MyFormat)
SetDataObject(do)

MyFormat.value= None

do2= GetDataObject()
format= do2.GetData(MyFormat)
print myFormat.value
\#>> None

</pre>


<pre>
MyFormat= text('blah here')
do= DataObject(MyFormat)
SetDataObject(do)

Flush()
MyFormat.value= None

do2= GetDataObject()
format= do2.GetData(MyFormat)
print myFormat.value
\#>> 'blah here'

</pre>


		<b>Return value</b><br>
		True if successfull, False otherwise
		</P>
	
	
	::item:: GetFormatName
		<code>GetFormatName(format)</code><br>	
		<P>returns the name of a (registered) format or None
		<br><br>
		See 
		<a HREF="../clipboard format wrappers/contents.html">clipboard format wrappers</a>
		for dtails
		</P>
	
	::item:: GetFrameworkName
		<code>GetFrameworkName(format)</code><br>	
		<P>returns the framework name of a format wich may or may not differ from
		the name returned by <a HREF="GetFormatName.html">GetFormatName</a>
		<br><br>
		If no name could be found return value is None
		</P>

	::item:: GetFormatNameN
		<code>GetFormatNameN(nFormat)</code><br>	
		<P>same as <a HREF="GetFormatName.html">GetFormatName</a>, but
		format should be an integer value
		</P>

	
	::item:: GetFrameworkNameN
		<code>GetFrameworkName(nFormat)</code><br>	
		<P>same as <a HREF="GetFrameworkName.html">GetFrameworkName</a>, but
		format should be an integer value
		</P>
		
	
	::item:: RegisterClipboardFormat
		<code>RegisterClipboardFormat(name)</code><br>	
		<P>Registers a clipboard format by name.
		<br><br>
		Subsequent registeing of the same name will allways return the same value, throughout
		the system.
		<br><br>
		<b>Return value</b><br>
		An integer representing the clipboard format
		</P>

	
	::item:: cf
		<code>cf</code><br>	
		<P>Stub class, returning a format wrapper class to handle the specified clipboard format
		<br><br>
				
<pre>
text= cf.text
html= cf.htmlraw('html here')
</pre>
	</P>



::folder:: clipboard datatypes
	the clipboard module defines the following datatypes

	::item:: FORMATETC
		<code>FORMATETC</code><br>	
		<P>the FORMATETC structure used to as format descriptor 
		</P>

	::item:: STGMEDIUM
		<code>STGMEDIUM</code><br>	
		<P>the STGMEDIUM structure used to store data for a format  
		</P>



::folder:: clipboard format wrappers
	<b>Note</b><br>
	All these wrappers are not heavily tested, so handle with care and report any bugs.
	<br><br>
	
	
	The clipboard uses wrapper classes to handle clipboard data.
	<br><br>
	The classes should know how to pack a certain data type, so that it can be handled
	by ole, and how to unpack it that it can be easily retrieved by a user.
	<br><br>
	All wrapper classes define an attribute 'value', wich is used to set and get the data
	contained in the wrapper class. If no data is available 'value' will always be None.
	<br><br>
	These classes are not defined in this module, they are imported at runtime.
	Use the <a HREF="../clipboard functions/cf.html">cf</a>
	function to import the desired format.
	<br><br>

	All wrapper classes define the following attributes and methods:
		
	<DL>
		<DT>value	(attribute)
		<DD>used to get or set data from the underlaying global memory handle in the STGMEDIUM. You can set value to None to clear the value and free
			memory handle, just the same as calling <b>Close</b> 
		<br><br>
		
		<DT>fmt	(attribute)
		<DD>the format descriptor of the format (ctypes.structure FORMATETC)
		<br><br>

		<DT>stg	(attribute)
		<DD>the storage medium of the format (ctypes.structure STGMEDIUM)
		<br><br>

		<DT>Close() 	(method)
		<DD>closes the format. This should free any memory allocated by for the storage of data
		<br><br>

		<DT>AsParam() 	(method)
		<DD>returns a tuple(pointer(fmt), pointer(stg)) you can pass to a method expecting
				pointers to the underlaying FORMATETC and FORMATETC structures of
				the format
		<br><br>

		<DT>__eq__()		(method)
		<DD>compares the format to another
	</DL>
	

<br><br>
each format can be compared for equality to any other format on the class or on the instance. 
<pre>
text= cf.text()
print text==text==cf.text
>> True
</pre>

	
	<br><br>
	The following wrapper classes are currently avaiable to set or retrive clipboard data
	or to be used in drag and drop operations:
	<br><br>
	
	
		::item:: null
		<code>null( fmt=None, stg=None)</code><br>	
		<P>wrapper for an empty format. 
			<br><br>
			This wrapper contains no valid clipboard format.
			You can use it for example to retrieve data in an unknown format, by adjusting
			its fmt and stg attribures as required. getattr(value) will always return 
			the hMem attribute of the stg structure. If you want you can pass custom
			FORMATETC and STGMEDIUM structures. If not, default onse are used
			with clipboard format set to 0
		</P>
	
	::item:: text
		<code>text(text=None)</code><br>	
		<P>wrapper for plain ANSI text format (CF_TEXT)
		</P>

	::item:: unicodetext
		<code>unicodetext(text=None)</code><br>	
		<P>wrapper for unicode text format
		</P>

	::item:: oemtext
		<code>oemtext(text=None)</code><br>	
		<P>wrapper for oem text format
		</P>
	
	::item:: htmlraw
		<code>htmlraw(html=None)</code><br>	
		<P>wrapper for html Format.
		<br><br>
		This wrapper handles setting and retrieving  Html Format as raw text string
		</P>

	::item:: filename
		<code>filename(path=None)</code><br>	
		<P>wrapper for filename format ("FileName").
		<br><br>
		Format to place and retrieve a file path from/to clipboard. path should be an absolute filepath
		</P>
	
	::item:: hdropfiles
		<code>hdropfiles(paths=None)</code><br>	
		<P>wrapper for hdrop format (CF_HDROP). 
		<br><br>
		Use this to place a list of files on the clipboard. paths should be a list or tuple
		of (ANSI) file paths
		
	::item:: hdropex
		<code>hdropex(dropdata=None)</code><br>	
		<P>extended wrapper for hdrop format (CF_HDROP). 
		<br><br>
		Same format as <a HREF"HDROP.html">hdrop</a>,
		but setting and retrieving	the complete data used by this format.
		<br><br>
		dropdata should be a tuple(x, y, fClientarea, fUnicode, (paths, )) containing
		the data of the drop
		
		<DL>
			<DT>x
			<DD>x-position where the drop took place (screen coordinates)
			<br><br>

			<DT>y
			<DD>y-position where the drop took place (screen coordinates)
			<br><br>

			<DT>fClientarea
			<DD>True if the drop took place in the client area of the window, False
					otherwise. (not like in the windows api the other way round)
			<br><br>

			<DT>fUnicode
			<DD>True if the filepaths are in unicode format, False otherwise
			<br><br>
			
			<DT>(paths, )
			<DD>the list or tuple of filepaths dropped
			<br><br>
		</DL>
		</P>
	
	::item:: filenamemap
		<code>filenamemap(paths=None)</code><br>	
		<P>wrapper for filemap format ("FileNameMap"). 
		<br><br>
		Use this to place a list of files on the clipboard. paths should be a list or tuple
		of (ANSI) file paths
		
	::item:: dropeffect_prefered
		<code>dropeffect_prefered(value)</code><br>	
		<P>wrapper for dropeffect_prefered format ("Preferred DropEffect"). 
		<br><br>
		
		Use this to place a information regarding the prefered drop effect of
		your drop source. value should be one or a
		combination of the following constants:
		<br><br>	
		DROPEFFECT_COPY	 = 1<br>
		DROPEFFECT_MOVE	= 2<br>
		DROPEFFECT_LINK	= 4<br>
		</P>
		
	::item:: dropeffect_performed
		<code>dropeffect_performed(value=None)</code><br>	
		<P>wrapper for dropeffect_performed format ("Performed DropEffect"). 
		<br><br>
		
		Use this to place a information regarding the actually performed drop effect of your drop target. value should be one or a
		combination of the following constants:
		<br><br>	
		DROPEFFECT_COPY	 = 1<br>
		DROPEFFECT_MOVE	= 2<br>
		DROPEFFECT_LINK	= 4<br>
		</P>		



	::item:: idlistarray
		<code>idlistarray(pIdls=None)</code><br>	
		<P>wrapper for idlarray format ("shell idlist array"). 
		<br><br>
		Use this to place or retrieve pIdls from the clipboard.
		<br><br>
		pIdls should be a list of pIdls,where the first item in the list has to be
		the absolute pIdl of the parent folder, followed by the relative pIdls of
		items in that folder

Some sample code might help here
<br><br>
<pre>
from wnd.api.shell import clipboard
from wnd.api import shell
	
\# get some nice and friendly pIdls
sh= shell.ShellNamespace()
pIdls= []
sh.OpenSpecialFolder(shell.CLSIDL_DRIVES)
pIdls.append(sh.GetCwd())
for i in sh:
	pIdls.append(i)

\# free the pIdls and set the format to clipboard 
il= clipboard.cf.idlistarray(pIdls)
for i in pIdls:
	shell.PidlFree(i)

do= clipboard.DataObject(il)
clipboard.SetDataObject(do)
clipboard.Flush()
do.Close()


\# test if it worked
do= clipboard.GetDataObject()
if do.HasFormat(il):
	if do.GetData(il):
		pIdls= il.value
		il.value= None
		for i in pIdls:
			shell.PidlFree(i)
		if pIdls:
			print '... got something in return'

</pre>
<br><br>
	</P>





::site:: defining own format wrappers
	
	
	Some step through example on this.
	<br><br>


<pre>
from wnd.api.shell.oledata.clipformats import *
	
cfName= 'my_format_name'
myClipformat= RegisterClipboardFormat()
CF_RNAMES.append([cfName, cfName, myClipformat])	
	
class MYFORMAT(object):
	
	fmt= FORMATETC()	
	fmt.cfFormat = myClipformat
	fmt.dwAspect = DVASPECT_CONTENT
	fmt.lindex =  INDEX_ALL
	fmt.tymed = TYMED_NULL	
		
	def __init__(self, data=None):
		self.stg= clipboard.STGMEDIUM()
		self.stg.tymed = self.fmt.tymed
		if text:
			self._set_value(data)
				
	def _set_value(self, data):
		if data==None:
			self.stg.hGlobal= 0
		else:	
			if self.stg.hGlobal:
				self.stg.hGlobal= 0
			self.stg.hGlobal = MyDataToHGlobal(data)
	
	def _get_value(self):
		if self.stg.hGlobal:
			value= MyDataFromHGlobal(self.stg.hGlobal) 
			return value
	
	def Close(self): self.stg.hGlobal= 0
	def __eq__(self, other): return IsSameFormat(self, other) 
	def __repr__(self): return Repr(self)
				
	value= property(_get_value, _set_value)
	
</pre>

<br><br>
First it could be quite handy to import all the required datatypes and functions.
The clipformat module defines these. Its a shamefully cluttered, so dir() is not to much of a help
in here.

<pre>

from wnd.api.shell.oledata.clipformats import *
	
cfName= 'my_format_name'
myClipformat= RegisterClipboardFormat()
CF_RNAMES.append([cfName, cfName, myClipformat])	
</pre>

The RegisterClipboardFormat funtion can be found here to register a format.
To let the framework know about the new format, append it to the  CF_RNAMES
list.

<br><br>
First it could be quite handy to import all the required datatypes and functions.
The clipformat module defines these. Its a shamefully cluttered, so dir() is not to much of a help
here.

<pre>

class MYFORMAT(object):
		
	fmt= FORMATETC()	
	fmt.cfFormat = myClipformat
	fmt.dwAspect = DVASPECT_CONTENT
	fmt.lindex =  INDEX_ALL
	fmt.tymed = TYMED_NULL
	
</pre>
 
 This will define the format your medium is in. The classname should corrospond to
 to the format registered (all upper case).
<br><br>
The FORMATETC structure should be filled in to give anyone an idea what kind of data to
expect ehen requesting it.
<br><br>
cfFormat should be self explanatory, its the clipboard format you registered or one of the
predefined clipboard formats.
<br><br>
cfAspect is the view aspect of your data. can be DVASPECT_CONTENT its embedable, 
DVASPECT_THUMBNAIL its athumbnail image ( SDK docs claim 120 by 120 pixel, 16-color is recommended),  DVASPECT_ICON its an icon or DVASPECT_DOCPRINT, to be hnest 
I didn' t check this up to now.
<br><br>
lindex is some value describing how to act if the data has to be split across page boundaries.
INDEX_ALL seems to be a sufficient choice here.
<br><br>
tymed is importand. It states what your data actually is.
<br>
TYMED_HGLOBAL = global memory handle.<br>
TYMED_FILE = a path to a file<br>
TYMED_ISTREAM  = a stream (IStrem)<br>
TYMED_ISTORAGE   = a storage (IStorage)<br>
TYMED_GDI = a gdi handle (bitmap)<br> 
TYMED_MFPICT = a metafile<br> 
TYMED_ENHMF = an enhanced metafile<br> 
TYMED_NULL = no data
<br><br>  

<pre>
	def __init__(self, data=None):
		self.stg= clipboard.STGMEDIUM()
		self.stg.tymed = self.fmt.tymed
		if text:
			self._set_value(data)

</pre>

Next up is __init__.
Here you set up you storage medium.
<br><br>
Like the FORMATETC it has a tymed member corrosponding to the FORMATETC's one.

<br><br>


<pre>

				
	def _set_value(self, data):
		if data==None:
			self.stg.hGlobal= 0
		else:	
			if self.stg.hGlobal:
				self.stg.hGlobal= 0
			self.stg.hGlobal = MyDataToHGlobal(data)
				
	
	def _get_value(self):
		if self.stg.hGlobal:
			value= MyDataFromHGlobal(self.stg.hGlobal) 
			return value

</pre>
The heart of this thinggy are the two descriptors. hey get called everytime the user
accesses the value attribute of the format wrapper.
<br>
When the user wants to set a value,  _set_value gets called you should transfer it into a
global handle or stream or storage and put it in the hGlobal member ot the STGMEDIUM 
structure. STGMEDIUM accepts only DWORD values. If data id None youshould free the allocated memory by setting stg.hGlobal to 0
<br><br>
When the user wants to retrieve data from the value attribute
_get_value will be called and its up to you how to convert from a hGlobal back into a 
human readable if stg.hGlobal contains a memory handle.
<br><br>


<pre>
	def Close(self): self.stg.hGlobal= 0
	def __eq__(self, other): return IsSameFormat(self, other) 
	def __repr__(self): return Repr(self)
				
	value= property(_get_value, _set_value)
</pre>

Last comb overs is on Close to set hGlobal to 0. STGMEDIUM comes equipped with its own
property and setting it to 0 will trigger  ole32.ReleaseStgMedium to free the memory.
<br><br>
IsSameFormat is a funtion defined in the module to handle format comparisons, 
<pre> is a pretty print function for better looks of the printable representation of the format.