From: Matt Birkholz Date: Sat, 14 Jul 2012 03:21:01 +0000 (-0700) Subject: gtk: Document the remaining exported bindings. X-Git-Tag: mit-scheme-pucked-9.2.12~576 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=5a737be7584ebe43da335ba9bf5aabae691cbfe9;p=mit-scheme.git gtk: Document the remaining exported bindings. Don't warn about undocumented make-*-demo and *-gc-cleanup bindings. Export . --- diff --git a/doc/gtk/check.scm b/doc/gtk/check.scm index e1d513ed2..8c3965d8c 100644 --- a/doc/gtk/check.scm +++ b/doc/gtk/check.scm @@ -101,7 +101,12 @@ (read-package-model "gtk" microcode-id/operating-system)))) (bindings (append (pmodel/global-exports pmodel) (pmodel/package-bindings pmodel '(gtk)))) - (missing (minus bindings deffns)) + (missing (minus (minus bindings deffns) + '(add-gc-cleanup + punt-gc-cleanup + make-pole-zero + make-fix-layout-demo + make-gtk-event-viewer-demo))) (extras (minus deffns bindings))) (if (not (null? dups)) (for-each (lambda (name) (warn "multiple-descriptions:" name)) dups)) diff --git a/doc/gtk/gtk.texinfo b/doc/gtk/gtk.texinfo index c8316b76c..2d0f5eb2c 100644 --- a/doc/gtk/gtk.texinfo +++ b/doc/gtk/gtk.texinfo @@ -230,15 +230,16 @@ dispose and finalize the GObject. Callbacks can be "connected" to gobjects --- one callback per signal name. The procedures run without-interrupts (or at least -without-preemption). Connecting a second callback disconnects the +without-preemption, or perhaps just without-toolkit). +Connecting a second callback disconnects the first. All connected callbacks are ``pinned'' by the @code{registered-callbacks} vector; they cannot be GCed until they are explicitly de-registered. The callback @emph{and} its closure are pinned. If the closure references the instance, the instance is -pinned and the garbage collector cannot help free the corresponding +also pinned and the garbage collector will never free the corresponding toolkit resources. Thus a callback might want to avoid closing over its instance, use its first parameter to reference the instance, and -have no other visible binding to the instance. +have no other binding through which the instance is reachable. @anchor{} @deffn Class @@ -340,7 +341,7 @@ Returns a list of strings --- the names of the ``children'' of A more direct interface to GIO's GFile operations is provided by the following 8 classes and 18 operations. -@pre +@verbatim make-gfile @@ -367,7 +368,7 @@ following 8 classes and 18 operations. gfile-append-to gfile-create gfile-replace -@end pre +@end verbatim @deffn Class Represents a @code{GFile} toolkit object. @@ -411,30 +412,82 @@ attribute's value is a GFileType member, e.g. @code{(C-enum other GIO constants, see your @file{gioenums.h} header file. Here are the 76 keys listed in the @file{gfileinfo.h} header: -standard::type, standard::is-hidden, standard::is-backup, -standard::is-symlink, standard::is-virtual, standard::name, -standard::display-name, standard::edit-name, standard::copy-name, -standard::description, standard::icon, standard::content-type, -standard::fast-content-type, standard::size, standard::allocated-size, -standard::symlink-target, standard::target-uri, standard::sort-order, -etag::value, id::file, id::filesystem, access::can-read, -access::can-write, access::can-execute, access::can-delete, -access::can-trash, access::can-rename, mountable::can-mount, -mountable::can-unmount, mountable::can-eject, mountable::unix-device, -mountable::unix-device-file, mountable::hal-udi, mountable::can-start, -mountable::can-start-degraded, mountable::can-stop, -mountable::start-stop-type, mountable::can-poll, -mountable::is-media-check-automatic, time::modified, -time::modified-usec, time::access, time::access-usec, time::changed, -time::changed-usec, time::created, time::created-usec, unix::device, -unix::inode, unix::mode, unix::nlink, unix::uid, unix::gid, -unix::rdev, unix::block-size, unix::blocks, unix::is-mountpoint, -dos::is-archive, dos::is-system, owner::user, owner::user-real, -owner::group, thumbnail::path, thumbnail::failed, preview::icon, -filesystem::size, filesystem::free, filesystem::used, -filesystem::type, filesystem::readonly, filesystem::use-preview, -gvfs::backend, selinux::context, trash::item-count, trash::orig-path, -trash::deletion-date. +@code{standard::type}, +@code{standard::is-hidden}, +@code{standard::is-backup}, +@code{standard::is-symlink}, +@code{standard::is-virtual}, +@code{standard::name}, +@code{standard::display-name}, +@code{standard::edit-name}, +@code{standard::copy-name}, +@code{standard::description}, +@code{standard::icon}, +@code{standard::content-type}, +@code{standard::fast-content-type}, +@code{standard::size}, +@code{standard::allocated-size}, +@code{standard::symlink-target}, +@code{standard::target-uri}, +@code{standard::sort-order}, +@code{etag::value}, +@code{id::file}, +@code{id::filesystem}, +@code{access::can-read}, +@code{access::can-write}, +@code{access::can-execute}, +@code{access::can-delete}, +@code{access::can-trash}, +@code{access::can-rename}, +@code{mountable::can-mount}, +@code{mountable::can-unmount}, +@code{mountable::can-eject}, +@code{mountable::unix-device}, +@code{mountable::unix-device-file}, +@code{mountable::hal-udi}, +@code{mountable::can-start}, +@code{mountable::can-start-degraded}, +@code{mountable::can-stop}, +@code{mountable::start-stop-type}, +@code{mountable::can-poll}, +@code{mountable::is-media-check-automatic}, +@code{time::modified}, +@code{time::modified-usec}, +@code{time::access}, +@code{time::access-usec}, +@code{time::changed}, +@code{time::changed-usec}, +@code{time::created}, +@code{time::created-usec}, +@code{unix::device}, +@code{unix::inode}, +@code{unix::mode}, +@code{unix::nlink}, +@code{unix::uid}, +@code{unix::gid}, +@code{unix::rdev}, +@code{unix::block-size}, +@code{unix::blocks}, +@code{unix::is-mountpoint}, +@code{dos::is-archive}, +@code{dos::is-system}, +@code{owner::user}, +@code{owner::user-real}, +@code{owner::group}, +@code{thumbnail::path}, +@code{thumbnail::failed}, +@code{preview::icon}, +@code{filesystem::size}, +@code{filesystem::free}, +@code{filesystem::used}, +@code{filesystem::type}, +@code{filesystem::readonly}, +@code{filesystem::use-preview}, +@code{gvfs::backend}, +@code{selinux::context}, +@code{trash::item-count}, +@code{trash::orig-path}, or +@code{trash::deletion-date}. @deffn Procedure gfile-info-list-attributes ginfo namespace Lists the gfile-info attribute keys. @@ -987,6 +1040,11 @@ Notify the toolkit of @var{widget}'s natural size. @var{Width} and initialized or changed. @end deffn +@deffn Procedure gtk-widget-get-size widget +Gets @var{widget}'s size allocation, a pair of integers: +@code{(width . height)}. +@end deffn + @subsection Gtk Widget Colors & Fonts @anchor{gtk-widget-parse-color} @@ -1480,46 +1538,102 @@ informed of any change to the widget's scroll position. The aliens will be NULL when the widget's scrollbars are removed. @end deffn -@node Fix Layout, Gdk Functions, Scheme Widget, API Reference -@section Fix Layout - -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 been implemented: line-ink, -rectangle-ink, arc-ink, simple-text-ink, image-ink and -box-ink. The last three are rendered by more modern toolkit -functions, from libraries like Pango and GdkPixbuf. +@section Fix Widget -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. +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. @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. +A direct subclass of scm-widget. A ScmWidget toolkit object. @end deffn @deffn Procedure fix-widget? object Type predicate. @end deffn +@deffn Procedure set-fix-widget-pointer-shape! widget shape +@var{Shape} can be any one of the following symbols: +@c another thing to check in doc/gtk/check.scm: +@code{x-cursor}, +@code{arrow}, +@code{based-arrow-down}, +@code{based-arrow-up}, +@code{boat}, +@code{bogosity}, +@code{bottom-left-corner}, +@code{bottom-right-corner}, +@code{bottom-side}, +@code{bottom-tee}, +@code{box-spiral}, +@code{center-ptr}, +@code{circle}, +@code{clock}, +@code{coffee-mug}, +@code{cross}, +@code{cross-reverse}, +@code{crosshair}, +@code{diamond-cross}, +@code{dot}, +@code{dotbox}, +@code{double-arrow}, +@code{draft-large}, +@code{draft-small}, +@code{draped-box}, +@code{exchange}, +@code{fleur}, +@code{gobbler}, +@code{gumby}, +@code{hand1}, +@code{hand2}, +@code{heart}, +@code{icon}, +@code{iron-cross}, +@code{left-ptr}, +@code{left-side}, +@code{left-tee}, +@code{leftbutton}, +@code{ll-angle}, +@code{lr-angle}, +@code{man}, +@code{middlebutton}, +@code{mouse}, +@code{pencil}, +@code{pirate}, +@code{plus}, +@code{question-arrow}, +@code{right-ptr}, +@code{right-side}, +@code{right-tee}, +@code{rightbutton}, +@code{rtl-logo}, +@code{sailboat}, +@code{sb-down-arrow}, +@code{sb-h-double-arrow}, +@code{sb-left-arrow}, +@code{sb-right-arrow}, +@code{sb-up-arrow}, +@code{sb-v-double-arrow}, +@code{shuttle}, +@code{sizing}, +@code{spider}, +@code{spraycan}, +@code{star}, +@code{target}, +@code{tcross}, +@code{top-left-arrow}, +@code{top-left-corner}, +@code{top-right-corner}, +@code{top-side}, +@code{top-tee}, +@code{trek}, +@code{ul-angle}, +@code{umbrella}, +@code{ur-angle}, +@code{watch}, or +@code{xterm}. +@end deffn + @deffn {Generic Procedure} fix-widget-new-geometry-callback widget This procedure is called when @var{widget} is resized. @end deffn @@ -1528,6 +1642,11 @@ This procedure is called when @var{widget} is resized. This procedure is called when @var{widget} is being realized. @end deffn +@deffn Procedure set-fix-widget-expose-handler! widget handler +Arranges to apply @var{handler} to @var{widget} and four fixnums: the +x and y coordinates, and width and height of the exposed area. +@end deffn + @deffn Procedure set-fix-widget-map-handler! widget handler Arranges to apply @var{handler} to @var{widget} when it is mapped. @end deffn @@ -1536,6 +1655,16 @@ Arranges to apply @var{handler} to @var{widget} when it is mapped. Arranges to apply @var{handler} to @var{widget} when it is unmapped. @end deffn +@deffn Procedure set-fix-widget-enter-notify-handler! widget handler +Arranges to apply @var{handler} to @var{widget} when the pointer +enters. +@end deffn + +@deffn Procedure set-fix-widget-leave-notify-handler! widget handler +Arranges to apply @var{handler} to @var{widget} when the pointer +leaves. +@end deffn + @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 @@ -1591,8 +1720,71 @@ coordinates of the pointer. See @bref{set-fix-widget-motion-handler!}. @end deffn +@section Fix Resizer + +Another simple fix-widget is a resizer similar to Gtk's GPaned. + +@deffn Class +A direct subclass of fix-widget. +@end deffn + +@deffn Procedure fix-resizer? object +Type predicate. +@end deffn + +@deffn {Generic Procedure} make-fix-resizer width height +A new fix-resizer with natural size @var{width} x @var{height}. +@end deffn + +@deffn {Generic Procedure} fix-resizer-before resizer +Returns the gtk-widget currently being resized as though to the right +or above @var{resizer}. +@end deffn + +@deffn {Generic Procedure} set-fix-resizer-before! resizer widget +Sets the gtk-widget being resized as though right/above @var{resizer}. +@end deffn + +@deffn {Generic Procedure} fix-resizer-after resizer +Returns the gtk-widget currently being resized as though to the left +or below @var{resizer}. +@end deffn + +@deffn {Generic Procedure} set-fix-resizer-after! resizer widget +Sets the gtk-widget being resized as though left/below @var{resizer}. +@end deffn + +@node Fix Layout, Gdk Functions, Scheme Widget, API Reference +@section Fix Layout + +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 been implemented: line-ink, +rectangle-ink, arc-ink, simple-text-ink, image-ink and +box-ink. The last three are rendered by more modern toolkit +functions, from libraries like Pango and GdkPixbuf. + +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. + @deffn Class -A direct subclass of fix-widget representing a reference to a ScmWidget. +A direct subclass of fix-widget. @end deffn @deffn Procedure fix-layout? object @@ -1618,6 +1810,11 @@ are all set in one fell swoop. If @var{layout} is already viewing multiple layouts that are on compatible screens. @end deffn +@deffn {Generic Procedure} fix-layout-view layout +The rectangle describing the area currently in view. It is shared +with @var{layout}; do not modify it. +@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. @@ -1635,6 +1832,12 @@ already displaying the view at that position, this procedure does nothing. Else it scrolls @var{layout} to the new position. @end deffn +@deffn Procedure fix-layout-scroll-nw! widget extent +Scroll just enough to view the entire @var{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. +@end deffn + @subsection Fix Drawing Fixnum-centric canvas, to which you can affix fix-ink spots. @@ -1643,6 +1846,10 @@ Fixnum-centric canvas, to which you can affix fix-ink spots. A direct subclass of instance. @end deffn +@deffn Procedure guarantee-fix-drawing object +Type guarantor. +@end deffn + @deffn Procedure make-fix-drawing A new fix-drawing. @end deffn @@ -2065,6 +2272,10 @@ The key name (character or symbol) associated with the Gdk A convenient procedure to call in an emergency. @end deffn +@deffn Procedure gtk-thread-running? +A convenient procedure to determine whether the toolkit is dead. +@end deffn + @deffn Procedure gtk-time-slice-window? #t if the time slice window is open, else #f. @end deffn diff --git a/src/gtk/fix-layout.scm b/src/gtk/fix-layout.scm index 7e5053c29..bb33c00c3 100644 --- a/src/gtk/fix-layout.scm +++ b/src/gtk/fix-layout.scm @@ -502,10 +502,6 @@ USA. (scroll widget x y)) (define (fix-layout-scroll-nw! widget extent) - ;; Scroll just enough to view the entire EXTENT (a fix-rect - ;; structure). 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. (let ((view (fix-layout-view widget))) (cond ((not (fix-rect-nominal? extent)) (error "Undefined extent:" extent)) diff --git a/src/gtk/gtk.pkg b/src/gtk/gtk.pkg index 8b47e81d7..b25249f58 100644 --- a/src/gtk/gtk.pkg +++ b/src/gtk/gtk.pkg @@ -137,6 +137,7 @@ USA. gtk-widget-parent gtk-widget-realized? gtk-widget-drawable? gtk-widget-has-focus? + gtk-widget-is-composited? gtk-widget-grab-focus gtk-widget-show gtk-widget-show-all @@ -222,7 +223,7 @@ USA. set-gtk-object-destroy-callback! gtk-object-destroy-callback) (export (gtk) - fix-widget? + fix-widget? fix-widget-new-geometry-callback fix-widget-realize-callback set-fix-widget-pointer-shape! set-fix-widget-expose-handler!