#lang scribble/doc
@(require scribble/manual
    (for-label scheme
    	       "picturing-programs.ss"
               ; "io-stuff.ss"
               ; "sb-universe.ss"
               ; "tiles.ss"
	       ; eachpack/htdp/image
	       ; teachpack/2htdp/universe
               (only-in lang/htdp-beginner check-expect)
               ))

@; teachpack["picturing-programs"]{Picturing Programs}
@title{Picturing Programs Teachpack}
@author{Stephen Bloch}

@defmodule[(planet sbloch/picturing-programs/picturing-programs)]

@section{About This Teachpack}

Provides a variety of functions for combining and manipulating images,
as well as a slightly modified version of the @scheme{universe} teachpack.
It is intended to be used with the book
@hyperlink["http://www.picturingprograms.com" "Picturing Programs"].

@section{Installation}
If you're reading this, you've probably already installed the teachpack successfully,
but if you need to install it on a different machine, ...
@itemize[#:style 'ordered
	@item{start DrScheme}
	@item{switch languages to Module and click "Run"}
	@item{in the Interactions pane, type
		@schemeblock[(require (planet sbloch/picturing-programs))]}
	@item{after a few seconds, you should see the message
              @schemeblock{Wrote file "picturing-programs.ss" to installed-teachpacks directory.}}
	@item{switch languages back to one of the HtDP languages, like Beginning Student}
	@item{either
		@itemize{
			@item{in the Definitions pane, type
				@schemeblock[(require installed-teachpacks/picturing-programs)]
				or}
			@item{from the Language menu, choose "Add Teachpack..." and select "picturing-programs.ss"}
			}
		}
	@item{click "Run"}
	]

@section{Functions from image.ss}

