<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<TITLE>Programming in XPCE/Prolog: Section 11.10</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="httpd.html">
<LINK REL=next HREF="debugging.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/
dd.defbody
{ margin-bottom: 1em;
}
dt.pubdef
{ background-color: #c5e1ff;
}
pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}
div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}
div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}
div.author
{ text-align: center;
font-style: italic;
}
div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}
div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}
div.toc-h1
{ font-size: 200%;
font-weight: bold;
}
div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}
div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}
div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}
span.sec-nr
{
}
span.sec-title
{
}
span.pred-ext
{ font-weight: bold;
}
/* Footnotes */
sup.fn { color: blue; text-decoration: underline; }
span.fn-text: { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="httpd.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="debugging.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>
<H2><A NAME="sec:11.10"><SPAN class="sec-nr">11.10</SPAN> <SPAN class="sec-title">Document
rendering primitives</SPAN></A></H2>
<A NAME="sec:docrender"></A>
<P>Dynamic HTML has enabled the presentation of user interfaces as
documents the user can interact with. None of the traditional GUI
components can deal with the mixture of properly formatted text with
(interactive) graphics. <font size=-1>XPCE</font> provides support using
a set of primitive classes that realise a box-model based on TeX . This
basic model is enhanced using a Prolog library providing HTML-based
primitives. First we will introduce the basics.
<P>
<UL>
<LI><I>Class <A class="" href="summary.html#class:parbox">parbox</A></I><BR>
This is the central class of the document-rendering support. It is a
subclass of <A class="" href="summary.html#class:device">device</A>,
placing <A class="" href="summary.html#class:hbox">hbox</A> objects as
words within a paragraph. Parbox devices have a <B><CODE><-></CODE>width</B>,
realise alignment and adjustment and can place text around <EM>floating</EM>
objects.
<P>
<LI><I>Class <A class="" href="summary.html#class:hbox">hbox</A></I><BR>
This is an abstract super-class for <A class="" href="summary.html#class:tbox">tbox</A>
and <A class="" href="summary.html#class:grbox">grbox</A> that allow for
text and graphics within a <A class="" href="summary.html#class:parbox">parbox</A>.
<P>
<LI><I>Class <A class="" href="summary.html#class:tbox">tbox</A></I><BR>
Represent text in a <A class="" href="summary.html#class:parbox">parbox</A>.
Normally, a <A class="" href="summary.html#class:tbox">tbox</A>
represents a word.
<P>
<LI><I>Class <A class="" href="summary.html#class:grbox">grbox</A></I><BR>
Embeds any <A class="" href="summary.html#class:graphical">graphical</A>
object in a <A class="" href="summary.html#class:parbox">parbox</A>. The
<A class="" href="summary.html#class:grbox">grbox</A> negotiates with
the <A class="" href="summary.html#class:parbox">parbox</A> on the
placement and then places the graphical on the <A class="" href="summary.html#class:parbox">parbox</A>
using normal behaviour of <A class="" href="summary.html#class:device">device</A>.
<P>
<LI><I>Class <A class="" href="summary.html#class:lbox">lbox</A></I><BR>
This is another subclass of <A class="" href="summary.html#class:device">device</A>
that realises LaTeX -like list-environment. The class deals with
placement of labels and text for the items. Both label and item are
arbitrary graphical objects. Items are normally instances of <A class="" href="summary.html#class:parbox">parbox</A>.
<P>
<LI><I>Class <A class="" href="summary.html#class:rubber">rubber</A></I><BR>
This is a data object containing information on the
<EM>stretchability</EM> of boxes. Rubber object are used to distribute
space horizontally as well as to determine the location of line-breaks.
A space in a <A class="" href="summary.html#class:parbox">parbox</A> is
realised using a <A class="" href="summary.html#class:hbox">hbox</A>
whose natrual width is the width of a space in the current <A class="" href="summary.html#class:font">font</A>
that can shrink a little and expand a bit easier.
</UL>
<P>Before discussing the library we show a small example using the
primitives directly.
<PRE class="code">
parbox :-
send(new(W, window), open),
send(W, display, new(P, parbox(W?width)), point(10,10)),
send(W, resize_message, message(P, width, @arg2?width-20)),
send(P, alignment, justify),
send_list(P,
[ append(grbox(box(40,40), left)),
cdata('This is the central class of the '),
cdata('document-rendering support. It is '),
cdata('a subclass of '),
cdata('device', style(underline := @on)),
cdata(', placing '),
cdata('hbox', style(underline := @on)),
cdata(' objects as words within a paragraph. '),
cdata('Parbox devices have a <->width, realise '),
cdata('alignment and adjustment and can place text '),
cdata('around '),
cdata('floating ', style(font := italic)),
cdata(' objects.')
]).</PRE>
<P><A NAME="fig:parbox1"></A>
<CENTER>
<IMG SRC="parbox1.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 29 : </B>A parbox floating text around a box</TABLE>
<P>In line 4, we forward changes to the width of the window to the
<A class="" href="summary.html#class:parbox">parbox</A> to force
reformatting the text if the width of the window changes. Line 6 asks
for a straight right-margin. Line 8 appends a <A class="" href="summary.html#class:box">box</A>
that is left aligned, the text floating around it. The remaining lines
append text. The method <A NAME="idx:parboxsendcdata:546"></A>`<B>parbox<CODE>-></CODE>cdata</B>'
breaks the argument into words and adds instances of <A class="" href="summary.html#class:tbox">tbox</A>
for each word, separated by instances of <A class="" href="summary.html#class:hbox">hbox</A>
with appropriate
<A class="" href="summary.html#class:rubber">rubber</A> for each
sequence of white-space, doing much the same as an HTML browser
processing <CODE>CDATA</CODE> text.
<P>Defining a document from Prolog text using these primitives is not
attractive. This is the motivation for using a library.
<H3><A NAME="sec:11.10.1"><SPAN class="sec-nr">11.10.1</SPAN> <SPAN class="sec-title">The
rendering library</SPAN></A></H3>
<A NAME="sec:docemit"></A>
<P>The directory <CODE>\bnfmeta{pcehome}/prolog/lib/doc</CODE> contains
the document-rendering library, providing HTML-oriented primitives for
document rendering. The translation process can be extended by defining
predicates for two <EM>multifile</EM> predicates.
<P>The central library is <CODE>library(doc/emit)</CODE>. This library
defines the predicate <A NAME="idx:emit3:547"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>:
<DL>
<DT class="pubdef"><A NAME="emit/3"><STRONG>emit</STRONG>(<VAR>+ListOfTerm,
+PBox, +Mode</VAR>)</A></DT>
<DD class="defbody">
This predicate takes a list of processing instructions and applies these
on <VAR>PBox</VAR>, an instance of class <B>pbox</B>, a subclass of
<A class="" href="summary.html#class:parbox">parbox</A> supporting this
library. <VAR>Mode</VAR> provides an instance of <B>doc_mode</B>, a
data-object holding style-information.
<P><VAR>ListOfTerm</VAR> consists of the following instructions:
<P>
<UL>
<LI><I><<VAR>Atomic</VAR>></I><BR>
Atomic data is added as text to the output. If <A NAME="idx:docmodegetspacemode:548"></A>`<B>doc_mode<CODE><-</CODE>space_mode</B>'
equals <CODE>preserve</CODE>, spaces are preserved. Otherwise space is
canonised, smashing multiple consecutive banks into a single (rubber)
space.
<P>
<LI><I><CODE>\</CODE>Action</I><BR>
Execute an <VAR>Action</VAR>. Actions are like TeX commands, which is
why we use the backslash. The built-in actions and the definition of new
actions is discussed in <A class="sec" href="docrender.html">section
11.10.3.2</A>.
<P>
<LI><I><A NAME="idx:Object:549"></A><B>@Object</B></I><BR>
<font size=-1>XPCE</font> objects are simply appended to the <B>pbox</B>.
This can be used to append self-created objects or use one of the
predefined layout objects defined in <A class="sec" href="docrender.html">section
11.10.2</A>.
</UL>
<P>Before handed to the above, <A NAME="idx:emit3:550"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
calls the multifile predicate doc:emit/3 passing the whole list as you
can see from the definition below. This allows the user-hook to process
sequences of instructions.
<PRE class="code">
emit(Term, PB, Mode) :-
doc:emit(Term, PB, Mode), !.
</PRE>
<P></DD>
</DL>
<H3><A NAME="sec:11.10.2"><SPAN class="sec-nr">11.10.2</SPAN> <SPAN class="sec-title">Predefined
objects</SPAN></A></H3>
<A NAME="sec:docobjects"></A>
<P>The file <CODE>library(doc/objects)</CODE> defines a number of
globally named instances of the box classes. Appending these objects is
like executing an action. These objects are:
<P>
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><A NAME="idx:br:551"></A><B>@br</B> </TD><TD>Nul-dimension <A class="" href="summary.html#class:hbox">hbox</A>
with rubber to force a line-break. </TD></TR>
<TR VALIGN=top><TD><A NAME="idx:nbsp:552"></A><B>@nbsp</B> </TD><TD>Non-breaking
space. </TD></TR>
<TR VALIGN=top><TD><A NAME="idx:hfill:553"></A><B>@hfill</B> </TD><TD>Rubber <A class="" href="summary.html#class:hbox">hbox</A>
for alignment and centering. </TD></TR>
<TR VALIGN=top><TD><A NAME="idx:spacerubber:554"></A><B>@space_rubber</B> </TD><TD>Rubber
used for <A class="" href="summary.html#class:hbox">hbox</A> objects
representing a space. This rubber allows for a line-break. </TD></TR>
<TR VALIGN=top><TD><A NAME="idx:h:555"></A><B>@h</B><<VAR>n</VAR>>_above</TD><TD>Space
above HTML section-headers. </TD></TR>
<TR VALIGN=top><TD><A NAME="idx:h:556"></A><B>@h</B><<VAR>n</VAR>>_below</TD><TD>Space
below HTML section-headers. </TD></TR>
</TABLE>
</CENTER>
<H3><A NAME="sec:11.10.3"><SPAN class="sec-nr">11.10.3</SPAN> <SPAN class="sec-title">Class
and method reference</SPAN></A></H3>
<A NAME="sec:docreference"></A>
<P>This section provides a partial reference to the classes and methods
defining the document-rendering library. For full information, please
use the <B>ClassBrowser</B> and check the source-code.
<DL>
<DT><STRONG>pbox ->show:</STRONG> <VAR>Content:prolog,
Mode:[doc_mode]</VAR></DT>
<DD class="defbody">
Calls <A NAME="idx:emit3:557"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
using <VAR>Content</VAR> and <VAR>Mode</VAR>. If mode is omitted, a
default mode object is created.</DD>
<DT><STRONG>pbox ->event:</STRONG> <VAR>Event:event</VAR></DT>
<DD class="defbody">
Handles clicking a button or footnote and showing <EM>balloons</EM> from
buttons after trying to pass the event to one of the embedded
graphicals.</DD>
<DT><STRONG>pbox <-anchor:</STRONG> <VAR>Name</VAR></DT>
<DD class="defbody">
tuple(Box, Index) Return the <VAR>Box</VAR> and index thereof in the <A NAME="idx:parboxgetcontent:558"></A>`<B>parbox<CODE><-</CODE>content</B>'
vector that starts the named anchor (see <A class="sec" href="docrender.html">section
11.10.3.2</A>.</DD>
<DT><STRONG>doc_mode ->initialise:</STRONG> <VAR></VAR></DT>
<DD class="defbody">
Creates a default document-rendering mode. This mode has the following
properties:
<P>
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><B>vfont</B></TD><TD>new(vfont)</TD><TD>The <EM>virtual</EM>
font for text </TD></TR>
<TR VALIGN=top><TD><B>link_colour</B></TD><TD>dark_green</TD><TD>Text-colour
while rendering buttons </TD></TR>
<TR VALIGN=top><TD><B>parsep</B></TD><TD>hbox(0,8)</TD><TD>Skip 8 pixels
between paragraphs </TD></TR>
<TR VALIGN=top><TD><B>parindent</B></TD><TD>hbox(0,0)</TD><TD>Do not
indent paragraphs </TD></TR>
<TR VALIGN=top><TD><B>space_mode</B></TD><TD>canonical</TD><TD>Collapse
spaces </TD></TR>
<TR VALIGN=top><TD><B>alignment</B></TD><TD>justify</TD><TD>Make a
right-margin </TD></TR>
<TR VALIGN=top><TD><B>base_url</B></TD><TD>''</TD><TD>URL for HTML
hyper-links </TD></TR>
</TABLE>
</CENTER>
</DD>
<DT><STRONG>doc_mode ->set_font:</STRONG> <VAR>Att:name, Value:any</VAR></DT>
<DD class="defbody">
Set an attribute of <B><CODE><-</CODE>vfont</B> and update <B><CODE><-</CODE>style</B>
and <B><CODE><-</CODE>space</B> to reflect the new font-settings.</DD>
<DT><STRONG>doc_mode ->colour:</STRONG> <VAR>Colour</VAR></DT>
<DD class="defbody">
Set the colour of <B><CODE><-</CODE>style</B>.</DD>
<DT><STRONG>doc_mode ->underline:</STRONG> <VAR>Bool</VAR></DT>
<DD class="defbody">
Set underline mode in <B><CODE><-</CODE>style</B>.
</DD>
</DL>
<H4><A NAME="sec:11.10.3.1"><SPAN class="sec-nr">11.10.3.1</SPAN> <SPAN class="sec-title">Class <B>vfont</B></SPAN></A></H4>
<P>The class <B>vfont</B> realises <EM>virtual</EM> fonts, Microsoft
also calls these <EM>logical</EM> fonts. <font size=-1>XPCE</font> <A class="" href="summary.html#class:font">font</A>
objects are read-only. When dealing with incremental font manipulation
it is necessary to have a font that can be manipulated. Therefore,
<B>vfont</B> defines a number of slots to represent the font attributes
regardless of the fonts existence. At any time the user can request the
best matching font using <A NAME="idx:vfontgetfont:559"></A>`<B>vfont<CODE><-</CODE>font</B>'.
The mapping between virtual font attributes and physical fonts can be
programmed by adding clauses to the multifile predicate
vfont:font_map/7. This class is defined in
<CODE>library(doc/vfont)</CODE> where you find further programming
details.
<H4><A NAME="sec:11.10.3.2"><SPAN class="sec-nr">11.10.3.2</SPAN> <SPAN class="sec-title">Rendering
actions</SPAN></A></H4>
<A NAME="sec:docactions"></A>
<P>The action subsystem processes actions (<CODE>\</CODE>Action) from <A NAME="idx:emit3:560"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>,
providing a hook for adding new actions. Before doing anything else, the
hook doc:action/3 is called:
<DL>
<DT class="pubdef"><A NAME="doc:action/3"><STRONG>doc:action</STRONG>(<VAR>+Action,
+PBox, +Mode</VAR>)</A></DT>
<DD class="defbody">
Execute <VAR>Action</VAR>. The actions are passed from <A NAME="idx:emit3:561"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
after stripping the backslash. If this hook succeeds the action is
considered handled.
</DD>
</DL>
<P>The built-in actions are:
<DL>
<DT><STRONG>ignorespaces</STRONG></DT>
<DD class="defbody">
Tells <A NAME="idx:emit3:562"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
eat all input until the first action or non-blank character.</DD>
<DT><STRONG>space</STRONG>(<VAR>SpaceMode</VAR>)</DT>
<DD class="defbody">
Tells <A NAME="idx:emit3:563"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
to <CODE>preserve</CODE> white-space or render it
<CODE>canonical</CODE>. Default is <B>canonical</B>.</DD>
<DT><STRONG>pre</STRONG>(<VAR>Text</VAR>)</DT>
<DD class="defbody">
Add verbatim text.</DD>
<DT><STRONG>par</STRONG></DT>
<DD class="defbody">
Start a new paragraph. This is the action-sequence <CODE>parskip</CODE>,
followed by <CODE>parsep</CODE>.</DD>
<DT><STRONG>parskip</STRONG></DT>
<DD class="defbody">
Inserts <B><CODE><-</CODE>parsep</B> from the current mode,
surrounded by two line-breaks (<A NAME="idx:br:564"></A><B>@br</B>).</DD>
<DT><STRONG>parindent</STRONG></DT>
<DD class="defbody">
Insert the <B><CODE><-</CODE>parindent</B> from the current mode.</DD>
<DT><STRONG>group</STRONG>(<VAR>Group</VAR>)</DT>
<DD class="defbody">
Use <A NAME="idx:emit3:565"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
on <VAR>Group</VAR> on a <B><CODE><-</CODE>clone</B> of the <B>doc_mode</B>
object. This is essentially the same as a TeX group, scoping changes to
the mode such as font-changes, etc.</DD>
<DT><STRONG>setfont</STRONG>(<VAR>Attribute, Value</VAR>)</DT>
<DD class="defbody">
Set an attribute of the font. Fonts are maintained using the Prolog
defined class <B>vfont</B> (<EM>virtual</EM> font) that allows for
independent changes to font attributes. When text needs to be rendered,
a close real font is mounted. Defined attributes are:
<CODE>family</CODE>, <CODE>encoding</CODE>, <CODE>slant</CODE>, <CODE>weight</CODE>,
<CODE>fixed</CODE> and <CODE>size</CODE>. See
<CODE>\bnfmeta{pcehome}/prolog/lib/doc/vfont.pl</CODE> for details.</DD>
<DT><STRONG>ul</STRONG></DT>
<DD class="defbody">
Switch on underlining. Normally this should be inside a group to limit
the scope.</DD>
<DT><STRONG>colour</STRONG>(<VAR>Colour</VAR>)</DT>
<DD class="defbody">
Set the text-colour.</DD>
<DT><STRONG>list</STRONG>(<VAR>Options, Content</VAR>)</DT>
<DD class="defbody">
Produce a list-environment. The option <CODE>class(Class)</CODE> defines
the subclass of <A class="" href="summary.html#class:lbox">lbox</A> used
to instantiate, default
<B>bullet_list</B>. The <VAR>Content</VAR> is passed to <A NAME="idx:emit3:566"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>,
using the created list-object as 2nd argument.
<P>When using a <B>bullet_list</B> or <B>enum_list</B> <VAR>Content</VAR>
must translated into a sequence of <CODE>li</CODE> commands. Using a
<B>definition_list</B>, a sequence of <CODE>dt</CODE> and <CODE>dd</CODE>
commands is expected.</DD>
<DT><STRONG>li</STRONG>(<VAR>Content</VAR>)</DT>
<DD class="defbody">
If we are processing a <B>bullet_list</B> or <B>enum_list</B>, start a
new item using `<B><CODE><-</CODE>make_item</B>', then emit <VAR>Content</VAR>
to the new item.</DD>
<DT><STRONG>dt</STRONG>(<VAR>ItemTitle</VAR>)</DT>
<DD class="defbody">
If we are processing a <B>definition_list</B>, create a new label from
<VAR>ItemTitle</VAR>.</DD>
<DT><STRONG>dd</STRONG>(<VAR>ItemContent</VAR>)</DT>
<DD class="defbody">
Create a <B>pbox</B> for the item body and emit <VAR>ItemContent</VAR>
to it.</DD>
<DT><STRONG>title</STRONG>(<VAR>Title</VAR>)</DT>
<DD class="defbody">
Get the <B><CODE><-</CODE>frame</B> of the <B>pbox</B> and send it
the given title using
<A NAME="idx:framesendlabel:567"></A>`<B>frame<CODE>-></CODE>label</B>'.</DD>
<DT><STRONG>body</STRONG>(<VAR>Options</VAR>)</DT>
<DD class="defbody">
Apply options to the window as a whole. Defines options are
<CODE>bgcolour(Colour)</CODE>, <CODE>background(Image)</CODE> and
<CODE>text(Colour)</CODE>.</DD>
<DT><STRONG>button</STRONG>(<VAR>Message, Content, Balloon</VAR>)</DT>
<DD class="defbody">
Add an active area (hyper-link) to the document. When depressed,
<VAR>Message</VAR> is executed. When hoovering, <VAR>Balloon</VAR> is
reported as status (see <A class="sec" href="report.html">section 10.7</A>). <VAR>Content</VAR>
is emitted inside a group after setting the default colour to <A NAME="idx:docmodegetlinkcolour:568"></A>`<B>doc_mode<CODE><-</CODE>link_colour</B>'
and underlining to <A NAME="idx:on:569"></A><B>@on</B>.</DD>
<DT><STRONG>anchor</STRONG>(<VAR>Label, Content</VAR>)</DT>
<DD class="defbody">
Label some content. This has no visual implications, but the the anchor
can be located using <A NAME="idx:pboxgetanchor:570"></A>`<B>pbox<CODE><-</CODE>anchor</B>'.</DD>
<DT><STRONG>parbox</STRONG>(<VAR>Content, Options</VAR>)</DT>
<DD class="defbody">
Add a sub-parbox. Defined options are:
<DL>
<DT><STRONG>width</STRONG>(<VAR>Width</VAR>)</DT>
<DD class="defbody">
Define the width of the sub-box.
</DD>
<DT><STRONG>rubber</STRONG>(<VAR>Rubber</VAR>)</DT>
<DD class="defbody">
Define the shrink- and stretchability of the sub-box.
</DD>
<DT><STRONG>align</STRONG>(<VAR>Alignment</VAR>)</DT>
<DD class="defbody">
Define text-adjustment (<CODE>left</CODE>,<CODE>center</CODE>,<CODE>right</CODE>,<CODE>justify</CODE>)
within the box.
</DD>
<DT><STRONG>valign</STRONG>(<VAR>VAlign</VAR>)</DT>
<DD class="defbody">
Define the vertical alignment of the box (<CODE>top</CODE>, <CODE>center</CODE>,
<CODE>bottom</CODE>.</DD>
<DT><STRONG>auto_crop</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
If <A NAME="idx:on:571"></A><B>@on</B>, tell the <B>pbox</B> its <B><CODE><-</CODE>area</B>
is determined by the content rather than the specified width. Text may
be formatted left-to-write without wrapping by defining a wide parbox
and using this option.
</DD>
</DL>
</DD>
<DT><STRONG>table</STRONG>(<VAR>Options, Content</VAR>)</DT>
<DD class="defbody">
Create a tabular layout using the class <B>doc_table</B>, a
<A class="" href="summary.html#class:device">device</A> holding a <A class="" href="summary.html#class:table">table</A>.
See also <A class="sec" href="tabular.html">section 11.5</A>. The
options and commands are modelled after HTML-3. Table-related commands
are <CODE>tr</CODE>, <CODE>td</CODE>, <CODE>col</CODE>, <CODE>thead</CODE>
and
<CODE>tbody</CODE>. Defined options are:
<DL>
<DT><STRONG>align</STRONG>(<VAR>Align</VAR>)</DT>
<DD class="defbody">
Graphical alignment, allowing placement as <CODE>left</CODE> or <CODE>right</CODE>
floating object or <CODE>center</CODE>ed placement.
</DD>
<DT><STRONG>width</STRONG>(<VAR>Width</VAR>)</DT>
<DD class="defbody">
Give the table a specified width.
</DD>
<DT><STRONG>bgcolor</STRONG>(<VAR>Colour</VAR>)</DT>
<DD class="defbody">
Set the default background colour for the rows, columns and cells.
</DD>
<DT><STRONG>cellpadding</STRONG>(<VAR>IntOrSize</VAR>)</DT>
<DD class="defbody">
Specify the space inside a cell around its content.
</DD>
<DT><STRONG>cellspacing</STRONG>(<VAR>IntOrSize</VAR>)</DT>
<DD class="defbody">
Specify the space between cells.
</DD>
</DL>
</DD>
<DT><STRONG>tr</STRONG></DT>
<DD class="defbody">
Open the next table-row.</DD>
<DT><STRONG>tr</STRONG>(<VAR>Options, Content</VAR>)</DT>
<DD class="defbody">
Open a new row and emit <VAR>Content</VAR> therein. <VAR>Options</VAR>
are applied to the row. See class <A class="" href="summary.html#class:table_row">table_row</A>
for details.</DD>
<DT><STRONG>td</STRONG>(<VAR>Options, Content</VAR>)</DT>
<DD class="defbody">
Add a table-cell and emit <VAR>Content</VAR> into it. <VAR>Options</VAR>
are applied to the new cell. See class <A class="" href="summary.html#class:table_cell">table_cell</A>
for details.</DD>
<DT><STRONG>col</STRONG>(<VAR>Options</VAR>)</DT>
<DD class="defbody">
Handle an HTML-3 <CODE>col</CODE> element, specifying parameters for the
next column. Defined <VAR>Options</VAR> are <CODE>span(Span)</CODE> to
apply these settings to the next <VAR>Span</VAR> columns and <CODE>width(Spec)</CODE>,
where <VAR>Spec</VAR> is an integer (pixels) or a term <CODE>*(N)</CODE>,
defining the weight for shrinking and stretching relative to other
columns using this notation. The following defines the second column to
be twice as wide as the first:
<PRE class="code">
[ \col(*(1)),
\col(*(2))
]
</PRE>
</DD>
<DT><STRONG>tbody</STRONG>(<VAR>Options</VAR>)</DT>
<DD class="defbody">
Start a row-group. See <A NAME="idx:tablerowsendendgroup:572"></A>`<B>table_row<CODE>-></CODE>end_group</B>'. <VAR>Options</VAR>
is currently ignored.</DD>
<DT><STRONG>thead</STRONG>(<VAR>Options, Content</VAR>)</DT>
<DD class="defbody">
Handle a table-head. It expects a number of rows in <VAR>Content</VAR>.
While processing <VAR>Content</VAR> it sets the default cell alignment
to <CODE>center</CODE> and font to <CODE>bold</CODE>.</DD>
<DT><STRONG>footnote</STRONG>(<VAR>Content</VAR>)</DT>
<DD class="defbody">
Add a footnote-mark. Pressing the mark shows a popup-window holding the
text of the footnote.</DD>
<DT><STRONG>preformatted</STRONG>(<VAR>Text</VAR>)</DT>
<DD class="defbody">
Adds <VAR>text</VAR> in a <A class="" href="summary.html#class:tbox">tbox</A>
to the parbox without checking the content. The current style is applied
to <VAR>Text</VAR>
</DD>
</DL>
<H3><A NAME="sec:11.10.4"><SPAN class="sec-nr">11.10.4</SPAN> <SPAN class="sec-title">Using
the ``doc/emit'' library</SPAN></A></H3>
<P>In <A class="sec" href="docrender.html">section 11.10.1</A> and <A class="sec" href="docrender.html">section
11.10.3.2</A> we have seen the definition of the basic rendering library
infrastructure. It uses concepts from TeX and HTML-3, introducing
primitives for grouping, attribute settings, lists, tables and
whitespace-handling.
<P>The <A NAME="idx:emit3:573"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
predicate as described above is not intended for direct use though. It
is hard to imagine a good syntax for defining significant amounts of
formatted text in a Prolog text-file. In some cases it is feasible to
define a suitable set of new commands and use <A NAME="idx:emit3:574"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
directly from Prolog. In most cases you'll want to use tokens from an
external source using an external markup language.
<P>One option to arrive at a token-list is using the XML/SGML parser
included in SWI-Prolog. It can be used either with a domain-specific
DTD, in which case you need to define the translations by hand or using
an HTML DTD, in which case the library <CODE>library(doc/html)</CODE>
defines the required translations.
<P>We will illustrate this in a small example. First the code to show
HTML inside a window is below. In line 1 we load the always-needed
document rendering infra-structure and register the <CODE>doc</CODE>
search-path to reflect the <CODE>\bnfmeta{pcehome}/prolog/lib/doc</CODE>
directory. Next we import <A NAME="idx:emit3:575"></A><A class="pred" href="docrender.html#emit/3">emit/3</A>
and load the HTML-rendering extensions to doc:emit/3 and doc:action/3.
<PRE class="code">
:- use_module(library('doc/load')).
:- use_module(doc(emit)).
:- use_module(doc(html)).
:- use_module(library(sgml)).
show_html(File) :-
send(new(P, picture), open),
send(P, display, new(PB, pbox), point(10,10)),
send(P, resize_message, message(PB, width, @arg2?width - 20)),
load_html_file(File, Tokens),
send(PB, show, Tokens).</PRE>
<P>Here is the HTML code loaded and the visual result.
<PRE class="code">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>Document rendering</title>
</head>
<body>
<h1>SWI-Prolog SGML-DOM</h1>
<p>
SWI-Prolog 4.0 provides a library for loading XML, SGML and
HTML files and convert them to a complex Prolog term. This
term has the format
<p>
<pre>
element(Name,
ListOfNameValue
ListOfContent)
</pre>
<p>
Where <var/ListOfNameValue/ reflects the attribute-list of the
element and <var/ListOfContent/ is mixed list of atoms representing
<em/CDATA/ and <b>element/3</b> terms representing nested elements.
</body>
</html>
</PRE>
<P><A NAME="fig:dochtml"></A>
<CENTER>
<IMG SRC="dochtml.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 30 : </B>Rendering HTML code</TABLE>
<P>In general you do not want to render plain HTML using <font size=-1>XPCE/P</font>rolog
as it is far less flexible than real browsers dealing with errornous
HTML, the implementation of HTML is incomplete and it supports Java nor
Javascript.
<P>It has proved to be worthwile using the extensibility of SGML and
this layout to render domain-specific documents, often using HTML
elements for the basic layout.
</BODY></HTML>
