@menu
* Introduction::
+* GTK Graphics Device::
* API Reference::
* Installation::
* Implementation Notes:: This is for Scheme widget developers.
* GNU Free Documentation License::
@end menu
-@node Introduction, API Reference, Top, Top
+@node Introduction, GTK Graphics Device, Top, Top
@chapter Introduction
The Gtk system is a collection of Scheme data types and procedures
is dropped and collected, the toolkit resource is freed, just as the
C/Unix FFI's malloced aliens are automatically freed.
-This manual assumes you are familiar with MIT Scheme's @code{src/}
-tree @emph{and} the GNOME toolkits. Thus a few examples, a terse API
-Reference, and The Code itself are all you have.
-
@unnumberedsec Hello, World!
Here is the ``Hello, World!'' program from the C/Unix FFI
@xref{Debugging Facilities}.
-@node API Reference, Installation, Introduction, Top
+@node GTK Graphics Device, API Reference, Introduction, Top
+@chapter GTK Graphics Device
+
+The Gtk system includes a graphics device type like those described in
+the reference manual
+@ifnothtml
+(@pxref{Graphics,, Graphics, mit-scheme-ref, The MIT/GNU Scheme Reference Manual}).
+@end ifnothtml
+@ifhtml
+(@uref{mit-scheme-ref/Graphics.html,, here}).
+@end ifhtml
+With the Gtk option loaded and running on a display,
+@bref{enumerate-graphics-types} will include the symbol @code{gtk}.
+
+A graphics device for Gtk is created by passing the symbol
+@code{gtk} as the graphics device type name to
+@bref{make-graphics-device}:
+
+@example
+(make-graphics-device 'gtk #!optional @var{width} @var{height} @var{no-window?})
+@end example
+
+A Cairo image surface is created @var{width} pixels by @var{height}
+pixels in size. If @var{no-window?} is specified (not @code{#f}) the
+device will write to the surface, but not put the surface in a window.
+Instead the device's descriptor, a @bref{<surface-ink>}, can be added
+to any fix-drawing, or its Cairo surface can be passed to e.g.
+@bref{cairo-surface-write-to-png}.
+
+By default (or when @var{no-window?} is @code{#f}) the device's output
+appears in a scrollable window.
+
+You can draw on the surface with the simple graphics interface and/or
+the following procedures.
+
+@deffn Procedure gtk-graphics/fill-polygon-list device points
+Draws a filled polygon. @var{Points} is a list of flo:vectors each
+containing at least two flonums, the x and y coordinates of a point.
+@end deffn
+
+@deffn Procedure gtk-graphics/draw-circle device x y radius
+Draws a circle centered at (@var{x}, @var{y}) with @var{radius}.
+@end deffn
+
+@deffn Procedure gtk-graphics/draw-text device x y string
+Draws @var{string} at (@var{x}, @var{y}). This was intended to
+implement the @bref{graphics-draw-text} operation (upright, left to
+right, at @var{x}) but it may be drawing text at @var{y}, not
+@var{y}-baseline.
+@end deffn
+
+@deffn Procedure gtk-graphics/draw-line device x0 y0 x1 y1
+Draws a line that connects the points (@var{x0}, @var{y0}) and
+(@var{x1}, @var{y1}).
+@end deffn
+
+@deffn Procedure gtk-graphics/set-foreground-color device color
+@deffnx Procedure gtk-graphics/set-background-color device color
+Sets the foreground and background colors for future drawing
+operations. @var{Color} can be a color name or specification.
+@xref{colors}.
+@end deffn
+
+@deffn Procedure gtk-graphics/flush device
+Applies @bref{cairo-surface-flush} to @var{device}'s Cairo surface,
+and updates any drawings containing @var{device}'s descriptor, a
+@bref{<surface-ink>}. @xref{cairo-surface-flush}. This is the method
+used by @code{graphics-flush}.
+@end deffn
+
+@node API Reference, Installation, GTK Graphics Device, Top
@appendix API Reference
This appendix lists all of the procedures and data types that make up
* Pixbuf Loader::
* Pango Layout::
* Cairo Context::
+* Cairo Surface::
+* Cairo Pattern::
* Gtk Adjustment::
* Gtk Widget::
* Gtk Container::
thereafter signal an error.
@end deffn
-@node Cairo Context, Gtk Adjustment, Pango Layout, API Reference
+@node Cairo Context, Cairo Surface, Pango Layout, API Reference
@section Cairo Context
This simple wrapper for @code{cairo_t} objects ensures that the
toolkit object is de-referenced when the Scheme object is garbage
-collected. The Scheme object is an alien of type @code{cairo_t} and
-is used directly in calls to the library's C functions.
+collected. The Scheme object is an alien of type @code{cairo_t}.
@deffn Procedure gdk-cairo-create window
Creates a cairo context targeting @var{window}.
De-references a @var{cairo} context object. Further operations on
@var{cairo} will produce an error.
@end deffn
-
+
+@deffn Procedure cairo-create surface
+Creates a new cairo context with all graphics state parameters set to
+default values and with @var{surface} as the target surface. The
+context will reference the surface so @bref{cairo-surface-destroy} can
+be called on it if the surface will no longer be used directly.
+@end deffn
+
+@deffn Procedure cairo-set-source-color cairo color
+Sets the source pattern within @var{cairo} to @var{color} which will
+then be used for future drawing operations. The default source
+pattern is opaque black.
+@xref{colors}.
+@end deffn
+
+@deffn Procedure cairo-set-source cairo pattern
+Sets the source pattern within @var{cairo} to @var{pattern} which will
+then be used for future drawing operations. The default source is
+solid, opaque black.
+@end deffn
+
+@deffn Procedure cairo-translate cairo dx dy
+Modifies the current transformation matrix of @var{cairo} by
+translating the user-space origin to (dx, dy).
+@end deffn
+
+@deffn Procedure cairo-scale cairo sx sy
+Modifies the current transformation matrix of @var{cairo} by scaling
+the X and Y user-space axes by @var{sx} and @var{sy} respectively.
+@end deffn
+
+@deffn Procedure cairo-arc cairo x y radius start end
+Adds a circular arc to the current path. The arc is centered at
+(@var{x}, @var{y}), has @var{radius}, begins at @var{start} and
+proceeds in the direction of increasing angles to @var{end}. If
+@var{end} is less than @var{start} it will be progressively increased
+by 2pi until it is greater than @var{start}.
+
+If there is a current point, an initial line segment will be added to
+the path to connect the current point to the beginning of the arc. If
+this initial line is undesired, it can be avoided by calling
+@bref{cairo-new-sub-path} before calling @code{cairo-arc}.
+
+@var{Start} and @var{end} should be given in radians. An angle of 0.0
+is in the direction of the positive X axis (in user space). An angle
+of pi/2 radians (90 degrees) is in the direction of the positive Y
+axis (in user space). With the default transformation matrix, angles
+increase in a clockwise direction.
+@end deffn
+
+@deffn Procedure cairo-paint cairo
+Paints the current source everywhere within the current clip region.
+@end deffn
+
+@deffn Procedure cairo-stroke cairo
+Strokes @var{cairo}'s current path according to the
+current line width, line join, line cap, and dash settings. The
+current path is then cleared.
+@end deffn
+
+@deffn Procedure cairo-fill cairo
+Fills @var{cairo}'s current path according to the current fill rule.
+Each sub-path is implicitly closed before being filled. The current
+path is then cleared.
+@end deffn
+
@deffn Procedure cairo-clip-extents cairo receiver
Calls @var{receiver} with the user-space bounding box of the area
inside @var{cairo}'s current clip. @var{Receiver} will be called with
four flonums: the left, top, right and bottom bounds of the clip.
@end deffn
-@node Gtk Adjustment, Gtk Widget, Cairo Context, API Reference
+@deffn Procedure cairo-set-font-matrix cairo matrix
+Sets @var{cairo}'s current font matrix to @var{matrix}, which gives a
+transformation from the design space of the font (in this space, the
+em-square is 1 unit by 1 unit) to user space. @var{Matrix} should be
+created using @bref{cairo-matrix}.
+@end deffn
+
+@deffn Procedure cairo-matrix xx yx x0 xy yy y0
+Creates a Cairo transformation matrix. A point @code{(x,y)} is
+transformed by this matrix into @code{(xx * x + xy * y + x0, yx * x +
+yy * y + y0)}.
+@end deffn
+
+@node Cairo Surface, Cairo Pattern, Cairo Context, API Reference
+@section Cairo Surface
+
+This simple wrapper for @code{cairo_surface_t} objects ensures that the
+toolkit object is de-referenced when the Scheme object is garbage
+collected. The Scheme object is an alien of type
+@code{cairo_surface_t}.
+
+@deffn Procedure cairo-image-surface-create width height
+Creates a Cairo image surface @var{width}x@var{height} pixels.
+@end deffn
+
+@deffn Procedure cairo-surface-flush surface
+Does any pending drawing for @var{surface}. Also restores any
+temporary modifications Cairo has made to the surface's state.
+@end deffn
+
+@deffn Procedure cairo-surface-destroy surface
+De-references a cairo @var{surface} object. Further operations on
+@var{surface} will produce an error.
+@end deffn
+
+@node Cairo Pattern, Gtk Adjustment, Cairo Surface, API Reference
+@section Cairo Pattern
+
+This simple wrapper for @code{cairo_pattern_t} objects ensures that the
+toolkit object is de-referenced when the Scheme object is garbage
+collected. The Scheme object is an alien of type
+@code{cairo_pattern_t}.
+
+@deffn Procedure cairo-pattern-create-radial x0 y0 radius0 x1 y1 radius1
+Creates a new radial gradient pattern from the circle defined by
+(@var{x0}, @var{y0}, @var{radius0}) to a second circle defined by
+(@var{x1}, @var{y1}, @var{radius1}). Before using the gradient
+pattern, a number of color stops should be defined using
+@bref{cairo-pattern-add-color-stop}.
+@end deffn
+
+@deffn Procedure cairo-pattern-create-linear x0 y0 x1 y1
+Creates a new linear gradient pattern along the line from (@var{x0},
+@var{y0}) to (@var{x1}, @var{y1}). Before using the gradient pattern,
+a number of color stops should be defined using
+@bref{cairo-pattern-add-color-stop}.
+@end deffn
+
+@deffn Procedure cairo-pattern-add-color-stop pattern offset color
+Adds a color stop to a gradient @var{pattern}. @var{Offset} specifies
+the location along the gradient's control vector. @var{Color} should
+be an RGBA color. @xref{colors}. If two (or more) stops are
+specified with identical offset values, they will be sorted according
+to the order in which the stops are added. Stops added earlier will
+compare less than stops added later. This can be useful for reliably
+making sharp color transitions instead of the typical blend.
+@end deffn
+
+@deffn Procedure cairo-pattern-destroy pattern
+De-references a cairo @var{pattern} object. Further operations on
+@var{pattern} will produce an error.
+@end deffn
+
+@node Gtk Adjustment, Gtk Widget, Cairo Patter, API Reference
@section Gtk Adjustment
@deffn Class <gtk-adjustment>
height so that a top-level window cannot be resized to a smaller size.
@end deffn
-@anchor{gtk-widget-set-size-request}
-
@subsection Gtk Widget Colors & Fonts
+@anchor{colors}
Colors are floating-vectors containing four flonums between 0. and
1. inclusive: the red, green, blue and alpha components. For example
will not resize @var{window}.
@end deffn
+@deffn Procedure gtk-window-set-type-hint window hint
+By setting the type hint for @var{window}, you allow the window
+manager to decorate and handle the window in a way which is suitable
+to the function of the window in your application. This function
+should be called before mapping @var{window}. @var{Hint} can be one
+of the symbols in the following table. See the Extended Window
+Manager Hints specification at
+@uref{http://www.freedesktop.org/Standards/wm-spec} for more details
+about window types.
+
+@table @code
+@item normal
+Normal toplevel window.
+@item dialog
+Dialog window.
+@item menu
+Window used to implement a menu; GTK+ uses this hint only for torn-off
+menus, see GtkTearoffMenuItem.
+@item toolbar
+Window used to implement toolbars.
+@item splashscreen
+Window used to display a splash screen during application startup.
+@item utility
+Utility windows which are not detached toolbars or dialogs.
+@item dock
+Used for creating dock or panel windows.
+@item desktop
+Used for creating the desktop background window.
+@item dropdown-menu
+A menu that belongs to a menubar.
+@item popup-menu
+A menu that does not belong to a menubar, e.g. a context menu.
+@item tooltip
+A tooltip.
+@item notification
+A notification - typically a "bubble" that belongs to a status icon.
+@item combo
+A popup from a combo box.
+@item dnd
+A window that is used to implement a DND cursor.
+@end table
+@end deffn
+
@deffn Procedure gtk-window-get-default-size window receiver
Applies @var{receiver} to @var{window}'s default width and height.
@end deffn
Set the position of @var{image} to (@var{x}, @var{y}).
@end deffn
+@subsection Surface Ink
+
+A fix-ink rendered by a Cairo image surface.
+
+@deffn Class <surface-ink>
+A direct subclass of fix-ink.
+@end deffn
+
+@deffn Procedure surface-ink? object
+Type predicate.
+@end deffn
+
+@deffn Procedure make-surface-ink width height
+Return a new surface ink --- a new Cairo @code{RGB24} image surface
+@var{width}x@var{height} pixels in size.
+@end deffn
+
+@deffn Procedure set-surface-ink-position! ink x y
+Set the position of @var{ink} to (@var{x}, @var{y}).
+@end deffn
+
+@deffn Procedure surface-ink-surface ink
+Return the cairo image surface used to render @var{ink}. If you draw
+on this surface, you need to call @code{drawing-damage} to notify any
+widgets.
+@end deffn
+
@subsection Box Ink
A fix-ink rendered by @code{gtk_paint_box}.
projects / mit-scheme.git / commitdiff