]> git.saurik.com Git - wxWidgets.git/blame - src/motif/mdi/doc/mwindow.html
wxMessageBox off the main thread lost result code.
[wxWidgets.git] / src / motif / mdi / doc / mwindow.html
CommitLineData
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>
9The XsMotifWindow Class
10</H2>
11
12<P>
13The <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
16documents. However, <I>XsMotifWindow</I>, derived from <I>XsMDIWindow</I>,
17defines a MWM-like look-and-feel to a document.
18
19<P>
20Documents in your application should be derived from <I>XsMotifWindow</I>.
21This class provides the look-and-feel of Motif window and supports the
22interaction with the <I>XsMDICanvas</I>. It is up to the application to
23define the contents of each document.
24
25<P>
26<B>Constructor and Destructor:</B>
27
28<P>
29The <I>XsMotifWindow</I> constructor accepts one argument:
30
31<DL>
32<DD>XsMotifWindow (const char *name)</DD>
33</DL>
34
35<P>
36The <I>name</I> parameter specifies the name of the document and is used
37as the widget name for the underlying implementation. The name parameter
38is 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
42widgets. Rather it only initializes internal variables. The widgets are
43not created until the document is added to the canvas. The <I>XsMDICanvas</I>
44calls the member-function <I>XsMotifWindow::_buildClientArea()</I> when it needs
45to create the document widgets.
46
47<P>
48The <I>XsMotifWindow</I> destructor destroys the document widgets (if they have
49been created) and frees its internal storage. It is up to the application
50to free all documents. The <I>XsMDICanvas</I> will <B>not</B> destroy the
51documents for you.
52
53<P>
54<B>Document Utilities:</B>
55
56<P>
57Although rarely called from the application, the <I>XsMotifWindow</I> supports
58a 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>
70The <I>close</I> member-function does not destroy the document, it simply
71hides it from view. You can restore a closed document with
72<I>XsMotifWindow::show()</I>.
73
74<P>
75The following member-functions are used to change/query the appearance of
76the 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>
93The <I>setPixmap</I> member-function accepts a pixmap which the document then
94uses as the decoration on the icon. Because the document does not make a copy
95of the pixmap, it is important that the application not free the pixmap until
96all documents that reference it are deleted. The document does, however, make
97a local copy of the title or icon-name string passed to it, so the application
98is free to do whatever it wants to the passed-in string. The <I>icon</I>
99member-function returns the widget that is used to implement the icon.
100
101
102<P>
103<B>Creating Window Subclasses:</B>
104
105<P>
106The application must derive its documents from <I>XsMotifWindow</I> in order to
107define the contents of the document. The <I>XsMDICanvas</I> calls the
108protected member-function <I>_buildClientArea</I> when it creates the
109document. Each class derived from <I>XsMotifWindow</I> <B>must</B> override
110this pure-virtual member-function.
111
112<P>
113The 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
119The <I>parent</I> argument should be used as the parent of the contents of
120the document. This widget is an unmanaged <I>XmForm</I> widget, and all of
121the standard resources and constrains apply to it. The <I>XsMDICanvas</I>
122is responsible for managing the parent widget at the appropriate time.
123
124<P>
125As an example, consider the following:
126
127<PRE>
128// _buildClientArea (called to create document contents)
129
130void 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>
147In this case, an <I>XmMainWindow</I> is created as the child of the parent
148widget. The <I>XmMainWindow</I> is then attached to the 4 sides of the parent
149form. Note also that the main window is managed before returning from the
150function.
151
152<P>
153<B>Resources:</B>
154
155<P>
156The <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
212corner 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
215corner 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,
238the 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,
243all 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
254the 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
259the 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>
270As a convenience to those who wish to modify the <I>XsMotifWindow</I> code,
271here 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>