[Wnd-commit] wnd/wnd_doc/doc/controls/control classes/propertysheet .CVSIGNORE,NONE,1.1 propertysheet.dtpl,NONE,1.1

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

Update of /cvsroot/wnd/wnd/wnd_doc/doc/controls/control classes/propertysheet
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3496

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

--- NEW FILE: .CVSIGNORE ---
*.html
*.gif

--- NEW FILE: propertysheet.dtpl ---


::site:: class PropertySheet
	<code class=import>defined in: wnd.controls.propertysheet</code><br><br>
	<code>PropertySheet(parent, title, *flags, **kwargs)</code><br>

	<P>
	Creates a propertysheet or a wizard dialog
		<br><br>


	
	<DL>
		<DT>title
		<DD>the title of the propertysheet (ignored for wizard)
		<DT>parent
		<DD>the parent window or None
		<DT>flags
		<DD>one or more flags adjusting several aspects of the dialogbox:
			<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'proptitle'</TD>
					<TD>prefixes the dialogbox title with the string 
						'Properties of ' (ignored for wizard)</TD>
				</TR>
				<TR>
					<TD>'hashelp'</TD>
					<TD>adds a 'help' button to the dialog</TD>
				</TR>
				<TR>
					<TD>'modeless'</TD>
					<TD>creates a modeless dialog instead of the modal default one. You can have only one instance of a modeless property
					sheet running at a time</TD>
				</TR>
				<TR>
					<TD>'noapplynow'</TD>
					<TD>hides the 'apply' button (ignored for wizard)</TD>
				</TR>
				<TR>
					<TD>'rtlreading'</TD>
					<TD>displays the text in the titlebar right to left reading (only
					used for arabic and hebrew languages)</TD>
				</TR>
				<TR>
					<TD>'stretchwatermark'</TD>
					<TD>if a watermark bitmap is used it stretches it to fit 
						the header area, rather then titling it (wizard only)</TD>
				</TR>
				
				<TR>
					<TD>'wizard97'</TD>
					<TD>creates a wizard dialog</TD>
				</TR>
			</TABLE>
		
		<br><br>
		
		<DT>kwargs
		<DD>the following keyword arguments are recognised:
			<TABLE class="table1" BORDER="1">
				<TR>
					<TD>icon</TD>
					<TD>the icon to display in the titlebar of the dialog</TD>
				</TR>
				<TR>
					<TD>startPage</TD>
					<TD>an integer specifying the zero based index of the page to 
					be shown initially</TD>
				</TR>
				<TR>
					<TD>bmpHeader</TD>
					<TD>a bitmap to be shown in the header (wizard only).
							Could not get this one to work. If anyone has any idea
							about it, let me know.</TD>
				</TR>
				<TR>
					<TD>bmpWatermark</TD>
					<TD>a bitmap to be shown as watermark (wizard only)</TD>
				</TR>
				</TABLE>
	</DL>
	
	
	<br><br>
	A propertysheet or wizard dialog consists of a main dialog provided
	by the win32 api, serving as a container for one or more dialogboxes, 
	shown as pages. The pages are created from templates in memory,so 
	the dialog being passed should based upon such a template.
	<br>
	<b>NOTE</b> 
	<br>
	By default the pages are created untill a page is actually selected for the
	first time. You can alter this behaviour by setting the 'premature' flag
	for a page. All method calls except 
	<a HREF="PropertySheet constants/Page.html">Page</a>
	do not have an effect untill the propertysheet is actually created by calling
	the <a HREF="PropertySheet constants/Run.html">Run</a> method

	
	<br><br>
	The size of the dialogboxes in the propertysheet is adjusted by the
	propertysheet to fit the size of the largest page passed, except when adding
	pages at runtime, where the propertysheet is not readjusted. So when adding
	a page at runtime it should not be larger then the largest page passed
	at init time. To fit the size of the 4-buttons on the bottom of the page
	you should set the width of the dialog boxes to 190 pixels.
	There are also some default sizes defined in the propertysheet module you 
	can use for the dialogs.
	<br>
	See <a HREF="PropertySheet constants.html">PropertySheet constants</a>
	
	<br><br>
	The propertysheet handles creation and destruction of the dialogboxes
	it contains, so you should not attempt to run or destroy them.

	<br><br>
	A must have at least on page and supports up to 100 pages.
	<br><br>
	Currently there is no keyboard interface for 'modeless' property sheets 
	or wizards




