1 | .COMMENT SCCS_data: @(#) Xmp.man 1.3 92/11/02 08:36:37 |
---|
2 | .TH "Xmp" 1 "1 March 1992" |
---|
3 | .SH NAME |
---|
4 | Xmp \- Motif Public Library |
---|
5 | .SH SYNOPSIS |
---|
6 | .ta 1.5i 2.5i |
---|
7 | .nf |
---|
8 | .ft B |
---|
9 | #include <X11/Intrinsic.h> |
---|
10 | #include <X11/Wc/WcCreate.h> |
---|
11 | #include <X11/Xmp/Xmp.h> |
---|
12 | |
---|
13 | /* All Wcl applications should provide at least the Wcl options: |
---|
14 | */ |
---|
15 | static XrmOptionDescRec options[] = { |
---|
16 | ... application specific command line options ... |
---|
17 | WCL_XRM_OPTIONS |
---|
18 | }; |
---|
19 | |
---|
20 | main ( argc, argv ) |
---|
21 | int argc; |
---|
22 | char* argv[]; |
---|
23 | { |
---|
24 | /* -- Intialize Toolkit creating the application shell |
---|
25 | */ |
---|
26 | Widget appShell = XtInitialize ( |
---|
27 | argv[0], WcAppClass( argc, argv ), /* app name & class */ |
---|
28 | options, XtNumber(options), /* argv option descr */ |
---|
29 | &argc, argv |
---|
30 | ); |
---|
31 | XtAppContext app = XtWidgetToApplicationContext(appShell); |
---|
32 | |
---|
33 | /* -- Register application specific callbacks and widget classes |
---|
34 | */ |
---|
35 | RegisterApplication ( app ); |
---|
36 | |
---|
37 | /* -- Register all widget classes and constructors |
---|
38 | */ |
---|
39 | XmpRegisterMotif( app ); |
---|
40 | |
---|
41 | /* -- Create widget tree below toplevel shell using Xrm database |
---|
42 | */ |
---|
43 | if ( WcWidgetCreation ( appShell ) ) |
---|
44 | exit(1); |
---|
45 | |
---|
46 | /* -- Realize the widget tree |
---|
47 | */ |
---|
48 | XtRealizeWidget ( appShell ); |
---|
49 | |
---|
50 | /* -- Catch `Close' from mwm menu on top level shell. |
---|
51 | */ |
---|
52 | XmpAddMwmCloseCallback( appShell, DeleteWindowCB, clientData ); |
---|
53 | |
---|
54 | /* -- and finally, enter the main application loop |
---|
55 | */ |
---|
56 | XtMainLoop ( ); |
---|
57 | } |
---|
58 | .fi |
---|
59 | .ft R |
---|
60 | |
---|
61 | .SH LINK BY |
---|
62 | .RS |
---|
63 | .nf |
---|
64 | .ft B |
---|
65 | example% ld -o prog prog.o -lXmp -lXm -lWc <dynLinkLib> -lXmu -lXt -lX11 |
---|
66 | .ft R |
---|
67 | .RE |
---|
68 | .LP |
---|
69 | On SunOS or SVR4 machines, the <dynLinkLib> is named -ldl. |
---|
70 | Other architectures cannot use the dynamic linking capabilites of |
---|
71 | Wcl, and therefore do not need any dynamic link library. |
---|
72 | .SH DESCRIPTION |
---|
73 | .LP |
---|
74 | .I Xmp |
---|
75 | is intended to be used with |
---|
76 | .I Wcl |
---|
77 | and the Motif widget set. Xmp provides a procedure for registering all |
---|
78 | Motif widgets, and convenience functions frequently needed by Motif |
---|
79 | applications. |
---|
80 | .SH REGISTRATION PROCEDURES |
---|
81 | .LP |
---|
82 | .I Wcl |
---|
83 | must be told the names of all widgets and widget constructors before |
---|
84 | it can create widgets as specified in the resource file of client |
---|
85 | applications. |
---|
86 | .I Xmp |
---|
87 | provides a registration procedure for registering all Motif widgets. |
---|
88 | For backward compatibility with previous releases of Wcl, this |
---|
89 | registration procedure has three names: MriRegisterMotif(), |
---|
90 | XmpRegisterAll(), and XmpRegisterMotif(). These procedures |
---|
91 | are exactly equivalent. |
---|
92 | .TP |
---|
93 | .B void XmpRegisterMotif( XtAppContext ) |
---|
94 | This procedure registers all of the Motif widget class pointer names, |
---|
95 | widget class names, and widget constructor function names with Wcl. |
---|
96 | It also registers all Xmp converters and action procedures with Xt, |
---|
97 | and all Xmp callback procedures with Wcl. |
---|
98 | .SH CONVERTERS |
---|
99 | .LP |
---|
100 | .I Xmp |
---|
101 | provides converters which are useful for specifying look and feel |
---|
102 | attributes of Motif user interfaces from resource files. It causes |
---|
103 | the WcCvtStringToWidget() converter to be invoked for setting |
---|
104 | constraints and menuIds. WcCvtStringToWidget() uses WcFullNameToWidget() |
---|
105 | to resolve the name, so the Wcl relative path naming conventions can |
---|
106 | be used to navigate the widget tree to find a specific widget. |
---|
107 | .LP |
---|
108 | .I Xmp |
---|
109 | causes the XmpCvtStringToXmString() |
---|
110 | converter to be invoked to provide multi-line labels to Motif |
---|
111 | widgets. This converter uses XmStringCreateLtoR() and the |
---|
112 | XmSTRING_DEFAULT_CHARSET to convert strings in the resource database |
---|
113 | into XmStrings. XmStringCreateLtoR() recognizes the two characters |
---|
114 | "\n" (backslash followed by a lower case "n"), and causes the XmString |
---|
115 | to break to a new line. Hence, "Hello\nThere" ends up being a two |
---|
116 | line label on an XmLabel. |
---|
117 | .SH ACTIONS AND CALLBACKS |
---|
118 | .LP |
---|
119 | Most Xmp actions are available as callbacks, and all callbacks are |
---|
120 | available as actions. The provided procedures, as named in the |
---|
121 | resource database, are as follows: |
---|
122 | .nf |
---|
123 | .ft B |
---|
124 | XmpFixTranslations( widget [widget ...] ) |
---|
125 | XmpAddMwmCloseCallback( widget callback(args) [callback(args) ...] ) |
---|
126 | XmpAddTabGroup( [widget] ) |
---|
127 | XmpTableChildConfig( widget col row [h_span [v_span [opts]]] ) |
---|
128 | XmpTableChildPosition( widget col row ) |
---|
129 | XmpTableChildResize( widget h_span v_span ) |
---|
130 | XmpTableChildOptions( widget options ) |
---|
131 | XmpPopup( widget ) |
---|
132 | .ft R |
---|
133 | .fi |
---|
134 | .LP |
---|
135 | Each callback procedure can also be named in resource files as |
---|
136 | the name of the procedure followed by CB: i.e, XmpFixTranslations() |
---|
137 | can also be invoked as a callback by giving the name XmpFixTranslationsCB() |
---|
138 | for a callback resource value. Also, each action procedure can also |
---|
139 | be named by appending ACT to the procedure name. Normally, I just use the |
---|
140 | procedure name, so it is less trouble to change behavior from callbacks |
---|
141 | to actions triggered by translations or accelerators, and vice versa. |
---|
142 | The CB and ACT endings are maintained for backward compatibility, and |
---|
143 | because some people like to be more explicit. It is all a matter of taste. |
---|
144 | .LP |
---|
145 | Arguments to the procedures are provided as strings, the characters |
---|
146 | between the parenthesis following the procedure name. If no parenthesis |
---|
147 | follow the procedure name, then a NULL string is passed to the procedure. |
---|
148 | Some procedures require arguments, some provide reasonable defaults when |
---|
149 | no arguments are given. For example: |
---|
150 | .RS |
---|
151 | .nf |
---|
152 | .ft B |
---|
153 | *foo.wcCreate: XmText |
---|
154 | *foo.wcCallback: XmpFixTranslations( this ^that ) |
---|
155 | |
---|
156 | *bar.wcCreate: XmPushButton |
---|
157 | *bar.activateCallback: XmpAddTabGroup |
---|
158 | .ft R |
---|
159 | .RE |
---|
160 | .LP |
---|
161 | Each |
---|
162 | .I Xmp |
---|
163 | procedure is discussed in detail below. |
---|
164 | .TP |
---|
165 | .B XmpFixTranslations( widget [widget ...] ) |
---|
166 | This works on XmText widgets only, and has the effect of fixing |
---|
167 | translations which get hammered when XmText widgets are put into |
---|
168 | dialogs. Normally, pressing newline in a multi-line text widget |
---|
169 | does a newline action. In a dialog, pressing return causes the |
---|
170 | dialog to go away. |
---|
171 | .TP |
---|
172 | .B XmpAddMwmCloseCallback( widget callback(args) [callback(args) ...] ) |
---|
173 | The callbacks are invoked in an Xt dependent order when the named widget |
---|
174 | receives the WM_DELETE_WINDOW or WM_SAVE_YOURSELF protocol event. Each |
---|
175 | of the named callbacks are added to the widget using XmAddProtocolCallback(). |
---|
176 | .TP |
---|
177 | .B XmpAddTabGroup( [widget] ) |
---|
178 | The named widget, or the widget providing the context for the callback if |
---|
179 | no widget is named, is passed to XmAddTabGroup(). The effect is simple: |
---|
180 | if the widget is a manager widget, then all the children are put in a |
---|
181 | tab group together. If the widget is a primitive, then that widget |
---|
182 | is in its own tab group. |
---|
183 | .TP |
---|
184 | .B XmpPopup( widget ) |
---|
185 | This is only available as an action triggered due to translations of |
---|
186 | accelerators, it cannot be invoked as a callback. The argument is the |
---|
187 | name of a menu pane (usually, a widget which was created with |
---|
188 | XmCreatePopupMenu()). The menu is positioned using XmMenuPosition() |
---|
189 | which is the same procedure used by Motif itself. This depends on |
---|
190 | the existance of an XmRowColumn somewhere in the interface. If |
---|
191 | you have a menuBar, then this will work. This is because XmRowColumn |
---|
192 | provides all sorts of wierd and wonderful event handlers for dealing |
---|
193 | with menus. |
---|
194 | .TP |
---|
195 | .B XmpTableChildConfig( w col row [h_span [v_span [opts]]] ) |
---|
196 | This allows a child of an XmpTable to be moved to a new row or |
---|
197 | column, to be given a different horizontal or vertical span, and |
---|
198 | to change the justification and re-size options of the child. |
---|
199 | .TP |
---|
200 | .B XmpTableChildPosition( w col row ) |
---|
201 | This allows a child of an XmpTable to be moved to a new row or |
---|
202 | column. |
---|
203 | .TP |
---|
204 | .B XmpTableChildResize( w h_span v_span ) |
---|
205 | This allows a child of an XmpTable to be given a different horizontal |
---|
206 | or vertical span. |
---|
207 | .TP |
---|
208 | .B XmpTableChildOptions( w options ) |
---|
209 | This allows a child of an XmpTable to be given new |
---|
210 | justification and re-size options. |
---|
211 | .SH "SEE ALSO" |
---|
212 | .BI XmpTable (3), |
---|
213 | .BI Mri (1), |
---|
214 | .BI Wcl (3), |
---|
215 | .BI X (1) |
---|
216 | .SH BUGS |
---|
217 | .LP |
---|
218 | realizeCallback, destroyCallback, popupCallback, and popdownCallback |
---|
219 | MUST NOT be specified using resource values for shell widgets derived |
---|
220 | from Motif Vendor Shell in most releases of Motif. Sorry, there is no |
---|
221 | way I can see for Wcl to work around this bug in the list of resources |
---|
222 | fetched by the Motif Vendor Shell Extension VendorExtInitialize() |
---|
223 | procedure. |
---|
224 | .LP |
---|
225 | If you want to specify these resources, specifiy a wcCallback resource |
---|
226 | and add the callbacks using WcAddCallbacks(). |
---|
227 | .LP |
---|
228 | Explanation for Xt and Motif gurus with source code: Xt has fetched |
---|
229 | these resources for the shell, and compiled the XtCallbackRec array |
---|
230 | generated by WcCvtStringToCallback into the |
---|
231 | InternalCallbackRec/XtCallbackRec "thang." This happens in |
---|
232 | Xt'Create.c'_XtCreate in R5. _XtCreate then allows the widget to |
---|
233 | initialize itself, calling CallInitialize(). This eventually invokes |
---|
234 | the Motif Vendor Shell initialization, which invokes the Motif Vendor |
---|
235 | Shell Extension initialization. Here, Motif incorrectly fetches again |
---|
236 | the above callback resources, applying the resources straight into the |
---|
237 | "new" widget with its already compiled callback lists. This causes the |
---|
238 | compiled callback list storage to be overwritten with the original, |
---|
239 | uncompiled form previously generated by WcCvtStringToCallback. The |
---|
240 | next XtAddCallback or XtCallAllCallbacks or XtSetValues on these |
---|
241 | resources will (or should!) fail due to mis-interpreting the callback |
---|
242 | list (the first element will again be an XtCallbackRec instead of an |
---|
243 | InternalCallbackRec). The fix is messy: somehow treat the callback |
---|
244 | resources as uniquely as Xt does everywhere else: fetch into a |
---|
245 | different (local) Widget instead of new, and then traverse the list of |
---|
246 | callbacks, invoking XtAddCallback( new, <callbackName>, cb->callback, |
---|
247 | cb->closure ), and then free up that locally allocated dummy widget. |
---|
248 | Yuck! |
---|
249 | .SH AUTHOR |
---|
250 | David E. Smyth (David.Smyth@sniap.mchp.sni.de) at Siemens Nixdorf |
---|
251 | Informationssysteme AG, Munich Germany. |
---|