[wxWidgets.git] / src / motif / mdi / doc / canvas.html

<HTML>

<HEAD>
<TITLE>XsMDICanvas Class</TITLE>
<LINK REV="made" HREF="mailto:ssadler@cisco.com">
</HEAD>

<H2>
The XsMDICanvas Class
</H2>

<P>
This section describes how to build and manipulate an MDI using the
<I>XsMDICanvas</I> class.  Minimally, you must perform the following actions
to build and display an MDI canvas:

<OL>
<LI>Create the <I>XsMDICanvas</I> object.</LI>
<LI>Create the documents as instances of subclasses of <I>XsMDIWindow</I>.</LI>
<LI>Add the documents to the canvas</LI>
<LI>Show the canvas</LI>
</OL>

<P>
<B>Constructor and Destructor:</B>

<P>
The <I>XsMDICanvas</I> accepts two arguments:

<DL>
<DD>XsMDICanvas (const char *name, Widget parent)</DD>
</DL>

<P>
The <I>name</I> parameter specifies the name of the canvas and is used
as the widget name for the underlying implementation.  The <I>parent</I>
parameter specifies the widget that is to be used as the parent of the
canvas.

<P>
The <I>XsMDICanvas</I> destructor destroys the canvas, but it <B>does not</B>
destroy any of the underlying documents.  It is up to the application to
destroy these.

<P>
<B>Adding and removing documents:</B>

<P>
After the documents are created, they must be added to the canvas.  The
<I>XsMDICanvas::add()</I> member-function adds documents to the canvas:

<DL>
<DD>virtual void add (XsMDIWindow *window)</DD>
</DL>

<P>
The behaviour of adding the same document to the canvas more than once
is undefined.  Documents can be removed from the canvas by using:

<DL>
<DD>virtual void remove (XsMDIWindow *window)</DD>
</DL>

<P>
Additionally, all documents can be removed from the canvas with:

<DL>
<DD>void removeAll ( )</DD>
</DL>

<P>
The number of documents currently installed in the canvas can be
retrieved with:

<DL>
<DD>int numWindows ( ) const</DD>
</DL>

<P>
<B>Showing the canvas:</B>

<P>
In order to show (manage) the canvas call the <I>show</I> member function:

<DL>
<DD>virtual void show ( )</DD>
</DL>

This member-function is responsible for cycling all of the installed documents
and calling their respective <I>XsMDIWindow::_buildClientArea()</I>
member-functions.  After each document has been created, <I>show</I> will then
manage each document and, finally, itself.

<P>
<B>Window Placement:</B>

<P>
The current implementation of <I>XsMDICanvas</I> uses a very simple algorithm
to place the documents on the canvas.  In order to implement a more specific
placement algorithm, derive a class from <I>XsMDICanvas</I> and override
the member-function:

<DL>
<DD>virtual  void _placeWindow (XsMDIWindow *win)</DD>
</DL>

<P>
This member-function is called for each document in the canvas to compute
the location of the document.  Please refer to the code (<I>XsMDICanvas.C</I>)
for more details.

<P>
<B>Canvas Behaviour:</B>

<P>
The <I>XsMDICanvas</I> is implemented as an <I>XmScrolledWindow</I> with an
<I>XmDrawingArea</I> work-window.  The instance name for the work-window
is <I>canvas</I>.  Internal callbacks in the canvas class force the work-window
to be at-least the size of the clip-window.  This prevents documents from
being clipped as they are moved around.  

<P>
By default, the <I>XmDrawingArea</I> work-window has its <I>XmNresizePolicy</I>
set to <I>XmRESIZE_GROW</I>.  This will allow the work-area to grow to
whatever size necessary, but it will not automatically shrink as windows
are manipulated.  If different behaviour is desired, the <I>XmNresizePolicy</I>
resource on the work-area can be set to <I>XmRESIZE_ANY</I>.  This will
force the work-window to recompute its size as windows are manipulated, and
it will grow and shrink as necessary.  However, the <I>XsMDICanvas</I> will
still force the work-area to be at-least the size of the clip-window.

<P>To change the default behaviour, add the following resource:

<DL>
<DD>&ltXsMDICanvas name&gt*canvas.resizePolicy:   XmRESIZE_ANY</DD>
</DL>

</BODY>
</HTML>
Commit	Line	Data
8704bf74 JS	1	<HTML>
	2
	3	<HEAD>
	4	<TITLE>XsMDICanvas Class</TITLE>
