1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
|
<META name="description" content="A free bubble or balloon help X Widget.">
<META name="keywords" content="X Motif Widget">
<body bgcolor="#FFFFFF">
<H3>
<p align=center>The LiteClue Widget
</H3>
</p><a name="ALiteClueDoc"></a><p><ident origin="/usr3/cgi/doc/xform/LiteClue.doc">
<H3><a name="H1">1. Copyright
</a></H3>
<br><p>Copyright 1995 Computer Generation, Inc. You may reproduce this document
without charge provided the copyright and disclaimer notices appear. The
software described in this document is copyrighted under separate terms.
See the source code available at
<a href="ftp://ftp.compgen.com/pub/widgets/LiteClue.tar.Z">ftp://ftp.compgen.com/pub/widgets/LiteClue.tar.Z</a>
<p>The software is provided "as is", without warranty of any kind, express
or implied, including but not limited to the warranties of
merchantability, fitness for a particular purpose and noninfringement.
In no event shall Computer Generation, inc. nor the author(s) be liable for
any claim, damages or other liability, whether in an action of contract,
tort or otherwise, arising from, out of or in connection with the
software or the use or other dealings in the software.
<p>The author welcomes comments and suggestions. <br>Gary Aviv <br>Computer Generation, Inc.,<br><a href="mailto:gary@compgen.com">gary@compgen.com</a><br>404-705-2811<br><p>Thanks to contributers:: J Satchell, Eric Marttila, Addy Klos.
<p>If you wish to be on an Emailing list regarding this or other
CGI widgets, please send a request to the above address.
You will be notified when this or other widgets are upgraded
or when new widgets become available.
<p>Updated: 30 October 1998
<p><br><H3><a name="H2">2. Introduction
</a></H3>
<br><p><p align=center><IMG src="LiteClue.gif"><p><p>LiteClue is a widget
which pops a one line help
message when the user passes the pointer over another "watched" widget. This is
known by various names in the industry such as hints, clues, tips,
bubble help and balloon help.
<p>Clues are particularly helpful for push buttons that contain graphic
pixmaps rather than text. They obviate the need to place text within graphics
in the button which creates internationalization problems.
A clue may be attached to virtually any widget that has a window (no gadgets).
LiteClue works with Motif but does not require it.
<p>None of this affects the behaviour of the watched widget itself.
LiteClue monitors enter and leave events of the watched widget's
window passively.
<p>LiteClue relies on EnterNotify and LeaveNotify events for the the widgets
it is watching. This will normally prevent clues from poping up
when the watched widgets are insensitive. See the function
<b>XcgLiteClueDispatchEvent</b> for a way to bypass this limitation.
<p>LiteClue inherits behaviour and ewsources from OverrideShell.
<p>The class pointer is xcgLiteClueWidgetClass.
<p>The class name is xcgLiteClue.
<p><br><H3><a name="H3">3. Version Information
</a></H3>
<br><p><b>Version 1.2</b>
<OL><LI>
R4 back compatibility
<LI>
Delay before pop up of help; <b>XcgNwaitperiod</b>
resource (default 500 ms).
<LI>
Button press in watched widget pops down help.
</OL><p><b>Version 1.3</b>
<OL><LI>
Support of cancelWaitPeriod resource. this is the period after
a help popdown occurs in which the normal waitPeriod is suspended
for the next popup.
<LI>
minor fixes
</OL><p><b>Version 1.4</b>
<OL><LI>
Support for clues on insensitive widgets. See <b>XcgLiteClueDispatch</b>
function below.
</OL><p><b>Version 1.4</b>
<OL><LI>
Position the clue above the watched widget or move the clue
right or left to make it visible if it would otherwise be off the
screen.
</OL><p><br><H3><a name="H4">4. Distribution Kit
</a></H3>
<br><p>The source distribution kit contains the following files:
<p><DL COMPACT><DT>
<b>LiteClue.c LiteClue.h LiteClueP.h </b>
<DD>
The LiteClue widget source code
<DT>
<b>LiteClueTest.c</b>
<DD>
A small demonstration program
<DT>
<b>Imake</b>
<DD>
an Imake file.
<DT>
<b>BUILD.COM</b>
<DD>
a command file for building under DEC VMS
<DT>
<b>LiteClue.html LiteClue.txt LiteClue.ps </b>
<DD>
Documentation in HTML, plain text and PostScript formats
</DL><p>LiteClue has been compiled successfully on NCR MPRAS,
Digital OSF/Unix, ULTRIX (XR4), Linux, VMS and probably many others.
<p>To build the test program:
<p><pre>
xmkmf
make
</pre><p>For VMS, see the file BUILD.COM.
<p>LiteClue is designed for X11R4 or higher. It checks
XtSpecificationRelease at compile time. When compiled for X11R5 or
higher, it uses font sets which gives it good internationalization
support (see Section <a href="LiteClue.html#H10">10</a> below). However, you can also force it to
use font structs instead by setting a compile time variable (see make
file).
<p>When using font sets, you may get the message:
<p><pre>
Warning: Missing charsets in String to FontSet conversion
Warning: Unable to load any usable fontset
</pre><p>which means that your locale does not support the font's character sets.
On many machine, the default C locale does not allow 8-bit characters
or the iso88591 character set required by the default fonts.
Fix this by setting your LANG environment variable. For example, on HP-UX
in the US you set:
<p><pre>
LANG=C.iso88591
</pre><p><br><H3><a name="H5">5. Resources
</a></H3>
<br><p>LiteClue adds the following resources to those it inherits. The resource class
is obtained by replacing the N by a C in the resource name (eg:
XtNfontSet is the name XtNfontSet is the class. The access types are
C (resource may be set at create time), S (may be se using XtSetValues), or
G (may be read using XtGetValues).
<p><HR><DL COMPACT><DT>
<b>XtNfontSet</b>
<DD>
Type = FontSet, Default = "-adobe-new century schoolbook-bold-r-normal-*-12-*, Access = CG<br>The font used to display the clue. For Xt Release 4 or less, the resource
name <b>XtNfont</b> and the type is FontStruct.
<HR><DT>
<b>XtNforeground</b>
<DD>
Type = Pixel, Default = "black", Access = CSG<br>The color used to render the clue text
<HR><DT>
<b>XcgNwaitperiod</b>
<DD>
Type = Integer, Default = 500, Access = CSG<br>The delay from the time the pointer enters the watched widget until
the help is popped up in milliseconds.
<HR><DT>
<b>XcgNcancelWaitPeriod</b>
<DD>
Type = Integer, Default = 2000, Access = CSG<br>The period (in milliseconds) after
a help popdown occurs in which the normal <b>waitPeriod</b> is suspended.
If the pointer should re-enter a watched widget during this period
help pops up immediately rather than waiting <b>waitPeriod</b> milliseconds.
</DL><HR><p>The background color resource <b>XtNbackground</b> of the clue popup is
inherited from OverrideShell.
<p><br><H3><a name="H6">6. Callbacks
</a></H3>
<br><p>LiteClue adds no new callbacks over those it inherits.
<p><H3><a name="H7">7. Translations
</a></H3>
<br><p>LiteClue has no translations.
<p><H3><a name="H8">8. LiteClue API
</a></H3>
<br><p>LiteClue contains the following functions that control the widget behaviour.
<p><H3><a name="H8.1">8.1 XcgLiteClueAddWidget -- Add a widget to be watched.
</a></H3>
<br><DL COMPACT><DT>
<b>Function</b>
<DD>
A widget will be added to the LiteClue watched list.
Clues are given for sensitive watched widgets when the pointer enters its
window. If the widget is already watched, the passed text replaces its
current clue text.
If text is null, the widget is still added, if it is not already
in the list, but no clue will appear. Text may be specified
with XcgLiteClueAddWidget in a subsequent call.
When text is null and the widget is already in the list, its
text is not changed.
When a widget will is added to the watched list, it automatically
becomes sensitive. Otherwise, its sensitivity is not changed.
A watched widget which is not sensitive retains its context but clues
are suppressed.
None of this affects the behaviour of the watched widget itself.
LiteClue monitors enter and leave events of the watched widget's
window passively.
<p><DT>
<b>C-call</b>
<DD>
void XcgLiteClueAddWidget(Widget w, Widget watch, char * text, int size, int option )
<p><DT>
<b>Input</b>
<DD>
<DL COMPACT><DT>
<b>w </b>
<DD>
LiteClue widget
<DT>
<b>watch </b>
<DD>
the widget for which clues will be given
<DT>
<b>text </b>
<DD>
pointer to buffer containing text. Must be null terminated
<DT>
<b>size </b>
<DD>
size of text, if 0, it will be computed (strlen)
<DT>
<b>option </b>
<DD>
option mask - must be zero
</DL><p><DT>
<b>Output</b>
<DD>
Nothing
</DL><p><br><H3><a name="H8.2">8.2 XcgLiteClueDeleteWidget -- Delete a widget that is watched.
</a></H3>
<br><p><DL COMPACT><DT>
<b>Function</b>
<DD>
A widget is deleted from the watched list and its resources are
freed. LiteClue is no longer given for the widget.
If the widget is not watched, nothing is done.
None of this affects the behaviour of the watched widget itself, just whether
a clue is poped for the widget.
<p><DT>
<b>C-call</b>
<DD>
void XcgLiteClueDeleteWidget(Widget w, Widget watch)
<p><DL COMPACT><DT>
<b>w </b>
<DD>
LiteClue widget
<DT>
<b>watch </b>
<DD>
the widget to remove from watched list
</DL><p><DT>
<b>Output</b>
<DD>
Nothing
</DL><p><H3><a name="H8.3">8.3 XcgLiteClueSetSensitive - Enable/disable clues for watched widget.
</a></H3>
<br><p><DL COMPACT><DT>
<b>Function</b>
<DD>
When a watched widget is sensitive, a clue is poped up when the
pointer enters its window. When a watched widget is insensitive,
the widget is retained in the watched list but no clue is poped.
The sensitivity of a watched widget relative to clues is set or reset
by this function.
The Xt sensitivity of the watched widget is not altered by this function.
<p><DT>
<b>C-call</b>
<DD>
void XcgLiteClueSetSensitive(Widget w, Widget watch, Boolean sensitive)
<p><DL COMPACT><DT>
<b>w </b>
<DD>
LiteClue widget
<DT>
<b>watch </b>
<DD>
the widget to alter sensitivity
<DT>
<b>sensitive</b>
<DD>
True - restore sensitivity<br>False - make insensitivity
</DL><p><DT>
<b>Output</b>
<DD>
Nothing
</DL><p><br><H3><a name="H8.4">8.4 XcgLiteClueGetSensitive - Get sensitivity setting for watched widget.
</a></H3>
<br><p><DL COMPACT><DT>
<b>Function</b>
<DD>
When a watched widget is sensitive, a clue is poped up when the
pointer enters its window. When a watched widget is insensitive,
the widget is retained in the watched list but no clue is poped.
The sensitivity state of a watched widget relative to clues is returned
by this function.
The Xt sensitivity of a widget is a totally independent concept.
<p><DT>
<b>C-call</b>
<DD>
Boolean XcgLiteClueGetSensitive (Widget w, Widget watch)
<p><DL COMPACT><DT>
<b>w </b>
<DD>
LiteClue widget
<DT>
<b>watch </b>
<DD>
the widget for which to get sensitivity state. If NULL
first watched widget is used. If there are no watched widgets,
False is returned.
</DL><p><DT>
<b>Output</b>
<DD>
Nothing
<p><DT>
<b>Return</b>
<DD>
True - watched widget is sensitive<br>False - watched widget is not sensitive
</DL><p><H3><a name="H8.5">8.5 XcgLiteClueDispatchEvent -- Dispatch event from main X event loop
</a></H3>
<br><p><DL COMPACT><DT>
<b>Function</b>
<DD>
This function may be used to enable clues for insensitive watched
widgets. Normally, XtAppMainLoop (which calls XtDispatchEvent) will not
deliver EnterNotify and LeaveNotify events to widgets that are not
sensitive (XtSetSensitive). This prevents clues from poping up for these
widgets. To bypass this limitation, you can break out XtAppMainLoop and
add a call to XcgLiteClueDispatchEvent ass follows:
<p><pre>
MyXtAppMainLoop(XtAppContext app)
{
XEvent event;
for (;;) {
XtAppNextEvent(app, &event);
XcgLiteClueDispatchEvent(w, event) ;
XtDispatchEvent(&event);
}
}
</pre><p><DT>
<b>C-call</b>
<DD>
Boolean XcgLiteClueDispatchEvent (Widget w, XEvent *event)
<p><DL COMPACT><DT>
<b>w </b>
<DD>
LiteClue widget
<DT>
<b>event </b>
<DD>
received event, normally from call to XtAppNextEvent.
</DL><p><DT>
<b>Output</b>
<DD>
Nothing
<p><DT>
<b>Return</b>
<DD>
<DL COMPACT><DT>
True
<DD>
- event was dispatched to non-sensitive watched widget.
<DT>
False
<DD>
- not a EnterNotify or LeaveNotify event or window in
event is not a non-sensitive watched widget.
</DL></DL><p><H3><a name="H9">9. Sample Use
</a></H3>
<br><p>Since LiteClue is a shell widget , you make an instance of the shell
as in this example:
<p><pre>
Widget liteClue, toplevel ;
...
toplevel = XtVaAppInitialize(&AppContext,
...
liteClue = XtVaCreatePopupShell( "LiteClue_shell",
xcgLiteClueWidgetClass, toplevel, ..., NULL);
</pre><p>If you want to change the font used by LiteClue, you could add
the fontSet resource at create time as in:
<p><pre>
#define RES_CONVERT( res_name, res_value) \
XtVaTypedArg, (res_name), XmRString, (res_value), strlen(res_value) + 1
liteClue = XtVaCreatePopupShell( "LiteClue_shell",
xcgLiteClueWidgetClass, toplevel,
RES_CONVERT(XtNfontSet, \
"-adobe-new century schoolbook-bold-r-normal-*-18-*"),
NULL);
</pre><p>You need only create a single instance of the widget for the application.
To attach help to a widget (usually a push button) use
the function <b>XcgLiteClueAddWidget</b> (Section <a href="LiteClue.html#H8.1">8.1</a>) as in:
<p><pre>
button_widg = XtVaCreateManagedWidget("Button1", xmPushButtonWidgetClass,
...
XcgLiteClueAddWidget(liteClue, button_widg, "Help Message", 0, 0);
</pre><p><br>In order to enable clues for insensitive widgets you will need to replace
the standard call to XtAppMainLoop with the code as illustrated in the
function <b>XcgLiteClueDispatchEvent</b>.
<p><br><H3><a name="H10">10. Internationalization
</a></H3>
<br><p>The LiteClue widget is designed to allow the display of internationalized
text. This has been tested on a limited basis with Japanese.
<p>In order to make use of internationalization, you must have support
in your operating system for the desired locale and must have the
needed fonts. In some cases, you may use the X provided locale
support instead. At initialization, you should have code that
looks something like:
<p><pre>
if (setlocale(LC_ALL,"") == NULL)
fprintf(stderr, "LiteCluetest: Can't set locale\n");
if (!XSupportsLocale())
{
fprintf(stderr, "LiteCluetest: X does not support locale\n");
setlocale(LC_ALL,NULL) ;
}
if (XSetLocaleModifiers("") == NULL)
fprintf(stderr, "LiteCluetest: Can't XSetLocaleModifiers\n");
</pre><p>If you need the X locale package, add the following:
<p><pre>
#define X_LOCALE
#include <X11/Xlocale.h>
</pre><p><br>LiteClue makes use of the XR5 Font Set technology. All
font resources are converted to Font Sets. For example, for Japanese
you will need three fonts for each font set:
<p><pre>
*XcgLiteClue.fontSet: \
-sony-fixed-medium-r-normal--0-110-100-100-c-0-jisx0201.1976-0,\
-adobe-new century schoolbook-medium-r-normal-*-14-*,\
-jis-fixed-medium-r-normal--16-110-100-100-c-160-jisx0208.1983-0
</pre><p>Finally, you must set the environment symbol LANG to the appropriate locale.
For Japanese, one possibility is "LANG=ja_JP.eucJP".
<br><title>LiteClue Widget</title>
|
