Smalltalk/X Webserver

Documentation of class 'ProgressIndicator':

Class: ProgressIndicator

Inheritance
Description
Class protocol
- instance creation
- simple public API
Instance protocol
Examples

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--ProgressIndicator
                  |
                  +--RoundProgressIndicator

Package:: stx:libwidg2

Category:: Views-Misc

Version:: rev: 1.105 date: 2023/10/05 08:16:17; user: stefan; file: ProgressIndicator.st directory: libwidg2; module: stx stc-classLibrary: libwidg2

Description:

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 also be set to display a proportion instead of a percent.
For this set showAsProportion to true and the total value.
If total is set different from 100 and showAsProportion is off,
it will calculate the percentage from the model and the total.

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.

copyrightCOPYRIGHT (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.

Class protocol:

instance creation

inBox: create a topView containing an instance of myself,
for later use with #showProgressOf:
inBoxWithLabel: aLabel: create a topView containing an instance of myself,
for later use with #showProgressOf:
inBoxWithLabel: aLabel abortable: abortable: create a topView containing an instance of myself,
for later use with #showProgressOf:
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:
inBoxWithLabel: aLabel text: text abortable: abortable: create a topView containing an instance of myself,
for later use with #showProgressOf:
inBoxWithLabel: aLabel text: text abortable: abortable view: additionalView: create a topView containing an instance of myself,
for later use with #showProgressOf:
inBoxWithLabel: aLabel text: text abortable: abortable view: additionalView closeWhenDone: closeWhenDoneBoolean: create a topView containing an instance of myself,
for later use with #showProgressOf:
progressOpenOn: progressModel label: aLabel: create and open a progressIndicator dialog window,
bit do not open it modal; instead, it is opened modeless
and control returns to the caller.
The models value is assumed to be 0..1
(which is for compatibility and different from ST/X's percentage use)
Added for VW compatibility (RB).
progressOpenOn: progressModel title: title label: aLabel: create and open a progressIndicator dialog window,
bit do not open it modal; instead, it is opened modeless
and control returns to the caller.
The models value is assumed to be 0..1
(which is for compatibility and different from ST/X's percentage use)
Added for VW compatibility (RB).

simple public API

displayBusyIndicator: aLabel abortable: abortable at: aPointOrNil during: aBlock

easy interface - show progress while evaluating aBlock.
The block is passed the progressIndicator as argument
so the block can change the label and/or change the progress value.

Usage example(s):

     ProgressIndicator
        displayBusyIndicator:'doobidoobidoo...'
        abortable:true
        at:(Screen default center)
        during:[
            200 to:400 by:5 do:[:i |
                Delay waitForSeconds:0.1.
            ]
        ].

     ProgressIndicator
        displayBusyIndicator:'doobidoobidoo...'
        abortable:true
        at:(Screen default center)
        during:[
            Delay waitForSeconds:3.
        ].

displayBusyIndicator: aLabel at: aPointOrNil during: aBlock

easy interface - show progress while evaluating aBlock.
The block is passed a valueHolder, which is to be set to values from
startValue to endValue during the block's evaluation.
This is scaled to 0..100% completion.
Set the valueHolder to nil, to get a busy-indicator

Usage example(s):

     ProgressIndicator
        displayBusyIndicator:'doobidoobidoo...'
        at:(Screen default center)
        during:[
            200 to:400 by:5 do:[:i |
                Delay waitForSeconds:0.1.
            ]
        ].

displayBusyIndicator: aLabel message: messageString abortable: abortable at: aPointOrNil during: aBlock

easy interface - show progress while evaluating aBlock.
The block is passed the progressIndicator as argument
so the block can change the label and/or change the progress value.

Usage example(s):

     ProgressIndicator
        displayBusyIndicator:'doobidoobidoo...'
        abortable:true
        at:(Screen default center)
        during:[
            200 to:400 by:5 do:[:i |
                Delay waitForSeconds:0.1.
            ]
        ].

     ProgressIndicator
        displayBusyIndicator:'doobidoobidoo...'
        abortable:true
        at:(Screen default center)
        during:[
            Delay waitForSeconds:3.
        ].

displayBusyIndicator: aLabel message: messageString at: aPointOrNil during: aBlock

Usage example(s):

     ProgressIndicator
        displayBusyIndicator:'doobidoobidoo...'
        message:'message'
        at:(Screen default center)
        during:[
            200 to:400 by:5 do:[:i |
                Delay waitForSeconds:0.1.
            ]
        ].

displayProgress: aLabel at: aPointOrNil from: startValue to: endValue during: aBlock

easy interface - show progress while evaluating aBlock.
The block is passed a valueHolder, which is to be set to values from
startValue to endValue during the block's evaluation.
This is scaled to 0..100% completion.
Set the valueHolder to nil, to get a busy-indicator

Usage example(s):

     ProgressIndicator
        displayProgress:'doobidoobidoo...'
        at:(Screen default center)
        from:200 to:400
        during:[:val |
            200 to:400 by:5 do:[:i |
                val value:i.
                Delay waitForSeconds:0.1.
            ]
        ].

displayProgress: aLabel message: messageString at: ignoredPointOrNil from: startValue to: endValue during: aBlock

Usage example(s):

     ProgressIndicator
        displayProgress:'doobidoobidoo...'
        at:(Screen default center)
        from:200 to:400
        during:[:val |
            200 to:400 by:5 do:[:i |
                val value:i.
                Delay waitForSeconds:0.1.
            ]
        ].

displayProgressNotifications: aLabel abortable: abortable at: ignoredPointOrNil during: aBlock

easy interface - show progress as provided by progressNotifications
while evaluating aBlock.
The block is passed the progressIndicator as optional argument,
however, progressNotifications are handled and update the percentage.

Usage example(s):

     ProgressIndicator
        displayProgressNotifications:'...'
        abortable:true
        at:nil
        during:[
            200 to:400 by:5 do:[:i |
                Delay waitForSeconds:0.1.
                ProgressNotification progressPercentage:(i / 4) messageText:'Now ', i printString.
            ]
        ].

Usage example(s):

     ProgressIndicator
        displayProgressNotifications:'doobidoobidoo...'
        abortable:true
        at:nil
        during:[
            Delay waitForSeconds:3.
        ].

displayProgressNotifications: aLabel message: messageString abortable: abortable at: ignoredPointOrNil during: aBlock

Usage example(s):

     ProgressIndicator
        displayProgressNotifications:'doobidoobidoo...'
        message:'loooooooooooooooooooooooooooooooooooooooong Message'
        abortable:true
        at:nil
        during:[
            200 to:400 by:5 do:[:i |
                Delay waitForSeconds:0.1.
                ProgressNotification progressPercentage:(i / 4).
            ]
        ].

Usage example(s):

     ProgressIndicator
        displayProgressNotifications:'doobidoobidoo...'
        message:'Message'
        abortable:true
        at:nil
        during:[
            Delay waitForSeconds:3.
        ].

Instance protocol:

accessing

getPercentage: the real percentage, i.e. 100*progress/total
labelWidget
model: aValueHolder: set my percentage holder
percentage: aNumber: set the percentage or the progress, if totalValue is not 100
showAsProportion: Show the percentage as proportion when displayed (e.g. 25/100 instead of 100%)
showAsProportion: aBoolean: Show the percentage as proportion when displayed (e.g. 25/100 instead of 100%)
showBusyIndication: aBooleanHolder: switch between percentage mode (if false) and busy indication (if true)
total: A ValueHolder containing the total, i.e. the aim value if the progress.
If it is nil, the classical 100 will be used.
total: aValueHolder: A ValueHolder containing the total, i.e. the aim value if the progress.
If it is nil, the classical 100 will be used.
totalValue: The total value. For classical percentage, this would be 100,
which is returned, if total (a ValueHolder) is or holds nil.
Else this returns the value of total.

accessing-behavior

closeTopWhenDone: aBoolean: set/clear the close-topView-when-done flag
finishAction: aBlock: define an action to be performed when finished

accessing-look

backgroundColor: return the percentage displays background color
backgroundColor: aColor: set the percentage display's background color
foregroundColor: return the percentage displays foreground color
foregroundColor: aColor: set the percentage display's foreground color
showPercentage: return the flag controlling if the percentage is to be shown numerically
showPercentage: aBoolean: set/clear the flag controlling if the percentage is to be shown numerically

change & update

update: aspect with: aParameter from: changedObject: react upon value changes of my model

drawing

progressString: The String the progress indicator will show, if showPercentage is set to true.
redraw: redraw the percentage bar and optional percentage string
sizeChanged: how from: oldExtentOrNil: my view has changed the size (not the contents)

initialization & release

destroy: (comment from inherited method)
unmap & destroy - make me invisible, destroy subviews then
make me unknown to the device
initStyle: initialize styleSheet values
initialize: (comment from inherited method)
must be called if redefined
mapped: (showBusy value) ifTrue:[
release
unmapped: (comment from inherited method)
the view has been unmapped
(either by some outside action - i.e. window manager iconified me,
or due to unmapping of my parentView).

private

connectToTop: top label: label: I am a modal progressindicator (running in a resizable topview)
startBusyIndicationProcess
stopBusyIndicationProcess
updateBusyIndicatorPosition: busyPosition >= 80 ifTrue:[

queries

computePreferredExtent: return my preferred extent

showing progress

new_showBusyIndicatorDuring: aBlock

new_showProgressOf: aBlock

show progress, while evaluating aBlock.
If the receiver has been created with inBox, show the
box centered on the screen. If not, the view is assumed to
be contained in another view, and no special startup actions
are performed.

The block is passed two arguments, the progressValue,
which should be set to the percentage from time-to-time
within the block and an action value, which should be set to
the currently performed action (a string) from time to time.
The second valueHolder can be left unchanged.

Caveat: cannot (currently) suppress close of the box ...

old_showBusyIndicatorDuring: aBlock

old_showProgressOf: aBlock

showBusyIndicatorDuring: aBlock

showProgressOf: aBlock

Usage example(s):

^ self old_showProgressOf:aBlock

Usage example(s):

      |p|

      p := ProgressIndicator inBox.
      p showBusyIndication:true.
      p showProgressOf:
            [:progressValue :currentAction |
                1 to:200 do:[:percent |
                    (Delay forSeconds:0.05) wait.
                    progressValue value:percent 
                ].
            ].

      'it can be reused ...'.  
      p showBusyIndication:false.
      p showProgressOf:
            [:progressValue :currentAction |
                1 to:100 by:5 do:[:percent |
                    (Delay forSeconds:0.05) wait.
                    progressValue value:percent 
                ].
            ].

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

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

as a busy indicator

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

changing colors, turning percentage display off:

  |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

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

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

with border (2D look):

  |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

getting progress from a model:

  |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

concrete example: search all files in the source directory for a string using grep. Show progress while doing so.

  |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

using the convenient inBox-interface (this creates a box and an activity label and evaluates a block to indicate ...) basic interface demonstration:

  |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 
          ]
        ]

above search example using this convenient interface:

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

a nice example: copying files a la windows ... the following copies all files to /dev/null.

  |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'.
                    ]
                ].
            ].
        ].

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

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 27 Jul 2024 03:34:08 GMT