Class: ActiveHelp

• Inheritance
• Description
• Class protocol
  • accessing
  • initialization
  • queries
  • start & stop
• Instance protocol
  • event handling
  • help texts
  • private
  • queries
  • show & hide help
  • start & stop
• Examples

Inheritance:

   Object
   |
   +--EventListener
      |
      +--ActiveHelp
         |
         +--FlyByHelp

Package:

stx:libview2

Category:

Interface-Help

Version:

rev: 1.132 date: 2023/11/21 14:40:03

user: cg

file: ActiveHelp.st directory: libview2

module: stx stc-classLibrary: libview2

Description:

The active help (tooltip) listener.

The one and only instance of myself intercepts incoming mouse & keyboard 
events for the display device, being especially interested in view-enter/
leave events. When such an event arrives, it asks the corresponding view
or its model for a help message and displays it via an ActiveHelpView.
Actually, the view is first asked if it would like to display it itself
- for example, in some information-view at the bottom of its main window.

The query for the helpText is repeated along the view's superView chain, 
until any model or view returns a nonNil answer for the 
#helpTextFor:<aSubView> at:<position> or #helpTextFor:<aSubView> message.

All I need for automatic help is some model/view/applicationModel along
the superview chain of the entered component, which responds to the
#helpTextFor: message with a non-nil (string-) answer.
I close down the help view after a while, if a key is pressed or the mouse
moved to another view.

Who should provide the helpText:
    the best place is the application object (an instance of ApplicationModel)
    or the topView, if it's a derived class of StandardSystemView.
    This should know about its components and return the string
    when asked via #helpTextFor:<aSubView>.
    See examples in FileBrowser, Launcher etc.

Be aware, that for applicationModels, there must be a link from the
topView to this applicationModel 
(set via: aTopView application:anApplicationModel)
otherwise, the helpManager has no means of finding the application which
corresponds to a view.

Who should display the helpText:
    by default, the helpListener opens a little popup view, which displays the
    returned help message. However, a nice trick which can be used by applications
    is to create an infoLabel as a subview of the topFrame (a la windows)
    and display the text right in the #helpTextFor: method. To cheat the
    help listener, this method should then return nil, to keep it silent.


Usage:
    If help is to be shown for all views (as enabled by the launchers help menu),
    use 'ActiveHelp start' and 'ActiveHelp stop'.

    Individual apps may enable/disable active help for themself by:
    'ActiveHelp startFor:app' or 'ActiveHelp stopFor:app', passing either
    the topView or the topViews application as argument.
    This is usually done by applications which want to show contextHelp in
    some infoView.
    Late note: thsi is no longer recommended - one such mouse watcher process is
    good enough for all views.
    

copyright
COPYRIGHT (c) 1995 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 currentHelpListener

return the activeHelp listener if activeHelp is turned on, nil otherwise

Usage example(s):

ActiveHelp currentHelpListener FlyByHelp currentHelpListener

 debugging

 debugging: aBoolean

DebuggingEvents := false.

self debugging:true
self debugging:false

 debuggingHelpText

 debuggingHelpText: aBoolean

self debuggingHelpText:true
self debuggingHelpText:false

 delayTime

return the delay (the time, the cursor has to be in the view
before help is shown). The default is 0.5 seconds.

 delayTime: numberOfSeconds

set the delay (the time, the cursor has to be in the view
before help is shown). The default is 2 seconds.

Usage example(s):

FlyByHelp delayTime:0.5 FlyByHelp delayTime:2 FlyByHelp delayTime:10

 showTime

set the number of seconds, a help messages is to be shown.
The default is 15 seconds.
0 means: show forever (i.e. until mouse is moved)

Usage example(s):

self showTime

 showTime: numberOfSeconds

set the number of seconds, a help messages is to be shown.
The default is defined in the getter.
0 means: show forever (i.e. until mouse is moved)

Usage example(s):

ActiveHelp showTime:10 ActiveHelp showTime:99999 ActiveHelp showTime:30

 singleton

 initialize

(comment from inherited method)
called only once - initialize signals

 isActive

return true, if activeHelp is turned on

Usage example(s):

FlyByHelp isActive

 initiateHelp

determine where the mouse pointer is located,
and start showing a tooltip for it.
This can be called to force update of the tooltip,
in case a widget has changed its mind
(typically: an undo menu button function might wonna do this,
to show changed info)

 isSuspended

 resume

resume activeHelp (eg. after doing a showMeHowItWorks)

Usage example(s):

ActiveHelp resume FlyByHelp resume

 start

start activeHelp for all apps

Usage example(s):

ActiveHelp start FlyByHelp start

 startFor: anApplicationOrTopView

start activeHelp for a single app

 stop

stop activeHelp for all (except for individual apps)

Usage example(s):

ActiveHelp stop FlyByHelp stop

 stopFor: anAppOrTopView

stop activeHelp for a single app

 suspend

suspend activeHelp (eg. before doing a showMeHowItWorks)

Usage example(s):

ActiveHelp suspend FlyByHelp suspend

Instance protocol:

 buttonMotion: buttonAndModifierState x: x y: y view: aView

handle motion events - prepare to show help

 handleMouseIn: aView x: x y: y

handle motion events - if the mousepointer left the
previous helped view, hide the help

 keyPress: key x: x y: y view: view

