"

 COPYRIGHT (c) 2001 by eXept Software AG

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

ActiveHelp subclass:#FlyByHelp

	instanceVariableNames:'currentFrame currentView currentHelpView showProcess closeProcess'

	classVariableNames:'MaxNumberOfLines MaxNumberOfColumns'

	poolDictionaries:''

	category:'Interface-Help'

!

!FlyByHelp class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 2001 by eXept Software AG

              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

"

    an instance of me is used to provide tooltips 

    (sigh: smalltalk was ahead of its time in the early 90's:

     initially called 'activeHelp', then renamed to 'flyByHelp' 

     and now commonly known as tooltip).

    I will watch the mouse movements via an event hook, and determine

    where the mouse pointer is. Then ask the underlying view about its

    helpText and display it in a little floating popup view.

    The hool is installed via:

     FlyByHelp start

    and possibly deactivated/uninstalled via:

     FlyByHelp stop

    There can be only one FlyByHelp at any time - the start/stop methods

    assure that.

"

!

examples

"

    UserPreferences current toolTipShapeStyle:nil

    UserPreferences current toolTipShapeStyle:#cartoon

     FlyByHelp isActive

     FlyByHelp stop

     FlyByHelp start

"

! !

!FlyByHelp class methodsFor:'accessing'!

currentlyShownView

    TheOneAndOnlyHelpListener isNil ifTrue:[^ nil].

    ^ TheOneAndOnlyHelpListener currentlyShownView

    "Modified: / 09-06-2010 / 16:35:48 / cg"

!

maxNumberOfColumns

    ^ MaxNumberOfColumns ? 200

!

maxNumberOfLines

    ^ MaxNumberOfLines ? 40

! !

!FlyByHelp methodsFor:'defaults'!

flyByHelpTimeoutMillis

    "abort flyby help text generation, if no text can be generated within that

     time delta. This is used to abort long-lasting parsing/scanning/analysis in

     large methods when the mouse is moved over some syntactic constructs, and

     it takes too long to parse...

     The returned time is given in ms"

    ^ 300

! !

!FlyByHelp methodsFor:'event handling'!

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

    aView == currentHelpView ifTrue:[

        "/ the help-bubble itself

        ^ false

    ].

    "/ don't start tooltip, if this view is not active.

    "/ The following line does not work, because motion events are reported for the current focus-view,

    "/ which is always active. Must check after we have determined the view under the pointer

    "/      aView topView isActive ifFalse:[^ false].

    ^ super buttonMotion:buttonAndModifierState x:x y:y view:aView

!

buttonPress:button x:x y:y view:aView

    |prevView|

    "/ hideHelp nils the currentView

    "/ we restore it, so the tooltip is not shown again for this view

    "/ until the mouse really leaves the view

    "/ let's call this the "do-not-show-in-this-view mode"

    prevView := currentView.

    self hideHelp.

    currentView := prevView.

    ^ false

    "Modified: / 23-12-2011 / 20:37:28 / cg"

!

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

    <resource: #keyboard (#Escape #Control #Shift)>

    |prevView text|

    currentHelpView notNil ifTrue:[

            "/ generate a line suitable for the resources file (a null translation)

            "/ into the clipboard; makes it easy to add missing translations to a .rs file,

            "/ by pressing paragraph whenever you see an untranslated helptext

            text := (lastHelpText storeString withoutCRs, '    ' , lastHelpText storeString withoutCRs).

            aView setClipboardText:text.

            self hideHelp.

        ].

        key == #Escape ifTrue:[

            prevView := currentView.

            self hideHelp.

            currentView := prevView.

        ].

        (#(#'Shift' #'Shift_L' #'Shift_R') includes:key) ifTrue:[

            aView device ctrlDown ifTrue:[

        ].

        (#(#'Control' #'Control_L' #'Control_R') includes:key) ifTrue:[

            "/ reopen showing the key

            self initiateHelpFor:aView at:(x@y) now:true.

        ].

        (#('Shift' #'Shift_L' #'Shift_R' #'Control' #'Control_L' #'Control_R') includes:key) ifTrue:[

            "/ do not close on those...

            ^ false

        ].

    ].    

    "/ hideHelp nils the currentView

    "/ we restore it, so the tooltip is not shown again for this view

    "/ until the mouse really leaves the view

    "/ let's call this the "do-not-show-in-this-view mode"

    prevView := currentView.

    self hideHelpIgnoringErrors.

    currentView := prevView.

    ^ false

    "/ ^ super keyPress:key x:x y:y view:aView

    "Modified (format): / 25-12-2011 / 10:25:23 / cg"

    "Modified (format): / 16-04-2018 / 16:53:15 / stefan"

