From 24d3d5015f6953a5d8459c06ae8ac281528168e4 Mon Sep 17 00:00:00 2001 From: Matthias Felleisen Date: Wed, 23 Apr 2008 21:19:57 +0000 Subject: [PATCH] first batch of docs svn: r9436 --- collects/teachpack/htdp/Docs/convert.scrbl | 50 +++++++++ collects/teachpack/htdp/Docs/convert.thtml | 40 ------- collects/teachpack/htdp/Docs/draw.scrbl | 93 ++++++++++++++++ collects/teachpack/htdp/Docs/draw.thtml | 100 ----------------- collects/teachpack/htdp/Docs/htdp.scrbl | 11 +- collects/teachpack/htdp/Docs/image.scrbl | 49 +++++---- collects/teachpack/htdp/Docs/testing.scrbl | 59 ---------- collects/teachpack/htdp/Docs/testing.thtml | 80 -------------- collects/teachpack/htdp/Docs/world.scrbl | 122 ++++++++++++++++++--- collects/teachpack/htdp/Docs/world.thtml | 112 ------------------- 10 files changed, 282 insertions(+), 434 deletions(-) create mode 100644 collects/teachpack/htdp/Docs/convert.scrbl delete mode 100644 collects/teachpack/htdp/Docs/convert.thtml create mode 100644 collects/teachpack/htdp/Docs/draw.scrbl delete mode 100644 collects/teachpack/htdp/Docs/testing.scrbl delete mode 100644 collects/teachpack/htdp/Docs/testing.thtml delete mode 100644 collects/teachpack/htdp/Docs/world.thtml diff --git a/collects/teachpack/htdp/Docs/convert.scrbl b/collects/teachpack/htdp/Docs/convert.scrbl new file mode 100644 index 0000000000..b7e74779b5 --- /dev/null +++ b/collects/teachpack/htdp/Docs/convert.scrbl @@ -0,0 +1,50 @@ +#lang scribble/doc + +@(require scribble/manual + (for-label scheme + teachpack/htdp/convert)) + +@title[#:tag "convert"]{Converting Temperaturs: convert.ss} + +@declare-exporting[teachpack/htdp/convert] + +The teachpack @scheme[convert.ss] provides three functions for +converting Fahrenheit temperatures to Celsius. It is useful for a single +exercise in HtDP. Its purpose is to demonstrate the independence of +``form'' (user interface) and ``function'' (also known as ``model''). + +@defproc[(convert-gui [convert (-> number? number?)]) true]{Consumes a +conversion function from Fahrenheit to Celsius and creates a graphical user +interface with two rulers, which users can use to convert temperatures +according to the given temperature conversion function.} + +@defproc[(convert-repl [convert (-> number? number?)]) true]{Consumes a +conversion function from Fahrenheit to Celsius and then starts a +read-evaluate-print loop. The loop prompts users to enter a number and then +converts the number according to the given temperature conversion function. +A user can exit the loop by entering ``x.''} + +@defproc[(convert-file [in string?][convert (-> number? number?)][out string?]) true]{Consumes a +file name @scheme[in], a +conversion function from Fahrenheit to Celsius, and a string +@scheme[out]. The program then reads all the number from +@scheme[in], converts them according to @scheme[convert], and prints the +results to the newly created file @scheme[out]. + +@bold{Warning}: If @scheme[out] already exists, it is deleted.} + +Example: Create a file with name @scheme["in.dat"] with some numbers in +it, using your favorite text editor on your computer. Define a function +@scheme[f2c] in the Definitions window and set teachpack to ``convert.ss'' +and click RUN. Then evaluate +@(begin +#reader scribble/comment-reader +(schemeblock + (convert-gui f2c) + ;; and + (convert-file "in.dat" f2c "out.dat") + ;; and + (convert-repl f2c) +)) +Finally inspect the file @scheme["out.dat"] and use the repl to check the +answers. diff --git a/collects/teachpack/htdp/Docs/convert.thtml b/collects/teachpack/htdp/Docs/convert.thtml deleted file mode 100644 index 7e31bf477d..0000000000 --- a/collects/teachpack/htdp/Docs/convert.thtml +++ /dev/null @@ -1,40 +0,0 @@ -{ (define LIBNAME "Convert") - (include "head.tinc") } - -

The teachpack convert.ss provides three functions: -

