[Wnd-commit] wnd/wnd_doc/doc/controls/control classes/propertysheet .CVSIGNORE,NONE,1.1 propertyshee
Status: Alpha
Brought to you by:
jurner
|
From: jürgen u. <cer...@us...> - 2005-07-23 19:55:02
|
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> |