src/motif/mdi/doc/mwindow.html

<HTML>

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

<H2>
The XsMotifWindow Class
</H2>

<P>
The <I>XsMDICanvas</I> requires that all documents be a subclass of
<I>XsMDIWindow</I> or a subclass of a class derived from it.  By itself
<I>XsMDIWindow</I> does not define any appearance or behavior for the
documents.  However, <I>XsMotifWindow</I>, derived from <I>XsMDIWindow</I>,
defines a MWM-like look-and-feel to a document.

<P>
Documents in your application should be derived from <I>XsMotifWindow</I>.
This class provides the look-and-feel of Motif window and supports the
interaction with the <I>XsMDICanvas</I>.  It is up to the application to
define the contents of each document.

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

<P>
The <I>XsMotifWindow</I> constructor accepts one argument:

<DL>
<DD>XsMotifWindow (const char *name)</DD>
</DL>

<P>
The <I>name</I> parameter specifies the name of the document and is used
as the widget name for the underlying implementation.  The name parameter
is also used as the default title and icon-name for the document.

<P>
<B>Note:</B>  The <I>XsMotifWindow</I> constructor does not create any
widgets.  Rather it only initializes internal variables.  The widgets are
not created until the document is added to the canvas.  The <I>XsMDICanvas</I>
calls the member-function <I>XsMotifWindow::_buildClientArea()</I> when it needs
to create the document widgets.

<P>
The <I>XsMotifWindow</I> destructor destroys the document widgets (if they have
been created) and frees its internal storage.  It is up to the application
to free all documents.  The <I>XsMDICanvas</I> will <B>not</B> destroy the
documents for you.

<P>
<B>Document Utilities:</B>

<P>
Although rarely called from the application, the <I>XsMotifWindow</I> supports
a number of utility functions to manipulate the document.

<DL>
<DD>virtual void raise ( )</DD>
<DD>virtual void lower ( )</DD>
<DD>virtual void minimize ( )</DD>
<DD>virtual void maximize ( )</DD>
<DD>virtual void restore ( )</DD>
<DD>virtual void close ( )</DD>
</DL>

<P>
The <I>close</I> member-function does not destroy the document, it simply
hides it from view.  You can restore a closed document with
<I>XsMotifWindow::show()</I>.

<P>
The following member-functions are used to change/query the appearance of
the document:

<DL>
<DD>void  setTitle (const char *name)</DD>
<DD>const char *title ( ) const</DD>
<DD>void  setIconName (const char *name)</DD>
<DD>const char *iconName ( ) const</DD>
<DD>void  setPixmap (Pixmap pixmap)</DD>
<DD>Pixmap pixmap ( ) const</DD>
<DD>Widget icon ( ) const</DD>
<DD>Boolean minimized ( ) const</DD>
<DD>Boolean  maximized ( ) const</DD>
<DD>virtual void setPosition (Position x, Position y)</DD>
<DD>virtual void setSize (Dimension width, Dimension height)</DD>
</DL>

<P>
The <I>setPixmap</I> member-function accepts a pixmap which the document then
uses as the decoration on the icon.  Because the document does not make a copy
of the pixmap, it is important that the application not free the pixmap until
all documents that reference it are deleted.  The document does, however, make
a local copy of the title or icon-name string passed to it, so the application
is free to do whatever it wants to the passed-in string.  The <I>icon</I>
member-function returns the widget that is used to implement the icon.


<P>
<B>Creating Window Subclasses:</B>

<P>
The application must derive its documents from <I>XsMotifWindow</I> in order to
define the contents of the document.  The <I>XsMDICanvas</I> calls the
protected member-function <I>_buildClientArea</I> when it creates the
document. Each class derived from <I>XsMotifWindow</I> <B>must</B> override
this pure-virtual member-function.

<P>
The member-function <I>_buildClientArea</I> is called with a single argument:

<DL>
<DD>virtual void _buildClientArea (Widget parent)</DD>
</DL>

The <I>parent</I> argument should be used as the parent of the contents of
the document.  This widget is an unmanaged <I>XmForm</I> widget, and all of
the standard resources and constrains apply to it.  The <I>XsMDICanvas</I>
is responsible for managing the parent widget at the appropriate time.

<P>
As an example, consider the following:

<PRE>
// _buildClientArea (called to create document contents)

