Thread: [Wnd-commit] wnd/wnd_doc/doc/api/shell shell.dtpl,1.2,1.3

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

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

Modified Files:
	shell.dtpl 
Log Message:
bit of this and a bit of that

Index: shell.dtpl
===================================================================
RCS file: /cvsroot/wnd/wnd/wnd_doc/doc/api/shell/shell.dtpl,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** shell.dtpl	17 May 2005 20:15:51 -0000	1.2
--- shell.dtpl	2 Jul 2005 09:32:59 -0000	1.3
***************
*** 5,12 ****

- 	

  ::folder:: Shell functions

  	::item:: HRESULT_CODE
--- 5,33 ----

  ::folder:: Shell functions

+ <br><br>
+ 	<b>Notes</b><br>
+ 	
+ 	<UL>
+ 		<LI>All pIdl functions are low level api calls. No python error check is applied
+ 			on them, so make shure to allways check for validness in case a pIdl is
+ 			returned.
+ 	</UL>
+ 
+ This check should be performed for all pIdl methods
+ <br>
+ <pre>
+ pIdl= PidlFromPath(MyPath)
+ if pIdl:
+ 	\# process
+ else:
+ 	\# something went wrong
+ 
+ </pre>
+ 
+ 
+ 	

::item:: HRESULT_CODE
***************
*** 31,76 ****
 		<DT>fileaction
 		<DD>either 'move', 'copy', 'delete' or 'rename'
 		<DT>From 
 		<DD>path of a singe file object
! 				or a list of file objects to move or rename
 		<DT>To
 		<DD>destination path
 			or a list of destination paths to move or rename the
! 			file^objects to. This alows easy renaming of multiple
 			files. If 'To' is any shorter or longer than From the first path encountered is assumend to be a directory to be created to stuff the file objects in.
 		<DT>title
 		<DD>Title of the progress dialog box
 		<DT>hwnd
 		<DD>Not yet tested. Currently should be 0.
 		<DT>flags
 		<DD>
! 		<DL>
! 			<DT>'allowundo'	
! 			<DD>Preserves undo information.
 					Ignored if 'From' is/are not fully
! 					qualified paths
! 			<DT>'filesonly'
! 			<DD>Performs the operation on files only
! 					if a wildcard is specified
! 			<DT>'noconfirm'		
! 			<DD>responds yes to all dialog boxes
! 			<DT>'noconfirmmkdir'		
! 			<DD>	responds yes if a directory needs to
! 					be created in the operation
! 			<DT>'noerrorui'
! 			<DD>Does not display error message boxes
! 			<DT>'nosecurityattrs'
! 			<DD>NT only. Does not move security
! 					attributes along with the file objects.
! 			<DT>'renameoncollision'
! 			<DD>renames any colliding files object to 
! 					'copy of ...'
! 			<DT>'silent'
! 			<DD>does not display a progress dialog
! 			<DT>'simpleprogress'	
! 			<DD>Displays a simple progress dialog
! 						without file object names.
! 		</DL>
! 
 	</DL>

--- 52,126 ----
  		<DT>fileaction
  		<DD>either 'move', 'copy', 'delete' or 'rename'
+ 		<br><br>
+ 
  		<DT>From 
  		<DD>path of a singe file object
! 				or a list of file paths to move or rename
! 		<br><br>
! 		
  		<DT>To
  		<DD>destination path
  			or a list of destination paths to move or rename the
! 			file objects to. This alows easy renaming of multiple
  			files. If 'To' is any shorter or longer than From the first path encountered is assumend to be a directory to be created to stuff the file objects in.
+ 		<br><br>
+ 		
  		<DT>title
  		<DD>Title of the progress dialog box
+ 		<br><br>
+ 		
  		<DT>hwnd
  		<DD>Not yet tested. Currently should be 0.
+ 		<br><br>
+ 
  		<DT>flags
  		<DD>
! 		<TABLE class="table1" BORDER="1">
! 			<TR>
! 				<TD>'allowundo'</TD>
! 				<TD>Preserves undo information.
  					Ignored if 'From' is/are not fully
