"{ Encoding: utf8 }"

"{ Package: 'stx:libtool2' }"

"{ NameSpace: Smalltalk }"

Object subclass:#ShowMeHowItWorks

	instanceVariableNames:'application opStream streamStack lastComponentName lastComponent

		lastResult voice translate language verifying

		closeApplicationWhenFinished defaultComponentWaitTime ui

		theShowFile defaultElementTimeout applicationStack'

	classVariableNames:'IntroShownCount DebugMode StartLabel'

	poolDictionaries:''

	category:'Interface-Help'

!

Object subclass:#ItemInView

	instanceVariableNames:'view item boundsInView'

	classVariableNames:''

	poolDictionaries:''

	privateIn:ShowMeHowItWorks

!

!ShowMeHowItWorks class methodsFor:'documentation'!

documentation

"

    automatic presentations.

    To see how it works, open a methodFinder:

        MethodFinderWindow open

    and select its 'Show me how it works' item in the help menu.

    [author:]

        Claus Gittinger

"

!

example

    MethodFinderWindow open.

    ShowMeHowItWorks do:#(

        ( showing: 'Choose the number of arguments' do:(

            moveTo: NumberOfArguments

            select: '1' 

        ))  

        (showing: 'Click into the "receiver" field' do:(

            moveTo: ReceiverEditor

            click: ReceiverEditor 

        ))

        (showing: 'Enter a value (or expression) into "receiver" field' do:(

            enter: '100'

        ))

        (showing: 'Click into the "first argument" field' do:(

            moveTo: Arg1Editor

            click: ReceiverEditor

        ))

        (showing: 'Enter a value (or expression) into "receiver" field' do:(

            enter: '100'

        ))

    )

!

scriptFormat

"

    speaking:

        show:           'text'

    mouse movement:

        moveTo:         '<component>'       move there and circle around

        fastMoveTo:     '<component>'       move without circling

        (drag: '<fromComponent>' toComponent: '<toComponent>' dropAt:<pos> show:'text')

            pos is one of #topLeft, #topCenter, #topRght, #bottomLeft, #bottomCenter, #bottomRight

            text is spoken before the drop

    mouse actions:

        click

        click:          buttonNumber

        select:         itemsIndexOrLabelOrPattern

            itemsIndexOrLabelOrPattern can be an integer or text

    misc:

        wait:           seconds             just pause

        label:          'name'              for debugging, presentation can be started at some

                                            label, by setting the StartLabel class variable

        (waitFor: '<component>' timeout:seconds)

                                            wait for a component to appear

        open            'nameOfAppModelClass'

                                            open an application (class)

        raise           'application'

        raise           'masterApplication'

        intro           

component naming:

    '<component>' can be:

        name of a component, as defined in the UI-spec's nameKey,

        helpKey

        title

        label

     a path like 'ProjectTree/ToolBar' will first find ProjectTrue, then ToolBar

     a menu item index like 'Toolbar/item[idx]'

"

! !

!ShowMeHowItWorks class methodsFor:'running'!

application:anApplicationOrNilForAll do:specArray 

    "spec contains a list of action commands (show: / moveTo: etc.)"

    self new 

        application:anApplicationOrNilForAll;

        do:specArray 

    "

     ShowMeHowItWorks do:

        #(

            (language: de)

            (show: 'üben üben üben')

            (wait: 0.5)

            (moveTo: NameOfComponent)

        )    

    "

    "Created: / 19-07-2019 / 10:52:59 / Claus Gittinger"

    "Modified (comment): / 23-07-2019 / 10:26:42 / Claus Gittinger"

!

application:anApplicationOrNilForAll doShowFile:aFilename 

    "spec contains a list of action commands (show: / moveTo: etc.)"

    self new 

        application:anApplicationOrNilForAll;

        doShowFile:aFilename 

    "

     ShowMeHowItWorks do:

        #(

            (language: de)

            (show: 'üben üben üben')

            (wait: 0.5)

            (moveTo: NameOfComponent)

        )    

    "

    "Created: / 19-07-2019 / 10:52:59 / Claus Gittinger"

    "Modified (comment): / 23-07-2019 / 10:26:42 / Claus Gittinger"

!

