wnd-commit

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

Update of /cvsroot/wnd/wnd/wnd_doc/doc/controls/window classes/mdiframe
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv7002

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

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

--- NEW FILE: mdiframe.dtpl ---

::defaultpage:: mdiframe

::site:: MDIFrame
	<IMG SRC="mdiframe.gif"></IMG>
	
	<br><br>
	Not a beauty, but you get the idea
	<br><br>
	<a HREF="contents.html">MDIFrame contents</a>
	<br><br>




::site:: class MDIFrame
	<code class=import>defined in: wnd.controls.combobox</code><br><br>
	<code>MDIFrame()</code><br>
	<P>
	This is the base class for MDI windows. MDIFrames support the same 
	messages and styles like any othe r main window. 
	
		
	<br><br>
	


Some step through sample of how to create a MDI window:

<pre>
from wnd.controls.mdiframe import MDIFrame
from wnd.controls.button import Button

class MyMDIFrame(MDIFrame):
	
	def __init__(self):
		
		\## init the mainframe
		MDIFrame.__init__(self, 'MDI test', 0, 0, 300, 300, 'sysmenu', 'sizebox')


		self.controls= {}	 ## used to keep references to the controls assigned
							\## to the MDI childwindows	
		
		self.mdi= self.MDIClient(0, 0, w, h, popMdi.handle)
		self.mdi.onMSG= self.on_mdi

		mdi= self.mdi.NewChild('mdi child 1' % self.n,  0, 0, w, h)
		mdi2= self.mdi.NewChild('mdi child 2' % self.n,  0, 0, w, h)

		bt= Button(mdi, 'test', 0, 0, 50, 50)
		self.controls[mdi.Hwnd]= bt

		
	def on_mdi(self, msg, wp, lp):
		pass

	def onMSG(self, msg, wp, lp):
		pass


w= MyMDIFrame()
w.Run()


</pre>
<br><br>

<pre>
class MyMDIFrame(MDIFrame):
	
	def __init__(self):
		
		\## init the mainframe
		MDIFrame.__init__(self, 'MDI test', 0, 0, 300, 300, 'sysmenu', 'sizebox')
		
		
		self.controls= {}	

</pre>
Nothing spectacular here. Use the MDIFrame class as base class for the window,
thats it. The diect 'controls' is used later to keep references to the controls assigned
to the MDI childwindows.

<br><br>

<pre>
		self.mdi= self.MDIClient(0, 0, w, h)
		self.mdi.onMSG= self.on_mdi

</pre>
This will create the MDI client window and overwrite the message handler.


<br><br>
<pre>
		
		mdi= self.mdi.NewChild('mdi child 1' % self.n,  0, 0, w, h)
		mdi2= self.mdi.NewChild('mdi child 2' % self.n,  0, 0, w, h)
</pre>
Now create a MDI childwindow, to be placed inside the MDI client window.
Mostly the MDI childwindows are intended created and destroyed
dynamically at runtime. The MDIClient comes equipped to handle
this, and its not necessary to keep references to the MDI childwindows   
	
<br><br>
<pre>
		bt= Button(mdi, 'test', 0, 0, 50, 50)
		self.controls[mdi.Hwnd]= bt

</pre>
Now assign a control to the MDI childwindow using the mdi child as parent 
window and keep track of the control. This has the side effect to remind
the scriptor to always keep references to any control created, throughout its
lifetime (the controls not the scriptors lifetime, that is). 

Removing a control lateron from the dict will leave quite some garbage behind.
Its one of the trickiest things in ctypes to avaoid garbage completely. Here it 
does not work at all. So some forced garbage collection might help dealing with it.

<br><br>
For more detailed sample code see 'gui_mdiframe.py' in the sample-guis folder. 
		
</P>