! 					qualified paths</TD>
! 			</TR>
! 			<TR>
! 				<TD>'filesonly'</TD>
! 				<TD>Performs the operation on files only
! 					if a wildcard is specified</TD>
! 			</TR>
! 			<TR>
! 				<TD>'noconfirm'</TD>
! 				<TD>responds yes to all dialog boxes</TD>
! 			</TR>
! 			<TR>
! 				<TD>'noconfirmmkdir'</TD>
! 				<TD>responds yes if a directory needs to
! 					be created in the operation</TD>
! 			</TR>
! 			<TR>
! 				<TD>'noerrorui'</TD>
! 				<TD>Does not display error message boxes</TD>
! 			</TR>
! 			<TR>
! 				<TD>'nosecurityattrs'</TD>
! 				<TD>NT only. Does not move security
! 					attributes along with the file objects.</TD>
! 			</TR>
! 			<TR>
! 				<TD>'renameoncollision'</TD>
! 				<TD>renames any colliding files object to 
! 					'copy of ...'</TD>
! 			</TR>
! 			<TR>
! 				<TD>'silent'</TD>
! 				<TD>does not display a progress dialog</TD>
! 			</TR>
! 			<TR>
! 				<TD>'simpleprogress'	</TD>
! 				<TD>Displays a simple progress dialog
! 						without file object names.</TD>
! 			</TR>
! 			
! 			</TABLE>
! 		
  	</DL>

***************
*** 81,85 ****
  	was encountered, True otherwise.
  	<br><br>
- 	The deal about FileOperation is, unlike os module, you get all the standard windows error dialogs.
  	</P>

--- 131,134 ----
***************
*** 109,112 ****
--- 158,214 ----
  		</P>

+ 	::item:: RenameFiles
+ 		<code>RenameFiles(From, To, title='', hwnd=0, *flags)</code><br>
+ 		<P>
+ 		Convenience wrapper for 
+ 		<a HREF="FileOperation.html">FileOperation</a> 'rename'
+ 		<P>
+ 	
+ 	
+ 	::item:: PidlFree
+ 		<code>PidlFree(pIdl)</code><br>
+ 		<P>Frees a pIdl
+ 		</P>
+ 	
+ 	::item:: PidlRemoveLast
+ 		<code>PidlRemoveLast(pIdl)</code><br>
+ 		<P>removes the last part from the pIdl
+ 		</P>
+ 	
+ 	::item:: PidlFromPath
+ 		<code>PidlFromPath(path)</code><br>
+ 		<P>Creates a pIdl from a path specified.
+ 		<br><br>
+ 		<b>Return value<b><br>
+ 		The new pIdl. 		
+ 		</P>
+ 	
+ 	::item:: PidlGetNext
+ 		<code>PidlGetNext(pIdl)</code><br>
+ 		<P>
+ 		Returns a pointer to the the next part of a pIdl.
+ 		<br><br>
+ 		The pIdl returned is not a newly allocated pIdl, so do not free it.
+ 		</P>
+ 	
+ 	
+ 		
+ 	::item:: PidlGetLast
+ 		<code>PidlGetLast(pIdl)</code><br>
+ 		<P>Returns a pointer to the last  part of a pIdl.
+ 		<br><br>
+ 		The pIdl returned is not a newly allocated pIdl, so do not free it.
+ 		</P>
+ 	
+ 	
+ 	::item:: PidlCopyFirst
+ 		<code>PidlCopyFirst(pIdl)</code><br>
+ 		<P>copies the first part of a pIdl and returns it.
+ 		<br><br>
+ 		Use some 
+ 		<a HREF="PidlFree.html">PidlFree</a> to
+ 		free it. 
+ 		</P>
+ 	

  	::item:: PidlCopy
***************
*** 118,121 ****
--- 220,246 ----
  		</P>

+ 	::item:: PidlGetChild
+ 		<code>PidlGetChild(pIdlParent, pIdlChild)</code><br>
+ 		<P>Given the pIdl of a parent and the pIdl of a child, returns a pointer to the unique portion of the childPidl.
+ 		<br><br>
+ 		The pIdl returned is not a newly allocated pIdl, so do not free it.
+ 		</P>
+ 		
+ 	
+ 	::item:: PidlAppend
+ 		<code>PidlAppend(pIdlParent, pIdlchild, toend)</code><br>
+ 		<P>Appends the child pIdl to the parent pidl. if toend is 0, inserts it 
+ 		to the beginning, if 1, appends it.
+ 		<br><br>
+ 		<b>Return value</b><br>
+ 		The resulting pIdl. Use <a HREF="PidlFree.html">PidlFree</a> to
+ 		free it. 
+ 		</P>
+ 	
+ 	::item:: PidlIsEqual
+ 		<code>PidlIsEqual(pIdl1, pIdl2)</code><br>
+ 		<P>Returns nonzero if both pIdls are equal, zero otherwise
+ 	</P>
+ 	
  	::item:: PidlDidAlloc
  		<code>PidlDidAlloc(pIdl)</code><br>
***************
*** 123,127 ****
  		Returns True if the pIdl was allocated using the shells 
  		allocator False otherwise. pIdls allocated with the shells
! 		allocator should be freed using this classes free method.
  		</P>

--- 248,256 ----
  		Returns True if the pIdl was allocated using the shells 
  		allocator False otherwise. pIdls allocated with the shells