unconditionally hide the help view

 keyRelease: key x: x y: y view: view

unconditionally hide the help view

 pointerEnter: state x: x y: y view: aView

handle pointer entering a view; prepare to show help

 pointerLeave: state view: aView

handle pointer leaving a view; hide help text

 processEvent: ev

Warning: this is invoked synchronously directly from the display's eventloop

 basicHelpTextFor: aView at: aDevicePointOrNil

retrieve helptext for aView as a string;
walk along the view's superView chain,
asking models and views encountered while walking.
The first one who understands and returns a nonNil answer to the
#helpTextFor:at: or #helpTextFor: message ends this search and the
returned string is returned.

 helpTextFor: aView at: aDevicePointOrNil

retrieve helptext for aView as a string;
walk along the view's superView chain,
asking models and views encountered while walking.
The first one who understands and returns a nonNil answer to the
#helpTextFor:at: or #helpTextFor: message ends this search and the
returned string is returned.

 helpTextFromModel: aModelOrTopView view: aView at: aPointOrNil

helper: ask aModel for its helpText.

 helpTextFromView: aView at: aPointOrNil

helper: ask aView for its helpText.

 hideIfPointerLeft: aView

hide help, if the pointer is not in aView

 interestedIn: aView

return true, if I am interested in aView (either listeningForAll,
or in my list of apps)

 targetViewInitiatesHelpViaSensor

true if the target view is asked to show the help via the sensor;
false, if I do it myself synchronously.

 delayTime

 showTime

how long shall the help be shown;
0 means: forever (until user moves the mouse);
>0 means that number of seconds

 hideHelp

hide the help text - nothing done here

 hideHelpIgnoringErrors

hide the help text

 initiateHelp

determine where the mouse pointer is located,
and start showing a tooltip for it right now.
This can be called to force update of the tooltip,
in case a widget has changed its mind
(typically: an undo menu button function might wonna do this,
to show changed info)

 initiateHelpFor: aView

start showing a tooltip for aView right now.
This can be called to force update of the tooltip,
in case a widget has changed its mind
(typically: an undo menu button function might wonna do this,
to show changed info)

 initiateHelpFor: aView at: aPointOrNil

ask aView for helpText, passing x/y coordinates;
start a timeout process to display this helpText after some delay;
Normally used internally, but can also be used by widgets to force
re-negotiation of the displayed helpText
(for example in a menu, when the selection changes)

Usage example(s):

('%1: initiateHelpFor: %2' bindWith:self className with:aView) infoPrintCR.

 initiateHelpFor: aView at: aPointOrNil now: showItNow

ask aView for helpText, passing x/y coordinates;
start a timeout process to display this helpText after some delay;
Normally used internally, but can also be used by widgets to force
re-negotiation of the displayed helpText
(for example in a menu, when the selection changes)

 stopHelpDisplayProcess

 listenFor: anAppOrTopView

start listening

 listenForAll

start listening

 start

 stop

 unlistenAll

stop listening

 unlistenFor: anApp

stop listening for an app

Examples:

      |app top myAppClass|

      Class withoutUpdatingChangesDo:[
          myAppClass := ApplicationModel 
                          subclass:#'Demos::DemoApp'
                          instanceVariableNames:''
                          classVariableNames:''
                          poolDictionaries:''
                          category:'demos'.

          myAppClass 
              compile:'helpTextFor:aView    Transcript showCR:''hello''. ^ ''this is some helpText'''.

      ].
      app := myAppClass new.

      top := StandardSystemView new.
      top extent:300@100.
      top application:app.
      top open.

      ActiveHelp startFor:app.

      Class withoutUpdatingChangesDo:[
          myAppClass removeFromSystem
      ]

      |app top button1 button2|

      app := Plug new.
      app respondTo:#helpTextFor:
               with:[:view | 
                             view == button1 ifTrue:[
                               'this is button1'
                             ] ifFalse:[
                               view == button2 ifTrue:[
                                 'some help for button2'
                               ] ifFalse:[
                                 nil
                               ]
                             ]
                    ].

      top := StandardSystemView new.
      top extent:300@100.
      button1 := Button label:'b1' in:top.
      button1 origin:0.0@0.0 corner:0.5@30. 
      button2 := Button label:'b2' in:top.
      button2 origin:0.5@0.0 corner:1.0@30.
      top model:app. '<-- normally this would be: top application:app'.
      top open

      |app top button1 button2 infoView|

      app := Plug new.
      app respondTo:#helpTextFor:
               with:[:view | infoView label:'info ...'.
                             view == button1 ifTrue:[
                               infoView label:'this is button1'
                             ].
                             view == button2 ifTrue:[
                               infoView label:'some help for button2'
                             ].
                             nil
                    ].

      top := StandardSystemView new.
      top extent:300@100.
      button1 := Button label:'b1' in:top.
      button1 origin:0.0@0.0 corner:0.5@30. 
      button2 := Button label:'b2' in:top.
      button2 origin:0.5@0.0 corner:1.0@30.
      infoView := Label label:'info ...' in:top.
      infoView level:-1; origin:0.0@1.0 corner:1.0@1.0.
      infoView topInset:(infoView preferredExtent y negated - 3);
               leftInset:3; 
               rightInset:3; 
               bottomInset:3;
               adjust:#left.
      top model:app. '<-- normally this would be: top application:app'.
      top open