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

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

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

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

--- NEW FILE: dragdrop.dtpl ---

::site:: module dragdrop
	
	This module contains stuff required for drag-and-drop actions
	Its mostly aimed at extension writers who want to implement drag and
	drop capabilities into their controls or to implement custom drag and
	drop if supported by a control.
	
	<br><br>
	Use this if you want to implement a control supporting drag-and-drop
	or for handling custom drag-and-drop for a control who supports this
	<br><br>
	Use the <a HREF="dragdrop functions/Register.html">Register</a>
	to register a window as drop target. <a HREF="dragdrop functions/Revoke.html">Revoke</a> this registration when the window is closed. To drag data use the <a HREF="dragdrop functions/DoDragDrop.html">DoDragDrop</a> function.

	<br><br>
	
	The keyboard is used like this in drag and drop operations:
	<br>
	When the user holds down the control key the data should be copied, control and shift down should link to it, none or shift down
	should move it.
	
	<br><br>
	The sample code registers a window as drop target, and users the drag
	source capabilities to drag data around 	
<pre>

from wnd.api.ole import dragdrop


		\# setup DragDrop class and register the window as drop target
		self.drag= dragdrop.DragDrop(self.Hwnd)
		self.drag.onMSG= self.onMSG
		dragdrop.Register(self.Hwnd, self.drag)
		
		\# init a dataObject for draging
		text= dragdrop.cf.text('my sample text')
		self.do= dataobject.DataObject(text)


	def onMSG(self, hwnd, msg, wp, lp):
		
		\# trigger draging of data
		\# todo: check if mouse has left drag rect
		if msg=="lmbdown":
			result=dragdrop.DoDragDrop(self.do, self.drag, 'move', 'copy', 'link')
			print result
		
				
		if msg=="dragdrop":
			\# handle drop target side			
			
			if wp=="dragenter":
				\# check if some interesting format is contained in DataObject
				\# self.SetFocus()
				return lp[0].HasFormat(dragdrop.cf.text)
												
			if wp=="dragover":
				\# move the cursor along, hilight items on the way or whatever
				pass
			
			elif wp=="drop":
				\# get the data
				if lp[0].HasFormat(dragdrop.cf.text):
					text= dragdrop.cf.text()
					lp[0].GetData(text)
					print text.value
					text.value= None

					\# check keystate if necessary
					if lp[1] & dragdrop.MK_LBUTTON:
						\# left mouse buton is down
						pass
					elif lp[1] & dragdrop.MK_RBUTTON:
						\# rigth mouse buton is down
						pass

				
		\# cleanup
		if msg=="destroy":
			try: self.do.Close()
			except: pass
			try: dragdrop.Revoke(hwnd)
			except: pass

</pre>


::site:: DropTargetPointer
	<code class=import>defined in: wnd.api.ole.dragdrop</code><br><br>
	
	<code>DropTargetPointer()</code><br>
	Wrapper around a IDropTarget pointer
	

::site:: dragdrop constants
	
	DROPEFFECT_NONE   = 0 <br>
	DROPEFFECT_COPY   = 1 <br>
	DROPEFFECT_MOVE   = 2 <br>
	DROPEFFECT_LINK   = 4 <br>
	DROPEFFECT_SCROLL = -2147483648<br>

	<br>
	MK_LBUTTON  = 1<br>
	MK_RBUTTON  = 2<br>
	MK_SHIFT    = 4<br>
	MK_CONTROL  = 8<br>
	MK_MBUTTON    =      16<br>
	MK_ALT	=  32<br>


