[Wnd-commit] wnd/wnd_doc/doc/api/shell/shellnotify shellnotify.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/shellnotify
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15542

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

Index: shellnotify.dtpl
===================================================================
RCS file: /cvsroot/wnd/wnd/wnd_doc/doc/api/shell/shellnotify/shellnotify.dtpl,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** shellnotify.dtpl	15 May 2005 10:19:34 -0000	1.2
--- shellnotify.dtpl	2 Jul 2005 09:37:37 -0000	1.3
***************
*** 1,14 ****

  ::site:: class ShellNotify
  	<code class=import>defined in: wnd.api.shell</code><br><br>
  	<code>ShellNotify(Window, message, callback)</code><br>
  	Sets a window for being the receiver of various shell 
! 	notification messages. 
  	<DL>
  		<DT>Window
  		<DD>the parent window
  		<DT>message
! 		<DD> Specify the message you want to receive in response to an event
! 		(WM_USER + x is recommendet here). 
  		<DT>callback
  		<DD>should be a function taking
--- 1,172 ----

+ 
+ ::site:: class ShellChangeNotification
+ 	<code class=import>defined in: wnd.api.shell</code><br><br>
+ 	<code>ShellChangeNotification()</code><br>
+ 	<br><br>
+ 
+ 	This class handles registration of a notificaion handle to monitor changes
+ 	in a specified folder.
+ 	<br><br>
+ 	You will not get informed in detail about the events occuring in the folder
+ 	like when using the <a HREF="class ShellNotify.html>ShellNotify</a>
+ 	class. You get a notification that a change ocured and its up to you
+ 	to find out what happend.
+ 
+ 
+ 
+ ::folder:: ShellChangeNotification methods
+ 	The ShellChangeNotification class defines the following methods: <br><br>
+ 	
+ 	::item:: Close
+ 		<code>Close()</code><br>
+ 		<P>
+ 		Closes a previously registered handle
+ 		</P>
+ 
+ 	::item:: Regisdter
+ 		<code>Register(path, *flags, **kwargs)</code><br>
+ 		<P>
+ 		<DL>
+ 			<DT>path
+ 			<DD>the path of the folder to monitor
+ 			<DT>*flags
+ 			<DD>one ore more of the following flags to specify wich events
+ 					to monitor:
+ 					<br>
+ 
+ 				<TABLE class="table1" BORDER="1">
+ 				<TR>
+ 					<TD>'attributes'</TD>
+ 					<TD>monitors attribute changes</TD>
+ 				</TR>
+ 				
+ 				<TR>
+ 					<TD>'creation'</TD>
+ 					<TD>??. I do not have any documentation about this flag</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'dirname'</TD>
+ 					<TD>monitors folder related changes. A folder is created, removed or similar</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'filename'</TD>
+ 					<TD>monitors file related changes. A file is created, removed or similar</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'lastaccess'</TD>
+ 					<TD>monitors changes affecting the last access time of a
+ 					file. This will fail on win9x systems</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'lastwrite'</TD>
+ 					<TD>monitors changes affecting the last write time of a
+ 					file. This will fail on win9x systems</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'size'</TD>
+ 					<TD>monitors changes affecting the size of a file</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'security'</TD>
+ 					<TD>monitors changes affecting the security descriptor of a
+ 						file. This will fail on win9x systems</TD>
+ 				</TR>
+ 				</TABLE>
+ 			
+ 					
+ 			
+ 			<DT>**kwargs
+ 			<DD>
+ 				<TABLE class="table1" BORDER="1">
+ 				<TR>
+ 					<TD>'hwnd'</TD>
+ 					<TD>can be a Hwnd of a window or any other identifyer
+ 						to be passed to the 
+ 						<a HREF="onMSG.html">onMSG</a> method as hwnd
+ 						parameter. Use this for example if you want to tell multiple
+ 						notification handlers apart.
+ 						</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'subtree'</TD>
+ 					<TD>If True changes are monitored for the whole directory tree</TD>
+ 				</TR>
+ 				<TR>
+ 					<TD>'timeout'</TD>
+ 					<TD>this is the timeout the handler will use when a message
+ 					arrives to wait for the next message, before it informs the user
+ 					that a message has arrived. 
+ 					<br>
+ 					Many events trigger multiple messages and its quite likely
+ 					that many events of the same type occur in the folder.
+ 					The handler waits for the specified timeout to filter multiple
+ 					messages out. This help to reduce traffic. The timeout defaults
+ 					to 200 (miliseconds). Adjust to your needs.
+ 					</TD>
+ 				</TR>
+ 				</TABLE>
+ 		</DL>
+ 	
+ 		<br><br>
+ 		<b>Notes<b>
+ 		<UL>
+ 			<LI>You may receive multiple notifications for an event registered.
+ 					For example if you registered for 'size' notifications you may
+ 					and up with 5 notifications being send for one event.
+ 			<LI>
+ 		</UL>
+ 				
+ 		
+ 		
+ 
+ 		
+ 		
+ 		
+ 		</P>
+ 
+ 	::item:: onMSG
+ 		<code>onMSG(hwnd, msg, wp, lp)</code><br>
+ 		<P>
+ 		The message handler for the class.
+ 		<br><br>
+ 		When an event occures the one and only message 'shellchange'
+ 		will be send to the handler. 
+ 
+ 		<DL>
+ 			<DT>hwnd
+ 			<DD>the hwnd you specified in the 
+ 					<a HREF="Register.html">Register</a> method or 0 (zero)
+ 			<DT>msg
+ 			<DD>'shellchange'
+ 			<DT>wp
+ 			<DD>allways zero
+ 			<DT>lp
+ 			<DD>always zero
+ 		</DL>
+ 
+ 		</P>
+ 
+ 		
+ 
+ 
+ 
+ 
  ::site:: class ShellNotify
  	<code class=import>defined in: wnd.api.shell</code><br><br>
  	<code>ShellNotify(Window, message, callback)</code><br>
