\input texinfo @c -*-Texinfo-*-
@comment %**start of header
@setfilename mit-scheme-gtk
-@set VERSION 0.2
+@set VERSION 0.3
@settitle Gtk @value{VERSION}
@comment %**end of header
+@ifhtml
@macro bref {name}
@ref{\name\,,@code{\name\}}
@end macro
+@end ifhtml
+@ifinfo
+@macro bref {name}
+\name\
+@end macro
+@end ifinfo
+@ifnothtml
+@ifnotinfo
+@macro bref {name}
+@code{\name\}
+@end macro
+@end ifnotinfo
+@end ifnothtml
@copying
This manual documents @acronym{Gtk} @value{VERSION}.
@node GObject, GIO, API Reference, API Reference
@section GObject
-An instance of @bref{<gobject>} represents a reference to a toolkit
+An instance of @code{<gobject>} represents a reference to a toolkit
object, typically one created by Scheme. The instance is ``live''
while Scheme holds the reference. @bref{gobject-unref!} kills it,
releasing Scheme's reference. Once dead to Scheme, the toolkit may
@end example
Note that @var{delete-callback} should reference @var{window} via
-parameter @emph{only}. See @bref{pinned-objects}.
+parameter @emph{only}. @xref{pinned-objects}.
@end deffn
@deffn Procedure g-signal-disconnect gobject name
@end example
@end deffn
-The @bref{gobject-get-property} and @bref{gobject-set-properties}
+The @code{gobject-get-property} and @code{gobject-set-properties}
procedures are an attempt to use Glib's introspection facilities to
automatically determine the type of a property's value and construct
an appropriate reflection of its value in Scheme. They have not been
@end deffn
There are many gfile attributes. Most have boolean or integer values.
-Some are enum constants. For example the @code{"standard::type"}
+Some are enum constants. For example the @code{standard::type}
attribute's value is a GFileType member, e.g. @code{(C-enum
"G_FILE_TYPE_UNKNOWN")}. For a complete list of GFileType members and
other GIO constants, see your @file{gioenums.h} header file.
@deffn Procedure gfile-info-list-attributes ginfo namespace
Lists the gfile-info attribute keys.
-@var{Namespace} should be e.g. @code{"standard"} or @code{"*"}.
+@var{Namespace} should be e.g. @code{standard} or @code{*}.
@end deffn
@deffn Procedure gfile-info-get-attribute-status ginfo key
alien, it is compared to the current entity tag of the file, and if
they differ an error is signaled. This generally means that the file
has been changed since you last read it. You can get the etag for a
-gfile from the @code{"etag::value"} attribute in
+gfile from the @code{etag::value} attribute in
its gfile-info. You can get the gfile-info for a gfile-input-stream
with @code{gfile-input-stream-query-info}. The etag for a
gfile-output-stream is available from
out, possibly changing @var{layout}'s dimensions.
@end deffn
+@deffn Procedure pango-layout-set-markup layout markup
+Sets @var{layout}'s text to @var{markup}, a simplified XML string.
+
+@var{Markup} is XML with the following simplifications.
+
+@itemize @bullet
+@item
+Only UTF-8 encoding is allowed.
+@item
+No user-defined entities.
+@item
+Processing instructions, comments and the doctype declaration are
+parsed but not interpreted in any way.
+@item
+No DTD nor validation.
+@end itemize
+
+The markup format does support:
+
+@itemize @bullet
+@item
+Elements
+@item
+Attributes
+@item
+5 standard entities: @code{& < > " '}
+@item
+Character references
+@item
+Sections marked as CDATA
+@end itemize
+
+Valid elements are:
+
+@table @code
+@item b
+Bold
+@item big
+Makes font relatively larger, equivalent to @code{<span size="larger">}.
+@item i
+Italic
+@item s
+Strikethrough
+@item sub
+Subscript
+@item sup
+Superscript
+@item small
+Makes font relatively smaller. Equivalent to @code{<span size="smaller">}.
+@item tt
+Monospace font
+@item u
+Underline
+@item span
+General form with many attributes listed below.
+@end table
+
+Valid attributes for the span element are:
+
+@table @code
+
+@item font, font_desc
+A font description string acceptable to
+@bref{pango-font-description-from-string} (e.g. @code{Sans Italic
+12}). Note that any other span attributes will override this
+description. If you have @code{font="Sans Italic"} and also
+@code{style="normal"}, you will get Sans normal, not italic.
+
+@item font_family, face
+A font family name.
+
+@item font_size, size
+Font size in 1024ths of a point, or one of the absolute sizes
+@code{xx-small}, @code{x-small}, @code{small}, @code{medium},
+@code{large}, @code{x-large}, @code{xx-large}, or one of the relative
+sizes @code{smaller} or @code{larger}. If you want to specify a
+absolute size, it is usually easier to take advantage of the ability
+to specify a partial font description using @code{font}; you can use
+@code{font="12.5"} rather than @code{size="12800"}.
+
+@item font_style, style
+One of @code{normal}, @code{oblique}, @code{italic}.
+
+@item font_weight, weight
+One of @code{ultralight}, @code{light}, @code{normal}, @code{bold},
+@code{ultrabold}, @code{heavy}, or a numeric weight.
+
+@item font_variant, variant
+One of @code{normal} or @code{smallcaps}.
+
+@item font_stretch, stretch
+One of @code{ultracondensed}, @code{extracondensed}, @code{condensed},
+@code{semicondensed}, @code{normal}, @code{semiexpanded},
+@code{expanded}, @code{extraexpanded}, @code{ultraexpanded}.
+
+@item foreground, fgcolor, color
+An RGB color specification such as @code{#00FF00} or a color name such
+as @code{red}.
+
+@item background, bgcolor
+An RGB color specification such as @code{#00FF00} or a color name such
+as @code{red}.
+
+@item underline
+One of @code{none}, @code{single}, @code{double}, @code{low},
+@code{error}.
+
+@item underline_color
+The color of underlines; an RGB color specification such as
+@code{#00FF00} or a color name such as @code{red}.
+
+@item rise
+Vertical displacement, in 10000ths of an em. Can be negative for
+subscript, positive for superscript.
+
+@item strikethrough
+@code{true} or @code{false} whether to strike through the text.
+
+@item strikethrough_color
+The color of strikethrough lines; an RGB color specification such as
+@code{#00FF00} or a color name such as @code{red}
+
+@item fallback
+@code{True} or @code{false} whether to enable fallback. If disabled,
+then characters will only be used from the closest matching font on
+the system. No fallback will be done to other fonts on the system that
+might contain the characters in the text. Fallback is enabled by
+default. Most applications should not disable fallback.
+
+@item lang
+A language code (e.g. @code{en} for english), indicating the text
+language.
+
+@item letter_spacing
+Inter-letter spacing in 1024ths of a point.
+
+@item gravity
+One of @code{south}, @code{east}, @code{north}, @code{west}, @code{auto}.
+
+@item gravity_hint
+One of @code{natural}, @code{strong}, @code{line}.
+@end table
+
+@end deffn
+
@deffn Procedure pango-layout-get-pixel-extents layout receiver
Applies @var{receiver} to @var{layout}'s width and height.
@end deffn
@deffn Procedure pango-font-description-from-string string
A new PangoFontDescription alien. If it is garbage collected, the
toolkit object will be freed with @bref{pango-font-description-free}.
+
+@var{String} can have three whitespace separated parts:
+@code{family-list style-options size}.
+
+@code{Family-list} can be a comma separated list of families optionally
+terminated by a comma.
+
+@code{Style-options} can be a whitespace separated list of
+words where each word describes one of style, variant, weight,
+stretch, or gravity.
+
+@code{Size} can be a decimal number (size in points) or an absolute
+size followed by the unit modifier @code{px}.
+
+Any one of these parts may be absent. If @code{family-list} is absent,
+then the family name field of the resulting font description will be
+empty. If @code{style-options} is missing, then all style options
+will be set to default values. If @code{size} is missing, the size in
+the resulting font description will be set to 0.
@end deffn
@deffn Procedure pango-font-description-to-string font
A gtk-widget is a gobject that can be "destroyed". Each instance is
connected to the "destroy" signal of its GtkWidget. The callback
-@bref{gobject-unref!}'s the instance, allowing the toolkit to finalize
-and dispose of the widget.
+applies @bref{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 @bref{gobject-unref!} and
@deffn Procedure set-gtk-widget-event-callback! widget callback
Arrange for @var{callback} to be applied to @var{widget} and an alien
-GdkEvent whenever the widget receives an @code{"event"} signal.
+GdkEvent whenever the widget receives an @code{event} signal.
@var{Callback} should return @code{#t} to stop emission of more
-specific signals like @code{"focus-in-event"} and @code{"focus"}. It
+specific signals like @code{focus-in-event} and @code{focus}. It
must return either @code{#t} or @code{#f} else a warning is issued.
Do @emph{not} capture @var{widget} in @var{callback}'s closure, else
it cannot be GCed.
@end deffn
@deffn Procedure gtk-window-type window
-The symbol @code{toplevel}, unless @var{window} is a popup. See
-@bref{gtk-window-new}.
+The symbol @code{toplevel}, unless @var{window} is a popup.
+@xref{gtk-window-new}.
@end deffn
@anchor{gtk-window-set-geometry-hints}
@deffn Procedure gtk-window-set-opacity window opacity
Request a partially transparent @var{window}. @var{Opacity} can vary
from 0.0 (fully transparent) to 1.0 (fully opaque). On X11 the
-request has no effect without a compositing manager. See
-@bref{gtk-widget-is-composited?}. Note that setting a window's
+request has no effect without a compositing manager.
+@xref{gtk-widget-is-composited?}.
+Note that setting a window's
opacity after the window has been shown causes it to flicker once on
Windows.
@end deffn
Returns @code{#f} if @var{string} is not a standard X geometry string.
Otherwise returns @code{#t} and sets @var{window}'s user-requested size
and/or position. An X geometry string is something like
-@code{"-0+0"}, meaning ``upper right hand corner''. The X manpage
+@code{-0+0}, meaning ``upper right hand corner''. The X manpage
contains the full details. Note that for this procedure to work
correctly (so that @var{window} is created at its final size and
position --- no moving, resizing, etc.) the window should have any
geometry hints already set, and a final size already determined by
-``showing'' the toplevel widget. See
-@bref{gtk-window-set-geometry-hints}.
+``showing'' the toplevel widget.
+@xref{gtk-window-set-geometry-hints}.
@end deffn
@deffn Procedure gtk-window-resize window width height
Resizes @var{window} as if the user had done so, obeying geometry
constraints. @var{width} and @var{height} should be positive fixnums.
When applied before @var{window} is shown for the first time, this
-procedure overrides @var{window}'s default size. See
-@bref{gtk-window-set-default-size}.
+procedure overrides @var{window}'s default size.
+@xref{gtk-window-set-default-size}.
These come from geometry hints, and a default constraint that windows
not be sized smaller than their natural size.
The difference between paned windows and paned viewports can be
observed by substituting @code{gtk-paned-new} and
-@code{gtk-paned-view-new} in the fix layout demo. See @bref{Fix
-Demo}.
+@code{gtk-paned-view-new} in the fix layout demo.
+@xref{Fix Demo}.
@end deffn
@deffn Procedure gtk-paned-view? object
The difference between a scrolled window and a scrolled viewport can
be observed by substituting @code{gtk-scrolled-view-new} and
-@code{gtk-scrolled-window-new} in the fix layout demo. See @bref{Fix
-Demo}.
+@code{gtk-scrolled-window-new} in the fix layout demo.
+@xref{Fix Demo}.
@end deffn
@deffn Procedure gtk-scrolled-view? object
GdkWindow, and dispatches events received on it.
@anchor{event-handler-note} Note that the event handlers are run by
-the generic @code{"event"} signal, and can return @code{#t} to stop
-emission of more specific signals like @code{"focus-in-event"} and
-@code{"focus"}. They must return either @code{#t} or @code{#f} else a
+the generic @code{event} signal, and can return @code{#t} to stop
+emission of more specific signals like @code{focus-in-event} and
+@code{focus}. They must return either @code{#t} or @code{#f} else a
warning is issued.
@deffn Class <fix-widget>
@deffn Procedure set-fix-widget-map-handler! widget handler
Arranges to apply @var{handler} to @var{widget} when it is mapped.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@deffn Procedure set-fix-widget-unmap-handler! widget handler
Arranges to apply @var{handler} to @var{widget} when it is unmapped.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@deffn Procedure set-fix-widget-enter-notify-handler! widget handler
Arranges to apply @var{handler} to @var{widget} when the pointer
enters.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@deffn Procedure set-fix-widget-leave-notify-handler! widget handler
Arranges to apply @var{handler} to @var{widget} when the pointer
leaves.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@deffn Procedure set-fix-widget-focus-change-handler! widget handler
when it receives a focus change event. The boolean is @code{#t} if
@var{widget} is now in focus.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@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}.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@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.
+and a bitmap of char-bits.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@anchor{set-fix-widget-motion-handler!}
@code{meta} and
@code{release}.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@deffn Procedure set-fix-widget-button-handler! widget type handler
@code{press}, @code{release}, @code{double-press} or
@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-widget-motion-handler!}.
+coordinates of the pointer.
+@xref{set-fix-widget-motion-handler!}.
@var{handler} must return @code{#t} or @code{#f}.
-See @bref{event-handler-note}.
+@xref{event-handler-note}.
@end deffn
@node Fix Layout, Gdk Functions, Scheme Widget, API Reference
@deffn Procedure set-simple-text-ink-text! ink widget string
Sets @var{ink}'s text to @var{string}, using @var{widget}'s font and
direction. It is assumed @var{widget} is compatible with all widgets
-displaying @var{ink}. See @bref{set-fix-layout-drawing!}.
+displaying @var{ink}.
+@xref{set-fix-layout-drawing!}.
@end deffn
@deffn Procedure simple-text-ink-font text
@deffn Procedure set-simple-text-ink-font! text font
Sets @var{text}'s pango layout's font to @var{font}. @var{Font}
should be a PangoFontDescription, or a string acceptable to
-@bref{pango-font-description-from-string} (e.g. @code{"courier 12"}).
+@bref{pango-font-description-from-string} (e.g. @code{courier 12}).
@end deffn
@subsection Image Ink
projects / mit-scheme.git / commitdiff