From 9469f911b866166ad56e48c2649590e48f68f632 Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Mon, 11 Feb 2013 16:49:10 -0700 Subject: [PATCH] gtk: Document pango-layout-set-markup. Fix many @brefs. Define @bref{}'s as actual references ONLY in the HTML version, where they can be hyperlinks to a binding's documentation. Otherwise they are just hyphenated names in @code style, except in Info. In Info, even single-quotes around these names is really too much. --- doc/gtk/gtk.texinfo | 264 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 221 insertions(+), 43 deletions(-) diff --git a/doc/gtk/gtk.texinfo b/doc/gtk/gtk.texinfo index b5cfc6bd6..15b56d5d3 100644 --- a/doc/gtk/gtk.texinfo +++ b/doc/gtk/gtk.texinfo @@ -1,13 +1,27 @@ \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}. @@ -224,7 +238,7 @@ the Gtk interface. @node GObject, GIO, API Reference, API Reference @section GObject -An instance of @bref{} represents a reference to a toolkit +An instance of @code{} 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 @@ -279,7 +293,7 @@ trampoline, as in this example: @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 @@ -289,7 +303,7 @@ parameter @emph{only}. See @bref{pinned-objects}. @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 @@ -411,7 +425,7 @@ information about the symlink itself will be returned. @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. @@ -496,7 +510,7 @@ Here are the 76 keys listed in the @file{gfileinfo.h} header: @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 @@ -608,7 +622,7 @@ on the target filesystem. 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 @@ -766,6 +780,151 @@ Sets @var{layout}'s text to @var{string}. The new text will be laid 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{}. +@item i +Italic +@item s +Strikethrough +@item sub +Subscript +@item sup +Superscript +@item small +Makes font relatively smaller. Equivalent to @code{}. +@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 @@ -780,6 +939,25 @@ character at @var{index}. @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 @@ -912,8 +1090,8 @@ is currently visible. 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 @@ -974,9 +1152,9 @@ context clipped to the area to be re-drawn. @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. @@ -1238,8 +1416,8 @@ be managed by the window manager, like a tooltip or popup menu window. @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} @@ -1284,8 +1462,9 @@ include the application name and current document. @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 @@ -1310,21 +1489,21 @@ Applies @var{receiver} to @var{window}'s default width and height. 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. @@ -1610,8 +1789,8 @@ both children. 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 @@ -1673,8 +1852,8 @@ and interferes with resizing. 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 @@ -1735,9 +1914,9 @@ specialized methods will draw. It allocates, moves and resizes the 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 @@ -1841,27 +2020,27 @@ This procedure is called when @var{widget} is being realized. @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 @@ -1869,24 +2048,22 @@ Arranges to apply @var{handler} to @var{widget} and a boolean value 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!} @@ -1914,7 +2091,7 @@ symbols @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 @@ -1923,10 +2100,10 @@ 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{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 @@ -2354,7 +2531,8 @@ A new simple-text-ink. @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 @@ -2364,7 +2542,7 @@ displaying @var{ink}. See @bref{set-fix-layout-drawing!}. @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 -- 2.25.1