do:specArray

    "spec contains a list of action commands (show: / moveTo: etc.)"

    self do:specArray withUI:false

    "

     ShowMeHowItWorks do:

        #(

            (language: de)

            (show: 'üben üben üben')

            (wait: 0.5)

            (moveTo: NameOfComponent)

        )    

    "

    "Created: / 19-07-2019 / 10:52:59 / Claus Gittinger"

    "Modified (comment): / 23-07-2019 / 10:26:42 / Claus Gittinger"

!

do:specArray from:startLabelOrNil withUI:withUIBoolean

    "spec contains a list of action commands (show: / moveTo: etc.)"

    self new 

        do:specArray 

        from:startLabelOrNil

        withUI:withUIBoolean

    "

     ShowMeHowItWorks 

        do:#(

            (language: de)

            (show: 'üben üben üben')

            (wait: 0.5)

            (moveTo: NameOfComponent)

        )

        withUI:true

    "

    "Created: / 19-07-2019 / 10:52:59 / Claus Gittinger"

    "Modified (comment): / 23-07-2019 / 10:26:42 / Claus Gittinger"

!

do:specArray withUI:withUIBoolean

    "spec contains a list of action commands (show: / moveTo: etc.)"

    self new do:specArray withUI:withUIBoolean

    "

     ShowMeHowItWorks 

        do:#(

            (language: de)

            (show: 'üben üben üben')

            (wait: 0.5)

            (moveTo: NameOfComponent)

        )

        withUI:true

    "

    "Created: / 19-07-2019 / 10:52:59 / Claus Gittinger"

    "Modified (comment): / 23-07-2019 / 10:26:42 / Claus Gittinger"

! !

!ShowMeHowItWorks methodsFor:'accessing'!

application:anApplication

    "if set, only that application is presented (widget search is limited to that one)"

    application := anApplication.

!

setLanguage:lang

    voice := OperatingSystem bestVoiceForLanguage:lang.

    language := lang.

    "Created: / 23-07-2019 / 10:27:02 / Claus Gittinger"

! !

!ShowMeHowItWorks methodsFor:'commands'!

closeApplication

    <action>

    application closeRequest.

!

freezePin:pinName ofStep:stepName with:freezeString

    <action>

    |diagramEditor pinPO|

    (diagramEditor := lastComponent) isScrollWrapper ifTrue:[

        diagramEditor := lastComponent scrolledView

    ].

    pinPO := self pinPOForPin:pinName ofStep:stepName. 

    diagramEditor selection:{ pinPO }.

    diagramEditor doubleClickOn:pinPO.

    self fastMoveTo:(lastComponentName,'/','EditField').

    self click.

    self clear.

    self type:freezeString.

    self key:#Return.

!

intro

    <action>

    verifying ifTrue:[^ self].

    IntroShownCount := (IntroShownCount ? 0).

    "/ only say this a few times..

    IntroShownCount > 3 ifTrue:[^ self].

    IntroShownCount := IntroShownCount + 1.

    language isNil ifTrue:[

        self setLanguage:(Smalltalk language). 

    ].

    self tell:(self class classResources 

                string:'You can stop this show, by pressing the SHIFT key').

    "Created: / 19-07-2019 / 15:49:19 / Claus Gittinger"

    "Modified: / 23-07-2019 / 11:06:13 / Claus Gittinger"

!

label:nameOfLabel

    <action>

    "/ skipped here; see goto

!

language:lang

    <action>

    self setLanguage:lang.

    translate := false.

    "Created: / 23-07-2019 / 10:27:02 / Claus Gittinger"

!

open:applicationClassName

    <action>

    |appClass|

    (appClass := Smalltalk classNamed:applicationClassName) isNil ifTrue:[

        self error:'no such application class'

    ].

    verifying ifFalse:[

        application := appClass new openAndWaitUntilVisible.

        closeApplicationWhenFinished := true.

    ].

    "Created: / 19-07-2019 / 15:09:45 / Claus Gittinger"

!

pause

    <action>

    Dialog information:(self class classResources 

                            stringWithCRs:'Show Paused.\Click on "OK" to proceed')

    "Created: / 19-07-2019 / 15:03:17 / Claus Gittinger"

    "Modified: / 19-07-2019 / 16:13:33 / Claus Gittinger"

!

popApplication

    <action>

    "go back to the previous app"

    application := applicationStack removeLast.

!

