]>
Commit | Line | Data |
---|---|---|
8704bf74 JS |
1 | <HTML> |
2 | ||
3 | <HEAD> | |
4 | <TITLE>XsMotifWindow Class</TITLE> | |
0d57be45 | 5 | <LINK REV="made" HREF="mailto:ssadler@cisco.com"> |
8704bf74 JS |
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> | |
4c51a665 | 231 | <DD>String used as the "lower" menu item.</DD> |
8704bf74 JS |
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> |