- -
  • {(idx convert-gui)}, which consumes a conversion function - from Fahrenheit to Celsius and creates a graphical user interface - with two rulers, which users can use to convert temperatures - according to the given temperature conversion function - -
  • {(idx convert-repl)}, which consumes a conversion function - from Fahrenheit to Celsius and then starts a read-evaluate-print - loop. The loop prompts users to enter a number and then converts the - number according to the given temperature conversion function. - A user can exit the loop by entering x. - -
  • {(idx convert-file)}; it consumes a file name in, a - conversion function from Fahrenheit to Celsius, and a string - out. The program then reads a number from - in, converts it according to the given temperature - conversion function, and prints the result to the newly created file - out.
    - -
    Warning: If out already exists, it is - deleted. - -
    •  - - -

    Example: Define a function f2c in the Definitons window. -Set teachpack to convert.ss and execute. Then evaluate -

    -> (convert-gui f2c)
->
-
    -This will create a graphical user interface with two rulers. Slide the top -one and click on convert to see the lower one move.

    - -{(include "foot.tinc")} diff --git a/collects/teachpack/htdp/Docs/draw.scrbl b/collects/teachpack/htdp/Docs/draw.scrbl new file mode 100644 index 0000000000..428b791f2e --- /dev/null +++ b/collects/teachpack/htdp/Docs/draw.scrbl @@ -0,0 +1,93 @@ +#lang scribble/doc + +@(require scribble/manual + (for-label scheme + teachpack/htdp/draw)) + +@title[#:tag "draw"]{Simple Drawing: draw.ss} + +@declare-exporting[teachpack/htdp/draw] + +The teachpack provides two sets of functions: one for drawing into a canvas +and one for reacting to canvas events. + +@bold{Warning:} @emph{This teachpack is deprecated. We strongly encourage +you to use the world teachpack instead; see @secref{world}.} + +@section[#:tag "drawing"]{Drawing on a Canvas} + +@deftech{DrawColor}: @scheme[(and/c symbol? (one-of/c 'white 'yellow 'red 'blue 'green 'black))] +These six colors are definitely provided. If you want other colors, +guess! For example, @scheme['orange] works, but @scheme['mauve] +doesn't. If you apply the function to a symbol that it doesn't recognize as +a color, it raises an error. + +@defproc[(start [width number?][height number?]) true]{Opens a +@scheme[width] x @scheme[height] canvas.} + +@defproc[(start/cartesian-plane [width number?][height number?]) +true]{Opens a @scheme[width] x @scheme[height] canvas and draws a Cartesian +plane.} + +@defproc[(stop) true]{Closes the canvas.} + +@defproc[(draw-circle [p posn?] [r number?] [c (unsyntax @tech{DrawColor})]) true]{Draws a +@scheme[c] circle at @scheme[p] with radius @scheme[r].} + +@defproc[(draw-solid-disk [p posn?] [r number?] [c (unsyntax @tech{DrawColor})]) true]{Draws a +@scheme[c] disk at @scheme[p] with radius @scheme[r].} + +@defproc[(draw-solid-rect [ul posn?] [width number?] [height number?] [c +(unsyntax @tech{DrawColor})]) true]{Draws a @scheme[width] x @scheme[height], @scheme[c] +rectangle with the upper-left corner at @scheme[ul].} + +@defproc[(draw-solid-line [strt posn?] [end posn?] [c (unsyntax @tech{DrawColor})]) true]{Draws +a @scheme[c] line from @scheme[strt] to @scheme[end].} + +@defproc[(draw-solid-string [p posn?][s string?]) true]{Draws @scheme[s] at +@scheme[p].} + +@defproc[(sleep-for-a-while [s number?]) true]{Suspends evaluation for +@scheme[s] seconds.} + +The teachpack also provides @scheme[clear-] operations for each +@scheme[draw-] operation. The arguments are the same. Note: use +@scheme[clear-rectangle] instead of @scheme[clear-string] for now. +The color argument for all @scheme[clear-] functions are optional. + +@;----------------------------------------------------------------------------- +@section[#:tag "interaction"]{Interactions with Canvas} + +@defproc[(wait-for-mouse-click) posn?]{Waits for the user to click on the +mouse, within the canvas.} + +@deftech{DrawKeyEvent}: @scheme[(or/c char? symbol?)] A +@tech{DrawKeyEvent} represents keyboard events: +@itemize[ + @item{@scheme[char?], if the user pressed an alphanumeric key;} + @item{@scheme[symbol?], if the user pressed, for example, an arror key: + @scheme['up] @scheme['down] @scheme['left] @scheme['right]} +] + +@defproc[(get-key-event) (or/c false (unsyntax @tech{DrawKeyEvent}))]{Checks whether the +user has pressed a key within the window; @scheme[false] if not.} + +@deftech{DrawWorld}: For proper interactions, using the teachpack + requires that you provide a data definition for @tech{DrawWorld} . In + principle, there are no constraints on this data definition. You can even + keep it implicit, even if this violates the Design Recipe. + +The following functions allow programs to react to events from the canvas. + +@defproc[(big-bang [n number?] [w (unsyntax @tech{DrawWorld})]) true]{Starts the clock, one tick every +@scheme[n] (fractal) seconds; @scheme[w] becomes the first ``current'' world.} + +@defproc[(on-key-event [change (-> (unsyntax @tech{DrawKeyEvent}) (unsyntax @tech{DrawWorld}) (unsyntax @tech{DrawWorld}))]) +true]{Adds @scheme[change] to the world. The function reacts to keyboard +events and creates a new @scheme[(unsyntax @tech{DrawWorld})].} + +@defproc[(on-tick-event [tock (-> (unsyntax @tech{DrawWorld}) (unsyntax @tech{DrawWorld}))]) true]{Adds @scheme[tock] +to the world. The function reacts to clock tick events, creating a new +current world.} + +@defproc[(end-of-time) (unsyntax @tech{DrawWorld})]{Stops the world; returns the current world.} diff --git a/collects/teachpack/htdp/Docs/draw.thtml b/collects/teachpack/htdp/Docs/draw.thtml index 0a8228a31f..e69de29bb2 100644 --- a/collects/teachpack/htdp/Docs/draw.thtml +++ b/collects/teachpack/htdp/Docs/draw.thtml @@ -1,100 +0,0 @@ -{ (define LIBNAME "Simple Drawing Exercises") - (include "head.tinc") } - -The teachpack provides two kinds of functions. The first four allow -students to simulate a small world of animated drawings and games: - -
  • {(idx big-bang)} : Number World -> true;
    -(define (big-bang n w) ...) -start the clock, one tick every n seconds; w -becomes the first world -
  • {(idx on-key-event)} : ((union char symbol) World -> World) -> true;
    -add a function to the world that processes keyboard events -
  • {(idx on-tick-event)} : (World -> World) -> true;
    -add a function to the world that processes tick events -
  • {(idx end-of-time)} : -> World;
    -stop the world, return the last world -
    •  -The world consists of a canvas and whatever the tick and keyevent handlers -draw on it. For the use of these functions, see the HtDP+ material. - -With the reminder, the students can write functions that draw into this -world: - -
  • {(idx start)} : Number Number -> true;
    -opens a canvas of specified size -
  • {(idx start/cartesian-plane)} : Number Number -> true;
    -opens a canvas of specified size and draws a Cartesian plane -
  • {(idx stop)} : -> true (no arguments);
    -closes the canvas -
  • {(idx draw-circle)} : Posn Number Symbol -> true;
    -draws a circle at posn with given radius and color -
  • {(idx draw-solid-disk)} : Posn Number Symbol -> true;
    -draws a disk at posn with given radius and color -
  • {(idx draw-solid-rect)} : Posn Number Number Symbol -> true;
    -draws a rectangle at posn with given width, height, and color -
  • {(idx draw-solid-line)} : Posn Posn Symbol -> true;
    -draws a line from one posn to other -
  • {(idx draw-solid-string)} : Posn String -> true;
    -draws a string at posn -
  • {(idx wait-for-mouse-click)} : -> Posn;
    -waits for the user to click on the mouse, within the window (the operation -is a quasi-constructor for posns) -
  • {(idx get-key-event)} : -> false or Character or Symbol ;
    -checks whether the user has pressed a key within the window; its result is -
      -
    1. false, if the user didn't press a key; -
    2. Character, if the user pressed an alphanumeric key; -
    3. Symbol, if the user pressed, for example, an arror key: - 'up 'down 'left 'right -
    -
    -
  • {(idx sleep-for-a-while)} : Number -> true;
    -suspends evaluation for the given number of seconds -
    -
  • The following symbols are recognized as colors: -
    -'white -'yellow -'red -'blue -'green -'black -
    -For other colors, guess! For example, 'orange works, but -'mauve doesn't. If you apply the function to a symbol that it -doesn't recognize as a color, it raises an error. -
    •  -
    -
    -
    -The teachpack also provides clear- operations for each -draw- operation. The arguments are the same. Note: use -clear-rectangle instead of clear-string for now. -
    -
    -
    -The color argument for all functions are optional. - -

    Sample session: Set teachpack to draw.ss and execute: -
    > (start 500 500) -
    > (draw-solid-disk (make-posn 100 100) 3 'red) -
    true -
    > (clear-solid-disk (make-posn 100 100) 3 'red) -
    true -
    > (sleep-for-a-while 1) -
    > (draw-solid-disk (make-posn 100 100) 3 'red) -
    true -
    > (clear-solid-disk (make-posn 100 100) 3) -
    true -
    > (stop) -
    > -
    -This session opens a window, draws a red disk, clears it, sleeps for a second, -and then repeats. The last expression closes the canvas. - -See http://www.ccs.neu.edu/home/matthias/HtDP/Extended/ -for an example on how to use get-key-event. The program is -the basis for an extended exercise under development. - -{(include "foot.tinc")} diff --git a/collects/teachpack/htdp/Docs/htdp.scrbl b/collects/teachpack/htdp/Docs/htdp.scrbl index 8d9220407d..7dcc4a19b2 100644 --- a/collects/teachpack/htdp/Docs/htdp.scrbl +++ b/collects/teachpack/htdp/Docs/htdp.scrbl @@ -9,11 +9,11 @@ @include-section["image.scrbl"] @include-section["world.scrbl"] -@;include-section["testing.scrbl" -@;include-section["convert.scrbl"] -@;include-section["guess.scrbl"] + +@include-section["convert.scrbl"] +@include-section["guess.scrbl"] @;include-section["mastermind.scrbl"] -@;include-section["draw.scrbl"] +@include-section["draw.scrbl"] @;include-section["hangman.scrbl"] @;include-section["arrows.scrbl"] @;include-section["documents.scrbl"] @@ -27,3 +27,6 @@ @;include-section["Simplified Scheme Web Servlets" @;include-section["Scheme Web Servlets" @;include-section["queen.scrbl"] + + +@;include-section["testing.scrbl" diff --git a/collects/teachpack/htdp/Docs/image.scrbl b/collects/teachpack/htdp/Docs/image.scrbl index 5c47788b83..318b7fa4c0 100644 --- a/collects/teachpack/htdp/Docs/image.scrbl +++ b/collects/teachpack/htdp/Docs/image.scrbl @@ -23,24 +23,27 @@ shapes. Additional primitives allow for the composition of images. @;----------------------------------------------------------------------------- @section[#:tag "modes-colors"]{Modes and Colors} -@defthing[Mode (one-of/c 'solid 'outline "solid" "outline")]{A @scheme[Mode] -is used to specify whether painting a shape fills or outlines the form.} +@deftech{Mode} @scheme[(one-of/c 'solid 'outline "solid" "outline")] + +A @tech{Mode} is used to specify whether painting a shape fills or +outlines the form.} -@deftogether[( -@defthing[Color (or/c symbol? string? color?)] @defstruct[color [(red (and/c natural-number/c (<=/c 255))) (green (and/c natural-number/c (<=/c 255))) (blue (and/c natural-number/c (<=/c 255)))]] -@defthing[RGB color?])]{ -A @scheme[Color] is a color-symbol (e.g., - @scheme['blue]) or a color-string (e.g., @scheme["blue"]) or an RGB structure. -An @scheme[RGB] describes a color via share of red, - blue, and green colors (e.g., @scheme[(make-color 100 200 30)]). -} +@deftech{RGB} @scheme[color?] -@defproc[(image-color? [x any]) boolean?]{ - Determines if the input is a valid image color.} +An @tech{RGB} describes a color via share of red, blue, and green colors + (e.g., @scheme[(make-color 100 200 30)]). + +@deftech{Color} @scheme[(or/c symbol? string? color?)] + +A @tech{Color} is a color-symbol (e.g., @scheme['blue]) or a color-string + (e.g., @scheme["blue"]) or an @tech{RGB} structure. + +@defproc[(image-color? [x any]) boolean?]{ Determines if the input is a + valid image @tech{Color}.} @;----------------------------------------------------------------------------- @section[#:tag "creational"]{Creating Basic Shapes} @@ -49,19 +52,19 @@ In DrScheme, you can insert images from your file system. Use PNG images instead whenever possible for insertions. In addition, you can create basic shapes with the following functions. -@defproc[(rectangle [w number?] [h number?] [m Mode] [c Color]) image?]{ +@defproc[(rectangle [w number?] [h number?] [m (unsyntax @tech{Mode})] [c (unsyntax @tech{Color})]) image?]{ Creates a @scheme[w] by @scheme[h] rectangle, filled in according to @scheme[m] and painted in color @scheme[c]} -@defproc[(circle [r number?] [m Mode] [c Color]) image?]{ +@defproc[(circle [r number?] [m (unsyntax @tech{Mode})] [c (unsyntax @tech{Color})]) image?]{ Creates a circle or disk of radius @scheme[r], filled in according to @scheme[m] and painted in color @scheme[c]} -@defproc[(ellipse [w number?] [h number?] [m Mode] [c Color]) image?]{ +@defproc[(ellipse [w number?] [h number?] [m (unsyntax @tech{Mode})] [c (unsyntax @tech{Color})]) image?]{ Creates a @scheme[w] by @scheme[h] ellipse, filled in according to @scheme[m] and painted in color @scheme[c]} -@defproc[(triangle [s number?] [m Mode] [c Color]) image?]{ +@defproc[(triangle [s number?] [m (unsyntax @tech{Mode})] [c (unsyntax @tech{Color})]) image?]{ Creates an upward pointing equilateral triangle whose side is @scheme[s] pixels long, filled in according to @scheme[m] and painted in color @scheme[c]} @@ -69,25 +72,25 @@ shapes with the following functions. @defproc[(star [n (and/c number? (>=/c 2))] [outer (and/c number? (>=/c 1))] [inner (and/c number? (>=/c 1))] - [m Mode] - [c Color]) image?]{ + [m (unsyntax @tech{Mode})] + [c (unsyntax @tech{Color})]) image?]{ Creates a multi-pointed star with @scheme[n] points, an @scheme[outer] radius for the max distance of the points to the center, and an @scheme[inner] radius for the min distance to the center. } -@defproc[(regular-polygon [s side] [r number?] [m Mode] [c Color] [angle real? 0]) image?]{ +@defproc[(regular-polygon [s side] [r number?] [m (unsyntax @tech{Mode})] [c (unsyntax @tech{Color})] [angle real? 0]) image?]{ Creates a regular polygon with @scheme[s] sides inscribed in a circle of radius @scheme[r], using mode @scheme[m] and color @scheme[c]. If an angle is specified, the polygon is rotated by that angle. } -@defproc[(line [x number?][y number?] [c Color]) image?]{ +@defproc[(line [x number?][y number?] [c (unsyntax @tech{Color})]) image?]{ Creates a line colored @scheme[c] from (0,0) to @scheme[(x,y)]. See @scheme[add-line] below. } -@defproc[(text [s string?] [f (and/c number? positive?)] [c Color]) Image]{ +@defproc[(text [s string?] [f (and/c number? positive?)] [c (unsyntax @tech{Color})]) Image]{ Creates an image of the text @scheme[s] at point size @scheme[f] and painted in color @scheme[c].} @@ -137,7 +140,7 @@ Images can be composed, and images can be found within compositions. [y number?] [z number?] [u number?] - [c Color]) image?]{ + [c (unsyntax @tech{Color})]) image?]{ Creates an image by adding a line (colored @scheme[c]) from @scheme[(x,y)] to @scheme[(z,u)] to image @scheme[i].} @@ -209,7 +212,7 @@ and converts a list of colors into an image. #reader scribble/comment-reader (schemeblock ;; -- @scheme[empty] -;; -- @scheme[(cons Color List-of-color)] +;; -- @scheme[(cons (unsyntax @tech{Color}) List-of-color)] ;; Interpretation: represents a list of colors. )) diff --git a/collects/teachpack/htdp/Docs/testing.scrbl b/collects/teachpack/htdp/Docs/testing.scrbl deleted file mode 100644 index b7fcc2593b..0000000000 --- a/collects/teachpack/htdp/Docs/testing.scrbl +++ /dev/null @@ -1,59 +0,0 @@ -#lang scribble/doc - -@(require scribble/manual - (for-label scheme/base - "../testing.ss")) - -@title[#:tag "testing"]{Testing: testing.ss} - -@declare-exporting[teachpack/htdp/testing] - -The @scheme[testing.ss] teachpack provides forms for formulating test cases -and a primitive for reporting on test cases. - -@defform[(check-expect test-expression expected-value)]{ - where @scheme[test-expression] and - @scheme[expected-value] are both expressions, though the latter - should ideally be just a value. - - The form evaluates @scheme[test-expression] and then - verifies that its value is the same as - @scheme[expected-value].} - -@defform[(check-within test-expression expected-value delta)]{ - where @scheme[test-expression], @scheme[expected-value], and - @scheme[delta] are expressions. - -The form evaluates @scheme[test-expression] and verifies that all numbers -within the value are equal to numbers in analogous positions in -@scheme[expected-value], plus or minus @scheme[delta]. - -Thus, -@schemeblock[(check-within (make-posn 10 .1) (make-posn 10 .109) .01)] -succeeds while -@schemeblock[(check-within (make-posn 10 .1) (make-posn 10 .19) .01)] -fails. -} - -@defform[(check-error test-expression message-string)]{ - where @scheme[test-expression] and @scheme[expected-message] are expressions. - -The form evaluates @scheme[test-expression] and verifies that it signals an -error with @scheme[message-string] as the error report. If -@scheme[test-expression] doesn't signal an error, the test case fails. -} - -@defproc[(generate-report) true]{ - Displays statistics of running tests created with @scheme[check-expect], - @scheme[check-within], and @scheme[check-error]. - - Place it at the end of the program or run the expression from the - Interactions window after clicking RUN. -} - -@section{Style} - -While you are developing functions, you should place test cases below the -relevant function definitions in the Definitions Window of -drscheme. Eventually though, you should collect all these tests at the bottom of -the window. diff --git a/collects/teachpack/htdp/Docs/testing.thtml b/collects/teachpack/htdp/Docs/testing.thtml deleted file mode 100644 index 8c2c8c284e..0000000000 --- a/collects/teachpack/htdp/Docs/testing.thtml +++ /dev/null @@ -1,80 +0,0 @@ -{ (define LIBNAME "Testing") - (include "head.tinc") } - -

    -

    - This teachpack provides four constructs for testing programs: -

    -

    - The first three forms create tests: -

    -
  • - ({(idx check-expect)} test-expression expected-value) - where test-expression and - expected-value are both expressions. -
    - The form evaluates test-expression and then - verifies that its value is the same as - expected-value. -
    • -
  • - ({(idx check-within)} test expected delta) - where test-expression, expected, and - delta are expressions. -
    - The form evaluates test-expression and verifies that - it produces a real number such that its value is equal to - expected plus or minus delta. -
    • -
  • - ({(idx check-error)} test message) - where test and expected-message are expressions -
    - The form evaluates test and verifies that it signals - an error with expected-message as the error report. -
    • -     - You should place them below the relevant function - definitions in the Definitions Window. Eventually you should place - all tests, such as these, at the bottom of the window. -

    - -

    - Finally, generate-report is a function that displays - statistics of running tests: -

    -
  • - {(idx generate-report)} : -> true -
    - (generate-report) displays the results of all tests - created with check-expect, check-within, - and check-error. -
    • -     - Place it at the end of the program or run the expression from the - Interactions window after clicking RUN. -

    - -Example: Place the following seven lines into the Definitions Window -and click RUN: -
    -
-(check-expect (+ 1 1) 2)
-(check-expect (+ 1 1) 3)
-
-(check-within (+ 1 1) 2.1 .001)
-(check-within (+ 1 1) 2.1 .1)
-
-(check-error (+ 1 1) "3")
-(check-error (/ 1 0) "/: division by zero")
-
-(generate-report)
-
-
    - Before you do so, try to figure out which of these tests succeed and which - fail. After clicking run, you see a separate frame that records how many - succeeded and failed and detail information about the failures, including - links for highlighting the source. -
    - -{(include "foot.tinc")} diff --git a/collects/teachpack/htdp/Docs/world.scrbl b/collects/teachpack/htdp/Docs/world.scrbl index c4c9f49a67..bc842a2875 100644 --- a/collects/teachpack/htdp/Docs/world.scrbl +++ b/collects/teachpack/htdp/Docs/world.scrbl @@ -8,8 +8,6 @@ @title[#:tag "world"]{Simulations and Animations: world.ss} -@;[May I suggest that in the docs, you give a simple world, and then translate it into a classical class.ss/GUI code, with timers, etc. ?] - @declare-exporting[teachpack/htdp/world] The teachpack provides two sets of tools. The first allows students to @@ -21,17 +19,16 @@ second one generalizes the first by adding interactive GUI features. The teachpack assumes working knowledge of the basic image manipulation primitives and introduces a special kind of image: a scene. -@deftogether[( -@defthing[Image image?] -@defthing[Scene (and/c image? (lambda (i) - (and (= (pinhole-x i) 0) (= (pinhole-y i) 0))))])]{ -For image creation and manipulation, see @secref["image"]. +@deftech{Scene}@schemeblock[(and/c image? + (lambda (i) + (and (= (pinhole-x i) 0) (= (pinhole-y i) 0))))] -A @scheme[Scene] is an image whose pinhole is at position @scheme[(0,0)]} +The teachpack can display only @tech{Scene}s, which are images whose +pinholes are at position @scheme[(0,0)]. -@defproc[(empty-scene [width natural-number/c][height natural-number/c]) Scene]{Creates a @scheme[width] x @scheme[height] Scene.} +@defproc[(empty-scene [width natural-number/c][height natural-number/c]) (unsyntax @tech{Scene})]{Creates a @scheme[width] x @scheme[height] @tech{Scene}.} -@defproc[(place-image [img image?] [x number?][y number?][s Scene]) Scene]{ +@defproc[(place-image [img image?] [x number?][y number?][s (unsyntax @tech{Scene})]) (unsyntax @tech{Scene})]{ Creates a scene by placing @scheme[img] at @scheme[(x,y)] into @scheme[s]; @scheme[(x,y)] are comp. graph. coordinates, i.e., they count left and down from the upper-left corner.} @@ -74,10 +71,103 @@ In addition, @;----------------------------------------------------------------------------- @section[#:tag "interactive"]{Interactions} -@defthing[World any/c]{For animated worlds and games, using the teachpack - requires that you provide a data definition for @scheme[World]. In - principle, there are no constraints on this data definition.} +An animation starts from a given ``world'' and generates new ones in response to events on the +computer. This teachpack keeps track of the ``current world'' and recognizes three kinds of events: +clock ticks; keyboard presses and releases; and mouse movements, mouse clicks, etc. Your program may +deal with such events via the @emph{installation} of @emph{handlers}. The teachpack provides for the +installation of three event handlers: @scheme[on-tick-event], @scheme[on-key-event], and +@scheme[on-mouse-event]. In addition, it provides for the installation of a @scheme[draw] handler, +which is called every time your program should visualize the current world. -Given a data definition for worlds, the following functions create worlds, - visualize it, make the clock tick, and provide feedback about the mouse - and keyboard actions that the program's users perform. +@deftech{World} @scheme[any/c] + + For animated worlds and games, using the teachpack requires that you + provide a data definition for @tech{World}. In principle, there are no + constraints on this data definition. You can even keep it implicit, even + if this violates the Design Recipe. + +@deftogether[( +@defproc[(big-bang [width natural-number/c] [height natural-number/c] [r number?] [world0 (unsyntax @tech{World})]) true]{} +@defproc[(big-bang [width natural-number/c] [height natural-number/c] [r number?] [world0 (unsyntax @tech{World})][animated-gif? boolean?]) true]{} +)]{ + Creates and displays a @scheme[width] x @scheme[height] canvas, + starts the clock, + makes it tick every n seconds, + and makes @scheme[w] the current world. + If it is called with five instead of four arguments and the last one + (@scheme[animated-gif?]) is @scheme[true], the teachpack allows the + generation of images from the animation, including an animated GIF image. } + +@defproc[(on-tick-event [tock (-> (unsyntax @tech{World}) (unsyntax @tech{World}))]) true]{ + Tell DrScheme to call @scheme[tock] on the current world every time the + clock ticks. The result of the call becomes the current world.} + +@deftech{KeyEvent} @scheme[(or/c char? symbol?)] + +A @tech{KeyEvent} represents key board events, e.g., keys pressed or + released, by the computer's user. A @scheme[char?] @tech{KeyEvent} is + used to signal that the user has hit an alphanumeric key. Symbols such + as @scheme['left], @scheme['right], @scheme['up], @scheme['down], + @scheme['release] denote arrow keys or special events, such as releasing + the key on the keypad. + +@defproc[(on-key-event [change (-> (unsyntax @tech{World}) (unsyntax @tech{KeyEvent}) (unsyntax @tech{World}))]) true]{ + Tell DrScheme to call @scheme[change] on the current world and a + @tech{KeyEvent} for every keystroke the user of the computer makes. The result + of the call becomes the current world. + + Here is a typical key-event handler: +@(begin +#reader scribble/comment-reader +(schemeblock +(define (change w a-key-event) + (cond + [(char? a-key-event) w] + ;; else (symbol? a-key-event) holds + [(symbol=? a-key-event 'left) (world-go w -DELTA)] + [(symbol=? a-key-event 'right) (world-go w +DELTA)] + [(symbol=? a-key-event 'up) (world-go w -DELTA)] + [(symbol=? a-key-event 'down) (world-go w +DELTA)] + [else w])) +)) + +} + +@deftech{MouseEvent} @scheme[(one-of/c 'button-down 'button-up 'drag 'move 'enter 'leave)] + + A @tech{MouseEvent} represents mouse events, e.g., mouse movements or mouse clicks, by the + computer's user. + +@defproc[(on-mouse-event [clack (-> (unsyntax @tech{World}) natural-number/c natural-number/c (unsyntax @tech{MouseEvent}) (unsyntax @tech{World}))]) true]{ + Tell DrScheme to call @scheme[clack] on the current world, the current + @scheme[x] and @scheme[y] coordinates of the mouse, and and a + @tech{MouseEvent} for every action of the mouse by the user of the + computer. The result of the call becomes the current world.} + +@defproc[(on-redraw [to-scene (-> (unsyntax @tech{World}) (unsyntax @tech{Scene}))]) true]{ Tell DrScheme to call @scheme[to-scene] + whenever the canvas must be redrawn. The canvas is usually re-drawn after a tick event, a keyboard + event, or a mouse event has occurred. The generated scene is displayed in the world's canvas.} + +@defproc[(end-of-time [msg string?]) true]{ + Stop the currently running animation. Specifically, stop the clock and ensure no @tech{KeyEvent}s + or @tech{MouseEvent}s are forwarded to the respective handlers. Display the given string to + signal the end of the animation.} + +@section{Scenes and Images} + +For the creation of scenes from the world, use the functions from @secref["image"]. The following two +functions have turned out to be useful for the creation of scenes, too. + + +@defproc[(nw:rectangle [width natural-number/c] [height natural-number/c] [solid-or-filled Mode] [c Color]) image?]{ + Creates a @scheme[width] x @scheme[height] rectangle, solid or outlined as specified by + @scheme[solid-or-filled] and colored according to @scheme[c], with a pinhole at the upper left + corner.} + +@defproc[(scene+line [s (unsyntax @tech{Scene})][x0 number?][y0 number?][x1 number?][y1 number?][c Color]) (unsyntax @tech{Scene})]{ + Creates a scene by placing a line of color @scheme[c] from @scheme[(x0,y0)] to + @scheme[(x1,y1)] into @scheme[scene]; + @scheme[(x,y)] are comp. graph. coordinates; + in contrast to the @scheme[add-line] function, this + one cuts off those portions of the line that go beyond the boundaries of + the given @scheme[s].} diff --git a/collects/teachpack/htdp/Docs/world.thtml b/collects/teachpack/htdp/Docs/world.thtml deleted file mode 100644 index 9379da01be..0000000000 --- a/collects/teachpack/htdp/Docs/world.thtml +++ /dev/null @@ -1,112 +0,0 @@ -{ (define LIBNAME "Animated Images, Simulating Worlds") - (include "head.tinc") } - - -
      -
    1. {(idx big-bang)} : Nat Nat Number World -> true
      - (big-bang width height n w) - creates and shows a width x height canvas, - starts the clock, - makes it tick every n seconds, - and makes w the first world - -
    2. {(idx big-bang)} : Nat Nat Number World Boolean -> true
      - big-bang takes an optional fifth argument. If it is - true, the world allows the generation of images from the - animation, including an animated GIF image - -
    3. {(idx on-tick-event)} : (World -> World) -> true
      - (on-tick-event tock) means that DrScheme must call tock - on the current world every time the clock ticks; it uses the result as the next world - -
    4. {(idx on-key-event)} : (World KeyEvent -> World) -> true
      - (on-key-event change) means that DrScheme must call - change on the current world and a (representation of the) - keyevent for every keystroke the programmer (user of the computer) makes; it uses - the result as the next world - -
      -
-   ;; A KeyEvent is one of: 
-   ;; -- Char (char?)
-   ;; -- Symbol (symbol?)
-
-   When the Keyevent is a char, the programmer (user of the computer) has hit an
-   alphanumeric key. Symbols such as 'left, 'right,
-   'up, 'down, 'release denote arrow keys
-   or the events of releasing a key on the keypad. 
-
      - -
    5. {(idx on-mouse-event)} : (World Nat Nat MouseEvent -> - World) -> true
      (on-mouse-event clack) means that - DrScheme must call clack on the current world, the current - x and y coordinates of the mouse, and and a - (representation of the) mouse event for every action of the mouse the - programmer (user of the computer) makes; it uses the result as the next - world - -
      -
-  ;; A MouseEvent is one of:
-  ;; - 'button-down
-  ;; - 'button-up
-  ;; - 'drag
-  ;; - 'move
-  ;; - 'enter
-  ;; - 'leave
-
-   The symbols denote the appropriate action with the mouse and (any of)
-   its button(s).
-
      - -
    6. {(idx on-redraw)} : (World -> Scene) -> true
      - (on-redraw world->scene) means that DrScheme calls - world->image whenever the canvas must be redrawn (usually - after a tick event/a keyboard event/a mouse event has occurred); - the function consumes the current world and produces a scene, which is - then displayed in the teachpack's canvas - -
    7. {(idx end-of-time)} : String u Symbol -> World
      When DrScheme - evaluates (end-of-time "the end"), it stops the clock and displays the - given string or symbol; no further tick events, key events, or redraw events - take place until the world is created again. -

    - - -

    For the creation of scenes from the world, use the following functions -plus the functions on images below: -

      -
    1. {(idx nw:rectangle)} : Nat Nat Mode Color -> Image
      - (nw:rectangle width height mode color) - creates a width x height rectangle, solid or outlined, - with its anchor in the NW corner - - -
    2. {(idx scene+line)} : Scene Number Number Number Number Color -> Scene
      - (scene+line scene x0 y0 x1 y1 c) - places a line of color c from (x0,y0) to - (x1,y1) into scene; - (x,y) are comp. graph. coordinates; - in contrast to the {(idx image.ss)} add-line function, this - one cuts off those portions of the line that go beyond the boundaries of - the given Scene. - -
    3. {(idx run-movie)} : (Listof Image) -> true
      - (run-movie loi) - shows the list of images in loi in a time-delayed manner; - assume: all images are of the same size -

    - -
    - -

    Image Manipulation

    - -

    Finally, the teachpack provides all the functions that image.ss -provides. For completeness, the documentation of this teackpack is -included here: - -{(include "image-content.tinc")} - -

    - -{(include "foot.tinc")}