"

 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:libwidg2' }"

"{ NameSpace: Smalltalk }"

View subclass:#ProgressIndicator

	instanceVariableNames:'percentage showPercentage fgColor bgColor connectedTop

		connectedLabel collector finishAction closeTopWhenDone showBusy

		busyPosition busyDelta busyIndicationProcess'

	classVariableNames:''

	poolDictionaries:''

	category:'Views-Misc'

!

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

"

    a view showing a rectangle filled according the percentage value.

    Can be used as a progress indicator a la MSwindows;

    it can also be configured as a non-percentage busy indication

    via the showBusyIndication flag (a la netscape).

    Can be used as a widget within an application, or

    via the convenient #inBox: instance creation messages,

    which shows a progressDisplay in a modalBox, while some

    action is performed.

    See examples.

    [author:]

	Claus Gittinger

    [see also:]

	ActionWaitBox AnimatedLabel

"

!

examples

"

    basic (internal) interface

    (if progress indicator is to be used in a complex box ...):

    Before you get frustrated - see the convenient-interface examples

    at the end ;-)

                                                                        [exBegin]

      |top p h|

      top := ModalBox new.

      top extent:300@100.

      top label:'Progress'.

      p := ProgressIndicator in:top.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p level:-1.

      h := p preferredExtent y.

      p topInset:(h // 2) negated; 

        bottomInset:(h // 2) negated;

        leftInset:5;

        rightInset:5.

      [

          1 to:100 do:[:val |

              (Delay forSeconds:0.05) wait.

              p percentage:val 

          ].

          top hide.

      ] fork.

      top open.

                                                                        [exEnd]

    as a busy indicator

                                                                        [exBegin]

      |top p h|

      top := ModalBox new.

      top extent:300@100.

      top label:'Busy'.

      p := ProgressIndicator in:top.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p level:-1.

      h := p preferredExtent y.

      p topInset:(h // 2) negated; 

        bottomInset:(h // 2) negated;

        leftInset:5;

        rightInset:5.

      p showBusyIndication:true.

      [

          'do something here ....'.

          (Delay forSeconds:5) wait.

          top hide.

      ] fork.

      top open.

                                                                        [exEnd]

    changing colors, turning percentage display off:

                                                                        [exBegin]

      |top p h|

      top := StandardSystemView new.

      top extent:300@100.

      top label:'Progress'.

      p := ProgressIndicator in:top.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p level:-1.

      p showPercentage:false.

      p foregroundColor:(Color red).

      h := 10.

      p topInset:(h // 2) negated; 

        bottomInset:(h // 2) negated;

        leftInset:5;

        rightInset:5.

      top open.

      [

          1 to:100 do:[:val |

              (Delay forSeconds:0.05) wait.

              p percentage:val 

          ]

      ] fork

                                                                        [exEnd]

    as a busy indicator and percentage display (as in netscape)

                                                                        [exBegin]

      |top p h|

      top := ModalBox new.

      top extent:300@60.

      top label:'Busy'.

      p := ProgressIndicator in:top.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p level:-1.

      p showPercentage:false.

      p backgroundColor:(Color cyan).

      h := p preferredExtent y.

      p topInset:(h // 3) negated; 

        bottomInset:(h // 3) negated;

        leftInset:5;

        rightInset:5.

      p showBusyIndication:true.

      [

          top label:'Busy'.

          1 to:100 do:[:i |

            (Delay forSeconds:0.05) wait.

          ].

          top label:'Percentage'.

          p showBusyIndication:false.

          1 to:100 do:[:i |

            (Delay forSeconds:0.05) wait.

            p percentage:i. 

          ].

          top hide.

      ] fork.

      top open.

                                                                        [exEnd]

    with border (2D look):

                                                                        [exBegin]

      |top p h|

      top := StandardSystemView new.

      top extent:300@100.

      top label:'Progress'.

      p := ProgressIndicator in:top.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p borderWidth:1.

      h := p preferredExtent y.

      p topInset:(h // 2) negated; 

        bottomInset:(h // 2) negated;

        leftInset:5;

        rightInset:5.

      top open.

      [

          1 to:100 do:[:val |

              (Delay forSeconds:0.05) wait.

              p percentage:val 

          ]

      ] fork

                                                                        [exEnd]

    getting progress from a model:

                                                                        [exBegin]

      |model top p h|

      model := 0 asValue.

      top := StandardSystemView new.

      top extent:300@100.

      top label:'Progress'.

      p := ProgressIndicator in:top.

      p model:model.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p level:-1.

      h := p preferredExtent y.

      p topInset:(h // 2) negated; 

        bottomInset:(h // 2) negated;

        leftInset:5;

        rightInset:5.

      top open.

      [

          1 to:100 do:[:val |

              (Delay forSeconds:0.05) wait.

              model value:val 

          ]

      ] fork

                                                                        [exEnd]

    concrete example:

      search all files in the source directory for a string

      using grep. Show progress while doing so.

                                                                        [exBegin]

      |top p h names done|

      top := StandardSystemView new.

      top extent:300@100.

      top label:'Searching ...'.

      p := ProgressIndicator in:top.

      p origin:(0.0@0.5) corner:(1.0@0.5).

      p level:-1.

      h := p preferredExtent y.

      p topInset:(h // 2) negated; 

        bottomInset:(h // 2) negated;

        leftInset:5;

        rightInset:5.

      top openWithPriority:(Processor activePriority + 1).

      names := 'source' asFilename directoryContents.

      done := 0.

      names do:[:aName |

        |fn stream line|

        p percentage:(done / names size * 100).

        fn := ('source/' , aName) asFilename.

        fn isDirectory ifFalse:[

            stream := fn readStream.

            [stream atEnd] whileFalse:[

                line := stream nextLine.

                (line findString:'subclass:') ~~ 0 ifTrue:[

                    Transcript showCR:line

                ].

            ].

            stream close.

        ].

        done := done + 1

      ].

      top destroy

                                                                        [exEnd]

   using the convenient inBox-interface

   (this creates a box and an activity label and evaluates a block

    to indicate ...)

    basic interface demonstration:

                                                                        [exBegin]

      |p|

      p := ProgressIndicator 

                inBoxWithLabel:'doing something  ...'

                abortable:true.

      p showProgressOf:

            [:progressValue :currentAction |

              1 to:100 do:[:val |

                  (Delay forSeconds:0.05) wait.

                  val == 25 ifTrue:[

                      currentAction value:'still going ...'

                  ].

                  val == 50 ifTrue:[

                      currentAction value:'halfway through ...'

                  ].

                  val == 75 ifTrue:[

                      currentAction value:'almost finished ...'

                  ].

                  progressValue value:val 

              ]

            ]

                                                                        [exEnd]

    above search example using this convenient interface:

                                                                        [exBegin]

      |p|

      p := ProgressIndicator 

                inBoxWithLabel:'searching files ...'

                abortable:false.

      p showProgressOf:

            [:progressValue :currentAction |

                |names nDone|

                names := 'source' asFilename directoryContents.

                nDone := 0.

                names do:[:aName |

                  |fn stream line|

                  progressValue value:(nDone / names size * 100).

                  currentAction value:'searching ' , 'source/' , aName , ' ...'.

                  fn := ('source/' , aName) asFilename.

                  fn isDirectory ifFalse:[

                      stream := fn readStream.

                      [stream atEnd] whileFalse:[

                          line := stream nextLine.

                          (line findString:'subclass:') ~~ 0 ifTrue:[

                              Transcript showCR:line

                          ].

                      ].

                      stream close.

                  ].

                  nDone := nDone + 1

                ].

            ].

                                                                        [exEnd]

    a nice example: copying files a la windows ...

    the following copies all files to /dev/null.

                                                                        [exBegin]

      |p|

      (ProgressIndicator 

                inBoxWithLabel:'copy files to /dev/null ...'

                abortable:true)

         showProgressOf:

            [:progressValue :currentAction |

                |files nFiles nDone|

                files := '.' asFilename directoryContents.

                nFiles := files size.

                nDone := 0.

                files do:[:aFileName |

                    |percent|

                    nDone := nDone + 1.

                    percent := nDone / nFiles * 100.

                    progressValue value:percent. 

                    aFileName asFilename isDirectory ifTrue:[

                        Transcript showCR:('skipping ' , aFileName , ' ...'). 

                        currentAction value:('skipping ' , aFileName , ' ...'). 

                    ] ifFalse:[

                        Transcript showCR:('copying ' , aFileName , ' ...').

                        currentAction value:('copying ' , aFileName , ' ...').

                        Object errorSignal handle:[:ex |

                            self warn:'an error occurred while copying ' , aFileName.

                            ex return

                        ] do:[

                            aFileName asFilename copyTo:'/dev/null'.

                        ]

                    ].

                ].

            ].

                                                                        [exEnd]

                                                                        [exBegin]

        ProgressIndicator 

            displayBusyIndicator:'Test...'

            at:(Screen default center)

            during:[:p |

                p labelWidget label:'bla...'.

                Delay waitForSeconds:0.5.

                1 to:3 do:[:idx |

                    Delay waitForSeconds:0.5.

                    p labelWidget label:('bla %1...' bindWith:idx).

                ].

                Delay waitForSeconds:0.5.

                p labelWidget label:'blabla...'.

                Delay waitForSeconds:0.5.

            ].

                                                                        [exEnd]

"

! !

!ProgressIndicator class methodsFor:'instance creation'!

inBox

    "create a topView containing an instance of myself,

     for later use with #showProgressOf:"

    ^ self inBoxWithLabel:'executing ...' abortable:false

    "Modified: 22.10.1997 / 21:08:37 / cg"

!

inBoxWithLabel:aLabel

    "create a topView containing an instance of myself,

     for later use with #showProgressOf:"

    ^ self inBoxWithLabel:aLabel abortable:false 

!

inBoxWithLabel:aLabel abortable:abortable

    "create a topView containing an instance of myself,

     for later use with #showProgressOf:"

    ^ self

	inBoxWithLabel:aLabel   

	text:''

	abortable:abortable

    "Modified: 17.7.1996 / 15:14:58 / cg"

!

inBoxWithLabel:aLabel icon:anIcon text:text abortable:abortable view:additionalView closeWhenDone:closeWhenDoneBoolean

    "create a topView containing an instance of myself,

     return the new instance, for later use with #showProgressOf:"

    |top p l y y2|

    top := Dialog new.

    top label:aLabel.

    top cursor:(Cursor wait).

    y2 := 0.

    anIcon notNil ifTrue:[

        y := top yPosition.

        l := top addTextLabel:anIcon.

        l borderWidth:0.

        l adjust:#left.

        l cursor:(Cursor wait).

        y2 := top yPosition.

        top yPosition:y.

    ].

    l := top addTextLabel:text.

    l borderWidth:0.

    l adjust:#left.

    l cursor:(Cursor wait).

    anIcon notNil ifTrue: [l leftInset:(anIcon width + 10)].

    top yPosition:(top yPosition max:y2).

    top addVerticalSpace.

    p := ProgressIndicator new.

    p extent:(1.0 @ p preferredHeight).

    p level:-1.

    p leftInset:5;

      rightInset:5.

    p cursor:(Cursor wait).

    p closeTopWhenDone:closeWhenDoneBoolean.

    p connectToTop:top label:l.

    top addComponent:p.

    additionalView notNil ifTrue:[

        top addComponent:additionalView.

        additionalView extent:(1.0 @ additionalView preferredHeight).

    ].

    abortable ifTrue:[

        top addVerticalSpace.

        top addAbortButton

    ].

    abortable ifFalse:[

        "/ top beUndecorated.  -- buggy for now; sets wrong height (caption not included ?)

        "/ would need the following kludge:

        "/ top preferredExtent:(top preferredExtent + (0@30)).

    ].