void MyDocument::_buildClientArea (Widget parent)
{
   assert (parent != 0);

// Create a main window with some dummy menus

   Widget mainW = XtVaCreateWidget ("mainWin", xmMainWindowWidgetClass, parent,
      XmNtopAttachment, XmATTACH_FORM, XmNbottomAttachment, XmATTACH_FORM,
      XmNleftAttachment, XmATTACH_FORM, XmNrightAttachment, XmATTACH_FORM,
      NULL);
   ...

   XtManageChild (mainW);
}
</PRE>

<P>
In this case, an <I>XmMainWindow</I> is created as the child of the parent
widget.  The <I>XmMainWindow</I> is then attached to the 4 sides of the parent
form.  Note also that the main window is managed before returning from the
function.

<P>
<B>Resources:</B>

<P>
The <I>XsMotifWindow</I> supports the following resources:

<PRE>
   Name              Class             Type           Default
------------------------------------------------------------------------------
   borderSize        BorderSize        Dimension      6
   buttonSize        ButtonSize        Dimension      23
   title             Title             String         dynamic
   titleFont         TitleFont         String         -*-helvetica-bold-o-normal-*-14-*-*-*-*-*-iso8859-1
   iconSize          IconSize          Dimension      70
   iconName          IconName          String         dynamic
   iconFont          IconFont          String         *-helvetica-bold-r-normal-*-12-*-*-*-*-*-iso8859-1
   XmNiconX          XmCIconX          Position       dynamic
   XmNiconY          XmCIconY          Position       dynamic
   saveUnder         SaveUnder         Boolean        True
   restoreString     RestoreString     String         "Restore"
   moveString        MoveString        String         "Move"
   sizeString        SizeString        String         "Size"
   minimizeString    MinimizeString    String         "Minimize"
   maximizeString    MaximizeString    String         "Maximize"
   raiseString       RaiseString       String         "Raise"
   lowerString       LowerString       String         "Lower"
   closeString       CloseString       String         "Close"
   menuFont          MenuFont          String         -*-helvetica-bold-o-normal-*-14-*-*-*-*-*-iso8859-1
   showBorder        ShowBorder        Boolean        True
   showResize        ShowResize        Boolean        True
   showTitle         ShowTitle         Boolean        True
   showMenu          ShowMenu          Boolean        True
   showMinimize      ShowMinimize      Boolean        True
   showMaximize      ShowMaximize      Boolean        True
   lowerOnIconify    LowerOnIconify    Boolean        False
   XmNminWidth       XmCMinWidth       Dimension      dynamic
   XmNmaxWidth       XmCMaxWidth       Dimension      dynamic
   XmNminHeight      XmCMinHeight      Dimension      dynamic
   XmNmaxHeight      XmCMaxHeight      Dimension      dynamic
</PRE>

<DL>
<DD>
<DL>
<DT>borderSize</DT>
<DD>Size of the window border.</DD>
<DT>buttonSize</DT>
<DD>Size of the window buttons.</DD>
<DT>title</DT>
<DD>Title of the window.  The default is the name of the window instance.</DD>
<DT>titleFont</DT>
<DD>Font used to draw the window title.</DD>
<DT>iconSize</DT>
<DD>Size of the icon representation.</DD>
<DT>iconName</DT>
<DD>String used on the title.  If unspecified, the window title is used.</DD>
<DT>iconFont</DT>
<DD>Font used to draw the icon-name.</DD>
<DT>XmNiconX</DT>
<DD>X-position of the icon.  The default location is the top-left
corner of the window when it is iconified.</DD>
<DT>XmNiconY</DT>
<DD>Y-position of the icon.  The default location is the top-left
corner of the window when it is iconified.</DD>
<DT>saveUnder</DT>
<DD>Enables/Disables save-unders for the menu.</DD>
<DT>restoreString</DT>
<DD>String used as the "restore" menu item.</DD>
<DT>moveString</DT>
<DD>String used as the "move" menu item.</DD>
<DT>sizeString</DT>
<DD>String used as the "size" menu item.</DD>
<DT>minimizeString</DT>
<DD>String used as the "minimize" menu item.</DD>
<DT>maximizeString</DT>
<DD>String used as the "maximize" menu item.</DD>
<DT>raiseString</DT>
<DD>String used as the "raise" menu item.</DD>
<DT>lowerString</DT>
<DD>String used as the the "lower" menu item.</DD>
<DT>closeString</DT>
<DD>String used as the "close" menu item.</DD>
<DT>menuFont</DT>
<DD>Font used to draw the menu strings.</DD>
<DT>showBorder</DT>
<DD>Enables/Disables the window border.  If the border is disabled,
the resize-handles are automatically disabled.</DD>
<DT>showResize</DT>
<DD>Enables/Disables the window resize handles.</DD>
<DT>showTitle</DT>
<DD>Enables/Disables the window title.  If the title is disabled,
all of the window buttons are automatically disabled.</DD>
<DT>showMenu</DT>
<DD>Enables/Disables the window menu button.</DD>
<DT>showMinimize</DT>
<DD>Enables/Disables the window minimize button.</DD>
<DT>showMaximize</DT>
<DD>Enables/Disables the window maximize button.</DD>
<DT>lowerOnIconify</DT>
<DD>Automatically lower windows when iconified.</DD>
<DT>XmNminWidth</DT>
<DD>Minimium window width.  The default is about four times the size of
the window button.</DD>
<DT>XmNmaxWidth</DT>
<DD>Maximum window width.  The default is not to constrain the maximum size.</DD>
<DT>XmNminHeight</DT>
<DD>Minimum window height.  The default is about four times the size of
the window button.</DD>
<DT>XmNmaxHeight</DT>
<DD>Maximum window height.  The default is not to constrain the maximum size.</DD>
</DL>
</DD>
</DL>