<br><br>
Sample code (create a medium sized property sheet)

<pre>
from wnd.controls import dialog
from wnd.controls import propertysheet
from wnd.controls import button

\# setup two (medium sized) dialogs to be hosted by the propertysheet
\# pass the propertysheet instance to the dialog on init, so it can call
\# methods upon

class dlg1(dialog.Dialog):
	def __init__(self, propsheet):
		self.propsheet= propsheet
		
		dialog.Dialog.__init__(self, 'dialog-1', 0, 0, propertysheet.PROP_MED_CXDLG, propertysheet.PROP_MED_CYDLG)

	def onINIT(self, hwnd, msg, wp, lp):
		self.bt= button.Button(self, 'Test', 20, 20, 60, 50)
		
		
class dlg2(dialog.Dialog):
	def __init__(self, propsheet):
		self.propsheet= propsheet
		
		dialog.Dialog.__init__(self, 'dialog-2', 0, 0, propertysheet.PROP_MED_CXDLG, propertysheet.PROP_MED_CYDLG)

	def onINIT(self, hwnd, msg, wp, lp):
		self.bt= button.Button(self, 'Test-1', 40, 20, 60, 50)
		self.bt.onMSG=self.on_bt

	def on_bt(self, hwnd, msg, wp, lp):
		if msg=='command':
			self.propsheet.PageChanged(hwnd)
			

\# init the propetysheet
p= propertysheet.PropertySheet('foo', None, 'proptitle', 'hashelp', startPage=0)

\# init the dialogs and set them as pages
d1= dlg1(p)
d2= dlg2(p)
p.Page(d1)
p.Page(d2)

\# run the propertysheet
result=p.Run()
</pre>
	
	
<br><br>
A bit more advanced sample you will find in the 'sample-gius' folder
as 'gui_propertysheet.py'

</P>





::site:: PropertySheet constants
	
	<TABLE class="table1" BORDER="1">
	<DH>wizard constants</DH>
	<TR>
		<TD>WIZ_BODYCX</TD>
		<TD>Width of the body of a page in a wizard property sheet. The body does not include the bitmap area.</TD>
	</TR>
	<TR>
		<TD>WIZ_BODYX</TD>
		<TD>Horizontal coordinate of the upper-left corner of the body of a page in a wizard property sheet. Use zero for the vertical coordinate of the body of a page</TD>
	</TR>
	<TR>
		<TD>WIZ_CXBMP</TD>
		<TD>Width of the bitmap area in a page of a wizard property sheet. Use WIZ_CYDLG for the height of the bitmap area. </TD>
	</TR>
	<TR>
		<TD>WIZ_CXDLG</TD>
		<TD>Width of a page in a wizard property sheet.</TD>
	</TR>
	<TR>
		<TD>WIZ_CYDLG </TD>
		<TD>Height of a page in a wizard property sheet</TD>
	</TR>
	</TABLE>
	
	<br><br>
	
	<TABLE class="table1" BORDER="1">
	<DH>propertysheet constants</DH>
	<TR>
		<TD>PROP_SM_CXDLG</TD>
		<TD>Width, in dialog units, of a small property sheet page.</TD>
	</TR>
	<TR>
		<TD>PROP_SM_CYDLG</TD>
		<TD>Height, in dialog units, of a small property sheet page.</TD>
	</TR>
	<TR>
		<TD>PROP_MED_CXDLG</TD>
		<TD>Width, in dialog units, of a medium-sized property sheet page.</TD>
	</TR>
	<TR>
		<TD>PROP_MED_CYDLG </TD>
		<TD>Height, in dialog units, of a medium-sized property sheet page.</TD>
	</TR>
	<TR>
		<TD>PROP_LG_CXDLG </TD>
		<TD>Width, in dialog units, of a large property sheet page.</TD>
	</TR>
	<TR>
		<TD>PROP_LG_CYDLG </TD>
		<TD>Height, in dialog units, of a large property sheet page.</TD>
	</TR>
	</TABLE>




