Chapter 2

Viewport Graphics

The viewport graphics library is a relatively simple toolbox of graphics commands. The library is not very powerful; it is intended as a simplified alternative to MrEd's full graphical toolbox.

The graphics library originated as SIXlib, a library of X Windows commands available within Chez Scheme at Rice University. The functionality of that library has been reproduced (with backward compatibility) in this version.

To use the viewport graphics library in a PLT language, load it via require:

(require (lib "graphics.ss" "graphics"))

which loads the graphics.ss library from the graphics collection. All of the names defined in this chapter will then be available.

2.1  Basic Commands

• (open-graphics)
  Initializes the library's graphics routines. It must be called before any other graphics operations.

• (close-graphics)
  Closes all of the windows and until open-graphics is called again, no graphics routines will work.

• (open-viewport name horiz vert)
  Takes a string name and integers horiz and vert and creates a new window called name. The window is horiz pixels wide and vert pixels high. For backward compatibility, a single posn value (see below) can be submitted in the place of horiz and vert. open-viewport returns a viewport descriptor.

• (open-pixmap name horiz vert)
  Like open-viewport, but the resulting viewport is not displayed on the screen. Offscreen pixmaps are useful for executing a sequence of drawing commands and displaying them all at once with copy-viewport.

  Offscreen pixmaps are also useful in conjunction with viewport->snip (see below). This allows functions to compute with graphical objects and view the graphics when results are returned to the interactions window.

• (close-viewport viewport)
  Takes a viewport descriptor. It removes the viewport from the screen and makes subsequent operations dealing with the viewport illegal.

2.2  Position Operations

A position is a pixel location within a viewport. The upper-left corner is pixel (0, 0) and the orientation of the position coordinates within a viewport is as follows:

• (make-posn x y)
  Takes two integers and returns a position with the specified x and y coordinates.

• (posn-x p), (posn-y p)
  Return the x and y coordinates, respectively, of a position.

• (posn? v)
  Reports whether v is a position.

• ((get-pixel viewport) p)
  Returns the color of the pixel at position p in viewport; 0 denotes white and 1 denotes not white.

• ((get-color-pixel viewport) p)
  Returns an RGB value for color of the pixel at position p in viewport.

• ((test-pixel viewport) color)
  Returns the color that will actually be used if color is used to draw.

2.3  Color Operations

A color can be represented in three ways: as a color index (an integer in 0 to 299, inclusive), as a color name string, or as a rgb value. All drawing functions which take a color argument accept colors in any form. An rgb value is assigned to an index with change-color.

• (make-rgb red green blue)
  Takes three values in the range 0 (dark) to 1 (bright) and returns an rgb (a color).

• (rgb-red color)
(rgb-blue color)
(rgb-green color)
  Return the red, green, and blue components, respectively, of a color.

• (rgb? v)
  Reports whether v is a color.

• (change-color index rgb)
  Changes the color at index in the color table to the color specified in rgb. Only the first twenty-one indices are initialized; a color index should not be used until it has been initialized.

• (default-display-is-color?)
  Returns #t if the default display screen for viewports is in color or #f otherwise.

2.4  Draw, Clear and Flip Operations

These are the basic graphics operations for drawing to a viewport. Each function takes a viewport as its argument and returns a function operating within that viewport. Further arguments, if any, are curried. For example, (draw-line viewport) returns a function, that can then be applied to the proper arguments to draw a line in the viewport corresponding to viewport descriptor viewport. An example follows.

Where ``draw-'' commands make pixels black, ``clear-'' commands make them white.

Where ``draw-'' commands make pixels black, a ``flip-'' commands cause them to change.

2.4.1  Viewports

• ((draw-viewport viewport) color)
  Takes a viewport descriptor. It returns a function that colors the entire contents of viewport. The optional color argument defaults to black.

• ((clear-viewport viewport))
  Takes a viewport descriptor. It returns a function that whitens the entire contents of viewport.

• ((flip-viewport viewport))
  Takes a viewport descriptor. It returns a function that flips the contents of viewport.

• (copy-viewport source-viewport destination-viewport)
  Takes two viewport descriptors. It copies the source-viewport into the destination-viewport.

2.4.2  Pixels

• ((draw-pixel viewport) p color)
  Takes a viewport descriptor. It returns a function that draws a pixel in viewport at the specified position. The optional color argument defaults to black.

