extra/animations/animations-docs.factor

   1 USING: help.markup help.syntax ;
   2 IN: animations
   3
   4 HELP: animate ( quot duration -- )
   5
   6 { $values
   7     { "quot" "a quot which uses " { $link progress } }
   8     { "duration" "a duration of time" }
   9 }
  10 { $description
  11     { $link animate } " calls " { $link reset-progress }
  12     " , then continously calls the given quot until the"
  13     " duration of time has elapsed. The quot should use "
  14     { $link progress } " at least once."
  15 }
  16 { $examples
  17     { $unchecked-example
  18         "USING: animations calendar threads prettyprint ;"
  19         "[ 1 sleep progress unparse write \" ms elapsed\" print ] "
  20         "1/20 seconds animate ;"
  21         "46 ms elapsed\n17 ms elapsed"
  22     }
  23     { $notes "The amount of time elapsed between these iterations will very." }
  24 } ;
  25
  26 HELP: reset-progress ( -- )
  27 { $description
  28     "Initiates the timer. Call this before using "
  29     "a loop which makes use of " { $link progress } "."
  30 } ;
  31
  32 HELP: progress ( -- time )
  33 { $values { "time" "an integer" } }
  34 { $description
  35     "Gives the time elapsed since the last time"
  36     " this word was called, in milliseconds."
  37 }
  38 { $examples
  39     { $unchecked-example
  40         "USING: animations threads prettyprint ;"
  41         "reset-progress 3 "
  42         "[ 1 sleep progress unparse write \"ms elapsed\" print ] "
  43         "times ;"
  44         "31 ms elapsed\n18 ms elapsed\n16 ms elapsed"
  45     }
  46     { $notes "The amount of time elapsed between these iterations will very." }
  47 } ;
  48
  49 ARTICLE: "animations" "Animations"
  50 "Provides a lightweight framework for properly simulating continuous"
  51 " functions of real time. This framework helps one create animations "
  52 "that use rates which do not change across platforms. The speed of the "
  53 "computer should correlate with the smoothness of the animation, not "
  54 "the speed of the animation!"
  55 { $subsection animate }
  56 { $subsection reset-progress }
  57 { $subsection progress }
  58 ! A little talk about when to use progress and when to use animate
  59     { $link progress } " specifically provides the length of time since "
  60     { $link reset-progress } " was called, and also calls "
  61     { $link reset-progress } " as its last action. This can be directly "
  62     "used when one's quote runs for a specific number of iterations, instead "
  63     "of a length of time. If the animation is like most, and is expected to "
  64     "run for a specific length of time, " { $link animate } " should be used." ;
  65 ABOUT: "animations"