[racket-dev] try the GRacket2 branch

The git repository now includes a "gr2" branch for the new
implementation of `racket/gui', which we've been informally calling
"GRacket2".

The new `racket/gui' is intended to be mostly compatible with the
current library, but there are some significant incompatibilities.
Those differences are described below in a copy of the "Porting from
v5.0.x to vX.Y" notes that are linked from the "Release Notes" page of
the documentation.

"GRacket2" is a misnomer in the sense that you can use the new
`racket/gui' with just `racket'. Furthermore, the drawing layer is
mostly unbundled from the GUI layer into a separate `racket/draw'
library, so you can manipulate images without a GUI (e.g., without an
X11 connection). The documentation doesn't yet reflect the GUI--Draw
split, Slideshow's pict library doesn't yet use `racket/draw', etc.,
but I hope to get to that next.

More immediately, it's time for you to try out the "gr2" branch for
everyday work. I've switched to GRacket2 for SirMail, Slideshow, and
DrRacket --- even during lecture. All library functionality is in
place, but I'm sure that gaps and problems will show up as we put the
library to work (and I know that some of the tests still fail). I
expect to see many bug reports; once the bug reports slow down, I'll
take that as a sign that GRacket2 can move to master branch.

----------------------------------------

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

Version X.Y 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.

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' and
`resume-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.


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

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.


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.