"{ 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'

	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)

        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 limtied 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'!

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"

!

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.

!

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 string:message]

                            ifFalse:[message].

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

    messageView := ActiveHelpView for:xLatedMessage.

    "/ messageView shapeStyle:#cartoon.

    [

        messageView origin:(Screen current pointerPosition + (0 @ 20)).

        messageView makeFullyVisible.

        messageView realize.

        self talking ifTrue:[

            talkDone := Semaphore new.

            [

                self tell:(sentenceOrNil ? xLatedMessage).

                talkDone signal

            ] fork.

            "/

            "/ allow speaker some headoff

            verifying ifFalse:[

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

            ].

        ].

        operationsOrNothing notEmptyOrNil ifTrue:[

            self doStream:(operationsOrNothing readStream).

        ].

    ] ensure:[

        messageView destroy

    ].

    self talking ifTrue:[

        talkDone wait.

    ].

    "Created: / 19-07-2019 / 11:19:27 / Claus Gittinger"

    "Modified: / 23-07-2019 / 10:52:30 / Claus Gittinger"

!

thankyou

    <action>

    self show:(self randomThankYou).

    "Created: / 23-07-2019 / 10:50:43 / Claus Gittinger"

!

wait:seconds

    <action>

    verifying ifTrue:[^ self].

    DebugMode == true ifTrue:[^ self].

    Display ctrlDown ifTrue:[^ self].

    Delay waitForSeconds:seconds

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

!

waitFor:componentName timeout:seconds

    <action>

    |endTime|

    verifying ifTrue:[^ self].

    endTime := Timestamp now + seconds.

    [   

        (self findComponent:componentName inAllApplications:true ifMultiple:nil) notNil ifTrue:[

            ^ self

        ].

        Delay waitForSeconds:0.05.

        Timestamp now > endTime ifTrue:[

            self error:('component %1 not present after %2' bindWith:componentName with:seconds)

        ]

    ] loop

! !

!ShowMeHowItWorks methodsFor:'commands - checking'!

isEmpty:componentName

    <action>

    |component|

    component := self componentNamed:componentName.

    component isScrollWrapper ifTrue:[ component := component scrolledView ].

    component isTextView ifTrue:[

        ^ component contents isEmptyOrNil

    ] ifFalse:[

        self halt.

    ].

    self error:'isEmpty: unhandled component type: ',component displayString.

    "Created: / 19-07-2019 / 15:33:47 / Claus Gittinger"

!

unless:query do:actions

    <action>

    |result|

    result := self doCommand:query.

    result ifFalse:[

        self doCommand:actions

    ].

    "Created: / 19-07-2019 / 15:33:32 / Claus Gittinger"

! !

!ShowMeHowItWorks methodsFor:'commands - mouse & keyboard'!

click

    "press-release"

    <action>