::site:: MDIFrame keyboard accelerators
	
	The win32 api defines the following keyboard accelerators for MDI childwindows:
	<br><br>
	<TABLE class="table1" BORDER="1">
	<TR>
		<TD>alt -</TD>
		<TD>opens the sytem menu</TD>
	</TR>
	<TR>
		<TD>ctrl F4</TD>
		<TD>closes the sctive MDI childwindow</TD>
	</TR>
	<TR>
		<TD>ctrl F6</TD>
		<TD>activates the nextMDI childwindow</TD>
	</TR>
	</TABLE>
	



::folder:: MDIFrame methods
	MDIFram windows support the following methods:

	<a HREF="||method-ctrl||">Common methods</a>
	+ all methods supported by main windows


	::item:: HasClient
		<code>HasClient()</code><br>	
		<P>Returns True if the MDIFrame has a MDIClient window, False otherwise 
		</P>

	

	::item:: MDIClient
		<code>MDIClient(x, y, w, h, *styles, **kwargs)</code><br>
		<P>
		Creates the client window to host the MDI child windows 
		<br><br>
		<DL>
			<DT>x, y, w, h
			<DD>the desired size and position of the MDI client window
			<DT>*styles
			<DD>any style you want to set. The MDI client window does not support 
					any special styles. Use the default styles like defined for any other
					control.
		</DL>
		
		<br><br>
		The following keyword arguments are recognized:
		<DL>
			<DT>hMenu
			<DD>the handle of a popupmenu. See remarks
		</DL

			
		<br><br>
		<b>Return value</b><br>
		A MDIClient instance
		<br>
		See <a HREF="../MDIClient methods/contents.html">MDIClient methods</a>
		for the methods supported by the MDIClient instance.
			<br><br>
		
		<b>Remarks</b><br>
		The api provides means to setup a menu keeping track of MDI childwindows.
		Yopu can pass the handle of a popup in the call to enable this.
		thre api will use the menu to reflect all relevant changes of the MDI
		childwindowsin the menu.
			
		If you want to insert own items into the menu you should query
		the <a HREF="../MDIFrame.html">MDIFrame</a> for the constant MIN_MENU_ID,
		defined by this class, to get the minimum allowable menu ID for user defined
		menu items. All IDs lower than this ID is reserved for the MDI menu.
		
		<br><br>
		Each MDIFrame may have only one MDIClient window
		
	</P>




::site:: MDIClient messages
		A MDIClient sends the following messages to the message handler:<br><br>
	 
	<DL>
			
		<DT>'childcreated'
		<DD>a MDI childwindow has been created<br> 
				wp=hwnd of the childwindow<br>
				lp=allways zero
				<br><br>
		
		<DT>'childdestroyed'
		<DD>a MDI childwindow has been destroyed<br>
				wp=hwnd of the childwindow<br>
				lp=allways zero
				<br><br>
		
		<DT>'childactivated'
		<DD>a MDI childwindow has been destroyed<br>
				wp=hwnd of the childwindow being activated<br>
				lp=hwnd of the childwindow being deactivated
				<br><br>
		
		<DT>'childsizing'
		<DD>a MDI childwindow has about to resize<br>
				wp=hwnd of the childwindow being resized<br>
				lp= tuple(x, y, w, h), containing the new dimensions of the client area
				<br><br>
				
	</DL>

	


