
  xautohelp.hlp = Notes on using the xautohelp routine.

  What xautohelp does
  -------------------
  The xautohelp routine can be used to display help text any time
  the mouse is moved over a widget component.  This can give extra
  info that helps in the operation of the widget, perhaps especially
  useful for buttons with bit map graphics that may not be immediately
  obvious in their application.  Single or multiline text may be
  displayed in either a text widget or label widget (single or
  multiple label widgets).

  Autohelp text display area placement
  ------------------------------------
  Perhaps the nicest looking application is to display the help text in
  a label widget or widgets running along the bottom of the application.
  This label area is blank unless the cursor is over a widget component that
  has autohelp text.  Multiple consecutive label widgets may be used to
  display multiline help text, lines are left-justified.  A text widget could
  be used in this position instead of a label widget.  The help text area need
  not be at the bottom, it can be wherever you wish.  It can also be used for
  other messages, the current time for example, or something more useful.
  You will have to be careful that the other messages do not overwrite the
  autohelp text before desired.  A timer routine can trigger events for a
  clock update, check that the autotext is displaying a blank or time before
  overwriting.

  The autotext display area may also be detached from the main widget.
  This is useful for small widgets where there would not be enough space
  to display useful text along the bottom.  The detached display area,
  either a label or text widget, can be positioned just below the main
  widget using the info returned by widget_info for the main base and the
  xoffset and yoffset keywords to the display area base widget.

  Using xautohelp in a widget routine
  -----------------------------------
  For a complete example that uses xautohelp (but doesn't do anything
  useful) see the routine xautohelp_example.pro.

  Their are two phases in using xautohelp, INITIALIZATION and TEXT DISPLAY.

  INITIALIZATION --- if a widget such as a button, slider, text entry area,
  and so on, is to have autohelp text displayed it must have tracking_events
  enabled.  The xautohelp is given the help text for that widget using the
  widget ID as an index.  This means it makes sense (but is not required) to
  save the autohelp text for each widget right after it is defined.  Here
  is a code fragment showing this:
	. . .
        b = widget_button(cc,val='Button 3',/track, uval='C')
        xautohelp,b,'Click here to QUIT.'
        b = widget_button(cc,val='Button 4',/track, uval='D')
        xautohelp,b,'Button # 4'
        s = widget_slider(top,/track,uval='S')
        xautohelp,s,'Slider.  Drag to desired value.'
	. . .

  Note tracking_events are turned on.  Multiline help text is entered as
  a single text string using delimiters as line separators.  The default
  delimiter is a slash (/) but any character may be used by specifying it
  using the DELIMITER=del keyword.  Remember single label widgets cannot
  display more than a single line and will terminate with an error since
  they want scalar values.  Multiple label widgets may be set up, just pass
  their addresses as an array to display multiple help text lines.
  Widgets to ignore simply do not have tracking events turned on (most labels
  for example).

  The autohelp text display is either a label or text widget.  Its widget
  ID must be saved for access inside the event handler routine so it may
  be passed into xautohelp.  This is done that same way other status info
  is passed to the event handler.  A common way is to pass this info through
  the USER_VALUE of the top level base since that is easy to access.  Often
  a structure with everything needed is used to keep the widget state
  information, the display area ID or IDs could be just another entry
  in such a structure.  If multiple labels are used pass their addresses
  in an array.  The display area may be part of the main widget or
  a detached window (with some initial position but movable by the
  user).  If it is detached make sure you set its group_leader to the ID of
  the main top level base so it will disappear when the main widget goes
  away.  Here is a code fragment examples for a detached dispay area:

	. . .
        ;------  Autotext window  -----------
        loc = widget_info(top,/geom)    ; Get top base size and position.
        tmp = widget_base(/col, group_leader=top, title=' ', $
          xoffset=loc.xoffset,yoffset=loc.yoffset+loc.ysize+8)
        lab = widget_label(tmp, val=spc(100,char='.'))  ; Force size.
        widget_control,tmp,/real                        ; Activate.
        widget_control,lab,set_val=' '                  ; Clear text.
	. . .

  The above detached display is positioned to be just beneath the main
  widget.  The +8 in the above yoffset value is a fudge value to allow
  for the size of the window frame around the widget, that's not given
  by widget_info and may vary on different systems.

  TEXT DISPLAY --- This part is easy, all you really need to worry about is
  getting the widget ID of the display widget from within the event handler.
  One simple way is to store it in the user value of the top level base, or
  more useful, inside a status structure stored there.  Perhaps the first
  operation of the event handler is to retireve this display area widget ID.
  Next send the event structure to xautohelp along with the display area
  widget ID.  On return check if the event structure is still a structure, if
  not then it has been processed as an autohelp text event so just return.
  Otherwise drop through to the regular event processing.  A code fragment:

	. . .
        ;-----  Look for authelp text events  ----
        widget_control, ev.top, get_uval=lab    ; Get text display area ID.
        xautohelp, ev, display=lab              ; Send event into xautohelp.
        if (size(ev))(2) ne 8 then return       ; Check if still a structure.
	. . .

  An example to display current time in autohelp display area when not used
  for autohelp text is given here.  After the widget is all set up but before
  calling xmanager, call for a timer event:
	widget_control, top, timer=1.           ; Set a timer (for 1 sec).

   The timer event will trigger a timer event which will call the event
   handler.  In the event handler these events are processed as follows:

        ;-----  Look for timer events  -----------
        if tag_names(ev,/structure_name) eq 'WIDGET_TIMER' then begin
          widget_control, lab, get_val=tmp
          if (tmp eq ' ') or (strmid(tmp,0,3) eq strmid(systime(),0,3)) then $
            widget_control, lab, set_val=systime()
          widget_control, ev.top, timer=1.              ; Next timer event.
          return
        endif

  This code comes after the xautohelp call.  It looks at the incoming event
  to see if it is a timer event, if not it is ignored by this part of the
  code.  If it is then the current text in the display area is grabbed and
  if it is a single space (first time only) or it looks like a time (first
  3 letters match the time output) then the current time is displayed there.
  Then a new timer event is requested to keep the cycle going.  The event
  handler is then exited since the event has been processed.  This code
  will then display the current time in the display area if no autohelp text
  is displayed there.

----------------------------------------------------------------------------
