LiteClue Widget

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. Please see the source code.

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 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: J Satchell, Eric Marttila.

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 inherits behaviour and ewsources from OverrideShell.

The class pointer is xcgLiteClueWidgetClass.

The class name is xcgLiteClue.

3. Version Information

Version 1.2

R4 back compatibility
Delay before pop up of help; XcgNwaitperiod resource (default 500 ms).
Button press in watched widget pops down help.

Version 1.3

Support of cancelWaitPeriod resource. this is the period after a help popdown occurs in which the normal waitPeriod is suspended for the next popup.
minor fixes

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: acommand 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.

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: XtNfont is the name XtNfont 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).

XtNfont: Type = FontSet, Default = "-adobe-new century schoolbook-bold-r-normal-*-12-*, Access = CG
The font used to display the clue.
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 inherite.

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

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

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);

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);

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 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");

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:

*normalFont: \
-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

*h1Font: \
-sony-fixed-medium-r-normal--0-170-100-100-c-0-jisx0201.1976-0,\
-adobe-new century schoolbook-bold-r-normal-*-24-*,\
-jis-fixed-medium-r-normal--24-170-100-100-c-240-jisx0208.1983-0

! etc for each font resource

Finally, you must set the environment symbol LANG to the appropriate locale. For Japanese, one possibility is "LANG=ja_JP.eucJP".
LiteClue Widget