]> git.saurik.com Git - wxWidgets.git/blob - src/motif/mdi/doc/mwindow.html
61fab7bed606af6f21ac018ea0e1698cd46ad6c1
[wxWidgets.git] / src / motif / mdi / doc / mwindow.html
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 "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>