[Wnd-commit] wnd/wnd_doc/doc/controls/dialog classes/browseforfolder browseforfolder.dtpl,NONE,1.1

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

Update of /cvsroot/wnd/wnd/wnd_doc/doc/controls/dialog classes/browseforfolder
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5487

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

--- NEW FILE: browseforfolder.dtpl ---


::site:: class BrowseForFolder
		<code class=import>defined in: wnd.dlgs.browseforfolder</code><br><br>
		<code>inst=BrowseForFolder()</code><br>

		<P>Creates a BrowseForFolder dialog
		</P>



::site:: BrowseForFolder messages
	
	A BrowseForFolder dialog the following messages to the message
	handler:<br><br>
	<DL>
				
		<DT>'bff_selchanged'
		<DD>the selected folder has changed<br>
				wp=pIdl of the selected folder<br>
				lp=always zero
				<br><br>
				The pIdl being passed if freed right after returning. If you
				want to keep it make a copy of it.
				<br><br>
		
		<DT>'bff_validatefailed'
		<DD>the user has entered an invalid path into the editbox<br>
				wp=path<br>
				lp=always zero
				<br><br>
				Return False here to disallow the dialog to be closed. 
				<br><br>
	</DL>	






::folder:: BrowseForFolder methods
	BrowseForFolder dialogs support the following methods:<br><br>
	
	::item:: Run
		<code>Run(hwnd, *flags, **kwargs)</code><br>
		Displays the choose color dialog.<br> 
		
		<P>
		<DL>
			<DT>hwnd
			<DD>The hwnd of the parent window or None
			
										
			
			<DT>*flags
			<DD>One or more of the following flags:
					<br>
					
					<TABLE class="table1" BORDER="1">
					<TR>
						<TD>'browseforcomputer'</TD>
						<TD>the user may only select computers</TD>
					</TR>
					<TR>
						<TD>'browseforprinter'</TD>
						<TD>the user may only select printers</TD>
					</TR>
					<TR>
						<TD>donotgobbledomain'</TD>
						<TD>Do not include network folders below the domain level in the tree view control. </TD>
					</TR>
					<TR>
						<TD>'editbox'</TD>
						<TD>adds an editbox to the dialog the user may enter paths 
								into</TD>
					</TR>
					<TR>
						<TD>'fsancestorssonly'</TD>
						<TD>the user may select only filesystem ancestors</TD>
					</TR>
					<TR>
						<TD>'fsdirsonly'</TD>
						<TD>the user may select only filesystem folders</TD>
					</TR>
					<TR>
						<TD>'hook'</TD>
						<TD>hooks the dialog so you can use it like any other
							dialog, except that the onINITDIALOG handler never gets
							called. Overwrite <a HREF="BrowseForFolder methods/onINIT.html">onINIT</a> instead</TD>
					</TR>
					<TR>
						<TD>'includefiles'</TD>
						<TD>includes files in folder display</TD>
					</TR>
					<TR>
						<TD>'statustext'</TD>
						<TD>includes a statustext area in the dialog</TD>
					</TR>
					<TR>
						<TD>'validate'</TD>
						<TD>will send a 'validatefailed' message to the message
							handler if the user typed in an invalid path into the
							editbox. Ignored if 'editbox' is not specified</TD>
					</TR>
					
					</TABLE>
					
			
			
			<DT>kwargs
			<DD>The following keyword arguments are recognised:
					<TABLE class="table1" BORDER="1">
					
					<TR>
						<TD>'root'</TD>
						<TD>can be the pIdl of the root folder of the dialog. 
								If omitted the dialog is rooted at the desktop.
								The pIdl passed is not freed in the call.</TD>
					</TR>
					<TR>
						<TD>'title'</TD>
						<TD>a string specifying the title of the dialogbox</TD>
					</TR>
			</DL>
		</DL>
		</P>
		
		
		<br><br>
		<b>Return value</b><br>
		The pIdl of the selected folder or None if the user canceled the dialog

		<br><br>
		<b>Notes</b><br>
		You have to free the returned pIdl after use. One way to do so is
		call the <b>PidlFree</b> method as defined in <code class=import>wnd.api.shell</code>  (no link yet)
		
		
	::item:: GetLastImageIndex
		<code>GetLastImageIndex</code><br>
		<P>The dialog is so kind to pass the index of the icon in the system 
			imagelist of the selected folder. Use this method to retrive it right
			after the dialog has been closed. Return value is None if
			the dialog was canceled.
		</P>

	::item:: SetStatusText
		<code>SetStatusText(text)</code><br>
		<P>As long as the dialog is displayed you may set a statustext to it.
			<br><br>
			Has no effect if the dialog was not created with the 'statustext' flag
		</P>

	::item:: DisableOK)
		<code>DisableOK()</code><br>
		<P>As long as the dialog is displayed you may disable the 'OK' button
		</P>

	
	::item:: EnableOK)
		<code>EnableOK()</code><br>
		<P>As long as the dialog is displayed you may enable the 'OK' button
		</P>

	::item:: SetSelection
		<code>SetSelection(pIdlOrPath)</code><br>
		<P>As long as the dialog is displayed you may select a folder, given its pIdl 
			or path. 
			<br><br>
			If you pass a pIdl it is is not freed in the call.
			
		</P>

	::item:: onMSG
		<code>onMSG(hwnd, msg, wp, lp)</code><br>
		<P>The message handler of the dialog. Overwrite to process messages
			while it is run
	
		</P>

	
	::item:: onINIT
		<code>onINIT(hwnd, msg, wp, lp)</code><br>
		<P>Called when the dialog has finished initializing. 
		<br><br>
		Slightly different to normal dialogs. msg will be BFFM_INITIALIZED
		<b>wp</b> and <b>lp</b> will always be zero
		<br><br>
		onINITDIALOG is never called for the BrowseForFolder dialog

	
		</P>