"{ Encoding: utf8 }"

"

 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.

"

"{ Package: 'stx:libview2' }"

"{ NameSpace: Smalltalk }"

EventListener subclass:#ActiveHelp

	instanceVariableNames:'lastHelpText listeningForAll applicationsOrTopViewsWithHelp

		lastHelpWidget lastPointerPosition pointerPositionAtShowTime

		suspended'

	classVariableNames:'Debugging DebuggingEvents DebuggingHelpText Suspended DoHelpKey'

	poolDictionaries:''

	category:'Interface-Help'

!

ActiveHelp class instanceVariableNames:'DelayTime ShowTime TheOneAndOnlyHelpListener'

"

 No other class instance variables are inherited by this class.

"

!

!ActiveHelp class methodsFor:'documentation'!

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.

"

!

documentation

"

    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.

    [author:]

        Claus Gittinger

    [start with:]

        ActiveHelp start

        ActiveHelp stop

    [See also:]

        ActiveHelpView

        WindowGroup WindowEvent

        ApplicationModel StandardSystemView

"

!

examples

"

  Active Help for a single view

  or app (whatever the global settings are):

  Can be initiated by an app when its opened.

                                                                        [exBegin]

        |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

        ]

                                                                        [exEnd]

  Active Help (for all views):

    (make certain that activeHelp is turned on ...

     ... otherwise, you will see nothing)

    the following example uses a Plug as a model replacement.

    In concrete application, you would create a method to implement the helpText

    query message.

                                                                        [exBegin]

        |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

                                                                        [exEnd]

    (make certain that activeHelp is turned on ...

     ... otherwise, you will see nothing)

    alternatively, display of the helpMessage in a local, private view:

                                                                        [exBegin]

        |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

                                                                        [exEnd]

"

! !

!ActiveHelp class methodsFor:'initialization'!

initialize

    Debugging := false.

    DebuggingEvents := false.

    DebuggingHelpText := false.

    "Modified: / 19-06-2018 / 12:53:36 / Claus Gittinger"

! !

!ActiveHelp class methodsFor:'accessing'!

currentHelpListener

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

    ^ TheOneAndOnlyHelpListener

    "

     ActiveHelp currentHelpListener

     FlyByHelp currentHelpListener

    "

    "Created: 28.6.1997 / 13:59:44 / cg"

!

debugging

    ^ Debugging ? false

    "Modified: / 22-12-2011 / 10:46:30 / cg"

    "Modified: / 11-06-2018 / 10:27:40 / Claus Gittinger"

!

debugging:aBoolean

    Debugging := aBoolean.

    "

     self debugging:true

     self debugging:false

    "

    "Modified (comment): / 22-12-2011 / 10:43:32 / cg"

    "Modified (format): / 11-06-2018 / 10:30:30 / Claus Gittinger"

!

debuggingHelpText

    ^ DebuggingHelpText ? false

    "Created: / 11-06-2018 / 10:30:10 / Claus Gittinger"

!

debuggingHelpText:aBoolean

    DebuggingHelpText := aBoolean.

    "

     self debuggingHelpText:true

     self debuggingHelpText:false

    "

    "Created: / 11-06-2018 / 10:30:24 / Claus Gittinger"

!

delayTime

    ^ DelayTime ? 0.4

!

delayTime:numberOfSeconds

    "set the delay (the time, the cursor has to be in the view

     before help is shown). The default is 2 seconds."

    DelayTime := numberOfSeconds

    "

     ActiveHelp delayTime:0.5

     ActiveHelp delayTime:2

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

    ^ ShowTime ? 15

    "

     self showTime

    "

    "Modified: / 10-11-2010 / 12:29:44 / cg"

!

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

    ShowTime := numberOfSeconds

    "

     ActiveHelp showTime:10

     ActiveHelp showTime:99999 

     ActiveHelp showTime:30

    "

    "Modified: / 10-11-2010 / 12:29:40 / cg"

!

singleton

    ^ TheOneAndOnlyHelpListener

    "Created: / 27-02-2019 / 11:06:32 / Claus Gittinger"

