From: Matt Birkholz Date: Fri, 13 Jul 2012 16:51:54 +0000 (-0700) Subject: gtk: Document , factored out of in d8c9c69. X-Git-Tag: mit-scheme-pucked-9.2.12~578 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=b06f0668c409902f801a284bdba4b6f35da03911;p=mit-scheme.git gtk: Document , factored out of in d8c9c69. --- diff --git a/doc/gtk/gtk.texinfo b/doc/gtk/gtk.texinfo index efd5346ac..6fc83abdf 100644 --- a/doc/gtk/gtk.texinfo +++ b/doc/gtk/gtk.texinfo @@ -12,7 +12,7 @@ @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 @@ -109,7 +109,7 @@ 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 @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 @@ -161,7 +161,7 @@ the @file{src/gtk} directory of your build tree. @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 @@ -182,7 +182,7 @@ 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, respectively. +by evaluating the first and second expressions below. @example (set-thread-timer-interval! 1000) @@ -317,7 +317,7 @@ signaled. 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. @@ -1238,90 +1238,57 @@ Each change to a drawing ``invalidates'' areas of affected widgets. The toolkit batches up the damaged areas, repairing them via the expose event handlers. -@deffn Class -A direct subclass of scm-widget representing a reference to a ScmWidget. +@deffn Class +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}, @@ -1343,14 +1310,58 @@ symbols @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 +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 @@ -1874,7 +1885,7 @@ class is a specialization of the abstract gtk-object class. @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 @@ -1894,8 +1905,8 @@ up early, adding the instance's alien to gc-cleanups @emph{before} 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. @@ -1910,12 +1921,12 @@ gobject instance. Scheme owns the toolkit object, holds a reference, 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