<P>
<B>XsMotifWindow Implementation:</B>

<P>
As a convenience to those who wish to modify the <I>XsMotifWindow</I> code,
here is a diagram of the internal class structure:

<P>
<IMG SRC="pics/winclass.gif" ALT="[Class Structure]">

</BODY>
</HTML>
Commit	Line	Data
	1	<HTML>
	2
	3	<HEAD>
	4	<TITLE>XsMotifWindow Class</TITLE>
	5	<LINK REV="made" HREF="mailto:ssadler@cisco.com">
	6	</HEAD>
	7
	8	<H2>
	9	The XsMotifWindow Class
	10	</H2>
	11
	12	<P>
	13	The <I>XsMDICanvas</I> requires that all documents be a subclass of
	14	<I>XsMDIWindow</I> or a subclass of a class derived from it. By itself
	15	<I>XsMDIWindow</I> does not define any appearance or behavior for the
	16	documents. However, <I>XsMotifWindow</I>, derived from <I>XsMDIWindow</I>,
	17	defines a MWM-like look-and-feel to a document.
	18
	19	<P>
	20	Documents in your application should be derived from <I>XsMotifWindow</I>.
	21	This class provides the look-and-feel of Motif window and supports the
	22	interaction with the <I>XsMDICanvas</I>. It is up to the application to
	23	define the contents of each document.
	24
	25	<P>
	26	<B>Constructor and Destructor:</B>
	27
	28	<P>
	29	The <I>XsMotifWindow</I> constructor accepts one argument:
	30
	31	<DL>
	32	<DD>XsMotifWindow (const char *name)</DD>
	33	</DL>
	34
	35	<P>
	36	The <I>name</I> parameter specifies the name of the document and is used
	37	as the widget name for the underlying implementation. The name parameter
	38	is also used as the default title and icon-name for the document.
	39
	40	<P>
	41	<B>Note:</B> The <I>XsMotifWindow</I> constructor does not create any
	42	widgets. Rather it only initializes internal variables. The widgets are
	43	not created until the document is added to the canvas. The <I>XsMDICanvas</I>
	44	calls the member-function <I>XsMotifWindow::_buildClientArea()</I> when it needs
	45	to create the document widgets.
	46
	47	<P>
	48	The <I>XsMotifWindow</I> destructor destroys the document widgets (if they have
	49	been created) and frees its internal storage. It is up to the application
	50	to free all documents. The <I>XsMDICanvas</I> will <B>not</B> destroy the
	51	documents for you.
	52
	53	<P>
	54	<B>Document Utilities:</B>
	55
	56	<P>
	57	Although rarely called from the application, the <I>XsMotifWindow</I> supports
	58	a number of utility functions to manipulate the document.
	59
	60	<DL>
	61	<DD>virtual void raise ( )</DD>
	62	<DD>virtual void lower ( )</DD>
	63	<DD>virtual void minimize ( )</DD>
	64	<DD>virtual void maximize ( )</DD>
	65	<DD>virtual void restore ( )</DD>
	66	<DD>virtual void close ( )</DD>
	67	</DL>
	68
	69	<P>
	70	The <I>close</I> member-function does not destroy the document, it simply
	71	hides it from view. You can restore a closed document with
	72	<I>XsMotifWindow::show()</I>.
	73
	74	<P>
	75	The following member-functions are used to change/query the appearance of
	76	the document:
	77
	78	<DL>
	79	<DD>void setTitle (const char *name)</DD>
	80	<DD>const char *title ( ) const</DD>
	81	<DD>void setIconName (const char *name)</DD>
	82	<DD>const char *iconName ( ) const</DD>
	83	<DD>void setPixmap (Pixmap pixmap)</DD>
	84	<DD>Pixmap pixmap ( ) const</DD>
	85	<DD>Widget icon ( ) const</DD>
	86	<DD>Boolean minimized ( ) const</DD>
	87	<DD>Boolean maximized ( ) const</DD>
	88	<DD>virtual void setPosition (Position x, Position y)</DD>
	89	<DD>virtual void setSize (Dimension width, Dimension height)</DD>
	90	</DL>
	91
	92	<P>
	93	The <I>setPixmap</I> member-function accepts a pixmap which the document then
	94	uses as the decoration on the icon. Because the document does not make a copy
	95	of the pixmap, it is important that the application not free the pixmap until
	96	all documents that reference it are deleted. The document does, however, make
	97	a local copy of the title or icon-name string passed to it, so the application
	98	is free to do whatever it wants to the passed-in string. The <I>icon</I>
	99	member-function returns the widget that is used to implement the icon.
	100
	101
	102	<P>
	103	<B>Creating Window Subclasses:</B>
	104
	105	<P>
	106	The application must derive its documents from <I>XsMotifWindow</I> in order to
	107	define the contents of the document. The <I>XsMDICanvas</I> calls the
	108	protected member-function <I>_buildClientArea</I> when it creates the
	109	document. Each class derived from <I>XsMotifWindow</I> <B>must</B> override
	110	this pure-virtual member-function.
	111
	112	<P>
	113	The member-function <I>_buildClientArea</I> is called with a single argument:
	114
	115	<DL>
	116	<DD>virtual void _buildClientArea (Widget parent)</DD>
	117	</DL>
	118
	119	The <I>parent</I> argument should be used as the parent of the contents of
	120	the document. This widget is an unmanaged <I>XmForm</I> widget, and all of
	121	the standard resources and constrains apply to it. The <I>XsMDICanvas</I>
	122	is responsible for managing the parent widget at the appropriate time.
	123
	124	<P>
	125	As an example, consider the following:
	126
	127	<PRE>
	128	// _buildClientArea (called to create document contents)
	129
	130	void MyDocument::_buildClientArea (Widget parent)
	131	{
	132	assert (parent != 0);
	133
	134	// Create a main window with some dummy menus
	135
	136	Widget mainW = XtVaCreateWidget ("mainWin", xmMainWindowWidgetClass, parent,
	137	XmNtopAttachment, XmATTACH_FORM, XmNbottomAttachment, XmATTACH_FORM,
	138	XmNleftAttachment, XmATTACH_FORM, XmNrightAttachment, XmATTACH_FORM,
	139	NULL);
	140	...
	141
	142	XtManageChild (mainW);
	143	}
	144	</PRE>
	145
	146	<P>
	147	In this case, an <I>XmMainWindow</I> is created as the child of the parent
	148	widget. The <I>XmMainWindow</I> is then attached to the 4 sides of the parent
	149	form. Note also that the main window is managed before returning from the
	150	function.
	151
	152	<P>
	153	<B>Resources:</B>
	154
	155	<P>
	156	The <I>XsMotifWindow</I> supports the following resources:
	157
	158	<PRE>
	159	Name Class Type Default
	160	------------------------------------------------------------------------------
	161	borderSize BorderSize Dimension 6
	162	buttonSize ButtonSize Dimension 23
	163	title Title String dynamic
	164	titleFont TitleFont String --helvetica-bold-o-normal--14-----*-iso8859-1
	165	iconSize IconSize Dimension 70
	166	iconName IconName String dynamic
	167	iconFont IconFont String -helvetica-bold-r-normal--12-----*-iso8859-1
	168	XmNiconX XmCIconX Position dynamic
	169	XmNiconY XmCIconY Position dynamic
	170	saveUnder SaveUnder Boolean True
	171	restoreString RestoreString String "Restore"
	172	moveString MoveString String "Move"
	173	sizeString SizeString String "Size"
	174	minimizeString MinimizeString String "Minimize"
	175	maximizeString MaximizeString String "Maximize"
	176	raiseString RaiseString String "Raise"
	177	lowerString LowerString String "Lower"
	178	closeString CloseString String "Close"
	179	menuFont MenuFont String --helvetica-bold-o-normal--14-----*-iso8859-1
	180	showBorder ShowBorder Boolean True
	181	showResize ShowResize Boolean True
	182	showTitle ShowTitle Boolean True
	183	showMenu ShowMenu Boolean True
	184	showMinimize ShowMinimize Boolean True
	185	showMaximize ShowMaximize Boolean True
	186	lowerOnIconify LowerOnIconify Boolean False
	187	XmNminWidth XmCMinWidth Dimension dynamic
	188	XmNmaxWidth XmCMaxWidth Dimension dynamic
	189	XmNminHeight XmCMinHeight Dimension dynamic
	190	XmNmaxHeight XmCMaxHeight Dimension dynamic
	191	</PRE>
	192
	193	<DL>
	194	<DD>
	195	<DL>
	196	<DT>borderSize</DT>
	197	<DD>Size of the window border.</DD>
	198	<DT>buttonSize</DT>
	199	<DD>Size of the window buttons.</DD>
	200	<DT>title</DT>
	201	<DD>Title of the window. The default is the name of the window instance.</DD>
	202	<DT>titleFont</DT>
	203	<DD>Font used to draw the window title.</DD>
	204	<DT>iconSize</DT>
	205	<DD>Size of the icon representation.</DD>
	206	<DT>iconName</DT>
	207	<DD>String used on the title. If unspecified, the window title is used.</DD>
	208	<DT>iconFont</DT>
	209	<DD>Font used to draw the icon-name.</DD>
	210	<DT>XmNiconX</DT>
	211	<DD>X-position of the icon. The default location is the top-left
	212	corner of the window when it is iconified.</DD>
	213	<DT>XmNiconY</DT>
	214	<DD>Y-position of the icon. The default location is the top-left
	215	corner of the window when it is iconified.</DD>
	216	<DT>saveUnder</DT>
	217	<DD>Enables/Disables save-unders for the menu.</DD>
	218	<DT>restoreString</DT>
	219	<DD>String used as the "restore" menu item.</DD>
	220	<DT>moveString</DT>
	221	<DD>String used as the "move" menu item.</DD>
	222	<DT>sizeString</DT>
	223	<DD>String used as the "size" menu item.</DD>
	224	<DT>minimizeString</DT>
	225	<DD>String used as the "minimize" menu item.</DD>
	226	<DT>maximizeString</DT>
	227	<DD>String used as the "maximize" menu item.</DD>
	228	<DT>raiseString</DT>
	229	<DD>String used as the "raise" menu item.</DD>
	230	<DT>lowerString</DT>
	231	<DD>String used as the the "lower" menu item.</DD>
	232	<DT>closeString</DT>
	233	<DD>String used as the "close" menu item.</DD>
	234	<DT>menuFont</DT>
	235	<DD>Font used to draw the menu strings.</DD>
	236	<DT>showBorder</DT>
	237	<DD>Enables/Disables the window border. If the border is disabled,
	238	the resize-handles are automatically disabled.</DD>
	239	<DT>showResize</DT>
	240	<DD>Enables/Disables the window resize handles.</DD>
	241	<DT>showTitle</DT>
	242	<DD>Enables/Disables the window title. If the title is disabled,
	243	all of the window buttons are automatically disabled.</DD>
	244	<DT>showMenu</DT>
	245	<DD>Enables/Disables the window menu button.</DD>
	246	<DT>showMinimize</DT>
	247	<DD>Enables/Disables the window minimize button.</DD>
	248	<DT>showMaximize</DT>
	249	<DD>Enables/Disables the window maximize button.</DD>
	250	<DT>lowerOnIconify</DT>
	251	<DD>Automatically lower windows when iconified.</DD>
	252	<DT>XmNminWidth</DT>
	253	<DD>Minimium window width. The default is about four times the size of
	254	the window button.</DD>
	255	<DT>XmNmaxWidth</DT>
	256	<DD>Maximum window width. The default is not to constrain the maximum size.</DD>
	257	<DT>XmNminHeight</DT>
	258	<DD>Minimum window height. The default is about four times the size of
	259	the window button.</DD>
	260	<DT>XmNmaxHeight</DT>
	261	<DD>Maximum window height. The default is not to constrain the maximum size.</DD>
	262	</DL>
	263	</DD>
	264	</DL>
	265
	266	<P>
	267	<B>XsMotifWindow Implementation:</B>
	268
	269	<P>
	270	As a convenience to those who wish to modify the <I>XsMotifWindow</I> code,
	271	here is a diagram of the internal class structure:
	272
	273	<P>
	274	<IMG SRC="pics/winclass.gif" ALT="[Class Structure]">
	275
	276	</BODY>
	277	</HTML>