::folder:: dragdrop functions
	This module defines the following functions:

			
	::item:: cf
		<code>cf(name)</code><br>
		<P>Imports a clipboard format given its name.
		<br><br>
		This is the same stub class as in <code class="import">wnd.api.clipboard</a>
		</P>
		
	
	::item:: Register
		<code>Register(hwnd, DragDrop)</code><br>
		<P>Registers awindow as drop target.
		<br><br>
		DragDrop should be an instance of the 
		<a HREF="../DragDrop.html">DragDrop</a> class to handle the drop
		target side.
		<br><br>
		<b>Return value</b><br>
		0 if sucessful, an error code if not
		
		</P>
	
	::item:: Revoke
		<code>Revoke(hwnd)</code><br>
		<P>Unregisters the window as drop target.
			You should make shure to call this when the window is closed
		<b>Return value</b><br>
		0 if sucessful, an error code if not
		<br><br>
		
		
		</P>
	
	::item:: DoDragDrop
		<code>DoDragDrop(DataObject, DropSource, *effects)</code><br>
		<P>
		
		<DL>
			<DT>DataObject
			<DD>a DataObject containing clipboard formats
			<br><br>
			
			<DT>DragDrop
			<DD>a <a HREF="../DragDrop.html">DragDrop</a>
				instance

			<br><br>
			
			<DT>*effects
			<DD>one or more effects allowed in the operation.

				<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'none'</TD>
					<TD>no effect</TD>
				</TR>
				<TR>
					<TD>'copy'</TD>
					<TD>the data may be copied</TD>
				</TR>
				<TR>
					<TD>'move'</TD>
					<TD>the data may be moved</TD>
				</TR>
				<TR>
					<TD>'link'</TD>
					<TD>the data may be linked to</TD>
				</TR>
				</TABLE>

				<br><br>
				The drop target decides wich effect to actually use from the
				allowed effects.
		
		</DL>
		<br><br>
		
		
		<b>Return value</b><br>
		a tuple(result, effect).
		<br><br>
		the first member of the tuple holds the result of the operation: 

		<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'cancel'</TD>
					<TD>the operstion was canceled</TD>
				</TR>
				<TR>
					<TD>'drop'</TD>
					<TD>the daqta has been dropped</TD>
				</TR>
				<TR>
					<TD>'outofmemory'</TD>
					<TD>one of these error codes</TD>
				</TR>
				<TR>
					<TD>'unexpected'</TD>
					<TD>another one, but this time we are surprised. Should 
					be	sufficient to pretend as if.	</TD>
				</TR>
				<TR>
					<TD>'unknown error'</TD>
					<TD>unknown</TD>
				</TR>
				<TABLE>
		
		<br><br>
		The second is the outcomming effect. Should be one of the effects
		or 'unknown'.
		
		<br><br>
		If the effect is 'move' you should remove the dragged data
		from yours. 

		
		</P>
	
		