This package includes all of 
@; @secref[#:doc '(lib "teachpack/teachpack.scrbl") "image"],
@seclink[#:doc '(lib "teachpack/teachpack.scrbl") "image" "the image teachpack"], 
so if you're using this teachpack, @emph{don't} also load the @tt{image} teachpack.
Some of the important functions:
@itemize{
  @item{@scheme[rectangle]}
  @item{@scheme[circle]}
  @item{@scheme[ellipse]}
  @item{@scheme[triangle]}
  @item{@scheme[star]}
  @item{@scheme[regular-polygon]}
  @item{@scheme[line]}
  @item{@scheme[text]}
  @item{@scheme[image-width]}
  @item{@scheme[image-height]}
  @item{@scheme[add-line]}
  @item{@scheme[overlay]}
}

@; @include-section{image.ss}

@section{New image functions}
@defproc[(above (img1 image?) (img2 image?) ...)         image?]{
Combines two or more images into one, putting the first above the second (above the third, ...).}

@defproc[(above-align-right (img1 image?) (img2 image?) ...)         image?]{
Just like @scheme[above], but lines up the right-hand edges of all the images.}

@defproc[(above-align-left (img1 image?) (img2 image?) ...)         image?]{
Just like @scheme[above], but lines up the left-hand edges of all the images.}

@defproc[(above-align-center (img1 image?) (img2 image?) ...)         image?]{
Just like @scheme[above], but lines up the centers of all the images.}

@defproc[(beside (img1 image?) (img2 image?) ...)         image?]{
Combines two or more images into one, putting the first to the left of the second
(to the left of the third, ...).}

@defproc[(beside-align-top (img1 image?) (img2 image?) ...)         image?]{
Just like @scheme[beside], but lines up the top edges of all the images.}

@defproc[(beside-align-bottom (img1 image?) (img2 image?) ...)         image?]{
Just like @scheme[beside], but lines up the bottom edges of all the images.}

@defproc[(beside-align-center (img1 image?) (img2 image?) ...)         image?]{
Just like @scheme[beside], but lines up the centers of all the images.}

@defproc[(reflect-vert (img image?)) image?]{
Flips an image top-to-botom.}

@defproc[(reflect-horiz (img image?)) image?]{
Flips an image left-to-right.}

@defproc[(reflect-main-diag (img image?)) image?]{
Flips an image from top-right to bottom-left, leaving the top-left and bottom-right unchanged.}

@defproc[(reflect-other-diag (img image?)) image?]{
Flips an image from top-left to bottom-right, leaving the top-right and bottom-left unchanged.}

@defproc[(rotate-cw (img image?)) image?]{
Rotates an image 90 degrees clockwise.}

@defproc[(rotate-ccw (img image?)) image?]{
Rotates an image 90 degrees counterclockwise.}

@defproc[(rotate-180 (img image?)) image?]{
Rotates an image 180 degrees around its center.}

@defproc[(show-pinhole (img image?)) image?]{
Overlays a small black dot at the pinhole of the given image, so you can
see where it is.
@; (This function will go away when pinholes go away....)
}

@defproc[(crop-top (img image?) (pixels natural-number/c)) image?]{
Chops off the specified number of pixels from the top of the image.}

@defproc[(crop-bottom (img image?) (pixels natural-number/c)) image?]{
Chops off the specified number of pixels from the bottom of the image.}

@defproc[(crop-left (img image?) (pixels natural-number/c)) image?]{
Chops off the specified number of pixels from the left side of the image.}

@defproc[(crop-right (img image?) (pixels natural-number/c)) image?]{
Chops off the specified number of pixels from the right side of the image.}

@defproc[(place-image (foreground image?) (x real?) (y real?)
	(background image?)) image?]{
Places the foreground image at the specified location relative to the
top-left corner of the background image, clipping if necessary so the
result is the same size as @tt{background}.  Differs from the bundled
version of @scheme[place-image] in not requiring a "scene"; any image will do.}

@defproc[(scene+line (background image?) (x0 real?) (y0 real?)
	(x1 real?) (y1 real?) (color color?)) image?]{
Adds a line from (x0, y0) to (x1, y1) in the specified color to the background
image, clipping if necessary so the result is the same size as
@tt{background}.
Differs from the bundled version of @scheme[scene+line] in not requiring a
"scene"; any image will do.
Differs from @scheme[add-line] in clipping the result to the background.}

@defproc[(empty-scene [width natural-number/c]
                      [height natural-number/c])
         image?]{
 creates a plain white, @scheme[width] x @scheme[height] image.
 It's roughly equivalent to @schemeblock[(rectangle width height "solid" "white")]}

@section{Input and Output}
This teachpack also provides five functions to help in testing
I/O functions (in Advanced Student language; ignore this section if
you're in a Beginner or Intermediate language):

@defproc[(with-input-from-string (input string?) (thunk (-> any/c))) any/c]{
Calls @tt{thunk}, which presumably uses @scheme[read],
in such a way that @scheme[read] reads from @tt{input} rather than from
the keyboard.}

@defproc[(with-output-to-string (thunk (-> any/c))) string?]{
Calls @tt{thunk}, which presumably uses @scheme[display], @scheme[print],
@scheme[write], and/or @scheme[printf], in such a way that its output is
accumlated into a string, which is then returned.}

@defproc[(with-input-from-file (filename string?) (thunk (-> any/c))) any/c]{
Calls @tt{thunk}, which presumably uses @scheme[read],
in such a way that @scheme[read] reads from the specified file
rather than from the keyboard.}

@defproc[(with-output-to-file (filename string?) (thunk (-> any/c))) any/c]{
Calls @tt{thunk}, which presumably uses @scheme[display], @scheme[print],
@scheme[write], and/or @scheme[printf], in such a way that its output is
redirected into the specified file.}

@defproc[(with-io-strings (input string?) (thunk (-> any/c))) string?]{
Combines @scheme[with-input-from-string] and @scheme[with-output-to-string]:
calls @tt{thunk} with its input coming from @tt{input} and accumulates
its output into a string, which is returned.  Especially useful for testing:
@schemeblock[
(define (ask question)
  (begin (display question)
         (read)))                  
(define (greet)
   (local [(define name (ask "What is your name?"))]
	(printf "Hello, ~a!" name)))
(check-expect
   (with-io-strings "Steve" greet)
   "What is your name?Hello, Steve!")]
}

@include-section{worlds.scrbl}

@include-section{universes.scrbl}