GRacket, Racket, Drawing, and GUIs
----------------------------------

Version 5.1 includes two major changes to the Racket drawing and GUI
API:

 * The drawing portion of the GUI toolbox is now available as a
   separate layer: `racket/draw'. This layer can be used independent
   of the `racket/gui/base' library, although `racket/gui' re-exports
   `racket/draw'.

   (The `racket/draw' library is built on top of the widely used Cairo
   drawing library and Pango text-rendering library.)

 * The GRacket executable is no longer strictly necessary for running
   GUI programs; the `racket/gui/base' library can be used from
   Racket.

   The GRacket executable still offers some additional GUI-specific
   functiontality however. Most notably, GRacket is a GUI application
   under Windows (as opposed to a console application, which is
   launched slightly differently by the OS), GRacket is a bundle under
   Mac OS X (so the dock icon is the Racket logo, for example), and
   GRacket manages single-instance mode for Windows and X.

The drawing and GUI libraries have also changed in further small ways.


Bitmaps
-------

Drawing to a bitmap may not produce the same results as drawing to a
canvas. Use the `make-screen-bitmap' function (from `racket/gui') or
the `make-bitmap' method of `canvas%' to obtain a bitmap that uses the
same drawing algorithms as a canvas.

A color bitmap can have an alpha channel, instead of just a mask
bitmap. When drawing a bitmap, alpha channels are used more
consistently and automatically than mask bitmaps. More significantly,
drawing into a bitmap with an alpha channel preserves the drawn
alphas; for example, drawing a line in the middle of an empty bitmap
produces an image with non-zero alpha only at the drawn line.

Only bitmaps created with the new `make-gl-bitmap' function support
OpenGL drawing. The `make-gl-bitmap' function takes a `gl-config%' as
an argument, and the `get-gl-config' and `set-gl-config' methods of
`bitmap%' have been removed.

Use the new `make-bitmap', `read-bitmap', `make-monochrome-bitmap',
`make-screen-bitmap', and `make-gl-bitmap' functions to create
bitmaps, instead of using `make-object' with `bitmap%'. The new
constructors are less overloaded and provide more modern defaults
(such as alpha channels by default).

Image formats can be read into a `bitmap%' from from input ports,
instead of requiring a file path. A newly created bitmap has an empty
content (i.e., white with zero alpha), instead of unspecified content.


Canvases
--------

Drawing to a canvas always draws into a bitmap that is kept offscreen
and periodically flushed onto the screen. The new `suspend-flush',
`resume-flush', and `flush' methods of `canvas%' provide some control
over the timing of the flushes, which in many cases avoids the need
for (additional) double buffering of canvas content.

OpenGL drawing in a canvas requires supplying 'gl as a style when
creating the `canvas%' instance. OpenGL and normal dc<%> drawing no
longer mix reliably in a canvas.


Drawing-Context Transformations
-------------------------------

A `dc<%>' instance supports rotation (via `set-rotation'), negative
scaling factors for flipping, and a general transformation matrix (via
`set-initial-matrix'). A transformation matrix has the form `(vector
xx xy yx yy x0 y0)', where a point (x1, y1) is transformed to a point
(x2, y2) with x2 = xx*x1 + yx*y1 + x0 and y2 = xy*x1 + yy*y1 + y0,
which is the usual convention.

New methods `translate', `scale', `rotate', and `transform' simplify
adding a further translation, scaling, rotation, or arbitrary matrix
transformation on top of the current transformation. The new
`get-translation' and `set-translation' methods help to capture and
restore transformation settings.

The old translation and scaling transformations apply after the
initial matrix. The new rotation transformation applies after the
other transformations. This layering is redundant, since all
transformations can be expressed in a single matrix, but it is
backward-compatibile. Methods like `get-translation',
`set-translation', `scale', etc. help hide the reundancy.


PostScript, PDF, and SVG Drawing Contexts
-----------------------------------------

The dimensions for PostScript output are no longer inferred from the
drawing. Instead, the width and height must be supplied when the
`post-script-dc%' is created.

The new `pdf-dc%' drawing context is like `post-script-dc%', but it
generates PDF output.

The new `svg-dc%' drawing context is similar to `post-script-dc%',
but it generates SVG output.


Other Drawing-Context Changes
-----------------------------

The alpha value of a `dc<%>' (as set by `set-alpha') is used for all
drawing operations, including drawing a bitmap.

The `draw-bitmap' and `draw-bitmap-section' methods now smooth bitmaps
while scaling, so the `draw-bitmap-section-smooth' method of
`bitmap-dc%' simply calls `draw-bitmap-section'.

A `region%' can be created as independent of any `dc<%>', in which
cases it uses the drawing context's current transformation at the time
that it is installed as a clipping region.

Brushes now support linear and radial gradients.

The old 'xor mode for pens and brushes is no longer available (since
it is not supported by Cairo).


Editor Changes
--------------

The `draw-caret' argument to a `snip%' or `editor<%>' `draw' or
`refresh' method can be a pair, which indicates that the caret is
owned by an enclosing display and the selection spans the snip or
editor. In that case, the snip or editor should refrain from drawing a
background for the selected region, and it should draw the foreground
in the color specified by `get-highlight-text-color', if any.


Other GUI Changes
-----------------

The `on-popup' method of `combo-field%' can be used to adjust the
content of the combo-box popup menu, but the default implementation no
longer triggers the popup menu; instead, the popup behavior is built
into the control.

Event callbacks are delimited by a continuation prompt using the
default continuation prompt tag. As a result, continuations can be
usufully captured during one event callback and applied during other
callbacks or outside of an even callback. The continuation barrier and
jump-defeating `dynamic-wind' that formerly guarded callbacks has been
removed.


Removed Functions
-----------------

The `write-resource, `get-reource', and `send-event' functions have
been removed from `racket/gui/base'. If there is any demand for the
removed functionality, it will be implemented in a new library.

The `current-ps-afm-file-paths' and `current-ps-cmap-file-paths'
functions have been removed, because they no longer apply. PostScript
font information is obtained through Pango.