::site:: PropertySheet messages
	A property sheet sends the following messages to the message
	handler:<br>
	
	<DL>
		
		<DT>'apply'
		<DD>send when the user clicked the 'OK' or 'Apply' Now button 
				and wants all changes to take effect<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
		
		<DT>'destroy'
		<DD>the property sheet is about to be destroyed<br>
				wp=allways zero<br>
				lp=allways zero
				<br><br>
				
		<DT>'help'
		<DD>the user clicked the 'Help' button<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
		
		<DT>'initialized'
		<DD>	the property sheet has been initialized, but no pages have 
				been created yet<br>
				wp=allways zero<br>
				lp=allways zero
				<br><br>
		
		<DT>'killactive'
		<DD>	the currently active page is becoming inactive<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
				You may return False here to disallow the change
				<br><br>
		
			
		
		<DT>'querycancel'
		<DD>	the user has cklicked the 'Cancel' button<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
				You may return False here to disallow the change
				<br><br>
		
		<DT>'reset'
		<DD>	the user has cklicked the 'Cancel' button, All 
		changes since the user has clicked the 'Apply' should canceled<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp='cancel' or 'close', wether the user clicked the corrosponding
						button
				<br><br>
				
		
		<DT>'setactive'
		<DD>	a page gas been activated<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
		
		<DT>'wizback'
		<DD>the user has clicked th e'Back' button in the wizard<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
				You may return False here to disallow the change
				<br><br>
	
		<DT>'wiznext'
		<DD>the user has clicked th e'Next' button in the wizard<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
				You may return False here to disallow the change
				<br><br>
	
		<DT>'wizfinish'
		<DD>the user has clicked th e'Finish' button in the wizard<br>
				wp=hwnd of the dialogbox residing on the page<br>
				lp=allways zero
				<br><br>
				You may return False here to disallow the change
				<br><br>
	
	</DL>			
				



::folder:: PropertySheet methods
	PropertySheet dialogs support the following methods:
	
	
	
	::item:: AddPage
		<code>AddPage(dlg, *flags, **kwargs)</code><br>
		<P>Appends a page to the propertysheet at runtime.
		<br><br>
		<b>Return value</b><br>
		True if the page was sucessfully added, False otherwise
	, 	</P>
	
	::item:: RemovePage
		<code>RemovePage(i)</code><br>
		<P>Removes a page to the propertysheet at runtime.
		</P>
	
	
	::item:: Page
		<code>Page(dlg, *flags, **kwargs)</code><br>
		<P>Creates a page in the dialog
		<br><br>
		<DL>
			<DT>dlg
			<DD>the dialogbox to place on the page. 
					The dialogbox has to be a DialogFromTemplate instance, 'cos
					the propertysheet dialog creates the pages from templates in
					memory.
			
			<DT>flags
			<DD>one or more flags adjusting several aspects of the dialogbox:
				<TABLE class="table1" BORDER="1">
					<TR>
						<TD>'hashelp'</TD>
						<TD>adds a 'help' button when the page is displayed</TD>
					</TR>
					<TR>
						<TD>'premature'</TD>
						<TD>the page is created emidiately when the propertysheet 	
							dialogox is created, otherwise the page is created untill the 
							page is selected</TD>
					</TR>
					<TR>
						<TD>'rtlreading'</TD>
						<TD>displays the text in the titlebar right to left reading (only
						used for arabic and hebrew languages)</TD>
					</TR>
					<TR>
						<TD>'hideheader'</TD>
						<TD>hides the header (wizard only)</TD>
					</TR>
				<TABLE>
				<br><br>
			
			
			<DT>kwargs
			<DD>the following keyword arguments are recognised:
				<TABLE class="table1" BORDER="1">
					<TR>
						<TD>title</TD>
						<TD>the title for the page. By default the title of the dialog
						being passed is used. This will overwrite it</TD>
					</TR>
					<TR>
						<TD>headerTitle</TD>
						<TD>the text displayed beneath the header (wizard only)</TD>
					</TR>
					<TR>
						<TD>headerSubTitle</TD>
						<TD>the text displayed beneath the headerTitle (wizard only)</TD>
					</TR>
					<TR>
						<TD>icon</TD>
						<TD>the icon to display in the tab of the page</TD>
					</TR>
					<TR>
						<TD>lp</TD>
						<TD>any lParam you want to assign to the page</TD>
					</TR>
					
					<TABLE>
	</DL>
	<br><br>
	Calling this method at runtime of the property sheet does not have an
	effect. A page will be added to the internal list of pages, but will not be 
	created untill the property sheet is created the next time 


