@copying
This manual documents @acronym{Gtk} @value{VERSION}.
-Copyright @copyright{} 2008, 2009, 2010, 2011 Matthew Birkholz
+Copyright @copyright{} 2008, 2009, 2010, 2011, 2012 Matthew Birkholz
@quotation
Permission is granted to copy, distribute and/or modify this document
whose methods are implemented by calls back into Scheme --- and a
straightforward translation of Havoc Pennington's GtkEv (from
@uref{http://developer.gnome.org/doc/GGAD/,, GGAD}). To see this
-widget, enter the following command lines in the @file{src/gtk}
+widget enter the following command lines in the @file{src/gtk}
directory of your build tree.
@example
@unnumberedsec The Gtk Package
-All of the Gtk system's public bindings are in the @code{(gtk)}
+Most of the Gtk system's public bindings are in the @code{(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
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, respectively.
+by evaluating the first and second expressions below.
@example
(set-thread-timer-interval! 1000)
A pixbuf loader encapsulates the loading of a pixbuf. The
@bref{load-pixbuf-from-port} procedure can feed data directly from a
-Scheme input port into a pixbuf loader, and the loaders various hooks
+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.
The toolkit batches up the damaged areas, repairing them via the
expose event handlers.
-@deffn Class <fix-layout>
-A direct subclass of scm-widget representing a reference to a ScmWidget.
+@deffn Class <fix-widget>
+A direct subclass of scm-widget representing a reference to a
+ScmWidget. This class handles the realization of a widget's
+GdkWindow. It will allocate/move/resize the GdkWindow and dispatch
+events received on it.
@end deffn
-@deffn Procedure fix-layout? object
+@deffn Procedure fix-widget? object
Type predicate.
@end deffn
-@deffn Procedure make-fix-layout width height
-A new fix-layout with natural size @var{width} x @var{height}.
+@deffn {Generic Procedure} fix-widget-new-geometry-callback widget
+This procedure is called when @var{widget} is resized.
@end deffn
-@deffn {Generic Procedure} fix-layout-drawing layout
-The fix-drawing displayed in @var{layout}, or #f.
+@deffn {Generic Procedure} fix-widget-realize-callback widget
+This procedure is called when @var{widget} is being realized.
@end deffn
-@anchor{set-fix-layout-drawing!}
-@deffn Procedure set-fix-layout-drawing! layout drawing x y
-@var{Drawing} must be a fix-drawing. @var{X} and @var{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 @var{layout} is already viewing
-@var{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.
+@deffn Procedure set-fix-widget-map-handler! widget handler
+Arranges to apply @var{handler} to @var{widget} when it is mapped.
@end deffn
-@deffn Procedure fix-layout-scroll-step layout
-A pair: the horizontal and vertical scroll increments. It is shared
-with @var{layout}; do not modify it.
+@deffn Procedure set-fix-widget-unmap-handler! widget handler
+Arranges to apply @var{handler} to @var{widget} when it is unmapped.
@end deffn
-@deffn Procedure set-fix-layout-scroll-step! layout width height
-Sets the horizontal and vertical ``step-increments'' to be used by
-@var{layout}'s scrollbars.
-@end deffn
-
-@deffn Procedure fix-layout-scroll-to! layout x y
-@var{X} and @var{y} are the integer coordinates of the upper-left
-corner of @var{layout}'s view of the drawing. If @var{layout} is
-already displaying the view at that position, this procedure does
-nothing. Else it scrolls @var{layout} to the new position.
-@end deffn
-
-@deffn {Generic Procedure} fix-layout-new-geometry-callback layout
-This procedure is called when @var{layout} is resized.
-@end deffn
-
-@deffn {Generic Procedure} fix-layout-realize-callback layout
-This procedure is called when @var{layout} is being realized.
-@end deffn
-
-@deffn Procedure set-fix-layout-map-handler! layout handler
-Arranges to apply @var{handler} to @var{layout} when it is mapped.
-@end deffn
-
-@deffn Procedure set-fix-layout-unmap-handler! layout handler
-Arranges to apply @var{handler} to @var{layout} when it is unmapped.
-@end deffn
-
-@deffn Procedure set-fix-layout-focus-change-handler! layout handler
-Arranges to apply @var{handler} to @var{layout} and a boolean value
+@deffn Procedure set-fix-widget-focus-change-handler! widget handler
+Arranges to apply @var{handler} to @var{widget} and a boolean value
when it receives a focus change event. The boolean is #t if
-@var{layout} is now in focus.
+@var{widget} is now in focus.
@end deffn
-@deffn Procedure set-fix-layout-visibility-notify-handler! layout handler
-Arranges to apply @var{handler} to @var{layout} and a symbol: one of
+@deffn Procedure set-fix-widget-visibility-notify-handler! widget handler
+Arranges to apply @var{handler} to @var{widget} and a symbol: one of
@code{visible}, @code{partially-obscured} or @code{obscured}.
@end deffn
-@deffn Procedure set-fix-layout-key-press-handler! layout handler
-Arranges to apply @var{handler} every time @var{layout} gets a key
-press event. @var{Handler} is applied to @var{layout}, a key name,
+@deffn Procedure set-fix-widget-key-press-handler! widget handler
+Arranges to apply @var{handler} every time @var{widget} gets a key
+press event. @var{Handler} is applied to @var{widget}, a key name,
and a bitmap of char-bits. See @bref{gdk-keyval->name} and
@bref{gdk-key-state->char-bits} for the range of the last two
arguments.
@end deffn
-@anchor{set-fix-layout-motion-handler!}
-@deffn Procedure set-fix-layout-motion-handler! layout handler
+@anchor{set-fix-widget-motion-handler!}
+@deffn Procedure set-fix-widget-motion-handler! widget handler
Arranges to apply @var{handler} every time the mouse moves.
-@var{Handler} is applied to @var{layout}, a list of modifiers, and the
-x and y coordinates of the pointer in the layout's window (not in the
+@var{Handler} is applied to @var{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
@code{shift},
@code{release}.
@end deffn
-@deffn Procedure set-fix-layout-button-handler! layout type handler
-Arranges to apply @var{handler} whenever @var{layout} receives a
+@deffn Procedure set-fix-widget-button-handler! widget type handler
+Arranges to apply @var{handler} whenever @var{widget} receives a
button event of the specified @var{type} --- one of the symbols
@code{press}, @code{release}, @code{double-press} or
-@code{triple-press}. @var{Handler} is applied to @var{layout},
+@code{triple-press}. @var{Handler} is applied to @var{widget},
@var{type}, the button number (a fixnum), the modifiers, and the
coordinates of the pointer. See
-@bref{set-fix-layout-motion-handler!}.
+@bref{set-fix-widget-motion-handler!}.
+@end deffn
+
+@deffn Class <fix-layout>
+A direct subclass of fix-widget representing a reference to a ScmWidget.
+@end deffn
+
+@deffn Procedure fix-layout? object
+Type predicate.
+@end deffn
+
+@deffn Procedure make-fix-layout width height
+A new fix-layout with natural size @var{width} x @var{height}.
+@end deffn
+
+@deffn {Generic Procedure} fix-layout-drawing layout
+The fix-drawing displayed in @var{layout}, or #f.
+@end deffn
+
+@anchor{set-fix-layout-drawing!}
+@deffn Procedure set-fix-layout-drawing! layout drawing x y
+@var{Drawing} must be a fix-drawing. @var{X} and @var{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 @var{layout} is already viewing
+@var{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.
+@end deffn
+
+@deffn Procedure fix-layout-scroll-step layout
+A pair: the horizontal and vertical scroll increments. It is shared
+with @var{layout}; do not modify it.
+@end deffn
+
+@deffn Procedure set-fix-layout-scroll-step! layout width height
+Sets the horizontal and vertical ``step-increments'' to be used by
+@var{layout}'s scrollbars.
+@end deffn
+
+@deffn Procedure fix-layout-scroll-to! layout x y
+@var{X} and @var{y} are the integer coordinates of the upper-left
+corner of @var{layout}'s view of the drawing. If @var{layout} is
+already displaying the view at that position, this procedure does
+nothing. Else it scrolls @var{layout} to the new position.
@end deffn
@subsection Fix Drawing
@unnumberedsec Gtk Thread
-When the Gtk system loads it starts a toolkit main loop with Scheme
+When the Gtk system loads, it starts a toolkit main loop with Scheme
attached as an custom idle task. The main loop then re-starts Scheme,
which creates a thread to ``run'' the toolkit (actually, return to
it). Thus Scheme threads multitask with the toolkit. Scheme runs as
calling out to the toolkit. This ensures that an allocated toolkit
object will not be dropped; its alien address is on the list of GC
cleanups before it is even allocated. @emph{After} the callout, the
-method should also @code{g_object_ref_sink} any floating refs it
-receives.
+initialize method should also @code{g_object_ref_sink} any floating
+refs it receives.
The following scenarios are typical of Gtk resource management.
and should eventually @code{g_object_unref} it. The instance may be
shared among any number of Scheme widgets or other data structures
(e.g a file->pixbuf cache) and @emph{never} explicitly ``killed''.
-When there are no more Scheme objects sharing the toolkit object, it
+When there are no more Scheme objects sharing the instance, it
will be GCed and its GC cleanup procedure will ``kill''
(@code{g_object_unref}) the toolkit object. This may release toolkit
-resources or not, depending on references elsewhere in the toolkit
-data structures. In any case, the instance was GCed so the toolkit
-object is dead to Scheme.
+resources or not depending on references elsewhere in the toolkit
+data structures. In any case the instance was GCed --- the object
+cannot be erroneously used by Scheme in the future.
Signals: The @bref{g-signal-connect} procedure takes pains not to hold
a strong reference to a gobject instance. These instances can be GCed
projects / mit-scheme.git / commitdiff