::site:: class DragDrop
	<code class=import>defined in: wnd.api.ole.dragdrop</code><br><br>
	<code>DragDrop(hwnd)</code><br>
	<P>
	Inits a class that handles the drop target and drop source side of a
	drag-and-drop action.
	<b>hwnd</b> can be be the hwnd of a window, a cookie or
	whatever, being passed as hwnd paramterer to the message handler
	
	<br><br>	
	
	All messages  during a drag-and-drop action are redirected to the 
	the message handler of the class:
	<br><br>
	<code>onMSG(hwnd, msg, wp, lp)</code><br>
	<br><br>
	Overwrite this message handler to process the messages.
	The following messages are send to the message handler:
	<br><br>
	<DL>
		<DT>'dragdrop'
		<DD>the mouse has entered the window, containing drag load.<br>
				wp='dragenter'<br>
				lp= tuple(DataObject, keystate, point, pEffect)
				<br><br>
				<TABLE class="table1" BORDER="1">
				<TR>
					<TD>DataObject</TD>
					<TD>the data object carried along as defined in 
						<code class=import>wnd.api.ole.dataobject</code>. </TD>
				</TR>
				<TR>
					<TD>keystate</TD>
					<TD>a flag indicating wich keys are down by that time:
						can be on or more of the MK_* constants defined in the module. See 
						<a HREF="dragdrop constants.html>dragdrop constants</a></TD>
				</TR>
				<TR>
					<TD>point</TD>
					<TD>a ||type-POINT|| containing the coordinates of the cursor</TD>
				</TR>
				<TR>
					<TD>pEffect</TD>
					<TD>pointer to a DWORD containing the drop effect</TD>
				</TR>
				</TABLE>
								
				<br><br>
				Most of the time it should be enough to query the DataObject
				passed if it contains anything of interest. Return False
				here to indicate that nothing you can make any use of carried
				along.
				<br><br>
		
	
		<DT>'dragdrop'
		<DD>the mouse draging over the window<br>
				wp='dragover'<br>
				lp= tuple(keystate, point, pEffect)
				<br><br>
				<TABLE class="table1" BORDER="1">
				<TR>
					<TD>keystate</TD>
					<TD>a flag indicating wich keys are down by that time:
						can be on or more of the following:  MK_SHIFT,
						MK_CONTROL</TD>
				</TR>
				<TR>
					<TD>point</TD>
					<TD>a ||type-POINT|| containing the coordinates of the cursor</TD>
				</TR>
				<TR>
					<TD>pEffect</TD>
					<TD>pointer to a DWORD containing the drop effect</TD>
				</TR>
				</TABLE>
								
				<br><br>
				Most interesting here is the ||type-POINT|| passed, so you can
				follow the cursor around while moving. Return False here
				to indicate that a drop is not allowde over the specified position.
				<br><br>
		
		<DT>'dragdrop'
		<DD>the mouse is leaving the window<br>
				wp='dragleave'<br>
				lp= allways zero
				<br><br>
				

		<DT>'dragdrop'
		<DD>the user has dropped the data<br>
				wp='drop'<br>
				lp= tuple(DataObject, keystate, point, pEffect)
				<br><br>
				<TABLE class="table1" BORDER="1">
				<TR>
					<TD>DataObject</TD>
					<TD>the data object carried along as defined in 
						<code class=import>wnd.api.ole.dataobject</code>. </TD>
				</TR>
				<TR>
					<TD>keystate</TD>
					<TD>a flag indicating wich keys are down by that time:
						can be on or more of the MK_* constants defined in the module. See 
						<a HREF="dragdrop constants.html>dragdrop constants</a></TD>
				</TR>
				<TR>
					<TD>point</TD>
					<TD>a ||type-POINT|| containing the coordinates of the cursor</TD>
				</TR>
				<TR>
					<TD>pEffect</TD>
					<TD>pointer to a DWORD containing the drop effect</TD>
				</TR>
				</TABLE>
								
				<br><br>
				You queried the DataObject on enter alreaddy if it contains
				something interesting, no matter, do it again and
				get whatever data you are interested in from the DataObject
				If you do not want to acceot the drop return False here.
				
				<br><br>
	
	
	</DL>	
	
	<br><br>
	<b>Notes</b><br>
	<UL>
		<LI>'feedback' is not send if the class is used to handle the drop
		target side only.All messages except 'feedback' are not send when 
			the class is used to handle the drop source side only.
			<br><br>
		
		<LI>Its best to init the class when you init the control. Initing it 
			through a method call at runtime runs the risk of being garbage
			collected. 
	</UL>
	
	
	<br><br>
	The DragDrop class defines some additional methods:
	<br><br>
	<code>GetDropTargetPointer()</code><br>
		<P>Returns a pointer to the IDropTarget pointer of the class
		<br><br>
	
	<br><br>
	<code>GetDropSourcePointer()</code><br>
		<P>Returns a pointer to the IDropSource pointer of the class
		<br><br>	
	
	
	<br><br>
	<code>SetDropEffect(*effects)</code><br>
		<P>This method is used for drop targets to adjust the drop effects
			the target supports. 
			<br><br>	
			By default all drop effects are supported,
			you may adjust them to your needs using this method, specifying
			one or more of the dropeffect flags:
			<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'none'</TD>
					<TD>no effect</TD>
				</TR>
				<TR>
					<TD>'copy'</TD>
					<TD>the data may be copied</TD>
				</TR>
				<TR>
					<TD>'move'</TD>
					<TD>the data may be moved</TD>
				</TR>
				<TR>
					<TD>'link'</TD>
					<TD>the data may be linked to</TD>
				</TR>
				</TABLE>
			<br><br>	
	
	<br><br>
	<code>GetDropEffect()</code><br>
		<P>For drop targets, returns the supported drop effect.
		<br><br>	
		Return value may be a list of one or more of the dropeffect flags
	
	</P>
	<br><br>