extra/progress-bars/models/models-docs.factor

   1 ! Copyright (C) 2011 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax quotations threads ;
   4 IN: progress-bars.models
   5
   6 HELP: set-progress-bar
   7 { $values
   8     { "ratio/float" "a real number between 0 and 1" }
   9 }
  10 { $description "Sets the progress-bar model in the current scope to the percent that the task has been completed." } ;
  11
  12 HELP: with-file-reader-progress
  13 { $values
  14     { "path" "a pathname string" } { "encoding" "an encoding" } { "quot" quotation }
  15 }
  16 { $description "Opens a file for reading, displays a progress bar, and calls the quotation for processing the file. The progress bar will automatically update every 100 milliseconds, but only if the quotation yields (by calling " { $link yield } ") so that the UI has a chance to redraw." }
  17 { $examples
  18     "Loop through the Factor image file, discarding each character as it's read and updating a progress bar:"
  19     { $unchecked-example "USING: system progress-bars.models prettyprint io.encodings.binary threads ;
  20 image-path binary [
  21     [ 4096 read yield ] loop
  22 ] with-file-reader-progress"
  23 ""
  24     }
  25 } ;
  26
  27 HELP: with-progress-bar
  28 { $values
  29     { "quot" quotation }
  30 }
  31 { $description "Makes a new model for a progress bar for a task that is 0% complete, sets this model in a dynamic variable in a new scope, and calls a quotation that has access to this model. Progress can be updated with " { $link set-progress-bar } "." } ;
  32
  33 ARTICLE: "progress-bars.models" "Progress bar models"
  34 "The " { $vocab-link "progress-bars.models" } " vocabulary makes a progress bar model and various utility words that make progress bars for common tasks." $nl
  35 "Making a generic progress bar:"
  36 { $subsections with-progress-bar }
  37 "Updating a progress-bar:"
  38 { $subsections set-progress-bar }
  39 "A progress bar for reading files:"
  40 { $subsections with-file-reader-progress } ;
  41
  42 ABOUT: "progress-bars.models"