! !

!ActiveHelp class methodsFor:'queries'!

isActive

    "return true, if activeHelp is turned on"

    TheOneAndOnlyHelpListener notNil ifTrue:[

        ((WindowSensor eventListeners ? #()) includesIdentical:TheOneAndOnlyHelpListener) ifTrue:[

            ^ true

        ].

        TheOneAndOnlyHelpListener := nil.

    ].

    ^ false.

    "

     FlyByHelp isActive

    "

    "Modified: 27.4.1996 / 15:07:57 / cg"

! !

!ActiveHelp class methodsFor:'start & stop'!

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

    self isActive ifTrue:[  

        TheOneAndOnlyHelpListener initiateHelp

    ].

    "Created: / 27-02-2019 / 11:08:54 / Claus Gittinger"

    "Modified (comment): / 27-02-2019 / 15:56:17 / Claus Gittinger"

!

isSuspended

    ^ Suspended ? false

!

resume

    "resume activeHelp (eg. after doing a showMeHowItWorks)"

    Suspended := false.

    "

     ActiveHelp resume

     FlyByHelp resume

    "

!

start

    "start activeHelp for all apps"

    TheOneAndOnlyHelpListener notNil ifTrue:[

        TheOneAndOnlyHelpListener stop.    

        TheOneAndOnlyHelpListener := nil.    

    ].

    Suspended := false.

    TheOneAndOnlyHelpListener isNil ifTrue:[

        TheOneAndOnlyHelpListener := self new.

    ].

    TheOneAndOnlyHelpListener start.

    ^ TheOneAndOnlyHelpListener

    "

     ActiveHelp start

     FlyByHelp start

    "

    "Modified: / 26.10.1997 / 23:16:54 / cg"

!

startFor:anApplicationOrTopView

    "start activeHelp for a single app"

    TheOneAndOnlyHelpListener isNil ifTrue:[

        Suspended := false.

        TheOneAndOnlyHelpListener := self new.

    ].

    TheOneAndOnlyHelpListener listenFor:anApplicationOrTopView

    "Modified: / 26.10.1997 / 23:17:05 / cg"

!

stop

    "stop activeHelp for all (except for individual apps)"

    TheOneAndOnlyHelpListener notNil ifTrue:[

        TheOneAndOnlyHelpListener stop.

        TheOneAndOnlyHelpListener := nil.

    ].

    "

     ActiveHelp stop

     FlyByHelp stop

    "

    "Modified: / 26.10.1997 / 23:18:58 / cg"

!

stopFor:anAppOrTopView

    "stop activeHelp for a single app"

    TheOneAndOnlyHelpListener notNil ifTrue:[

        TheOneAndOnlyHelpListener unlistenFor:anAppOrTopView.

    ].

    "Modified: / 26.10.1997 / 23:12:55 / cg"

    "Created: / 26.10.1997 / 23:18:41 / cg"

!

suspend

    "suspend activeHelp (eg. before doing a showMeHowItWorks)"

    Suspended := true.

    "

     ActiveHelp suspend

     FlyByHelp suspend

    "

! !

!ActiveHelp methodsFor:'event handling'!

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

    "handle motion events - prepare to show help"

    |realViewUnderCursor realP|

    (Suspended ? false) ifTrue:[^ false].   

    (aView sensor hasButtonMotionEventFor:aView) ifTrue:[^ false].

    "/ DebuggingEvents := true

    "/ DebuggingEvents := false

    DebuggingEvents == true ifTrue:[

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

    ].

    "/ Debugging := true

    "/ Debugging := false

    buttonAndModifierState == 0 ifTrue:[

"/        realViewUnderCursor := aView device viewFromPoint:(aView pointerPosition).

"/        realP := aView device translatePoint:(x@y) fromView:aView toView:realViewUnderCursor.

"/        self handleMouseIn:realViewUnderCursor x:realP x y:realP y.

        DebuggingEvents ifTrue:[('%1: motion %3@%4 in %5' bindWith:self className with:aView with:x with:y) infoPrintCR].

        self handleMouseIn:aView x:x y:y.