The LiteClue Widget
1. Copyright
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
ftp://ftp.compgen.com/pub/widgets/LiteClue.tar.Z
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.
The author welcomes comments and suggestions. Gary Aviv Computer
Generation, Inc., gary@compgen.com 404-705-2811
Thanks to contributers:: J Satchell, Eric Marttila.
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.
Updated: 06 January 1998
2. Introduction
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.
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.
None of this affects the behaviour of the watched widget itself. LiteClue
monitors enter and leave events of the watched widget's window passively.
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 XcgLiteClueDispatchEvent
for a way to bypass this limitation.
LiteClue inherits behaviour and ewsources from OverrideShell.
The class pointer is xcgLiteClueWidgetClass.
The class name is xcgLiteClue.
3. Version Information
Version 1.2
1. R4 back compatibility
2. Delay before pop up of help; XcgNwaitperiod resource (default 500 ms).
3. Button press in watched widget pops down help.
Version 1.3
1. Support of cancelWaitPeriod resource. this is the period after a help
popdown occurs in which the normal waitPeriod is suspended for the
next
popup.
2. minor fixes
Version 1.4
1. Support for clues on insensitive widgets. See XcgLiteClueDispatch
function
below.
4. Distribution Kit
The source distribution kit contains the following files:
LiteClue.c LiteClue.h LiteClueP.h
The LiteClue widget source code LiteClueTest.c
A small demonstration program Imake
an Imake file. BUILD.COM
a command file for building under DEC VMS LiteClue.html LiteClue.txt
LiteClue.ps
Documentation in HTML, plain text and PostScript formats
LiteClue has been compiled successfully on NCR MPRAS, Digital OSF/Unix,
ULTRIX (XR4), Linux, VMS and probably many others.
To build the test program:
xmkmf
make
For VMS, see the file BUILD.COM.
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 10 below). However,
you can also force it to use font structs instead by setting a compile time
variable (see make file).
When using font sets, you may get the message:
Warning: Missing charsets in String to FontSet conversion Warning: Unable
to load any usable fontset
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:
LANG=C.iso88591
5. Resources
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).
XtNfontSet
Type = FontSet, Default = "-adobe-new century
schoolbook-bold-r-normal-*-12-*, Access = CG
The font used to display the clue. For Xt Release 4 or less, the
resource
name XtNfont and the type is FontStruct.
XtNforeground
Type = Pixel, Default = "black", Access = CSG
The color used to render the clue text
XcgNwaitperiod
Type = Integer, Default = 500, Access = CSG
The delay from the time the pointer enters the watched widget until
the
help is popped up in milliseconds.
XcgNcancelWaitPeriod
Type = Integer, Default = 2000, Access = CSG
The period (in milliseconds) after a help popdown occurs in which the
normal waitPeriod is suspended. If the pointer should re-enter a
watched
widget during this period help pops up immediately rather than waiting
waitPeriod milliseconds.
The background color resource XtNbackground of the clue popup is inherited
from OverrideShell.
6. Callbacks
LiteClue adds no new callbacks over those it inherits.
7. Translations
LiteClue has no translations.
8. LiteClue API
LiteClue contains the following functions that control the widget
behaviour.
8.1 XcgLiteClueAddWidget -- Add a widget to be watched.
Function
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.
C-call
void XcgLiteClueAddWidget(Widget w, Widget watch, char * text, int
size,
int option )
Input
w LiteClue widget
watch
the widget for which clues will be given
text
pointer to buffer containing text. Must be null terminated
size
size of text, if 0, it will be computed (strlen)
option
option mask - must be zero
Output
Nothing
8.2 XcgLiteClueDeleteWidget -- Delete a widget that is watched.
Function
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.
C-call
void XcgLiteClueDeleteWidget(Widget w, Widget watch)
w LiteClue widget
watch
the widget to remove from watched list
Output
Nothing
8.3 XcgLiteClueSetSensitive - Enable/disable clues for watched widget.
Function
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.
C-call
void XcgLiteClueSetSensitive(Widget w, Widget watch, Boolean
sensitive)
w LiteClue widget
watch
the widget to alter sensitivity
sensitive
True - restore sensitivity
False - make insensitivity
Output
Nothing
8.4 XcgLiteClueGetSensitive - Get sensitivity setting for watched widget.
Function
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.
C-call
Boolean XcgLiteClueGetSensitive (Widget w, Widget watch)
w LiteClue widget
watch
the widget for which to get sensitivity state. If NULL first
watched
widget is used. If there are no watched widgets, False is
returned.
Output
Nothing
Return
True - watched widget is sensitive
False - watched widget is not sensitive
8.5 XcgLiteClueDispatchEvent -- Dispatch event from main X event loop
Function
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:
MyXtAppMainLoop(XtAppContext app)
{
XEvent event;
for (;;) {
XtAppNextEvent(app, &event);
XcgLiteClueDispatchEvent(w, event) ;
XtDispatchEvent(&event);
}
}
C-call
Boolean XcgLiteClueDispatchEvent (Widget w, XEvent *event)
w LiteClue widget
event
received event, normally from call to XtAppNextEvent.
Output
Nothing
Return
True - event was dispatched to non-sensitive watched widget.
False
- not a EnterNotify or LeaveNotify event or window in event is
not a
non-sensitive watched widget.
9. Sample Use
Since LiteClue is a shell widget , you make an instance of the shell as in
this example:
Widget liteClue, toplevel ;
...
toplevel = XtVaAppInitialize(&AppContext,
...
liteClue = XtVaCreatePopupShell( "LiteClue_shell",
xcgLiteClueWidgetClass, toplevel, ..., NULL);
If you want to change the font used by LiteClue, you could add the fontSet
resource at create time as in:
#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);
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
XcgLiteClueAddWidget (Section 8.1) as in:
button_widg = XtVaCreateManagedWidget("Button1",
xmPushButtonWidgetClass,
...
XcgLiteClueAddWidget(liteClue, button_widg, "Help Message", 0, 0);
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 XcgLiteClueDispatchEvent.
10. Internationalization
The LiteClue widget is designed to allow the display of internationalized
text. This has been tested on a limited basis with Japanese.
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:
if (setlocale(LC_ALL,"") == NULL)
fprintf(stderr, "LiteCluetest: Can't set locale0);
if (!XSupportsLocale())
{
fprintf(stderr, "LiteCluetest: X does not support locale0);
setlocale(LC_ALL,NULL) ;
}
if (XSetLocaleModifiers("") == NULL)
fprintf(stderr, "LiteCluetest: Can't XSetLocaleModifiers0);
If you need the X locale package, add the following:
#define X_LOCALE
#include <X11/Xlocale.h>
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:
*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
Finally, you must set the environment symbol LANG to the appropriate
locale. For Japanese, one possibility is "LANG=ja_JP.eucJP".
