abcaa1775c
and document the change that the PS bounding box is no longer inferred from drawing operations
157 lines
6.1 KiB
Plaintext
157 lines
6.1 KiB
Plaintext
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 and PDF 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.
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
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.
|