!

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

    <resource: #keyboard (#Control)>

    currentHelpView notNil ifTrue:[

        (#(#'Control' #'Control_L' #'Control_R') includes:key) ifTrue:[

            "/ reopen showing the text

            self initiateHelpFor:aView at:(x@y) now:true.

            ^ true

        ].

        (#('Shift' #'Shift_L' #'Shift_R' #'Control' #'Control_L' #'Control_R') includes:key) ifTrue:[

            "/ do not close on those...

            ^ false

        ].

    ].

    ^ super keyRelease:key x:x y:y view:aView

    "Created: / 20-02-2019 / 11:26:19 / Claus Gittinger"

!

mouseWheelMotion:state x:x y:y amount:amount deltaTime:dTime view:aView

    currentHelpView notNil ifTrue:[

        self handleMouseIn:aView x:x y:y.

    ].

    ^ false

!

pointerLeave:state view:aView

    aView == currentHelpView ifTrue:[^ true].

    "/ clear the do-not-show-in-this-view mode (see keyPress)

"/     (currentHelpView isNil and:[currentView notNil]) ifTrue:[currentView := nil].

    ^ super pointerLeave:state view:aView

! !

!FlyByHelp methodsFor:'help texts'!

helpTextFromModel:aModel view:aView at:aPointOrNil 

    "helper: ask aModel for its helpText."

    |text|

    (aPointOrNil notNil and:[aModel respondsTo:#helpTextFor:at:]) ifTrue:[

        text := aModel helpTextFor:aView at:aPointOrNil.

        text notNil ifTrue:[

            "/ Transcript showCR:aModel.

            "/ Transcript showCR:'via model-text'; showCR:text.

            ^ text

        ].

    ].

    (aModel respondsTo:#helpTextFor:) ifTrue:[

        text := aModel helpTextFor:aView.

        text notNil ifTrue:[

            "/ Transcript showCR:aModel.

            "/ Transcript showCR:'via model-text'; showCR:text.

            ^ text

        ].

    ].

    ^ nil

    "Modified: / 09-01-2018 / 17:35:26 / stefan"

    "Modified: / 11-06-2018 / 09:53:40 / Claus Gittinger"

!

helpTextFromView:aView at:aPointOrNil 

    "helper: ask aView for its helpText."

    |text key app|

    "/ is there any view which does not understand helpTextAt: ???

    (aPointOrNil notNil and:[aView respondsTo:#helpTextAt:]) ifTrue:[

        text := aView helpTextAt:aPointOrNil.

        text notNil ifTrue:[

            "/ Transcript showCR:'via helpTextAt:'; showCR:text.

            ^ text

        ].

    ].

    "/ is there any view which does not understand helpText ???

    (aView respondsTo:#helpText) ifTrue:[

        text := aView helpText.

        text notNil ifTrue:[

            "/ Transcript showCR:'via helpText'; showCR:text.

            ^ text value

        ].

    ].

    "/ to be enabled in next release...

"/    (aView superView notNil

"/    and:[aView superView respondsTo:#helpTextFor:]) ifTrue:[

"/        text := aView superView helpTextFor:aView.

"/        text notNil ifTrue:[^ text].

"/    ].

    "/ is there any view which does not understand helpKey ???

    (aView respondsTo:#helpKey) ifTrue:[

        key := aView helpKey.

        key notNil ifTrue:[

            app := aView application.

            app isNil ifTrue:[

                |topView topViewsHelpSpec|

                "/ special case for oldStyle Dialog subclasses.

                topView := aView topView.

                (topViewsHelpSpec := topView helpSpec) notNil ifTrue:[

                    text := topViewsHelpSpec at:key ifAbsent:nil.

                    text notNil ifTrue:[

                        "/ Transcript showCR:'via topViewspec+helpKey'; showCR:text.

                        ^ topView resources stringWithCRs:text.

                    ].    

                ].    

                app := Error handle:[:ex | nil] do:[ aView windowGroup mainGroup application ].

            ].

            app notNil ifTrue:[

                text := app helpTextForKey:key.

                true "text notNil" ifTrue:[

                    "/ Transcript showCR:'via helpKey+helpTextForKey:'; showCR:text.

                    ^ text

                ].

            ].

            text := aView resources string:key.

            true "(text notNil and:[text ~= key])" ifTrue:[

                "/ Transcript showCR:'via helpKey'; showCR:text.

                ^ text

            ]    

        ].

    ].

    ^ nil.

    "Modified: / 09-01-2018 / 17:38:42 / stefan"

    "Modified (format): / 07-06-2018 / 09:51:41 / sr"

    "Modified: / 07-02-2019 / 19:18:39 / Claus Gittinger"

! !

!FlyByHelp methodsFor:'queries'!

currentlyShownView

    ^ currentHelpView

!

toolTipFollowsMouse

    "if true, the tooltip-window moves with the pointer

     so that it stays away from (does not cover) the mouse pointer"

    ^ false

    "Modified: / 06-06-2018 / 17:37:19 / Claus Gittinger"

! !

!FlyByHelp methodsFor:'show & hide help'!

activeHelpViewForApplication:applicationOrNil text:helpText onDevice:aDevice

    applicationOrNil notNil ifTrue:[

        ^ applicationOrNil activeHelpViewFor:helpText onDevice:aDevice

    ].

    ^ ActiveHelpView for:helpText onDevice:aDevice.

    "

     (ActiveHelpView for:'Hello' onDevice:Display) open

    "

!

hideHelp

    "hide the help text"

    |p|

    "/ lastHelpText := nil.

    self stopHelpDisplayProcess.

    lastHelpText := nil.

    currentHelpView notNil ifTrue:[

        [

            currentHelpView notNil ifTrue:[

                currentHelpView destroy.

                currentHelpView := nil.

                currentView := nil.

            ]

        ] valueUninterruptably

    ].

    currentFrame := nil.

    (p := closeProcess) notNil ifTrue:[

        closeProcess := nil.

        p terminate.

    ]

    "Modified: / 28-06-1997 / 14:03:50 / cg"

    "Modified: / 16-04-2018 / 16:51:01 / stefan"

!

hideIfPointerLeft:aView

    "hide help, if the pointer is not in aView"

    |helpFrame whereOnScreen|

    (helpFrame := currentFrame) notNil ifTrue:[

        whereOnScreen := aView graphicsDevice pointerPosition.

        ((helpFrame insetBy:1@1) containsPoint:whereOnScreen) ifFalse:[

            self hideHelp.

        ] ifTrue:[

            pointerPositionAtShowTime notNil ifTrue:[

                (whereOnScreen dist:pointerPositionAtShowTime) > 10 ifTrue:[

                    self hideHelp.

                ].    

            ].    

        ].            

    ].

    "Modified: / 28-05-1996 / 20:18:28 / cg"

    "Modified: / 16-04-2018 / 16:59:48 / stefan"

    "Modified: / 08-06-2018 / 10:30:04 / Claus Gittinger"

!

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

    |text delayTime|