! 		allocator should be freed using the <a HREF="PidlFree.html">PidlFree</a> function.
! 		<br><br>
! 		This is more or less a sanity check. Normally all pIdls should have been
! 		allocated by the shells allocator.
! 		
  		</P>

***************
*** 133,141 ****
  	</P>

! 	::item:: PidlFree
! 		<code>PidlFree(pIdl)</code><br>
! 		<P>Frees a pIdl
! 		</P>

  	::item:: PidlGetParent
  		<code>PidlGetParent(pIdl)</code><br>
--- 262,279 ----
  	</P>

! 			

+ 	::item:: PidlisParent
+ 		<code>PidlIsParent(pIdlParent, pIdlChild, fEmidiate)</code><br>
+ 		<P>checks is the parent pIdl is a parent of child pIdl.
+ 		<br><br>
+ 		Set fEmidiate to 1 allow the child only to be an emidate descendend, 
+ 		to 0 to indicate any descendency will do
+ 		<br><br>
+ 		<b>Return value</b><br>
+ 		nonzero if True, zero otherwise.
+ 		</P>
+ 	
+ 	
  	::item:: PidlGetParent
  		<code>PidlGetParent(pIdl)</code><br>
***************
*** 144,150 ****
  		</P>

::item:: PidlGetSize
 		<code>PidlGetSize(pIdl)</code> 
! 		Returns the size of a pIdl.

--- 282,303 ----
  		</P>

+ 	
+ 		
+ 	::item:: ILIsZero
+ 		<code>ILIsZero(pIdl)</code><br>
+ 		<P>Returns True if the pIdl is zero, False otherwise.
+ 		<br><br>
+ 		A pIdl is zero either the memory allocated for the pIdl is zero
+ 		or the ITEMIDLIST pointed to has a length of zero.
+ 		The desktops pIdl has allways a zero lenght ITEMIDLIST
+ 		<br><br>
+ 		Use this method in enumerations for example to check if the next
+ 		pIdl returned points to a valid item
+ 		</P>
+ 	
  	::item:: PidlGetSize
  		<code>PidlGetSize(pIdl)</code><br>
! 		<P>Returns the size of the allocated memory (in bytes) of a pIdl.
! 		
  		</P>

***************
*** 152,155 ****
--- 305,309 ----
  		<code>PidlJoin(pIdlBase, pIdlAdd)</code><br>
  		<P>Joins two pIdls (parent/child) and returns a new pIdl.
+ 	<br><br>
  	Use some <a HREF="PidlFree.html">PidlFree to</a>  to free it.
  	</P>
***************
*** 158,163 ****
  		<code> PidlSplit(pIdl)</code><br>
  		<P>Splits a pIdl in a pair root, trail. Return value is the
! 		trailing pIdl. The trailing pIdl is a newly allocated pIdl so
! 		remember to free it.
  		</P>

--- 312,318 ----
  		<code> PidlSplit(pIdl)</code><br>
  		<P>Splits a pIdl in a pair root, trail. Return value is the
! 		trailing pIdl or None if the pIdl could not be split. 
! 		<br><br>
! 		Use some <a HREF="PidlFree.html">PidlFree to</a>  to free the returned pIdl it.
  		</P>

***************
*** 170,179 ****
  		</P>

! 	::item:: RenameFiles
! 		<code>RenameFiles(From, To, title='', hwnd=0, *flags)</code><br>
! 		<P>
! 		Convenience wrapper for 
! 		<a HREF="FileOperation.html">FileOperation</a> 'rename'
! 		<P>

\ No newline at end of file
--- 325,357 ----
  		</P>

! 			
! 	::item:: GetIShellFolder
! 		<code>GetIShellFolder(pIdl)</code> 
! 		Returns a pointer to the items IShellFolder interface given the absolute
! 		pIdl of a folder
! 		
! 	
! 	::item:: GetSpecialFolderPath
! 		<code>GetSpecialFolderPath(clsidl)</code> 
! 		Retrieves the file sysem path of a special folder or None.
! 		 
! 		clsidl should be one of the CLSIDL_* constants defined by the shell module
! 		
! 
! 	
! 	::item:: CLSIDL_FromPidl
! 		<code>CLSIDL_FromPidl(pIdl)</code> 
! 		Maps an absolute pIdl of a folder to its CLSIDL.
! 		 
! 		Return value 
! 		a tuple(CLSIDL, clsidl-name), where CLSIDL is one of the CLSIDL_*
! 		constants as defined in the shell and clsidl name is the framework
! 		name of the CLSIDL. So the returned tuple may look like this:
! 		 
! 		(0, 'desktop')
! 		 
! 		If the shell does not define a CLSIDL for the item, return value is None
! 		
!

\ No newline at end of file

Thread: [Wnd-commit] wnd/wnd_doc/doc/api/shell shell.dtpl,1.2,1.3

wnd-commit