pushApplication:newApplicationOrName

    <action>

    "goto another app, remembering where we were before"

    |newApplication|

    (newApplication := newApplicationOrName) isString ifTrue:[

        newApplication := self findApplication:newApplicationOrName ifMultiple:nil.

        self assert: newApplication notNil.

    ].

    applicationStack isNil ifTrue:[applicationStack := OrderedCollection new].

    applicationStack add:application.

    self application:newApplication.

!

raise:what

    <action>

    verifying ifTrue:[^ self].

    what == #application ifTrue:[

        application topView raise.

        ^ self

    ].

    what == #masterApplication ifTrue:[

        application windowGroup isModal ifTrue:[

            application windowGroup mainGroup topViews first raise

        ] ifFalse:[

            (application masterApplication ? application) topViews first raise.

        ].

        ^ self

    ].

    self halt.

!

selectPin:pinName ofStep:stepName

    <action>

    |diagramEditor pinPO count|

    (diagramEditor := lastComponent) isScrollWrapper ifTrue:[

        diagramEditor := lastComponent scrolledView

    ].

    count := 0.

    [

        Delay waitForSeconds:0.1.

        pinPO := self pinPOForPin:pinName ofStep:stepName.

    ] doWhile:[pinPO isNil and:[ (count := count+1) < 20]].

    self movePointerToComponent:diagramEditor offset:(pinPO frame center).

    diagramEditor selection:{ pinPO }. 

!

show:message

    "showing (and speak) some message."

    <action>

    self showing:message saying:nil do:nil

    "Created: / 19-07-2019 / 15:59:18 / Claus Gittinger"

    "Modified (comment): / 19-07-2019 / 18:54:36 / Claus Gittinger"

!

show:message for:seconds

    "showing (and speak) some message and wait for some time."

    <action>

    DebugMode == true ifTrue:[^ self].

    self show:message.

    self wait:seconds.

    "Created: / 19-07-2019 / 18:54:20 / Claus Gittinger"

!

show:message saying:sentenceOrNil

    "showing (and speak) some message."

    <action>

    self showing:message saying:sentenceOrNil do:nil

    "Created: / 19-07-2019 / 15:59:18 / Claus Gittinger"

    "Modified (comment): / 19-07-2019 / 18:54:36 / Claus Gittinger"

!

show:message saying:sentenceOrNil for:seconds

    "showing (and speak) some message and wait for some time."

    <action>

    DebugMode == true ifTrue:[^ self].

    self show:message saying:sentenceOrNil.

    self wait:seconds.

    "Created: / 19-07-2019 / 18:54:20 / Claus Gittinger"

!

showing:message do:operationsOrNothing

    "execute operationsOrNothing while showing (and speaking) some message."

    <action>

    self showing:message saying:nil do:operationsOrNothing

!

showing:message saying:sentenceOrNil do:operationsOrNothing

    "execute operationsOrNothing while showing (and speaking) some message."

    <action>

    |xLatedMessage messageView talkDone|

    xLatedMessage := (translate and:[application notNil]) 

                            ifTrue:[application resources stringWithCRs:message]

                            ifFalse:[message withCRs].

    self assert:(operationsOrNothing isNil or:[operationsOrNothing isSequenceable]).

    messageView := ActiveHelpView for:xLatedMessage.

    "/ messageView shapeStyle:#cartoon.

    [

        |p top left bot right w h|

        w := messageView preferredExtent x.

        h := messageView preferredExtent y.

        p := Screen current pointerPosition.

        left := p x. top := p y.

        bot := top + h. right := left + w.

        messageView origin:(left @ top).

        messageView makeFullyVisible.

        messageView realize.

        self talking ifTrue:[

            talkDone := Semaphore new.

            [

                |sentence|

                sentence := (sentenceOrNil ? xLatedMessage) copy withCRs replaceAny:c'\t' with:(Character space).

                sentence := sentence copy withCRs replaceAny:c'\n\r' with:(Character space).

                self tell:sentence.

                talkDone signal

            ] fork.

            "/

            "/ allow speaker some headoff

            verifying ifFalse:[

                Delay waitForSeconds:(xLatedMessage size / 15)+0.5.

            ].

        ].

        operationsOrNothing notEmptyOrNil ifTrue:[

            self doStream:(operationsOrNothing readStream).

        ].

    ] ensure:[