• ((clear-pixel viewport) p)
  Takes a viewport descriptor. It returns a function that clears a pixel in viewport at the specified position.

• ((flip-pixel viewport) p)
  Takes a viewport descriptor. It returns a function that flips a pixel in viewport at the specified position.

2.4.3  Lines

• ((draw-line viewport) p1 p2 color)
  Takes a viewport descriptor. It returns a function that draws a line in the viewport connecting positions p1 and p2. The optional color argument defaults to black.

• ((clear-line viewport) p1 p2)
  Takes a viewport descriptor. It returns a function that clears a line in viewport connecting positions p1 and p2.

• ((flip-line viewport) p1 p2)
  Takes a viewport descriptor. It returns a function that flips a line in viewport connecting positions p1 and p2.

2.4.4  Rectangles

• ((draw-rectangle viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that draws a rectangle border in the viewport with the top-left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to black.

• ((clear-rectangle viewport) posn width height)
  Takes a viewport descriptor. It returns a function that clears a rectangle border in the viewport with the top-left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to black.

• ((flip-rectangle viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that flips a rectangle border in the viewport with the top-left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to black.

• ((draw-solid-rectangle viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that paints a solid rectangle in the viewport with the top-left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to black.

• ((clear-solid-rectangle viewport) posn width height)
  Takes a viewport descriptor. It returns a function that erases a solid rectangle in the viewport with the top-left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to black.

• ((flip-solid-rectangle viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that flips a solid rectangle in the viewport with the top-left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to black.

2.4.5  Ellipses

• ((draw-ellipse viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that draws an ellipse border in the viewport. The posn, width, and height arguments are as in draw-rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to black.

• ((clear-ellipse viewport) posn width height)
  Takes a viewport descriptor. It returns a function that clears an ellipse border in the viewport. The posn, width, and height arguments are as in clear-rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to black.

• ((flip-ellipse viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that flips an ellipse border in the viewport. The posn, width, and height arguments are as in flip-rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to black.

• ((draw-solid-ellipse viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that paints a solid ellipse in the viewport. The posn, width, and height arguments are as in draw-rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to black.

• ((clear-solid-ellipse viewport) posn width height)
  Takes a viewport descriptor. It returns a function that erases a solid ellipse in the viewport. The posn, width, and height arguments are as in clear-rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to black.

• ((flip-solid-ellipse viewport) posn width height color)
  Takes a viewport descriptor. It returns a function that flips a solid ellipse in the viewport. The posn, width, and height arguments are as in flip-rectangle; the ellipse is be inscribed within the specified rectangle. The optional color argument defaults to black.

2.4.6  Polygons

• ((draw-polygon viewport) posn-list posn color)
  Takes a viewport descriptor. It returns a function that draws a polygon border in the viewport using posn-list for the polygon vertices and posn as an offset for the polygon. The optional color argument defaults to black.

• ((clear-polygon viewport) posn-list posn)
  Takes a viewport descriptor. It returns a function that erases a polygon border in the viewport using posn-list for the polygon vertices and posn as an offset for the polygon.

• ((flip-polygon viewport) posn-list posn)
  Takes a viewport descriptor. It returns a function that flips a polygon border in the viewport using posn-list for the polygon vertices and posn as an offset for the polygon.

• ((draw-solid-polygon viewport) posn-list posn color)
  Takes a viewport descriptor. It returns a function that paints a solid polygon in the viewport using posn-list for the polygon vertices and posn as an offset for the polygon. The optional color argument defaults to black.

• ((clear-solid-polygon viewport) posn-list posn)
  Takes a viewport descriptor. It returns a function that erases a solid polygon in the viewport using posn-list for the polygon vertices and posn as an offset for the polygon.

• ((flip-solid-polygon viewport) posn-list posn)
  Takes a viewport descriptor. It returns a function that flips a solid polygon in the viewport using posn-list for the polygon vertices and posn as an offset for the polygon.

  2.4.7  Strings

• ((draw-string viewport) p string color)
  Takes a viewport descriptor. It returns a function that draws a string at a specified location in the viewport. The lower left of the string begins at p. The optional color argument defaults to black.

• ((clear-string viewport) p string)
  Takes a viewport descriptor. It returns a function that clears a string at a specified location in viewport. The lower left of the string begins at p.

• ((flip-string viewport) p string)
  Takes a viewport descriptor. It returns a function that flips a string at a specified location in viewport. The lower left of the string begins at p.

2.4.8  Pixmaps

• (((draw-pixmap-posn filename type) viewport) posn color)
  

  Draws a pixmap into viewport with its upper left corner at position posn. The type is an optional symbol, one of 'gif, 'gif/mask, 'xbm, 'xpm, 'bmp, 'pict, 'unknown, or 'unknown/mask, and defaults to 'unknown/mask. If type is 'unknown or 'unknown/mask, then the content of the file is examined to determine the type. All formats are supported on all platforms, except 'pict which is only supported under Mac OS X. The 'gif/mask and 'unknown/mask types draw the bitmap with a transparent background if filename refers to a GIF file with a transparent background.

  The argument color is only used when the pixmap is black and white. In that case, the color is used instead of black in the drawn image.

• ((draw-pixmap viewport) filename p color)
  Draws a pixmap into viewport w with its upper left corner at position p. If color is not #f it is passed to set-viewport-pen with the viewport. It defaults to #f.

• ((save-pixmap viewport) filename type)
  Saves the current content of viewport to filename. The type is an optional symbol, one of 'xbm, 'xpm, 'bmp (Windows only), or 'pict (Mac OS X only); the default is 'xpm.

2.5  World Operations

Every canvas comes with an associated world. A client program can set the world, start the world's clock, stop the world's clock, and deal with tick events (the clock ticks) and keyboard inputs (keyevents).

• ((init-world viewport) X)
  Takes a viewport descriptor. It returns a function whose input becomes the initial value of the world associated with this canvas.

• ((set-on-tick-event viewport) number unary procedure)
  Takes a viewport descriptor. It returns a function whose first input is a number and the second one is a function from worlds to worlds. The number determines how frequently the clock ticks. The given function is called for every clock tick on the current world; the result becomes the next world.

• ((stop-tick viewport))
  Takes a viewport descriptor. It returns a function of no arguments that can stop the clock for this canvas's world.

• ((set-on-key-event viewport) unary procedure)
  Takes a viewport descriptor. It returns a function whose input becomes the keyevent callback function. This callback consumes the latest keyevent and the current world and a keyevent; it produces the next world.

2.6  Miscellaneous Operations

• ((get-string-size viewport) string)
  Takes a viewport descriptor. It returns a function that returns the size of a string as a list of two numbers: the width and height.

• (viewport->snip viewport)
  Takes a viewport descriptor. It returns an object that can be inserted into an editor buffer to display the current image in the viewport. (Subsequent drawing to the viewport does not affect the snip's image.)

  When snips are the results of computations in the interactions window, DrScheme will print show the contents of the viewport, right in the interactions window.

• (viewport-dc viewport)
  Takes a viewport descriptor. It returns an object that can be used with the primitive MrEd toolbox functions to draw into the viewport's on-screen representation (if any). Mirror all such drawing to the result of (viewport-offscreen-dc viewport), too.

• (viewport-offscreen-dc viewport)
  Takes a viewport descriptor. It returns an object that can be used with the primitive MrEd toolbox functions to draw into the viewport's off-screen representation. Mirror all such drawing to the result of (viewport-dc viewport), too.

2.7  An Example

(open-graphics)
;; nothing appears to happen, but the library is initialized...

(define w (open-viewport "practice" 300 300))
;; viewport appears

((draw-line w) (make-posn 30 30) (make-posn 100 100))     
;; line appears

(close-viewport w)
;; viewport disappears

(close-graphics)
;; again, nothing appears to happen, but
;; unclosed viewports (if any) would disappear

2.8  A More Complicated Example

The use of multiple viewports, viewport descriptors, drawing operations for multiple viewports is as easy as the use of a single viewport:

(open-graphics)
(let* (;; w1 and w2 are viewport descriptors for different windows
       [w1  (open-viewport "viewport 1" 300 300)]
       [w2  (open-viewport "viewport 2" 200 500)]
       ;; d1 and d2 are functions that draw lines in different viewports
       [d1  (draw-line w1)]
       [d2  (draw-line w2)])
  ;; draws a line in viewport labeled "viewport 1"
  (d1 (make-posn 100 5) (make-posn 5 100))
  ;; draws a line in viewport labeled "viewport 2"
  (d2 (make-posn 100 100) (make-posn 101 400)))
 
;; we no longer have access to viewports 1 and 2, 
;; since their descriptors did not escape the let
(close-graphics) 
;; removes the viewports

2.9  Protecting Graphics Operations

To guarantee the proper closing of viewports in cases of errors, especially when a program manages several viewports simultaneously, a programmer should use dynamic-wind:

(let ([w (open-viewport "hello" 100 100)])
  (dynamic-wind
    ;; what we want to happen first: nothing
    void
    ;; the main program (errors constrained to this piece)
    (lambda () (draw-pixel 13))  ; an error
    ;; what we would like to happen, whether the main program finishes 
    ;; normally or not
    (lambda () (close-viewport w))))

2.10  Mouse Operations

The graphics library contains functions that determine where the mouse is, if there are any clicks, etc. The functions get-mouse-click and ready-mouse-click first return a ``mouse-click descriptor,'' and then other functions take the descriptor and return the mouse's position, which button was pushed, etc. Mouse clicks are buffered and returned in the same order in which they occurred. Thus, the descriptors returned by get-mouse-click and ready-mouse-click may be from clicks that occurred long before these functions were called.

• (get-mouse-click viewport)
  Takes a viewport descriptor and returns a mouse click descriptor. It returns the next mouse click in the viewport, waiting for a click if necessary.

• (ready-mouse-click viewport)
  Takes a viewport descriptor and returns either a mouse click descriptor, or else #f if none is available. Unlike the previous function, ready-mouse-click returns immediately.

• (ready-mouse-release viewport)
  Takes a viewport descriptor and returns either a click descriptor from a mouse-release (button-up) event, or else #f if none is available.

• (query-mouse-posn viewport)
  Takes a viewport descriptor and returns either the position of the mouse cursor within the viewport, or else #f if the cursor is currently outside the viewport.

• (mouse-click-posn mouse-click)
  Takes a mouse click descriptor and returns the position of the pixel where the click occurred.

• (left-mouse-click? mouse-click)
  Takes a mouse click descriptor and returns #t if the click occurred with the left mouse button, or else #f.

• (middle-mouse-click? mouse-click)
  Similar to left-mouse-click?.

• (right-mouse-click? mouse-click)
  Similar to left-mouse-click?.

2.11  Keyboard Operations

The graphics library contains functions that report key presses from the keyboard. The functions get-key-press and ready-key-press return a ``key-press descriptor,'' and then key-value takes the descriptor and returns a character or symbol (usually a character) representing the key that was pressed. Key presses are buffered and returned in the same order in which they occurred. Thus, the descriptors returned by get-key-press and ready-key-press may be from presses that occurred long before these functions were called.

• (get-key-press viewport)
  Takes a viewport descriptor and returns a key press descriptor. It returns the next key press in the viewport, waiting for a click if necessary.

• (ready-key-press viewport)
  Takes a viewport descriptor and returns either a key press descriptor, or else #f if none is available. Unlike the previous function, ready-key-press returns immediately.

• (key-value key-press)
  Takes a key press descriptor and returns a character or special symbol for the key that was pressed. For example, the Enter key generates #\return, and the up-arrow key generates 'up. For a complete list of possible return values, see PLT MrEd: Graphical Toolbox Manual.

2.12  Flushing

• (viewport-flush-input viewport)
  As noted above, key presses and mouse clicks are buffered. viewport-flush-input takes a viewport descriptor and empties the input buffer of mouse and keyboard events.

2.13  Unitized Graphics

To use a unitized version of the graphics library (see PLT MzLib: Libraries Manual for more information on units), get the signatures graphics^, graphics:posn-less^, and graphics:posn^ with:

(require (lib "graphics-sig.ss" "graphics"))

The graphics^ signature includes all of the names defined in this chapter. The graphics:posn-less^ signature contains everything except the posn structure information, and graphics:posn^ contains only the posn structure.

To obtain graphics@, which imports mred^ (all of the MrEd classes, functions, and constants) and exports graphics^:

(require (lib "graphics-unit.ss" "graphics"))

The graphics-posn-less-unit.ss library provides graphics-posn-less@, which imports graphics:posn^ in addition to MrEd.