"{ Encoding: utf8 }"

"

 COPYRIGHT (c) 2018 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:libtool2' }"

"{ NameSpace: Smalltalk }"

Object subclass:#ShowMeHowItWorks

	instanceVariableNames:'application opStream streamStack lastComponentName lastComponent

		lastResult voice translate language verifying

		closeApplicationWhenFinished defaultComponentWaitTime ui

		theShowFile defaultElementTimeout applicationStack pronunciations'

	classVariableNames:'IntroShownCount DebugMode StartLabel Verify'

	poolDictionaries:''

	category:'Interface-Help'

!

Object subclass:#ItemInView

	instanceVariableNames:'view item boundsInView'

	classVariableNames:''

	poolDictionaries:''

	privateIn:ShowMeHowItWorks

!

!ShowMeHowItWorks class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 2018 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

"

    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'

        ))

    )

!

example2

    ShowMeHowItWorks do:#(

        language: 'de'

        (pronounce:'feature' as:'fiedscher')

        (pronounce:'suite' as:'swied')

        (pronounce:'expecco' as:'expecko')

        (pronounce:'read me' as:'ried mie')

        (pronounce:'python' as:'paiton')

        (pronounce:'jenkins' as:'dschengkins')

        show:'jenkins'

        show:'dies ist ein neues feature'

        show:'suite'

        show:'expecco'

        show:'read me'

        show:'python'

        show:'node'

    )

!

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:'instance creation'!

new

    "return an initialized instance"

    ^ self basicNew initialize.

! !

!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. 

    pinPO isNil ifTrue:[

        self error:('No pin named "%1" for step "%2" found in diagram' bindWith:pinName with:stepName).

        ^ self.

    ].

    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 

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

!

pronounce:word as:pronunciation

    <action>

    pronunciations isNil ifTrue:[

        pronunciations := OrderedDictionary new.

    ].

    pronunciations at:word put:pronunciation

!

pushApplication:newApplicationOrName

    <action>

    "goto another app, remembering where we were before"

    |newApplication|

    (newApplication := newApplicationOrName) isString ifTrue:[

        newApplication := self findApplication:newApplicationOrName ifMultiple:nil.

        newApplication isNil ifTrue:[

            self error:('Could not find an application named "%1" (to switch to)' bindWith:newApplicationOrName).

        ].

        "/ 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]].

    pinPO isNil ifTrue:[

        self error:('No pin named "%1" for step "%2" found in diagram' bindWith:pinName with:stepName).

        ^ self.

    ].

    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