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

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:

[misclib-Z-G-1.gif]

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.

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

2.4.2  Pixels

2.4.3  Lines

2.4.4  Rectangles

2.4.5  Ellipses

2.4.6  Polygons

2.4.8  Pixmaps

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).

2.6  Miscellaneous Operations

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.

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.

2.12  Flushing

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.