Next: Introduction, Previous: (dir), Up: (dir)
This manual documents MIT/GNU Scheme Pucked Gtk 0.13.
Copyright © 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Matthew Birkholz
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”
| • Introduction: | ||
| • GTK Graphics Device: | ||
| • API Reference: | ||
| • Implementation Notes: | This is for Scheme widget developers. | |
| • GNU Free Documentation License: |
Next: GTK Graphics Device, Previous: Top, Up: Top
The Gtk system is a collection of Scheme data types and procedures providing a Schemely interface to the GNOME toolkit(s), not entirely unlike Perl’s Gtk2 “binding” (http://gtk2-perl.sourceforge.net) though by no means as extensive. Very little of the libraries’ APIs has been wrapped — just what is listed herein. As one might expect of a “Schemely” interface, all toolkit resources are protected from “leaking” by the 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.
The Gtk toolkits are built “on top” of GLib, which is not
thread-safe. To ensure that just one Scheme thread is “in” the
toolkits, the with-glib-lock procedure should be used, else
every callout will write a warning line to stderr.
See with-glib-lock in GLib Plugin Manual.
Here is the “Hello, World!” program from the C/Unix FFI
(here)
re-written to use the Gtk system. Notice that the program does not
need the FFI; it uses no FFI syntax. There is no need to
(load-option 'ffi).
#| -*-Scheme-*-
This is Havoc Pennington's Hello World example
from GGAD, wrapped in Scheme. |#
(define (hello)
(with-glib-lock
(lambda ()
(let ((window (gtk-window-new 'toplevel))
(button (gtk-button-new))
(label (gtk-label-new "Hello, World!")))
(gtk-container-add button label)
(gtk-container-add window button)
(gtk-window-set-title window "Hello")
(gtk-container-set-border-width button 10)
(let ((counter 0))
(set-gtk-window-delete-event-callback!
window
(lambda (window)
(outf-error ";Bite me "(- 2 counter)" times.\n")
(set! counter (1+ counter))
;; Three or more is the charm.
(if (> counter 2) 0 1)))
(set-gtk-button-clicked-callback!
button
(lambda (button)
(let ((text (gtk-label-get-text label)))
(gtk-label-set-text
label (list->string (reverse! (string->list text)))))
unspecific)))
(gtk-widget-show-all window)
window))))
To run this program, enter the following lines.
mit-scheme (load-option 'gtk) (ge '(gtk)) (load "hello") (hello)
The Gtk Event Viewer is a simple Scheme widget — a GtkWidget whose methods are implemented by calls back into Scheme — and a straightforward translation of Havoc Pennington’s GtkEv (from GGAD). To see this widget enter the following lines.
mit-scheme (load-option 'gtk) (make-gtk-event-viewer-demo)
The code can be found in gtk-ev.scm.
Create a window displaying the Gtk Event Viewer app.
The Gtk system provides a fixnum-centric canvas abstraction based on the ancient X Window draw requests: XDrawLine, XDrawRectangle, XDrawArc, etc. The canvas is a fix-drawing composed of fix-inks, each rendered on fix-layout widgets according to ancient custom.
A demo of two fix-layout widgets displaying one drawing is provided. The drawing contains a sample of each type of fix-ink with animation and mouse tracking (highlighting the character under the pointer, and reporting the inks under a click). To see these widgets in action, enter the following lines.
mit-scheme (load-option 'gtk) (make-fix-layout-demo)
The code can be found in fix-demo.scm.
Create a window displaying the Fix Layout Demo app.
The Gtk system contains a proof-of-concept emulation of the old Tk3.2 interface — SWAT, The Scheme Widget Application Toolkit, as described in Introduction to SWAT, by Hal Abelson, Natalya Cohen and Jim Miller. The emulation lacks many widget types and options, and is just sufficient to run Pole Zero.
To see the Pole Zero application, enter the following lines.
mit-scheme-pucked (load-option 'gtk) (make-pole-zero)
Create a window displaying the SWAT Pole Zero app.
Most of the Gtk system’s public bindings are in the (gtk)
package — not exported to the global environment. It is assumed
that modules mucking about with the toolkit(s) will be loaded in a
subpackage where they will define Gtk-specific procedures, such as
methods for generics imported from a more abstract interface.
The Scheme machine can be configured (via the
--enable-debugging option) to include some debugging
facilities, like a time slice counter. Evaluating the following
expression should cause a small window to pop up.
(gtk-time-slice-window! #t)
The window is created and updated on the toolkit side of the interface, and shows a running count of the number of times the toolkit has yielded to Scheme (or vice versa), and the channels currently being polled by Scheme. The count can be slowed and stopped by evaluating the first and second expressions below.
(set-thread-timer-interval! 1000) (set-thread-timer-interval! #f)
See Debugging Facilities.
Next: API Reference, Previous: Introduction, Up: Top
The Gtk system includes a graphics device type like those described in
the reference manual
(here).
With the Gtk option loaded and running on a display,
enumerate-graphics-types will include the symbol gtk.
A graphics device for Gtk is created by passing the symbol
gtk as the graphics device type name to
make-graphics-device:
(make-graphics-device 'gtk #!optional width height no-window?)
A Cairo image surface is created width pixels by height
pixels in size. If no-window? is specified (not #f) the
device will write to the surface, but not put the surface in a window.
Instead the device’s descriptor, a <surface-ink>, can be added
to any fix-drawing, or its Cairo surface can be passed to e.g.
cairo-surface-write-to-png.
By default (or when no-window? is #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.
Draws a filled polygon. Points is a list of flo:vectors each containing at least two flonums, the x and y coordinates of a point.
Draws a circle centered at (x, y) with radius.
Draws string at (x, y). This was intended to
implement the graphics-draw-text operation (upright, left to
right, at x) but it may be drawing text at y, not
y-baseline.
Draws a line that connects the points (x0, y0) and (x1, y1).
Sets the foreground and background colors for future drawing operations. Color should be a color name or specification understood by the Cairo plugin. See Cairo Colors in MIT/GNU Scheme Cairo Plugin.
Paints the background color over all of device’s Cairo surface, after resetting its clip region.
Applies cairo-surface-flush to device’s Cairo surface,
and updates any drawings containing device’s descriptor, a
<surface-ink>. This is the method
used by graphics-flush.
Next: Implementation Notes, Previous: GTK Graphics Device, Up: Top
This appendix lists all of the procedures and data types that make up the Gtk interface.
| • Pixbuf Loader: | ||
| • Gtk Adjustment: | ||
| • Gtk Widget: | ||
| • Gtk CSS Provider: | ||
| • Gtk Container: | ||
| • Gtk Window: | ||
| • Gtk Label: | ||
| • Gtk Button: | ||
| • Gtk Check Button: | ||
| • Gtk Grid: | ||
| • Gtk Frame: | ||
| • Gtk Paned: | ||
| • Gtk Scrolled Window: | ||
| • Scheme Widget: | ||
| • Fix Layout: | ||
| • Gdk Functions: | ||
| • Debugging Facilities: |
Next: Gtk Adjustment, Previous: API Reference, Up: API Reference
A pixbuf loader encapsulates the loading of a pixbuf. The
load-pixbuf-from-port procedure can feed data directly from a
Scheme input port into a pixbuf loader, and the loader’s various hooks
will notify the user when the pixbuf size is determined, when the
pixbuf is allocated, when areas of the pixbuf have been updated, and
when the pixbuf is complete.
A direct subclass of gobject representing a reference to a GdkPixbufLoader.
A direct subclass of gobject representing a reference to a GdkPixbuf.
A new pixbuf-loader instance.
Initializes loader and starts a new thread loading from input-port.
Initializes loader and starts a new thread loading from filename.
#f or the procedure that will be applied to the pixbuf size (two
integers, width and height).
Arrange for receiver to be applied to loader’s pixbuf’s size (two integers, width and height) as soon as it can be determined. If the size has already been determined, receiver is applied immediately.
#f or the procedure that will be applied to the pixbuf as soon as it
is allocated.
Arrange for receiver to be applied to loader’s pixbuf (an
instance of <pixbuf>) as soon as it is allocated. If the
pixbuf has already been created, receiver is applied
immediately.
#f or the procedure that will be applied to areas of the pixbuf
recently updated.
Arrange for receiver to be applied to areas of the pixbuf as they are updated. Receiver will be applied to four integers — the x and y coordinates of the upper-left corner, and width and height of the updated area. If the pixbuf is complete before receiver is set, it will never be called.
#f or the thunk that will be invoked when loading is complete.
Arrange for thunk to be invoked when loading is complete. If loading is complete before thunk is set, it will be invoked immediately.
#f or the pixbuf that is loading (or was loaded).
#f or a string describing any error encountered during the loading.
Next: Gtk Widget, Previous: Pixbuf Loader, Up: API Reference
A direct subclass of gobject representing a reference to a GtkAdjustment.
Type predicate.
Type guarantor.
A new gtk-adjustment instance.
Set the members of a GtkAdjustment and emit the changed and/or
value_changed signals.
valueA real magnitude.
lowerThe minimum value.
upperThe maximum value.
step_incrementThe increment to use to make minor changes to the value. In a GtkScrollbar this increment is used when the mouse is clicked on the arrows at the top and bottom.
page_incrementThe increment to use to make major changes to the value. In a GtkScrollbar this increment is used when the mouse is clicked in the trough.
page_sizeThe page size. In a GtkScrollbar this is the size of the area which is currently visible.
Next: Gtk CSS Provider, Previous: Gtk Adjustment, Up: API Reference
A gtk-widget is a gobject that can be "destroyed". Each instance is
connected to the "destroy" signal of its GtkWidget. The callback
applies gobject-unref! to the instance,
allowing the toolkit to finalize and dispose of the widget.
If a Gtk Widget is "dropped", never destroyed, eventually GCed, the
usual gobject cleanup will effect a gobject-unref! and
(potentially) release the toolkit resources.
A Gtk Widget also has a “parent” slot — a gtk-container or
#f.
An abstract, direct subclass of gobject.
Type predicate.
Type guarantor.
#f if widget has not been destroyed.
Destroys widget.
The parent gtk-container, or #f.
Arrange for callback to be applied to widget and an alien GtkAllocation whenever the widget’s size changes. Do not capture widget in callback’s closure, else it cannot be GCed.
Arrange for callback to be applied to widget when it is realized. Do not capture widget in callback’s closure, else it cannot be GCed.
Arrange for callback to be applied to widget when it is unrealized. Do not capture widget in callback’s closure, else it cannot be GCed.
Arranges for callback to be applied to widget and a cairo context clipped to the area to be re-drawn.
Arrange for callback to be applied to widget and an alien
GdkEvent whenever the widget receives an event signal.
Callback should return #t to stop emission of more
specific signals like focus-in-event and focus. It
must return either #t or #f else a warning is issued.
Do not capture widget in callback’s closure, else
it cannot be GCed.
#t if widget has been realized.
#t if widget can be drawn, i.e. it is realized and visible.
Causes widget to have the keyboard focus for the GtkWindow it’s inside. Widget must be a focusable widget, such as a GtkEntry; something like a GtkFrame will not work. The widget also needs to be realized. Grabbing the focus immediately after creating the widget will likely fail and cause critical warnings.
#t if widget has the keyboard.
Request a partially transparent widget. Opacity can vary from 0.0 (fully transparent) to 1.0 (fully opaque). On X11 the request has no effect without a compositing manager. Note that setting a window’s opacity after the window has been shown causes it to flicker once on Windows.
Indicates widget is ready to be displayed. If you want to show
all widgets in a container, it is easier to call
gtk-widget-show-all on the container. Note that the containers
containing widget must also be “shown” else widget
cannot be displayed. When a toplevel container is shown, it is
immediately realized, as well as any descendents that are
“showing”.
Recursively shows widget all of its children (if any).
Notifies the user about an input-related error on widget. This may sound a short beep, flash a visual cue associated with widget’s toplevel window, or do nothing at all, per user preference and window manager support.
The area occupied by widget is invalidated. An expose event for the entire area will be delivered when the toolkit is idle.
Flags widget to have its size renegotiated and invalidates its area. An expose event for the entire area will be delivered when the toolkit is idle.
Flags widget to have its size renegotiated but does not invalidate its entire area.
A PangoContext with the appropriate font map, font description, and
base direction for widget. This context is owned by
widget but it can be used until widget’s screen or
toplevel changes. It will be updated to match changes to
widget’s attributes. Widget’s style-set and
direction-changed signals indicate when the context has
changed. If you keep a PangoLayout using this default context, the
signal callbacks should apply pango-layout-context-changed.
Creates a new pango-layout with the appropriate font map, font
description, and base direction for drawing text for widget.
The layout will be empty unless text, a string, is provided. If
widget’s base direction or font changes, apply
pango-layout-context-changed to re-lay-out the text.
Gets widget’s size allocation, a pair of integers:
(width . height).
Set whether widget would like any available extra horizontal space or not, overriding the default expand behavior.
Set whether widget would like any available extra vertical space or not, overriding the default expand behavior.
Notify the toolkit of widget’s natural size. Width and height should be positive. This is just a request. Widget’s size-allocate callback will be applied when its size is initialized or changed. Unfortunately this procedure also overrides the minimum width and height so that a top-level window cannot be resized to a smaller size.
Next: Gtk Container, Previous: Gtk Widget, Up: API Reference
A GtkWidget’s GtkStyleContext specifies its default font and colors
per its state and theme. A GtkCssProvider can be added to the context
to specify defaults (or overrides) using a language similar to
Cascading Style Sheets (CSS). In this language, element
names select widgets by class (e.g. ScmWidget) and element ids
select widgets by name.
Gives widget name. The style of the widget (its font, colors, etc.) can then be specified using name in syntax much like the id selectors of Cascading Style Sheets (CSS). Note that the CSS selector syntax allows only alphanumerics, dashes and underscores in widget names.
Returns the GtkStyleContext associated with widget. Widget must be realized. The returned object is only valid until widget changes style.
Type predicate.
Adds provider, a GtkStyleProvider, to the style context.
Priority can be a non-negative integer or one of the symbols
fallback, theme, settings, application or
user (equivalent to the integers 1, 200, 400, 600 and 800
respectively). Styles specified with high priority override lower
priority specifications.
A direct subclass of gobject representing a reference to a GtkCssProvider.
Type predicate.
Type guarantor.
A new GtkCssProvider.
Returns the provider containing the style settings used as a fallback for all widgets.
Returns a GtkCssProvider in which a named theme has been loaded.
Name must be a string. Variant can be #f or a
string, for example: "dark".
Loads the CSS-like string into provider, clearing any previously loaded information.
Loads the CSS-like content of gfile (a GFile) into provider, clearing any previously loaded information.
Loads the CSS-like content of the file named path (a string or pathname) into provider, clearing any previously loaded information.
Next: Gtk Window, Previous: Gtk CSS Provider, Up: API Reference
A Gtk widget with a list of “children”. The list records only the
children that were created and added via this interface. Other
toolkit code may add, remove or re-order children and this list will
not be updated. This should probably be fixed with add and
remove signal callbacks.
An abstract, direct subclass of gtk-widget.
Type predicate.
Type guarantor.
A fresh list of container’s known children — those created and added via this interface.
The first known child in a container, e.g. the only child of a GtkBin created via this interface.
Adds child to container. Child should not already
be in a container. Typically used for GtkBins, where positioning the
child in the container is trivial. When applied to a more complex
container, the results may be unexpected. Consider a more specialized
procedure like gtk-grid-attach.
Removes child from container. If child is not in container, an error is signaled. If you intend to destroy child, you do not need to remove it.
Sets the border width of container to width. The border width of a container is the amount of space to leave around the outside of the container. The only exception to this is Gtk window; because toplevel windows can’t leave space outside, they leave the space inside.
Next: Gtk Label, Previous: Gtk Container, Up: API Reference
These objects are not GCed, but held strongly by the
toplevel-windows list in the (gtk gtk-object) package.
The toolkit object is a GtkBin, and should have no more than one
child, though this is not enforced, on the Scheme side, yet.
A direct subclass of gtk-container representing a reference to a GtkWindow.
Type predicate.
Type guarantor.
A new gtk-window instance. Type should be the symbol
toplevel. It can also be popup, but the window will not
be managed by the window manager, like a tooltip or popup menu window.
The symbol toplevel, unless window is a popup.
See gtk-window-new.
Sets window’s geometry hints. Widget can be #f or any
widget that is “showing” in window (not just window’s
immediate child). When specified, the geometry hints are applied to
widget’s size, sizing window to account for decorations,
scrollbars, etc. Hints should be an alist. Values associated
with names (symbols) in the following table will specify certain
resizing constraints.
min-width min-heightThe minimum fixnum dimensions of widget or window. -1 specifies their natural size. Both width and height should be specified.
max-width max-heightThe maximum dimensions of widget or window.
base-width base-height width-increment height-incrementAllow dimensions that are N increments greater than a base value, for non-negative integers N. Both width and height, for base and increment, should be specified — four fixnums.
min-aspect max-aspectThe minimum and maximum aspect ratios (reals).
gravityKeep the specified reference point of each child a constant distance
from the corresponding reference point of the window when it is
resized. The value of this property should be one of these symbols:
north, northeast, east, southeast,
south, southwest, west, northwest, or
center.
Sets the title of window to string. The title of a window is displayed in its title bar. It should help a user distinguish this window from other windows they may have open. A good title might include the application name and current document.
Sets window’s default size to width x height. If either dimension is -1, the default for that dimension is unset. If a dimension is 0, it is treated like 1, which means “as small as possible”. With a default size set, window may still request a larger size. The final size will be clamped according to window’s geometry hints. If window has already been shown, this procedure has no effect; it will not resize window.
By setting the type hint for 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 realizing window. Hint can be one of the symbols in the following table. See the Extended Window Manager Hints specification at http://www.freedesktop.org/Standards/wm-spec for more details about window types.
normalNormal toplevel window.
dialogDialog window.
menuWindow used to implement a menu; GTK+ uses this hint only for torn-off menus, see GtkTearoffMenuItem.
toolbarWindow used to implement toolbars.
splashscreenWindow used to display a splash screen during application startup.
utilityUtility windows which are not detached toolbars or dialogs.
dockUsed for creating dock or panel windows.
desktopUsed for creating the desktop background window.
dropdown-menuA menu that belongs to a menubar.
popup-menuA menu that does not belong to a menubar, e.g. a context menu.
tooltipA tooltip.
notificationA notification - typically a "bubble" that belongs to a status icon.
comboA popup from a combo box.
dndA window that is used to implement a DND cursor.
Applies receiver to window’s default width and height.
Resizes window as if the user had done so, obeying geometry constraints. width and height should be positive fixnums. When applied before window is shown for the first time, this procedure overrides window’s default size. See gtk-window-set-default-size.
These come from geometry hints, and a default constraint that windows not be sized smaller than their natural size.
Presents window to the user. This may mean raising the window in the stacking order, deiconifying it, moving it to the current desktop, and/or giving it the keyboard focus, possibly dependent on the user’s platform, window manager, and preferences. If window is hidden, it is shown.
Connect callback to window’s delete_event signal.
The signal will apply callback to window. Do not
capture window in callback’s closure, else it cannot be
GCed.
Next: Gtk Button, Previous: Gtk Window, Up: API Reference
A direct subclass of gtk-container representing a reference to a GtkLabel.
Type predicate.
Type guarantor.
A new gtk-label instance. Text, a string, will be displayed in the new label.
The text of label.
Sets label’s text to string.
Sets label’s natural size to n-chars.
Next: Gtk Check Button, Previous: Gtk Label, Up: API Reference
A direct subclass of gtk-container representing a reference to a GtkButton.
Type predicate.
Type guarantor.
A new gtk-button instance.
Connect callback to button’s "clicked" signal. The signal will apply callback to button. Do not capture button in callback’s closure, else it cannot be GCed.
Next: Gtk Grid, Previous: Gtk Button, Up: API Reference
A direct subclass of gtk-container representing a reference to a GtkCheckButton.
Type predicate.
Type guarantor.
A new gtk check button.
#t if button is “on”, #f if it is “off”.
If active?, turns button “on”, else “off”.
Connect callback to button’s "toggled" signal. The signal will apply callback to button. Do not capture button in callback’s closure, else it cannot be GCed.
Next: Gtk Frame, Previous: Gtk Check Button, Up: API Reference
GtkGrids arrange their children in rows and columns.
A direct subclass of gtk-container representing a reference to a GtkGrid.
Type predicate.
Type guarantor.
A new gtk-grid.
Set the distance between rows of grid to space pixels.
Set the distance between columns of grid to space pixels.
Set the homogeneity of row heights. If homogeneous? is
#f, rows can have different heights. Else they are all
allocated the same height.
Set the homogeneity of column widths. If homogeneous? is
#f, columns can have different widths. Else they are all
allocated the same width.
Place widget in grid at column left spanning width columns, and at row top spanning height rows.
Add widget to grid at side of sibling spanning
width columns and height rows. Side should be one
of the symbols left, right, top or bottom.
Sibling must be a child widget of grid or #f. When
sibling is #f, widget is placed on the side of
row or column 0. Thus adding three widgets on the left (with
sibling #f) causes the third widget to be layed out at
(-2,0), the first at (0,0).
Returns a GtkOrientable’s orientation — one of the symbols
horizontal or vertical.
Set a GtkOrientable to orientation which should be one of the
symbols horizontal or vertical.
Next: Gtk Paned, Previous: Gtk Grid, Up: API Reference
A bin with a decorative frame and optional label.
A direct subclass of gtk-container representing a reference to a GtkFrame.
Type predicate.
Type guarantor.
A new gtk frame. Label should be a string. A null string punts the label.
Type should be one of the symbols none, in,
out, etched-in, or etched-out.
Next: Gtk Scrolled Window, Previous: Gtk Frame, Up: API Reference
A paned widget draws a separator between two child widgets with a
small handle that the user can drag to move the separator. Each child
has two options that can be set, “resize” and “shrink”. If resize
is not #f, then when the GtkPaned is resized, that child will
expand or shrink along with the paned widget. At least one child
should be resizable; if resize is #f for both children, they
will both be resized. If shrink is #f, then the child will not
be made smaller than its minimum size.
A direct subclass of gtk-container representing a reference to a GtkPaned widget.
Type predicate.
A new gtk-paned instance. Orientation should be one of the
symbols horizontal or vertical.
Sets paned’s first child to child which should be a
gtk-widget. Child is allowed to resize or shrink when
resize? or shrink? are not #f respectively.
Sets paned’s second child to child which should be a
gtk-widget. Child is allowed to resize or shrink when
resize? or shrink? are not #f respectively.
Returns paned’s first child, or #f if there is none.
Returns paned’s second child, or #f if there is none.
Returns the position of the divider between the two panes—the pixel size of child1.
Sets the position of the divider between the two panes, forcing child1’s allocation to be position pixels. A negative size causes the position to be unset.
A direct subclass of gtk-scrolled-view representing a reference to a GtkPanedView. This is an extension to the Gtks, a specialization of GtkPaned that overrides its widget geometry protocol.
A GtkPaned allows the user to shrink a child (or not!), displaying it in a smaller area than its minimum size normally allows. If neither child is indicated as the shrinkable one, it is assumed both childen can be shrunk. The geometry implementation completely ignores the natural size of the children, sizing and expanding them in proportion to their minimum sizes (until the divider’s position is set). It will truncate the “beginning” of a child that does not fit, displaying its “end” (per the writing direction).
A GtkPanedView sizes/expands its children according to their natural sizes and respects their minimum sizes (while the position of its divider is unset, unless indicated as shrinkable). If neither child is allowed to shrink, it is assumed neither child should be shrunk. The minimum size of the paned view allows for the minimum sizes of both children.
The difference between paned windows and paned viewports can be
observed by substituting gtk-paned-new and
gtk-paned-view-new in the fix layout demo.
See Fix Layout Demo.
Type predicate.
A new gtk-paned-view instance. Orientation should be one of the
symbols horizontal or vertical.
Next: Scheme Widget, Previous: Gtk Paned, Up: API Reference
A direct subclass of gtk-container representing a reference to a GtkScrolledWindow.
Type predicate.
Type guarantor.
A new gtk scrolled window.
Horizontal and vertical should be one of the symbols
always, auto or never.
Placement should be one of the symbols top-left,
bottom-left, top-right or bottom-right. This is
the placement of the scrolled window, not the scrollbars. If the
scrolled window is placed “bottom left”, the scrollbars will appear
above and to the right.
A direct subclass of gtk-scrolled-window representing a reference to a GtkScrolledView. This is an extension to the Gtks, a specialization of GtkScrolledWindow that overrides its widget geometry protocol.
A GtkScrolledWindow is used to squeeze an overly large widget into a
smaller space and allow the user to scroll it. The geometry
implementation ignores the natural size of the problem widget,
expecting gtk_widget_set_size_request to override its minimum
size.
A GtkScrolledView is used to stick scrollbars on a viewport. Its
natural size is the natural size of the viewport, plus scrollbars,
frame, etc. Using gtk_widget_set_size_request is unnecessary
and interferes with resizing.
The difference between a scrolled window and a scrolled viewport can
be observed by substituting gtk-scrolled-view-new and
gtk-scrolled-window-new in the fix layout demo.
See Fix Layout Demo.
Type predicate.
A new gtk-paned-view instance. Orientation should be one of the
symbols horizontal or vertical.
Next: Fix Layout, Previous: Gtk Scrolled Window, Up: API Reference
A Scheme widget is a GtkWidget implemented by Scheme. Scheme creates
a ScmWidget toolkit object and connects to its various gsignals, like
size_allocate and realize. Its representative in
Scheme, a scm-widget instance, arranges to clean these up if it is
garbage collected, like any other gobject instance. Scheme widgets
implement the GtkScrollable interface, emitting a
set_scroll_adjustments signal when the “vadjustment” or
“hadjustment” properties are set. They also participate in the
width-for-height (or height-for-width) geometry management protocol
in GTK_SIZE_REQUEST_CONSTANT_SIZE mode.
A direct subclass of gtk-widget representing a reference to a ScmWidget.
Type guarantor.
Arranges for callback to be applied to widget and the horizontal and vertical GtkAdjustments (aliens). These need to be informed of any change to the widget’s scroll position. The aliens will be NULL when the widget’s scrollbars are removed.
Sets widget’s minimum width and height. This procedure does not
request a resize; it only changes the values returned by ScmWidget
methods like get_preferred_width.
Sets widget’s natural width and height. This procedure does not
request a resize; it only changes the values returned by ScmWidget
methods like get_preferred_height_for_width.
This simple Scheme widget manages the GdkWindow on which more specialized methods will draw. It allocates, moves and resizes the GdkWindow, and dispatches events received on it.
Note that the event handlers are run by
the generic event signal, and can return #t to stop
emission of more specific signals like focus-in-event and
focus. They must return either #t or #f else a
warning is issued.
A direct subclass of scm-widget. A ScmWidget toolkit object.
Type predicate.
Shape can be any one of the following symbols:
x-cursor,
arrow,
based-arrow-down,
based-arrow-up,
boat,
bogosity,
bottom-left-corner,
bottom-right-corner,
bottom-side,
bottom-tee,
box-spiral,
center-ptr,
circle,
clock,
coffee-mug,
cross,
cross-reverse,
crosshair,
diamond-cross,
dot,
dotbox,
double-arrow,
draft-large,
draft-small,
draped-box,
exchange,
fleur,
gobbler,
gumby,
hand1,
hand2,
heart,
icon,
iron-cross,
left-ptr,
left-side,
left-tee,
leftbutton,
ll-angle,
lr-angle,
man,
middlebutton,
mouse,
pencil,
pirate,
plus,
question-arrow,
right-ptr,
right-side,
right-tee,
rightbutton,
rtl-logo,
sailboat,
sb-down-arrow,
sb-h-double-arrow,
sb-left-arrow,
sb-right-arrow,
sb-up-arrow,
sb-v-double-arrow,
shuttle,
sizing,
spider,
spraycan,
star,
target,
tcross,
top-left-arrow,
top-left-corner,
top-right-corner,
top-side,
top-tee,
trek,
ul-angle,
umbrella,
ur-angle,
watch, or
xterm.
This procedure is called when widget is resized.
This procedure is called when widget is being realized.
Arranges to apply handler to widget when the pointer
enters.
handler must return #t or #f.
See event-handler-note.
Arranges to apply handler to widget when the pointer
leaves.
handler must return #t or #f.
See event-handler-note.
Arranges to apply handler to widget and a boolean value
when it receives a focus change event. The boolean is #t if
widget is now in focus.
handler must return #t or #f.
See event-handler-note.
Arranges to apply handler to widget and a symbol: one of
visible, partially-obscured or obscured.
handler must return #t or #f.
See event-handler-note.
Arranges to apply handler every time widget gets a key
press event. Handler is applied to widget, a key name,
and a bitmap of char-bits.
handler must return #t or #f.
See event-handler-note.
Arranges to apply handler every time the mouse moves.
Handler is applied to widget, a list of modifiers, and the
x and y coordinates of the pointer in the widget’s window (not in the
drawing’s coordinates). The modifiers include zero or more of the
symbols
shift,
lock,
control,
mod1,
mod2,
mod3,
mod4,
mod5,
button1,
button2,
button3,
button4,
button5,
super,
hyper,
meta and
release.
handler must return #t or #f.
See event-handler-note.
Arranges to apply handler whenever widget receives a
button event of the specified type — one of the symbols
press, release, double-press or
triple-press. Handler is applied to widget,
type, the button number (a fixnum), the modifiers, and the
coordinates of the pointer.
See set-fix-widget-motion-handler!.
handler must return #t or #f.
See event-handler-note.
Next: Gdk Functions, Previous: Scheme Widget, Up: API Reference
The Gtk system provides a fixnum-centric canvas abstraction based on the ancient X Window draw requests: XDrawLine, XDrawRectangle, XDrawArc, etc. A fix-layout is a Scheme widget that uses these requests to paint (and repaint) a view of a canvas on its GdkWindow. The canvas is a logical device space; all positions and dimensions are in fixnum pixels. Thus flonums are rarely needed, and actually avoided. For a flonum-oriented canvas (with scale, rotate, splines, etc.), a cairo-layout seems inevitable.
Just a few types of fix-ink have been implemented: line-ink, rectangle-ink, arc-ink, simple-text-ink, and image-ink.
Each fix-ink has a position on the canvas and a position in the drawing’s display list. The display list determines the order in which the inks are (re)drawn. An ink can be drawn in all views or conditionally, such that it only appears in specific widgets. Multiple fix-layout widgets can display different views of the same fix-drawing.
Animation (editing) is supported through the standard Gtk mechanism. Each change to a drawing “invalidates” areas of affected widgets. The toolkit batches up the damaged areas, repairing them via the expose event handlers.
A direct subclass of fix-widget.
Type predicate.
A new fix-layout with natural size width x height and background color bgcolor.
The fix-drawing displayed in layout, or #f.
Drawing must be a fix-drawing. X and y are the integer coordinates of the upper-left corner of the view. They are required so that the drawing, and the position from which to view it, are all set in one fell swoop. If layout is already viewing drawing, but at a different position, "move" to that position — snap, not scroll. Note that a drawing may only be viewed by multiple layouts that are on compatible screens.
The rectangle describing the area currently in view. It is shared with layout; do not modify it.
A pair: the horizontal and vertical scroll increments. It is shared with layout; do not modify it.
Sets the horizontal and vertical “step-increments” to be used by layout’s scrollbars.
X and y are the integer coordinates of the upper-left corner of layout’s view of the drawing. If layout is already displaying the view at that position, this procedure does nothing. Else it scrolls layout to the new position.
Scroll just enough to view the entire extent (a fix-rect). If the view is too small to include the entire extent, the layout is scrolled so that its NW corner matches the NW corner of the extent.
Fixnum-centric canvas, to which you can affix fix-ink spots.
A direct subclass of instance.
Type guarantor.
A new fix-drawing.
A list of fix-layout widgets displaying views of drawing. This is shared with drawing; do not modify it.
This is just the scrollable area, used mostly by scrollbars to scale their thumbs(?).
A list of fix-inks in drawing, displayed in widget, whose bounding boxes include the point (x, y).
Adds ink to the top of the display list for drawing. If
where is specified, it should be the symbol top (or #f),
the symbol bottom, or an ink already in the display list. When
where is an ink, ink is spliced in just under (before) it.
Abstract class for all inks that can be found in fix-drawings and rendered on fix-layouts.
A direct subclass of instance.
Type predicate.
Ink’s fix-drawing, or #f.
The widgets in which ink should be drawn, #t if it is drawn in
all views.
Draw ink only in the widgets. If widgets is #t,
ink will appear in all views of the drawing.
Moves ink by the specified x and y offsets.
Removes ink from its drawing.
This type of ink draws (outlines and/or fills) a shape according to a variety of options similar to those kept in an X GC (graphics context) for e.g. XDrawLine.
A direct subclass of fix-ink.
A draw-ink rendered with color, width and dashes as if by an
XDrawLine request.
A direct subclass of draw-ink.
Type predicate.
A new line-ink.
Set line to start at (x1,y1) and end at (x2,y2).
The width of line. () if not set.
Width should be a small positive integer (fixnum). Line will be redrawn unless it is already drawn at the specified width.
() if line’s color is not set, else the color last
provided to set-line-ink-color!.
Sets line’s foreground color.
() if line’s dash pattern is not set, else the pattern last
provided to set-line-ink-dashes!.
Dashes must be a list of flonums specifying the lengths for
dashes and spaces. One flonum is the same as two of the same. An
empty list makes the line solid. Note that the
line-ink-dash-color (if any) is painted along the line between
the dashes.
() if line’s dash color is not set, else the color last
provided to set-line-ink-dash-color!.
Sets line’s dash color. This color will appear between the
foreground colored dashes along the line. Note that a dash pattern
must also be set using set-line-ink-dashes!.
A draw-ink rendered with a fill color or outline width and color as if
by an XDrawRectangle request.
A direct subclass of draw-ink.
Type predicate.
A new rectangle-ink.
Sets the size and position of rectangle.
() if rectangle’s line color is not set, else the color
last provided to set-rectangle-ink-color!.
Sets rectangle’s line color (not the fill color).
() if rectangle’s line width is not set, else the
width last provided to set-rectangle-ink-width!.
Sets the width of the line used to draw rectangle’s outline.
() if rectangle’s fill color is not set, else the
color last provided to set-rectangle-ink-fill-color!.
Sets rectangle’s fill color. If color is #f,
rectangle is outlined, not filled.
A draw-ink rendered with a fill color or outline width and color as if
by an XDrawArc request. Its position, width and height define
the bounding box of an ellipse. The portion drawn starts with a
start-angle and ends after a sweep-angle. Both angles are in degrees
and are measured clockwise from 3 o’clock on the ellipse’s circle —
the ellipse scaled into a circle.
A direct subclass of draw-ink.
Type predicate.
A new arc-ink.
Sets the position and size of arc’s ellipse.
Arc’s start-angle (degrees).
Sets arc’s start-angle.
Arc’s sweep-angle (degrees).
Sets arc’s sweep-angle.
() if arc’s line color is not set, else the color last
provided to set-arc-ink-color!.
Sets arc’s line color (not the fill color).
() if arc’s line width not set, else the width last
provided to set-arc-ink-width!.
Sets the width of the line used to draw arc.
() if arc’s fill color is not set, else the color last
provided to set-arc-ink-fill-color!.
Sets arc’s fill color. If color is #f, arc is not
filled.
A draw-ink rendered by a PangoLayout. This abstract class uses an
abstract pango-layout slot provided by the generic function
text-ink-pango-layout, which is implemented by e.g. the simple
text ink (below).
An abstract, direct subclass of draw-ink.
Type predicate.
Sets the position of the upper left corner of text, a text-ink.
If (x, y) is in text’s extent, return the index of
the character at that point, else #f.
Applies receiver to the position and size (four fixnums) of the
indexth character in text’s text. If text has no
text, this procedure just returns #f; it does not apply
receiver. It normally returns receiver’s return value.
() if text’s color is not set, else the color last
provided to set-text-ink-color!.
Sets text’s default color.
A text-ink whose abstract text-ink-pango-layout slot is implemented by
an actual instance slot. Use set-simple-text-ink-text! to fill
it.
A direct subclass of text-ink.
Type predicate.
A new simple-text-ink.
Ink’s text — a string.
Sets ink’s text to string, using widget’s font and direction. It is assumed widget is compatible with all widgets displaying ink. See set-fix-layout-drawing!.
#f or a PangoFontDescription alien.
Sets text’s pango layout’s font to font. Font
should be a PangoFontDescription, or a string acceptable to
pango-font-description-from-string (e.g. courier 12).
A draw-ink rendered by a pixbuf. It uses a pixbuf-loader so that it can render the pixbuf as it loads.
A direct subclass of fix-ink.
A new image-ink whose pixbuf-loader is loading from filename.
Set the position of image to (x, y).
A fix-ink rendered by a Cairo image surface.
A direct subclass of fix-ink.
Type predicate.
Return a new surface ink — a new Cairo RGB24 image surface
widthxheight pixels in size.
Set the position of ink to (x, y).
Return the cairo image surface used to render ink. If you draw
on this surface, you need to call drawing-damage to notify any
widgets.
Next: Debugging Facilities, Previous: Fix Layout, Up: API Reference
A bitmap of char-bits (char-bit:control, char-bit:meta, char-bit:super, and char-bit:hyper) corresponding to the bits set in modifier-state, a GdkModifierType bitmap from a key or button event.
The key name (character or symbol) associated with the Gdk keyval.
Next: API Reference, Previous: Gdk Functions, Up: API Reference
#t if the time slice window is open, else #f.
If open? is #f, the time slice window is closed, else it is opened.
Next: GNU Free Documentation License, Previous: API Reference, Up: Top
This chapter is for the hapless debugger, or potential widget developer. It provides an overview of the mechanisms behind the scenes, like gtk-thread.
The procedures implementing the API are thin wrappers, trivial convenience functions that do type checking and conversion, and hide the details of the C API. For example, a GtkLabel’s text is retrieved in two steps: a toolkit function returns an alien address, and the C string at that address is copied into the heap.
(let ((retval (make-alien '|gchar|)))
(C-call "gtk_label_get_text" retval (gobject-alien label))
(c-peek-cstring retval))
⇒ "!dlrow ,olleH"
The gtk-label-get-text wrapper procedure hides these details.
(gtk-label-get-text label) ⇒ "!dlrow ,olleH"
In the example call to gtk-label-get-text above, a Scheme
object represents the GtkLabel. It is a gtk-label instance, whose
class is a specialization of the abstract gtk-object class.
Previous: Implementation Notes, Up: Top
Copyright © 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warrany Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.