From ad20e50ed0e523d258215f0a31aef51717de53e5 Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Sat, 13 Apr 2013 10:49:32 -0700 Subject: [PATCH] Catch up Gtk documentation. Fix typo in ref-manual/graphics.texi. --- doc/gtk/gtk.texinfo | 301 +++++++++++++++++++++++++++++++++-- doc/ref-manual/graphics.texi | 2 +- 2 files changed, 289 insertions(+), 14 deletions(-) diff --git a/doc/gtk/gtk.texinfo b/doc/gtk/gtk.texinfo index 15b56d5d3..ff7889301 100644 --- a/doc/gtk/gtk.texinfo +++ b/doc/gtk/gtk.texinfo @@ -67,13 +67,14 @@ Software Foundation raise funds for GNU development.'' @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 @@ -87,10 +88,6 @@ garbage collector. When Scheme's representative of a toolkit resource 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 @@ -206,7 +203,77 @@ by evaluating the first and second expressions below. @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{}, 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{}. @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 @@ -218,6 +285,8 @@ the Gtk interface. * Pixbuf Loader:: * Pango Layout:: * Cairo Context:: +* Cairo Surface:: +* Cairo Pattern:: * Gtk Adjustment:: * Gtk Widget:: * Gtk Container:: @@ -1019,13 +1088,12 @@ Releases Scheme's reference to @var{metrics} with 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}. @@ -1035,14 +1103,152 @@ 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 @@ -1268,9 +1474,8 @@ Unfortunately this procedure also overrides the minimum width and 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 @@ -1481,6 +1686,49 @@ will be clamped according to @var{window}'s geometry hints. If 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 @@ -2562,6 +2810,33 @@ A new image-ink whose pixbuf-loader is loading from @var{filename}. 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 +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}. diff --git a/doc/ref-manual/graphics.texi b/doc/ref-manual/graphics.texi index d1f4533e1..6a07970bb 100644 --- a/doc/ref-manual/graphics.texi +++ b/doc/ref-manual/graphics.texi @@ -711,7 +711,7 @@ This draws a quarter circle pie slice, standing on its point, with point at virtual coordinates (3,5): @example -(graphics-opereration g 'draw-arc 3 5 .5 .5 45 90 #t) +(graphics-operation g 'draw-arc 3 5 .5 .5 45 90 #t) @end example @end defop -- 2.25.1