LiteClue Widget

###

The LiteClue Widget

### 1. Copyright

Copyright 1995 Computer Generation, Inc. You may reproduce this document without charge provided this copyright notice appears. 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

### 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 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 does not require Motif

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

LiteClue has been compiled successfully on NCR MPRAS, Digital OSF/Unix, and Linux.

To build the test program:

    	xmkmf
    	make

### 4. 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 = C
  The font used to display the clue.

XtNforeground
  Type = Pixel, Default = "black", Access = C
  The color used to render the clue text

The background color resource XtNbackground of the clue popup is inherited from OverrideShell.

### 5. Callbacks

LiteClue adds no new callbacks over those it inherite.

### 6. Translations

LiteClue has no translations.

### 7. LiteClue API

LiteClue contains the following functions that control the widget behaviour.

### 7.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

### 7.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

### 7.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

### 7.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

### 7.5 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".