::folder:: MDIClient methods
	MDIClient windows support the following methods:

	::item:: onMSG
		<code>onMSG(hwnd, msg, wp, lp)</code><br>	
		<P>thew message handler for the MDIClient window
		</P>
	
	::item:: __iter__
		<code>__iter__()</code><br>	
		<P>Returns the hwnd of the next childwindow in turn
		</P>

	::item:: IsChild
		<code>IsChild(hwnd)</code><br>	
		<P>Retuns True if hwnd is the hwnd of a MDI childwindow of the frame, 
				False otherwise
		</P>
	
	::item:: GetChild
		<code>GetChild(hwnd)</code><br>	
		<P>Wraps methods around the hwnd of a MDI childwindow.
			<br><br>
			<b>Return value</b><br>
			A ControlFromHandle instance. You can not subclass this instance.
		</P>

	::item:: NewChild
		<code>NewChild(title, x, y, w, h, *styles, **kwargs)</code><br>	
		<P>Creates a new MDI childwindow.
		<br><br>
		<DL>
			<DT>title
			<DD>the text that will appear in the title bar
			<DT>x, y, w, h
			<DD>the desired initial dimensions
			<DT>*styles
			<DD>one or more of the following styles:
				<TABLE class="table1" BORDER="1">
				<TR>
					<TD>'maximized'</TD>
					<TD>the MDI child window is created initially maximized</TD>
				</TR>
				<TR>
					<TD></TD>
					<TD>the MDI child window is created initially minimized</TD>
				</TR>
				<TR>
					<TD>'hscroll'</TD>
					<TD>the MDI child window is created with a horizontal
						scrollbar</TD>
				</TR>
				<TR>
					<TD>'vscroll'</TD>
					<TD>the MDI child window is created with a vertical
							scrollbar</TD>
				</TR>
				</TABLE>
		
		</DL>	
			
		<br><br>
		The following keyword args are recognized:
		<DL>	
			<DT>icon
			<DD>the Icon that will appeasr in the title bar. The icon is released in
					the call so you can not use it any longer.
		</DL>
		
		
		<b>Return value</b><br>
		A ControlFromHandle instance wrapping the hwnd of the new 
		MDI childwindow
		</P>


		::item:: Activate
		<code>Activate(hwnd)</code><br>	
		<P>Activates the MDI childwindow
		</P>
	
	::item:: GetActive
		<code>GetActive()</code><br>	
		<P>Returns the hwnd of the currently active MDI child
		</P>
	
	::item:: ActivateNext
		<code>ActivateNext(hwnd=None)</code><br>	
		<P>Activates the next MDI childwindow.
		<br><br>
		If hwnd is None the next window being activated is the window emidiately 
		following the currently active window
		</P>

	::item:: ActivatePrevious
		<code>ActivatePrevious(hwnd=None)</code><br>	
		<P>Activates the previous MDI childwindow.
		<br><br>
		If hwnd is None the previous window being activated is the window emidiately 
		preceeding the currently active window
		</P>


	::item:: Destroy
		<code>Destroy(hwnd)</code><br>	
		<P>Destroys a MDI childwindow
			<br><br>
			You should not this method to destroy a childwindow, and avoid using
			the childwindow instances 'Close' method.
		</P>

	::item:: Clear
		<code>Clear()</code><br>	
		<P>Destroys all MDI childwindows, clearing the MDIClient window
		</P>
	
	
	::item:: Maximize
		<code>Maximize(hwnd)</code><br>	
		<P>Maximizes the MDI childwindow
		</P>

	::item:: IsMaximized
		<code>IsMaximized(hwnd)</code><br>	
		<P>Returns True if the MDI childwindow is maximized, False otherwise
		</P>
	
	::item:: Minimize
		<code>Minimize(hwnd)</code><br>	
		<P>Minimizes the MDI childwindow
		</P>

	::item:: IsMinimized
		<code>IsMinimized(hwnd)</code><br>	
		<P>Returns True if the MDI childwindow is minimized, False otherwise
		</P>
	
		
	::item:: Restore
		<code>Restore(hwnd)</code><br>	
		<P>Restores a MDI childwindow from maximized or minimized state
		</P>

	::item:: Cascade
		<code>Cascade(skipdisabled=True)</code><br>	
		<P>Cascades all MDI childwindows.
		<br><br>
		If 'skipdisabled' is True, disabled windows are skipped
		</P>

	::item:: Tile
		<code>Tile(flag='vertical')</code><br>	
		<P>Tiles all MDI childwindows.
		<br><br>
		'flag' can be 'vertical' to tile the childwindows vertically or 'horizontal'
		to tile them horizontally
			
		</P>

	::item:: IconArrange
		<code>IconArrange()</code><br>	
		<P>Aranges all icons of all minimized MDI childwindows
		</P>