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 untilopen-graphicsis called again, no graphics routines will work.(open-viewportnamehorizvert)
Takes a stringnameand integershorizandvertand creates a new window calledname. The window ishorizpixels wide andvertpixels high. For backward compatibility, a singleposnvalue (see below) can be submitted in the place ofhorizandvert.open-viewportreturns a viewport descriptor.(open-pixmapnamehorizvert)
Likeopen-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 withcopy-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-viewportviewport)
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-posnxy)
Takes two integers and returns a position with the specifiedxandycoordinates.(posn-x,p)(posn-yp)
Return thexandycoordinates, respectively, of a position.(posn?v)
Reports whethervis a position.((get-pixelviewport)p)
Returns the color of the pixel at positionpinviewport; 0 denotes white and 1 denotes not white.((get-color-pixelviewport)p)
Returns an RGB value for color of the pixel at positionpinviewport.((test-pixelviewport)color)
Returns the color that will actually be used ifcoloris 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-rgbredgreenblue)
Takes three values in the range 0 (dark) to 1 (bright) and returns anrgb(a color).(rgb-redcolor)
(rgb-bluecolor)
(rgb-greencolor)
Return the red, green, and blue components, respectively, of a color.(rgb?v)
Reports whethervis a color.(change-colorindexrgb)
Changes the color atindexin the color table to the color specified inrgb. 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#tif the default display screen for viewports is in color or#fotherwise.
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-viewportviewport)color)
Takes a viewport descriptor. It returns a function that colors the entire contents ofviewport. The optionalcolorargument defaults to black.((clear-viewportviewport))
Takes a viewport descriptor. It returns a function that whitens the entire contents ofviewport.((flip-viewportviewport))
Takes a viewport descriptor. It returns a function that flips the contents ofviewport.(copy-viewportsource-viewportdestination-viewport)
Takes two viewport descriptors. It copies thesource-viewportinto thedestination-viewport.
2.4.2 Pixels
((draw-pixel viewport)pcolor)
Takes a viewport descriptor. It returns a function that draws a pixel inviewportat the specified position. The optionalcolorargument defaults to black.((clear-pixelviewport)p)
Takes a viewport descriptor. It returns a function that clears a pixel inviewportat the specified position.((flip-pixelviewport)p)
Takes a viewport descriptor. It returns a function that flips a pixel inviewportat the specified position.
2.4.3 Lines
((draw-lineviewport)p1p2color)
Takes a viewport descriptor. It returns a function that draws a line in theviewportconnecting positionsp1andp2. The optionalcolorargument defaults to black.((clear-lineviewport)p1p2)
Takes a viewport descriptor. It returns a function that clears a line inviewportconnecting positionsp1andp2.((flip-lineviewport)p1p2)
Takes a viewport descriptor. It returns a function that flips a line inviewportconnecting positionsp1andp2.
2.4.4 Rectangles
((draw-rectangleviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that draws a rectangle border in theviewportwith the top-left of the rectangle at the positionposnand with sideswidthacross andheighttall. The optionalcolorargument defaults to black.((clear-rectangleviewport)posnwidthheight)
Takes a viewport descriptor. It returns a function that clears a rectangle border in theviewportwith the top-left of the rectangle at the positionposnand with sideswidthacross andheighttall. The optionalcolorargument defaults to black.((flip-rectangleviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that flips a rectangle border in theviewportwith the top-left of the rectangle at the positionposnand with sideswidthacross andheighttall. The optionalcolorargument defaults to black.((draw-solid-rectangleviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that paints a solid rectangle in theviewportwith the top-left of the rectangle at the positionposnand with sideswidthacross andheighttall. The optionalcolorargument defaults to black.((clear-solid-rectangleviewport)posnwidthheight)
Takes a viewport descriptor. It returns a function that erases a solid rectangle in theviewportwith the top-left of the rectangle at the positionposnand with sideswidthacross andheighttall. The optionalcolorargument defaults to black.((flip-solid-rectangleviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that flips a solid rectangle in theviewportwith the top-left of the rectangle at the positionposnand with sideswidthacross andheighttall. The optionalcolorargument defaults to black.
2.4.5 Ellipses
((draw-ellipseviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that draws an ellipse border in theviewport. Theposn,width, andheightarguments are as indraw-rectangle; the ellipse is inscribed within the specified rectangle. The optionalcolorargument defaults to black.((clear-ellipseviewport)posnwidthheight)
Takes a viewport descriptor. It returns a function that clears an ellipse border in theviewport. Theposn,width, andheightarguments are as inclear-rectangle; the ellipse is inscribed within the specified rectangle. The optionalcolorargument defaults to black.((flip-ellipseviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that flips an ellipse border in theviewport. Theposn,width, andheightarguments are as inflip-rectangle; the ellipse is inscribed within the specified rectangle. The optionalcolorargument defaults to black.((draw-solid-ellipseviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that paints a solid ellipse in theviewport. Theposn,width, andheightarguments are as indraw-rectangle; the ellipse is inscribed within the specified rectangle. The optionalcolorargument defaults to black.((clear-solid-ellipseviewport)posnwidthheight)
Takes a viewport descriptor. It returns a function that erases a solid ellipse in theviewport. Theposn,width, andheightarguments are as inclear-rectangle; the ellipse is inscribed within the specified rectangle. The optionalcolorargument defaults to black.((flip-solid-ellipseviewport)posnwidthheightcolor)
Takes a viewport descriptor. It returns a function that flips a solid ellipse in theviewport. Theposn,width, andheightarguments are as inflip-rectangle; the ellipse is be inscribed within the specified rectangle. The optionalcolorargument defaults to black.
2.4.6 Polygons
((draw-polygonviewport)posn-listposncolor)
Takes a viewport descriptor. It returns a function that draws a polygon border in theviewportusingposn-listfor the polygon vertices andposnas an offset for the polygon. The optionalcolorargument defaults to black.((clear-polygonviewport)posn-listposn)
Takes a viewport descriptor. It returns a function that erases a polygon border in theviewportusingposn-listfor the polygon vertices andposnas an offset for the polygon.((flip-polygonviewport)posn-listposn)
Takes a viewport descriptor. It returns a function that flips a polygon border in theviewportusingposn-listfor the polygon vertices andposnas an offset for the polygon.((draw-solid-polygonviewport)posn-listposncolor)
Takes a viewport descriptor. It returns a function that paints a solid polygon in theviewportusingposn-listfor the polygon vertices andposnas an offset for the polygon. The optionalcolorargument defaults to black.((clear-solid-polygonviewport)posn-listposn)
Takes a viewport descriptor. It returns a function that erases a solid polygon in theviewportusingposn-listfor the polygon vertices andposnas an offset for the polygon.((flip-solid-polygonviewport)posn-listposn)
Takes a viewport descriptor. It returns a function that flips a solid polygon in theviewportusingposn-listfor the polygon vertices andposnas an offset for the polygon.2.4.7 Strings
((draw-stringviewport)pstringcolor)
Takes a viewport descriptor. It returns a function that draws a string at a specified location in theviewport. The lower left of the string begins atp. The optionalcolorargument defaults to black.((clear-stringviewport)pstring)
Takes a viewport descriptor. It returns a function that clears a string at a specified location inviewport. The lower left of the string begins atp.((flip-stringviewport)pstring)
Takes a viewport descriptor. It returns a function that flips a string at a specified location inviewport. The lower left of the string begins atp.
2.4.8 Pixmaps
(((draw-pixmap-posnfilenametype)viewport)posncolor)
Draws a pixmap into
viewportwith its upper left corner at positionposn. Thetypeis an optional symbol, one of'gif,'gif/mask,'xbm,'xpm,'bmp,'pict,'unknown, or'unknown/mask, and defaults to'unknown/mask. Iftypeis'unknownor'unknown/mask, then the content of the file is examined to determine the type. All formats are supported on all platforms, except'pictwhich is only supported under Mac OS X. The'gif/maskand'unknown/masktypes draw the bitmap with a transparent background iffilenamerefers to a GIF file with a transparent background.The argument
coloris only used when the pixmap is black and white. In that case, the color is used instead of black in the drawn image.((draw-pixmapviewport)filenamepcolor)
Draws a pixmap intoviewportwwith its upper left corner at positionp. Ifcoloris not#fit is passed toset-viewport-penwith the viewport. It defaults to#f.((save-pixmapviewport)filenametype)
Saves the current content ofviewporttofilename. Thetypeis 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-worldviewport)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-eventviewport)numberunary 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-tickviewport))
Takes a viewport descriptor. It returns a function of no arguments that can stop the clock for this canvas's world.((set-on-key-eventviewport)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-sizeviewport)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->snipviewport)
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-dcviewport)
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, too.viewport)(viewport-offscreen-dcviewport)
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, too.viewport)
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-linew) (make-posn30 30) (make-posn100 100)) ;; line appears (close-viewportw) ;; 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* (;;w1andw2are 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-linew1)] [d2 (draw-linew2)]) ;; draws a line in viewport labeled "viewport 1" (d1 (make-posn100 5) (make-posn5 100)) ;; draws a line in viewport labeled "viewport 2" (d2 (make-posn100 100) (make-posn101 400))) ;; we no longer have access to viewports 1 and 2, ;; since their descriptors did not escape thelet(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: nothingvoid;; the main program (errors constrained to this piece) (lambda () (draw-pixel13)) ; an error ;; what we would like to happen, whether the main program finishes ;; normally or not (lambda () (close-viewportw))))
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-clickviewport)
Takes a viewport descriptor and returns a mouse click descriptor. It returns the next mouse click in theviewport, waiting for a click if necessary.(ready-mouse-clickviewport)
Takes a viewport descriptor and returns either a mouse click descriptor, or else#fif none is available. Unlike the previous function,ready-mouse-clickreturns immediately.(ready-mouse-releaseviewport)
Takes a viewport descriptor and returns either a click descriptor from a mouse-release (button-up) event, or else#fif none is available.(query-mouse-posnviewport)
Takes a viewport descriptor and returns either the position of the mouse cursor within theviewport, or else#fif the cursor is currently outside theviewport.(mouse-click-posnmouse-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#tif the click occurred with the left mouse button, or else#f.(middle-mouse-click?mouse-click)
Similar toleft-mouse-click?.(right-mouse-click?mouse-click)
Similar toleft-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-pressviewport)
Takes a viewport descriptor and returns a key press descriptor. It returns the next key press in theviewport, waiting for a click if necessary.(ready-key-pressviewport)
Takes a viewport descriptor and returns either a key press descriptor, or else#fif none is available. Unlike the previous function,ready-key-pressreturns immediately.(key-valuekey-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-inputviewport)
As noted above, key presses and mouse clicks are buffered.viewport-flush-inputtakes 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.