+ 	
+ 	<P>
  	Sets a window for being the receiver of various shell 
! 	notification messages.
! 		
! 	
  	<DL>
  		<DT>Window
  		<DD>the parent window
  		<DT>message
! 		<DD> Specify the message you want to receive in response to an event.
! 				Use <code class='import'>RegisterWindowMessage</code> (sorry
! 				no link here) to register a message. 
  		<DT>callback
  		<DD>should be a function taking
***************
*** 41,48 ****
  </pre>

! <br><br>
! See <a HREF="ShellNotify methods/HandleMessage.html">HandleMessage</a>
! for an overview of events.

--- 199,235 ----
  </pre>

! 	 
! 	See <a HREF="ShellNotify methods/HandleMessage.html">HandleMessage</a>
! 	for an overview of events.
! 	 
! 	This class has some advantages and some disadvantages over 
! 	<a HREF="class ShellChangeNotification.html>ShellChangeNotification</a>
! 	 
! 	<OL>
! 		<LI> + is that you can specify a pIdl to monitor
! 				 
! 				This makes it possible to monitor changes in virtual folders that
! 				do not have a file system path - like 'drives' or 'printer' or similar.
! 				 
! 
! 		<LI>+ is you get very detailed information on changes
! 			 
! 			
! 		<LI>- is that the way this api is implemented is somewhat slow.
! 					The underlaying api hooks into Explorers notification loop,
! 					and there is a chance that it might not work with explorer not
! 					being present on the system.
! 					
! 				 
! 				
! 		
! 	</OL>
! 	 
! 	If you have to rely on geting notified more quickly use the
! 	<a HREF="class ShellChangeNotification.html>ShellChangeNotification</a>
! 	class

+ 	</P>
+ 	

***************
*** 55,64 ****
 	::item:: Close
 		<code>Close()</code> 
 		Closes the wrapper and frees all related resources.
 		You should take care to call this method

! 	::item:: 
! 		<code></code><br>
! 	
  	::item:: Register
  		<code>Register(pIdl, *flags)</code><br>
--- 242,251 ----
  	::item:: Close
  		<code>Close()</code><br>
+ 		<P>
  		Closes the wrapper and frees all related resources.
  		You should take care to call this method
+ 		</P>

! 		
  	::item:: Register
  		<code>Register(pIdl, *flags)</code><br>
***************
*** 84,88 ****
--- 271,277 ----

  	::item:: HandleMessage
+ 		
  		<code>HandleMessage(hwnd, msg, wp, lp)</code><br>
+ 		<P>
  		The window should call HandleMessage in response to
  		s notification message. This method translates the
***************
*** 244,247 ****
  		</UL>

! 		

\ No newline at end of file
--- 433,436 ----
  		</UL>

! 	<P>

\ No newline at end of file