</P>

	::item:: Run
		<code>Run()</code><br>
		<P>Runs the propertysheet dialog
		<br><br>
		<b>Return value</b><br>
		If the propertysheet was run modeless the return value is True if
		sucessfull, False otherwise.
		<TABLE class="table1" BORDER="1">
		<TR>
			<TD>'ok'</TD>
			<TD>the dialog was run sucessfull</TD>
		</TR>
		<TR>
			<TD>'cancel'</TD>
			<TD>the dialog was canceled or something went wrong</TD>
		</TR>
		<TR>
			<TD>'reboot'</TD>
			<TD>one of the pages set the reboot flag. The system should 
			be rebooted in response</TD>
		</TR>
		<TR>
			<TD>'restart'</TD>
			<TD>one of the pages set the restart flag. windows should 
			be restarted in response</TD>
		</TR>
		</TABLE>

		
		<br><br>
		If run modal the return value is the hwnd of the dialogbox or None 
		if something went wrong.
		<br><br>
		To query the 'reboot' flag for 'modeless' property sheets use the
		<a HREF="GetReboot.html">GetReboot</a> method
		</P>

	::item:: onMSG
		<code>onMSG(hwnd, msg, wp, lp)</code><br>
		<P>Message handler for the propertysheet. Overwrite
			this method to process messages for the propertysheet
		</P>

	::item:: PageChanged
		<code>PageChanged(hwnd)</code><br>
		<P>Enables the 'applynow' button (propertysheet only).
			'hwnd' should be the hwnd of the dialogbox residing on the page 

		</P>

	::item:: PageUnchanged
		<code>PageUnchanged(hwnd)</code><br>
		<P>Disables the 'applynow' button (propertysheet only)
		'hwnd' should be the hwnd of the dialogbox residing on the page 
		</P>
	
	::item:: CancelToClose
		<code>CancelToClose()</code><br>
		<P>Turns the 'cancel' button of the propertysheet to a 'close' button
			(propertysheet only)
		</P>
	
	
	::item:: PressButton
		<code>PressButton(button)</code><br>
		<P>presses a button in in a propertysheet or wizard.
		<br><br>
		'button' to press can be:
			<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'back'</TD>
					<TD>(wizard only)</TD>
				</TR>
				<TR>
					<TD>'next'</TD>
					<TD>(wizard only)</TD>
				</TR>
				<TR>
					<TD>'finish'</TD>
					<TD>(wizard only)</TD>
				</TR>
				<TR>
					<TD>'ok'</TD>
					<TD>(propertysheet only)</TD>
				</TR>
				<TR>
					<TD>applynow'</TD>
					<TD>(propertysheet only)</TD>
				</TR>
				<TR>
					<TD>'cancel'</TD>
					<TD></TD>
				</TR>
				<TR>
					<TD>'help'</TD>
					<TD></TD>
				</TR>
			</TABLE>

	::item:: SetTitle
		<code>SetTitle(title, proptitle=False)</code><br>
		<P>sets the title of the propertysheet. If 'proptitle' is True
		the title will be prefixed with the string: 'Properties of '.
		This flag is ignored for wizard controls
		</P>
	
	::item:: Reboot
		<code>Reboot()</code><br>
		<P>Sets an internal flag that is returned to the propertysheets 'Run'
		method indicating the system should be rebooted
		</P>

	::item:: Restart
		<code>Restart()</code><br>
		<P>Sets an internal flag that is returned to the propertysheets 'Run'
		method indicating that windows should be restarted
		</P>
	
	
	::item:: SetFinishText
		<code>SetFinishText(text)</code><br>
		<P>(wizard only) 
		<br>
		Sets the text for the 'finish' button, enables it
		and hides the 'next' and 'back' buttons
		</P>
	
	::item:: SetWizardButtons
		<code>SetWizardButtons(*buttons)</code><br>
		<P>(wizard only)
			<br>
			Enables or disables wizard buttons.
			<br>
			'buttons' can be:
			<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'back'</TD>
					<TD>enables the 'back' button. If not specified th ebutton 
						is disabled</TD>
				</TR>
				<TR>
					<TD>'next'</TD>
					<TD>enables the 'next' button. If not specified th ebutton 
						is disabled</TD>
				</TR>
				<TR>
					<TD>'finish'</TD>
					<TD>turns the 'next' button into the 'finish' button.</TD>
				</TR>
				<TR>
					<TD>'disablefinish'</TD>
					<TD>same as 'finish' but disables it. Do not specify both at 
						the same time</TD>
				</TR>
			</TABLE>
	
	
	::item:: Select
		<code>Select(i)</code><br>
		<P>Selects the specified page given its zero based index.
		<br><br>
		<b>Return value</b><br>
		True if sucessful, False otherwise
		</P>
	
	::item:: SelectHwnd
		<code>SelectHwnd(i)</code><br>
		<P>Selects the specified page given its hwnd.
		<br><br>
		<b>Return value</b><br>
		True if sucessful, False otherwise
		</P>
	
	
	::item:: GetCurrentPage
		<code>GetCurrentPage()</code><br>
		<P>Returns the hwnd of the current page
		</P>

	::item:: GetTabControl
		<code>GetTabControl()</code><br>
		<P>Returns the tab control of the propertysheet as TabFromHandle instance
			or None
		</P>

	::item:: GetReboot
		<code>GetReboot()</code><br>
		<P>Returns the current state of the reboot flag
		<br><br>
		<b>Return value</b><br>
		Either 'reboot', 'restart' or None if the flag is not set
		
		<br><br>
		<b>Notes</b><br>
		By caling <a HREF="Reboot.html">Reboot</a> or <a HREF="Resart.html">Restart</a> a flahg is set indicating if the system or
		windows should be restarted. When running the property sheet in
		'modal' mode this flag is returned as result of the 
		<a HREF="Run.html">Run</a> method. This does not work if
		the property sheet is run in 'modeless' mode. Use this method to
		query the flag for both, either 'modal' or 'modeless' property sheets.
		
		</P>



		::item:: QuerySiblings
		<code>QuerySiblings(wParam, lParam)</code><br>
		<P>Causes to send the property sheet to send a message to all
			of its pages in tuurn.
			<br><br>
			'wParam' and 'lParam' can be any int or long. You can use
			this method to establish a simple conversation inbetween
			pages of a property sheet. If any page returns a nonzero value
			the property sheet stops sending the message to subsequent
			siblings.
			<br><br>
			The dialog associated to a page will send a 'prop_querysiblings'
			message to its message handler with wParam and lParam set
			to the values specified.
			
			
			<br><br>
			<b>Return value</b><br>
			Whatever nonzero value a page returned or 0 if no page
			returned nonzero.
		</P>