0d57be45	5	<LINK REV="made" HREF="mailto:ssadler@cisco.com">
8704bf74 JS	6	</HEAD>
	7
	8	<H2>
	9	The XsMDICanvas Class
	10	</H2>
	11
	12	<P>
	13	This section describes how to build and manipulate an MDI using the
	14	<I>XsMDICanvas</I> class. Minimally, you must perform the following actions
	15	to build and display an MDI canvas:
	16
	17	<OL>
	18	<LI>Create the <I>XsMDICanvas</I> object.</LI>
	19	<LI>Create the documents as instances of subclasses of <I>XsMDIWindow</I>.</LI>
	20	<LI>Add the documents to the canvas</LI>
	21	<LI>Show the canvas</LI>
	22	</OL>
	23
	24	<P>
	25	<B>Constructor and Destructor:</B>
	26
	27	<P>
	28	The <I>XsMDICanvas</I> accepts two arguments:
	29
	30	<DL>
	31	<DD>XsMDICanvas (const char *name, Widget parent)</DD>
	32	</DL>
	33
	34	<P>
	35	The <I>name</I> parameter specifies the name of the canvas and is used
	36	as the widget name for the underlying implementation. The <I>parent</I>
	37	parameter specifies the widget that is to be used as the parent of the
	38	canvas.
	39
	40	<P>
	41	The <I>XsMDICanvas</I> destructor destroys the canvas, but it <B>does not</B>
	42	destroy any of the underlying documents. It is up to the application to
	43	destroy these.
	44
	45	<P>
	46	<B>Adding and removing documents:</B>
	47
	48	<P>
	49	After the documents are created, they must be added to the canvas. The
	50	<I>XsMDICanvas::add()</I> member-function adds documents to the canvas:
	51
	52	<DL>
	53	<DD>virtual void add (XsMDIWindow *window)</DD>
	54	</DL>
	55
	56	<P>
4c51a665	57	The behaviour of adding the same document to the canvas more than once
8704bf74 JS	58	is undefined. Documents can be removed from the canvas by using:
	59
	60	<DL>
	61	<DD>virtual void remove (XsMDIWindow *window)</DD>
	62	</DL>
	63
	64	<P>
	65	Additionally, all documents can be removed from the canvas with:
	66
	67	<DL>
	68	<DD>void removeAll ( )</DD>
	69	</DL>
	70
	71	<P>
	72	The number of documents currently installed in the canvas can be
	73	retrieved with:
	74
	75	<DL>
	76	<DD>int numWindows ( ) const</DD>
	77	</DL>
	78
	79	<P>
	80	<B>Showing the canvas:</B>
	81
	82	<P>
	83	In order to show (manage) the canvas call the <I>show</I> member function:
	84
	85	<DL>
	86	<DD>virtual void show ( )</DD>
	87	</DL>
	88
	89	This member-function is responsible for cycling all of the installed documents
	90	and calling their respective <I>XsMDIWindow::_buildClientArea()</I>
	91	member-functions. After each document has been created, <I>show</I> will then
	92	manage each document and, finally, itself.
	93
	94	<P>
	95	<B>Window Placement:</B>
	96
	97	<P>
	98	The current implementation of <I>XsMDICanvas</I> uses a very simple algorithm
	99	to place the documents on the canvas. In order to implement a more specific
	100	placement algorithm, derive a class from <I>XsMDICanvas</I> and override
	101	the member-function:
	102
	103	<DL>
	104	<DD>virtual void _placeWindow (XsMDIWindow *win)</DD>
	105	</DL>
	106
	107	<P>
	108	This member-function is called for each document in the canvas to compute
	109	the location of the document. Please refer to the code (<I>XsMDICanvas.C</I>)
	110	for more details.
	111
	112	<P>
4c51a665	113	<B>Canvas Behaviour:</B>
8704bf74 JS	114
	115	<P>
	116	The <I>XsMDICanvas</I> is implemented as an <I>XmScrolledWindow</I> with an
	117	<I>XmDrawingArea</I> work-window. The instance name for the work-window
	118	is <I>canvas</I>. Internal callbacks in the canvas class force the work-window
	119	to be at-least the size of the clip-window. This prevents documents from
	120	being clipped as they are moved around.
	121
	122	<P>
	123	By default, the <I>XmDrawingArea</I> work-window has its <I>XmNresizePolicy</I>
	124	set to <I>XmRESIZE_GROW</I>. This will allow the work-area to grow to
	125	whatever size necessary, but it will not automatically shrink as windows
4c51a665	126	are manipulated. If different behaviour is desired, the <I>XmNresizePolicy</I>
8704bf74 JS	127	resource on the work-area can be set to <I>XmRESIZE_ANY</I>. This will
	128	force the work-window to recompute its size as windows are manipulated, and
	129	it will grow and shrink as necessary. However, the <I>XsMDICanvas</I> will
	130	still force the work-area to be at-least the size of the clip-window.
	131
4c51a665	132	<P>To change the default behaviour, add the following resource:
8704bf74 JS	133
	134	<DL>
	135	<DD>&ltXsMDICanvas name&gt*canvas.resizePolicy: XmRESIZE_ANY</DD>
	136	</DL>
	137
	138	</BODY>
	139	</HTML>
	140