The HView HTML Widget

1. Copyright


Copyright 1998 Computer Generation, Inc., all rights reserved. You may reproduce this document without charge provided it is reproduced in its entirety, including this copyright notice. The software described in this document is copyrighted under separate terms. See the file COPYRIGHT.

The author welcomes comments and suggestions. A HTML version of the document is also available via return E-mail.

Gary.aviv Aviv
Intec Billing gary.aviv@intecbilling.com
+1 404-705-2811

Last update: 05-March-1999
Last version is 1.6 R1.23
See Section 13 for version information.


2. Introduction


HView is a Motif widget that renders HTML text. It supports most all HTML 2.0 DTD with the major exception that it does not support input fields (<FORM>, <INPUT>, <TEXTAREA>, etc.). In addition, it supports <TABLE> from the HTML+ feature set. HView renders graphic images given to it as Pixmaps. Free routines are provided to convert GIF and PNG graphic files to Pixmap.

HView requires Motif since it uses the Motif widgets xmDrawingAreaWidget, and xmScrollBarWidget. It also inherits behaviors from xmManager and uses the Motif function XmGetColors. Finally it defines OSF virtual bindings. All of these reliances could be removed in favor of Xt/Xaw counterparts if necessary.

The primary reason we developed the HView widget is for our on-line help system. The supplied program HViewtest is a stand-alone local file browser which demonstrates how the HView widget could be used to build a browser. Using the CERN toolkit, the browser can be extended to allow Web access. We do not see the point of building a complete browser since the market is already saturated with inexpensive browsers. The main advantage of having the HTML rendering engine in a widget is to be able to add HTML viewing capability to existing applications. A help system is just one example of this. Another example is as a display only text widget. The program dynamically creates HTML output which is rendered by HView. The result is significantly more pleasing than can be achieved with a text widget, especially when multiple fonts and tables are involved.

3. Distribution Kit


Please see the file README for the contents of the distribution kit and other associated files. See the file COPYRIGHT for copyright information. The source code for the HView widget contains the following files:

HView.c HView1.c HView2.c
The HView widget source code
HViewP.h
The HView widget private header
HView.h
The HView widget public header

HView has been compiled successfully on NCR MPRAS, UnixWare SYSV, HP UX, QNX, Digital OSF/Unix/VMS, Linux, and Sun Solaris. It should build on any system that has XR5 and Motif 1.2 or later.

4. HTML Implementation


Currently, HView includes the following tags and options:

TagAttributesNotes
A /A HREF="<url>"
NAME="<text>"
Anchor
ADDRESS
/ADDRESS
noneAddress style - causes a switch to italic font
B /BnoneBolds the current font, looks for best fit among available fonts
BLOCKQUOTE
/BLOCKQUOTE
noneIndents left margin 5 font spaces. A blank line precedes and follows the block
BODY
/BODY
BGCOLOR=<color>
TEXT=<color>
LINK=<color>
VLINK=<color>
The various attributes of the display are changed: background color, text color, un-visited text color, and visited text color. Colors may be specified in #rrggbb format or as color names recognized by the font alias file.
BR none Line Break - The current line is ended, new text appears as a new line. Multiple breaks do not cause further line feeds.
BRANY
/BRANY
A CGI enhanced tag. The string between the tag and its terminator may be broken to a new line at any character position. This allows a long string that otherwise has no whitespace to be continued on a new line when the right margin is reached. Without this, the entire string would be considered a word and could not be split.
CAPTION
/CAPTION
none Table Caption - text between <CAPTION> and </CAPTION> is rendered before the table. These tags must appear in the scope of a table or they are ignored.
CENTER
/CENTER
none The text between the opening and closing center tag is centered. This is similar to <P ALIGN=CENTER> except no paragraph is started. Tables and images may also be centered using the center tag.
CITE
/CITE
none Citation style - causes a switch to italic font
CODE
/CODE
none Coding style - causes a switch to a fixed font
DD none Definition Description - Used within a <DL> </DL> block, the text that follows is the definition description for the term of the previous term given by the <DT>. The <DD> text is indented.
DL /DLCOMPACT Definition List - Encloses a definition list block containing pairs of <DT> and <DD> tags. The COMPACT attribute causes HView to suppress the normal line feed between the <DT> and <DD> when the <DT> text would not run into the <DD> start of text.
DT none Definition Term - Used within a <DL> </DL> block, the text that follows is the definition term. Normally, a <DD> tag follows which contains the definition description of this term.
EM /EM none Emphasis - - causes a switch to italics.
FONT
/FONT
COLOR=<color>
SIZE=<n>
changes font size and/or color. Colors may be specified in #rrggbb format or as color names recognized by the font alias file. The size parameter ranges from 1 (smallest) to 7 (largest). Size may also have a leading sign (+/-) in which case the resulting size is the sum of this value and basefont which defaults to 3.
H1 H2 H3
H4 H5 H6
/H1 /H2 /H3
/H4 /H5 /H6
ALIGN=CENTER
ALIGN=RIGHT
Level n Heading - Switch to corresponding font as given by the resources XcgNh1Font ... XcgNh6Font. Headers appear on new lines with vertical space before and after. ALIGN=CENTER causes the text to be centered while ALIGN=RIGHT causes the text to be right justified.
HEAD /HEAD none Header Information - The text contained within is information regarding the document. These tags are ignored by HView.
HR none Horizontal Rule - Draws a horizontal line. The line spans the current left and right margins.
HTML
/HTML
none HTML Block - The text between the tags is an HTML document. These tags are ignored by HView.
I none Italic - causes a switch to italics.
IDENT ORIGIN="<string>"Identification - A CGI enhanced tag which functions as a comment to identify the document that was used to generate this HTML. See the function XcgHViewFindIdent.
IMG SRC="URL" Include Graphic image - The application callback defined by the getImageCallback resource is called. It must return a Pixmap which is displayed.
KBD
/KBD
none Keyboard Font - - causes a switch to a fixed font.
LI TYPE=1
A or a
list Item - Used within a <OL> <MENU> or <UL> block, the text that follows is a list item
MENU
/MENU
none Menu Block - same as unordered list <UL>.
OL none Ordered List - Indented numbered list. Each item is preceded by <LI> tag.
P ALIGN=CENTER
ALIGN=RIGHT
Paragraph - A new paragraph is begun. Normally, a blank line precedes the paragraph. The ALIGN=CENTER causes the text to be centered (see also <CENTER>). ALIGN=RIGHT causes the text to be right justified.
PRE none Preformatted style - rendered literally (respecting tabs and linefeeds of input stream) in a fixed font.
S /S none Strike-through - The text within is displayed with strike-through.
SAMP
/SAMP
noneSample style - causes a switch to fixed font
SKIP_IF
/SKIP_IF
DEF="<string>"
SKIP_MASK
Run time text exclusion - A CGI enhanced tag which allows the section of HTML text and tags between <SKIP_IF> and </SKIP_IF> to be excluded form processing depending on the conditions given in the attributes.
DEF="<string>"
<string> is an environment symbol - skip is performed if symbol is defined and is non-empty.
SKIP_MASK
skip is performed if skipMask resource is non-zero.
If neither attribute is present, skip is performed unconditionally. If both are present, they are logically ORed. No nesting of this tag is allowed at this time.
STRONG /STRONG none Emphasis - causes switch to bold font.
SUB
/SUB
noneSubscript. Text between <SUB> and </SUB> is rendered as a subscript or slightly lower but in the same font of the preceding text. Nesting of <SUP> and <SUB> is not permitted.
SUP
/SUP
noneSuperscript. Text between <SUP> and </SUP> is rendered as a superscript or slightly elevated but in the same font of the preceding text. Nesting of <SUP> and <SUB> is not permitted.
TABLE
/TABLE
BORDER Table - Specifies the definition of a table containing columns (<TD> and <TH> tags) and rows (<TR> tags). The border option causes a border to be drawn in the table.
TBR Test Break - A CGI enhanced tag which causes a break if the next word does not fit on the line. If it does, <TBR> does not insert a space. Thus <TBR> functions as whitespace for word separation but does not generate whitespace in the displayed text except for a possible new-line.
TD NOWRAP
ALIGN=LEFT (def)
ALIGN=RIGHT
ALIGN=CENTER
COLSPAN=n
ROWSPAN=n
Table Column - Begins a table column. Text within the column is aligned as specified. The NOWRAP attribute forces the text in the column to be on a single line. For rowspan, text is always vertically aligned to the top of the row.
TH See TDTable Column Header - Functions exactly like <TD> except that the text is also bolded.
TITLE
/TITLE
none Document Title - The text within is captured and returned to the application via the titleCallback. A browser typically displays this text in the window decoration.
TR none Table Row - Concludes a table row. Used within a <TABLE> </TABLE> block. The final <TR> prior to </TABLE> is optional.
TT /TT none Typewrite Style - causes a switch to a fixed font.
U /U none Underline - The text within is underlined.
UL none Unordered List Block - a bullet list is begun. Each item is designated by a <LI> tag and is preceded by a bullet.
VAR
/VAR
noneVariable style - causes a switch to bold font
META any Meta - a callback is triggerred if the resource XcgNmetaTagCallback is set. The option/value pairs are returned to the application.
<!--
-->
none Comment - Everything in between the opening < and closing > is ignored. This includes text and tags. Comments may be nested allowing large sections of HTML to be safely omitted.


5. Resources


HView adds the following resources to those it inherits. The resource class is obtained by replacing the N by a C in the resource name (eg: XcgNh1Font is the name XcgC1Font is the class. The access types are C (resource may be set at create time), S (may be se using XtSetValues), or G (may be read using XtGetValues).


XcgNanchorCallback
Type = Callback, Default = NULL, Access = C
Callback function invoked when the user clicks on a reference. The text following the HREF attribute of the <A> tag is returned to the application.
XcgNanchorColor
Type = Pixel, Default = "blue", Access = C
The color that is used to render reference link text (i.e. between <A HREF=..> and </A> ).
XcgNselectColor
Type = Pixel, Default = " ffffce", Access = C
The color that is used for background for selected text or found text.
XcgNdrawBackground
Type = Pixel, Default = "lightgray", Access = C
The draw area background color. The draw area is where the HTML is rendered.
XcgNfixedFont
Type = FontSet, Default = "-adobe-courier-medium-r-normal-*-14-*", Access = C
The font used for various fixed font applications (<PRE>, <TT>, <CODE>, <KBD>). See 6 below.
XcgNdrawForeground
Type = Pixel, Default = Dynamic, Access = C
The color used to draw normal text. The default color is computed based on XcgNdrawBackground to ensure contrast (normally black). You may override this computation with this resource.
XcgNgetImageCallback
Type = Callback Default = None, Access = C
The callback invoked when an <IMG SRC=...> tag is encountered. The application is passed the string following SRC and is expected to return a Pixmap.
XcgNh1Font
Type = FontSet, Default = Dynamic, Access = C
XcgNh2Font
Type = FontSet, Default = Dynamic, Access = C
XcgNh3Font
Type = FontSet, Default = Dynamic, Access = C
XcgNh4Font
Type = FontSet, Default = Dynamic, Access = C
XcgNh5Font
Type = FontSet, Default = Dynamic, Access = C
XcgNh6Font
Type = FontSet, Default = Dynamic, Access = C
The fonts used for the <H1> through <H6> tags. The default fonts are derived from XcgNnormalFont. See 6 below.
XcgNhighColor
Type = Pixel, Default = "red", Access = C
The color used to render reference link text while the mouse button is pressed.
XcgNmetaTagCallback
Type = Callback, Default = NULL, Access = C
The callback invoked when a <META> tag is encountered. The option/value pairs are returned to the application.
XcgNmaxCachedPixmaps
Type = Integer, Default = 20, Access = CS
HView caches pixmaps up to the number specified by this resource. This cache speeds up rendering particularly when the same pixmap is used repeatedly in a document. The pixmaps are not freed when a new document is rendered in the hope that the new document will reuse pixmaps from previous documents. The key to a cached pixmap is the full path for the URL specified in the SRC parameter of the <IMG>. The full path is returned to HView as part of the callback getImageCallback (Section 7.1.)
XcgNnormalFont
Type = FontSet, Default = "-adobe-new century schoolbook-medium-r-normal-*-14-*", Access = C
The font used to render regular text and to derive header fonts. See 6 below.
XcgNtitleCallback
Type = Callback, Default = NULL, Access = C
The callback invoked when a <TITLE> tag is encountered. The text between <TITLE> and </TITLE> is returned to the application.
XcgNvisitedColor
Type = Pixel, Default = "blueviolet", Access = C
The color used to render reference link text which has already been visited.
XmNmarginHeight
Type = Dimension, Default = 4, Access = C
XmNmarginWidth
Type = Dimension, Default = 4, Access = C
The margins around text in the draw area. This is a keepout area so that text does not butt up against the top and bottom (marginHeight) or left and right (marginWidth) extents of the draw area.
XmNshadowThickness
Type = HorizontalDimension, Default = 2, Access = C
The thickness of the shadow drawn around the draw area.
XcgNskipMask
Type = Int, Default = 0, Access = CSG
Used with the <skip_if> tag to control run-time conditional text exclusion. See description of skip_if tag above.
XcgNflashAnchorOption
Type = Int, Default = 0, Access = CSG
When the user clicks on a reference the normal action is to place the corresponding anchor at the top of the window (see function XcgHViewPosToRef). However, if the anchor is close to the bottom of the text, placing it at the top of the window creates dead space in the window following the end of text. HView scrolls the text down to avoid this except where the text entirely fits within the window. This means the anchor is no longer at the top of the window. It is then not visually obvious where the anchor is located. The XcgNflashAnchorOption resource causes the anchor to flash for one second in order to draw attention to it. The resource has 3 possible values:
0
The anchor is never flashed (the default)
1
The anchor is flashed only if it does not appear at the top of the window,
2
The anchor is always flashed.

XcgNverboseHView
Type = Boolean, Default = False, Access = CS
HView will normally ignore or adjust silently to HTML syntax errors it encounters. When set True, warnings are displayed for these errors. Use this to aid in debugging when you get unexpected rendering results that may be cause by errors in your HTML source or a bug in HView.
XcgNdebugHView
Type = Integer Default = 0 Access = CS
Sets debug level. A value of 1 causes HView to print each tag as it is processed. The character position within the HTML file where the tag occurs is shown in parenthesis. Use along with XcgNverboseHView to aid in debugging. For example:
    HViewtest -xrm "*verboseHView: True" -xrm "*debugHView: 1" 2> log.tmp


6. Fonts


The minimal font resources that HView requires are XcgNnormalFont and XcgNfixedFont. Header fonts may optionally be specified. If not, they are derived from XcgNnormalFont by taking its attributes but changing the stroke to bold and adding +10, +4, +2, 0, -2, -4 to the point size for <H1> to <H6> respectively. For the default XcgNnormalFont (14 point) this yields 24, 18, 16, 14, 12, 10. The XcgNfixedFont is scaled to match the size of XcgNnormalFont. In addition, the <FONT SIZE=n> tag may cause either XcgNnormalFont or XcgNfixedFont to be scaled. The tags <B> and <I> can cause HView to convert any font to bold or italic. Therefore, you should make sure that the fonts XcgNnormalFont and XcgNfixedFont are scalable and have, bold, italic and bold italic versions.


7. Callbacks


Each callback passes a pointer to the following structure:

typedef struct _XcgHViewCallbackData
{
	XcgReasonType reason;	/* reason for callback */
	XEvent *event;		/* mostly NULL */
	char *href;		/* the href text <A HREF="<href>" */
	char *image;		/* the text <IMG src="image">, or title */
	Widget draw;		/* the widget in which image is drawn */
	XcgHViewPixmap * pixmap_info; /* loaded with address for
				application to return pixmap data */
} XcgHViewCallbackData;


7.1 getImageCallback


When HView encounters an <IMG SRC="URL"> tag, it invokes the callback list given by the getImageCallback resource twice as will be explained below. The fields of XcgHViewCallbackData are set as follows:

reason
set to XcgImageNameReason then to XcgImageReason
event
NULL
href
NULL
image
the URL text <IMG SRC="URL"> (without double quotes) Treat as read only.
draw
the widget in which the image will be drawn.
pixmap_info
loaded with address of a XcgHViewPixmap structure defined below.

typedef struct _XcgHViewPixmap
{
	Dimension width;	/* width of Pixmap */
	Dimension height;	/* height of Pixamp */
	Pixmap pixmap;		/* the pixmap itself */
	char * name;		/* app provides the image name */
	int fu;			/* future use */
} XcgHViewPixmap;

For the first callback the reason is XcgImageNameReason. You supply the full filename for the image whose URL is given in image. Place a pointer to this string in the name field of XcgHViewPixmap dereferenced by pixmap_info. The string pointed to by name is copied by HView. For example, if the tag is <IMG SRC="../test.gif"> you would return the full path to this file. HView uses this name to index its pixmap cache. If the pixmap is already cached, the second callback can be avoided. You may ignore the XcgImageNameReason callback in which case HView assumes the full path is the image field of the callback structure (i.e. the string following SRC.)

The second callback the reason is XcgImageReason. You must retrieve the image file and convert it to a Pixmap in the context of the draw widget. Then return the fields width, height and pixmap in XcgHViewPixmap dereferenced by pixmap_info as shown above. The name field is preserved from the first callback for this image for your convenience.

If pixmap is returned as null, HView will substitute a pixmap depicting an error.


7.2 anchorCallback


When the user clicks on an anchor reference <A HREF="URL">, HView invokes the callback list given by the anchorCallback resource. The fields of XcgHViewCallbackData are set as follows:

reason
set to XcgAnchorReason or XcgAnchorViewReason
event
NULL
href
Pointer to the URL text <A HREF="URL"> (without double quotes). Treat as read only. May be NULL if no HREF specified.
image
When image was selected, pointer to URL of SRC="URL" (without double quotes) of IMG tag. Otherwise, NULL. Treat as read only.
draw
NULL
pixmap_info
NULL

When the reason is XcgAnchorReason, the application should read the document at URL and request that HView render it. This is normally bound to <Btn1Up> (left mouse button up) event.

When the reason is XcgAnchorViewReason,, the application just displays the URL. This is normally bound to Ctrl<Btn1Up> event. Most browsers display the URL on a pointer motion alone. For efficiency, HView defaults to the button event, though you can change this. Note that HView also invokes this callback when the user clicks on an image that is not a HREF. In this case href is NULL and image contains a pointer to the image source. Sample code follows:

void _xf_html_anchor_cb(Widget w, XtPointer clientd, XcgHViewCallbackData * cbs)
{
	if (cbs->reason == XcgAnchorViewReason)
	{
		if (cbs->image) /* clicked on image, get the src= string*/
			Display("Image Source='%s'\n", cbs->image);
		if (cbs->href)
			Display("Href='%s'\n", cbs->href);
		return;
	}
	else if (cbs->reason == XcgAnchorViewReason)
	{
		XcgHViewSetVisited(w, cbs->href, 0);
		/* take steps to format and display file at cbs->href */
		return;
	}
	/* unknown reason, bug in HView */
}


7.3 titleCallback


When HView encounters a <TITLE> text </TITLE> combination, it invokes the callback list given by the titleCallback resource. The fields of XcgHViewCallbackData are set as follows:

reason
set to XcgTitleReason
event
NULL
href
NULL
image
pointer to the text contained between the <TITLE> and </TITLE> tags. Treat as read only.
draw
NULL
pixmap_info
NULL

Normally, the application copies the title text and displays it as part of the window decoration.

7.4 metaTagCallback


When HView encounters a <META ...> it invokes the callback list given by the metaTagCallback resource. The fields of XcgHViewCallbackData are set as follows:

reason
set to XcgMetaTagReason
event
NULL
href
NULL
image
pointer to an array of char pointers (cast as char **) giving the option/value pairs. Option names are always upshifted. Non-quoted values are also upshifted. If a value is not present, its pointer is null. The array is terminated by a pair of null pointers. Treat the array as read only.
draw
NULL
pixmap_info
NULL

Lets assume the following tag is encountered:

<META HTTP-EQUIV="Refresh" CONTENT="5; URL=http://www.tripod.com/"  >

then consider the following code:

void _xf_html_anchor_cb(Widget w, XtPointer clientd, XcgHViewCallbackData * cbs)
{
	if (cbs->reason == XcgMetaTagReason)
	{
		char ** opt_val = (char **) cbs->image;
		char * option;
		char * value;
		
		while ( *opt_val )
		{
			option = *opt_val++;		
			value = *opt_val++;		
			if (!option)
				return;	/* end of array */
			if (strcmp(option, "HTTP-EQUIV") == 0)
			{
				if (!value)	/* no value given */
					...
				if (strcmp(value,"Refresh") == 0)
					...
			}			
		}
	}
}


8. Translations


<Key>osfUp HViewScrollDisp(u)
<Key>osfDown HViewScrollDisp(d)
<Key>osfLeft HViewScrollDisp(l)
<Key>osfRight HViewScrollDisp(r)
<Key>osfPageUp HViewScrollDisp(U)
<Key>osfPageDown HViewScrollDisp(D)
Shift<Btn1Down> HViewSelect(e)
Shift<Btn1Up> HViewSelect(u)
<Btn1Down> HViewPick(d)
Ctrl<Btn1Up> HViewPick(U)
<Btn1Up> HViewPick(u) HViewSelect(u)
<Btn1Motion> HViewSelect(m)


9. Action Routines


HViewScrollDisp
When vertical or horizontal scroll bars are present, scrolls the display according to its single parameter:

u
Scroll up one increment
d
Scroll down one increment
U
Scroll up one page
D
Scroll down one page
l
Scroll left one increment
r
Scroll right one increment

A vertical scroll increment is approximately the height of a single line in the normal font. A page is approximately 90% the height of the draw area. A horizontal scroll increment is approximately 10% of the width of the draw area.

HViewPick
Actions normally associated with mouse button 1 events. A single parameter is passed:

d
The text object under the pointer is internally marked. If it is an anchor reference, it is rendered in red. If a select is active, it is released. A new select region base point is established.
U
If a previously marked object is an anchor reference, the anchorCallback list is called with XcgAnchorReason reason.
u
If a previously marked object is an anchor reference, the anchorCallback list is called with XcgAnchorViewReason reason.

HViewSelect
Actions associated with selection. Select data is passed in the PRIMARY_SELECTION property. Normally, <Btn1Down> begins a select region by establishing a base point. This erases any previous selection. <Btn1Motion> extends the select region. The motion position becomes the end point. The region is bounded by the base point and the end point. The base point does not change. Shift<Btn1Down> establishes a new end point as if motion occurred to this point. The user may extend a region beyond the viewable window by scrolling the window and resuming the selection using Shift<Btn1Down>. A double click of <Btn1Down> cuases a word to be selected.

A single parameter is passed to these action routines:

m
A select region is established or extended. Its base point was established by HViewPick(d). If that base point was in an anchor reference, it is rendered back to normal foreground and anchor processing is cancelled. It would have been highlighted from HViewPick(d).
e
A select region is established or extended. If no select is active, a new one is established at this point as its base. If one already is established, its endpoint becomes the clicked point. The base point does not change.
u
Ownership of the PRIMARY_SELECTION property is requested. This makes the select region available for pasting into another screen.
w
Select a word. A word is separated by spaces or a format change (such as bolding). This action is not called directly from a translation. The double click timing is handled internally because Xt has problems with <Btn1Down>(2) type translations obscuring motion events.


10. HView API


HView contains an extensive set of functions that control the widget behaviour.


10.1 XcgHViewFormatText - Format HTML text into the HView widget.


Function
Format HTML text into the HView widget. Start with a fresh slate, freeing resources used for any previous displayed text.

C-call
void XcgHViewFormatText(Widget w, char * text, int size, int option)

Input
w
HView widget
text
pointer to buffer containing text. Must be null terminated
size
size of text, if 0, it will be computed (strlen)
option
option mask
HViewOptRawText
treats entire text as raw, no HTML tags are processed
HViewOptAutoResize
Reformat automatically on resize This requires the widget save an internal copy of the passed text.
HViewOptFreePixmapCache
Cached Pixmaps are freed. Normally, HView caches Pixmaps between Format calls in particular to speed redraws. Use this when you change a pixmap file and you want to see the new one appear.

Output
text buffer may be dirty at conclusion. It is treated as read/write by the widget. It must not be freed by the application until a subsequent call to this routine. It is not freed by HView.


10.2 XcgHViewPosToRef -- Position the display window to the passed reference


Function
Position the display window to the passed reference. You must call XcgHViewDisplay to cause the change to be visible.

C-call
int XcgHViewPosToRef(Widget w, char * text)

Input
w
HView widget
text
pointer to buffer containing text. Must be null terminated This is the text following the name in the tag <A NAME="xxxxx">

Output
None

Return
True - anchor was found
False - anchor was not found and no positioning took place


10.3 XcgHViewDisplay -- Display text into the HView widget.


Function
Display text into the HView widget. The text must have previously been formatted with XcgHViewFormatText. This function makes this text visible. The display window is positioned at the top or as specified by one of the positioning functions.

C-call
void XcgHViewDisplay(Widget w, int option)

Input
w
HView widget
option
option mask, future use, zero for now.

Output
Nothing

10.4 XcgHViewGetPos -- Return the relative position of the display window



Function
Return the relative position the display window in the text. This value may be used in subsequent XcgHViewSetPos call to reposition the display as it was. For example, you could take the position of the display prior to redisplaying the text when the user requests a re-read. This way, if the user has scrolled vertically, the window returns to this scroll position.

In another example, you take the position of the display prior to following a link. When the user clicks a "Back" button, you return to the original position using XcgHViewSetPos, in perhaps another file.

C-call
unsigned long XcgHViewGetPos(Widget w, int option)

Input
w
HView widget
option
option mask, future use, zero for now.

Output
Nothing

Return
opaque position


10.5 XcgHViewSetPos -- Scroll the display window to a saved position


Function
Scroll the display window within to a saved position. This value must have been obtained with a call to XcgHViewGetPos. Note that you must call XcgHViewDisplay to actually force out the new display.

C-call
void XcgHViewSetPos(Widget w, unsigned long position, int option)

Input
w
HView widget
position
the relative position as obtained from XcgHViewGetPos.
option
option mask, future use, zero for now.

Output
Nothing

10.6 XcgHViewSetVisitedList - Set a list of visited anchors


Function
Set a list of visited anchors. Anchor refs on this list are displayed in a different color. This routine should be used prior to calling XcgHViewFormatText. It does not affect the current display.

C-call
void XcgHViewSetVisitedList(Widget w, char ** visited_list, int option)

Input
w
HView widget
visited
An array of strings. Each string is a visited reference. The last member of the array must be NULL. This buffer is owned by the widget until XcgHViewFormatText is called.
option
option mask, future use, zero for now.

Output
Nothing

10.7 XcgHViewSetVisited -- Set a single visited anchor


Function
Set a single visited anchor. This anchor reference is displayed in a different color. This routine should be called after XcgHViewFormatText. It does not affect the current display until a XcgHViewDisplay is performed. Use XcgHViewSetVisitedList instead to set an array of visited anchors prior to XcgHViewFormatText.

C-call
int XcgHViewSetVisited(Widget w, char * visited, int option)

Input
w
HView widget
visited
The anchor ref text This buffer is copied by the widget.
option
option mask, future use, zero for now.

Output
Nothing
Return
True - anchor found
False - anchor not found

10.8 XcgHViewSetAppContext - associate a context pointer with the widget


Function
Associate an application context pointer with the widget to aid in writing re-entrant code. This is similar to the XmNuserData resource which is also available. In many cases, XmNuserData is already taken and so we provide another context word. See XcgHViewGetAppContext to retrieve context

C_call
void XcgHViewSetAppContext(Widget w, XtPointer context)

Input
w
HView widget
context
a context word to store.

Output
Nothing


10.9 XcgHViewGetAppContext -- Retrieve the application context


Function
Retrieve the application context pointer associated with the widget. Use this to aid in writing re-entrant code. This is similar to the XmNuserData resource which is also available. In many cases, XmNuserData is already taken and so we provide another context word. See XcgHViewSetAppContext to set context.

C-call
XtPointer XcgHViewGetAppContext(Widget w)

Input
w
HView widget

Output
Nothing

Return
context - the context word previously set with XcgHViewSetAppContext or zero if never set.


10.10 XcgHViewFindString -- Search for a string in the displayed text


Function
The current text is searched for the passed string. The search starts at the last found string, or at the top or bottom of the text. The display window is positioned so that the found text is visible. If text has already been displayed (i.e. XcgHViewDisplay has been called prior to XcgHViewFindString) then the display is refreshed with the found text (if any) visible. if XcgHViewDisplay has never been called, XcgHViewDisplay must be called manually at which time the found text will be visible. Use this method to position an initial display after a parse.

C-call
int XcgHViewFindString(Widget w, char * target, XcgStartSearch start_search, int options)

Input
w
HView widget
target
the target text to find, NULL terminated. If empty string is passed, then no search is performed and True is returned. Use empty target with zero option to un-highlight all previous found strings.

start_search
where the search begins
XcgStartTop
start search at top of text or at bottom of text (when XcgHFindBackwards)
XcgStartAtLastFound
from the point of last found target or at top of text (bottom when XcgHFindBackwards) if no last.
options
(mask)
XcgHFindCaseInsensitive
default is case sensitive
XcgHFindBackwards
Search backwards, default is search in forward direction
XcgHFindNoClear
Normally, any previously found strings are un-highlighted prior to each new search. This bit suppresses this action allowing multiple strings to be highlighted at the same time. Use this to implement a find all function.
XcgHFindNoPosition
Don't position to found string. Default is to scroll so the just found string is visible in window.
XcgHFindPositionCenter
found string is positioned in the center of the window. Default is to place it at the top of the window if it was not already visible.

Output
Nothing

Return
True - target was found
False - target was not found


10.11 XcgHViewFindIdent -- Search for Ident Marker


Function
From the last marked position, the IDENT tag is located in the reverse direction. The position is established from the last button down event, if within the viewable window, or the center of the viewable window otherwise. When a reverse search is unsuccessful, a forward search to the nearest IDENT tag is done.

This is a CGI enhanced tag which gives the origin of the document which generated this HTML output. The tag format is <IDENT ORIGIN="<path>". The user marks a position by clicking anywhere in the document (other than a link). The browser may use this function to open an edit window with the origin document.

C-call
int XcgHViewFindIdent(Widget w, char ** origin, int options)

Input
w
HView widget
origin
character pointer to receive origin string, null terminated. The widget owns this string - it is read only to the application.
options
0 - Future

Output
*origin - pointer to origin string or NULL if not found.

Return
True - IDENT tag was found
False - no IDENT tag found


10.12 XcgHViewSetIdent -- Set origin string for this document


Function
Emulates the creation of an IDENT tag at the top of the document as if <IDENT ORIGIN="<path>"> was encountered. This is a CGI enhanced tag which gives the origin of the document which generated this HTML output. See XcgHViewFindIdent.

C-call
void XcgHViewSetIdent(Widget w, char * origin, int options)

Input
w
HView widget
origin
character pointer to origin string, null terminated. The widget copies the pointer to the string only. It must remain valid for the duration of the display.
options
0 - Future

Output
Nothing


10.13 XcgHViewRemoveHTMLTags -- Removes HTML tags from a buffer


Function
This is a convenience routine for utility writers. It is not used by the widget but it uses many subroutines within. It removes all HTML tags and comments from a buffer leaving only pure text.

C-call
void XcgHViewRemoveHTMLTags(char * text)

Input
text
buffer containing the entire document, null terminated.

Output
*text
updated buffer, with tags removed


10.14 XcgHViewGetNextRef -- Return the text for the next reference (anchor)


Function
The next or first reference (anchor) text is returned. This is the text following the name in the tag <A NAME="xxxxx"> You may obtain all references in the document using the loop:
void * context;
char * ref_text;

for(context=NULL; ref_text = XcgHViewGetNextRef(w,&context) ;)
	printf("Ref=%s\n", ref_text);

C-call
char * XcgHViewGetNextRef(Widget w, void ** context)

Input
w
HView widget
context
pointer to a context word previously returned by a call to this function. If *context is NULL, the first reference is returned. Otherwise, the next reference text is returned.

Output
*context
opaque context for current reference returned.
Return
Pointer to Anchor text or NULL if no more references. The text pointed to must be treated as read-only. It is NULL terminated.


10.15 XcgHViewTextOut -- Produce a text file containing formatted HTML source


Function
A plain text file is created containing the displayed or passed HTML source. The default width is 80 characters.

C-call
void XcgHViewTextOut(Widget w, char * text, int size, FILE * outf, int option );

Input
w
HView widget
text
pointer to text to process. If null, internal copy is used if HViewOptAutoResize was specified. In this case the displayed text is processed. If text is explicitly provided, its contents will be dirtied but is otherwise owned by the caller.
size
size of text, if text is explicitly provided. May be zero in which case a strlen will be done.
outf
the FILE * to receive the output. This file is opened and closed by the caller
options
0 - Future

Output
*text
Buffer is dirtied.
Return
Nothing


10.16 XcgHViewGetText -- Return a pointer to the HTML source text


Function
A pointer to the current HTML text being displayed is returned. This only works if HViewOptAutoResize was specified at time of format. Otherwise, HView does not keep a copy of the input text.

C-call
char * XcgHViewGetText(Widget w, int option );

Input
w
HView widget
options
0 - Future

Output
Nothing

Return
A pointer to the HTML text or NULL if HView does not have a copy of it. The buffer is owned by the widget and should not be changed or freed.


10.17 XcgHViewScrollVertical -- Position the display window


Function
The display window is scrolled up or down according to the passed parameters. You must call XcgHViewDisplay to cause the change to be visible.
C-call
int XcgHViewScrollVertical(Widget w, int option, int rel_pos)

Input
w
HView widget
option
XcgHScrollPercent
rel_pos is an signed integer representing the percentage down (negative) or up (positive) to scroll the window. For example a value of -50 scrolls the top line of the window to the middle of the window.
XcgHScrollLastAnchor
the last anchor found by XcgHViewPosToRef is brought into view according rel_pos (0-100). If 0 it is placed at the top of the window, 100 at bottom and so on.
rel_pos
meaning depends on option above

Output
Nothing

Return
True - Positioning successful
False - partial or no positioning done because requested scrolling would cause dead space at the top or bottom of display window.


10.18 XcgHViewChangeFontSize -- The fonts are re-scaled.


Function
The entire set of fonts used by HView are re-scaled according to the increment parameter. The normalFont and fixedFont resources are the only font resources that are used. These must specify scalable fonts. All the header fonts are then rescaled proportionately unless they were explicitly specified by resource. See Section 6.

You must refresh the screen to see the effect of all this.

C-call
int XcgHViewChangeFontSize(Widget w, int increment, int option )

Input
w
HView widget
increment
the point size (in tenths) that the fonts are altered by. If positive, the fonts get bigger. If negative, they get smaller. For example, specify 20 to increase the size by 2 points.
option
future use, must be zero.

Output
Nothing

Return
True - successful
False - error

11. Internationalization


The HView widget is designed to allow the display of internationalized HTML text. This has been tested on a limited basis with Japanese.

In order to make use of internationalization, you must have support in your operating system for the desired locale and must have the needed fonts. In some cases, you may use the X provided locale support instead. At initialization, you should have code that looks something like:

	if (setlocale(LC_ALL,"") == NULL)
		fprintf(stderr, "HViewtest: Can't set locale\n");
	if (!XSupportsLocale())
	{
		fprintf(stderr, "HViewtest: X does not support locale\n");
		setlocale(LC_ALL,NULL) ;
	}
	if (XSetLocaleModifiers("") == NULL)
		fprintf(stderr, "HViewtest: Can't XSetLocaleModifiers\n");

If you need the X locale package, add the following:

	#define X_LOCALE
	#include <X11/Xlocale.h>


HView makes use of the XR5 Font Set technology. All font resources are converted to Font Sets. For example, for Japanese you will need three fonts for each font set:

*normalFont: \
-adobe-new century schoolbook-medium-r-normal-*-*-140-75-75-*-*-iso8859-1",\
-sony-fixed-medium-r-normal-*-*-140-75-75-c-*-jisx0201.1976-0,\
-jis-fixed-medium-r-normal-*-*-140-75-75-c-*-jisx0208.1983-0

! etc for each font resource

Finally, you must set the environment symbol LANG to the appropriate locale. For Japanese, one possibility is "LANG=ja_JP.eucJP".


12. Character Sets


HView respects the character set of the main font when translating entity codes such as &Uacute; or &#218; to the appropriate 8-bit character.

The character set of the font specified by the XcgNnormalFont resource (the first font of the font set) is examined. All other fonts should share this character set. Currently, HView supports the Latin-1 (iso8859-1) and Roman-8 (hp-roman8) character sets. All other character sets are treated as Latin-1 for the purpose of translating entity codes. Most multi-byte fonts map Latin-1 in their low 8-bits and so will be compatible with this treatment.


13. Version Information


Version 1.1
  1. Reduce flicker in Expose method.
  2. cache Pixmaps for faster refresh
  3. general bug fixing
Version 1.2
  1. Mark and Cut support (see HViewSelect below)
  2. Add XcgHFindNoClear option in XcgHViewFindString function
  3. Add XcgHViewGetNextRef function
  4. Handle &NBSP; for fonts that do not define a non breaking space.
  5. general bug fixing
Version 1.3
  1. Add XcgNdebugHView resource which prints each tag as it is processed.
  2. Fix Tab keyboard traversal.
  3. Improve table formatting capability.
  4. Support -- > as and of comment (i.e. whitespace between -- and >)
  5. Add drawForeground resource to allow control of normal text color.
  6. Add COMPACT attribute for <DL>
  7. Fix lack of further indentation when <dl> follows another <dl>
  8. Support Roman8 character set.
Version 1.4
  1. <skip_if> tag
  2. <SUB> and <SUP> tags
Version 1.5
  1. <CAPTION> support within Table
  2. <BODY BGCOLOR=color TEXT=color LINK=color VLINK=color > tag
  3. <FONT SIZE=n COLOR=color> tag
  4. ALIGN=RIGHT in <p> tag
  5. ALIGN=[RIGHT | CENTER]in <Hn> tag
  6. Scalable font support. Remove resources XcgNfixedBoldFont XcgNfixedItalicFont XcgNnormalBoldFont and XcgNnormalItalicFont because these fonts are derived directly from XcgNnormalFont and XcgNfixedFont. Resources XcgNh*Font (*=1-6) now default to bold version XcgNnormalFont of various sizes. See Section 6.
  7. add XcgHViewScrollVertical function
Version 1.6
  1. The point sizes of the header fonts are now derived from the normal font. See Section 6.
  2. The compile symbol UNIX_BSD has been added. With it set, sprintf(buf,...) will be assumed to return buf rather than the customary integer size. This symbol is needed for SunOS 4. Also, see HViewtest.make for other notes regarding the use of UNIX_BSD in the test browser code.
  3. The XcgHViewChangeFontSize allows you to change the font size on the fly. The test browser demonstrates this with its larger/smaller font button.
  4. The XcgHViewScrollVertical allow programatic positioning of the display window.
  5. New flashAnchorOption resource (see Section 5 above).
  6. <OL> now supports TYPE=a or A or 1
  7. Fixed spelling of XcgHViewSetVisited (old spelling - Visisted - preserved for back compatibility)
  8. XcgHViewFindString now supports backward search. (See Section 10.10 above.) The test browser now demonstrates this with its find dialogue.
  9. The test browser now supports limited HTTP protocol.
Version 1.7
  1. Support for colspan and rowspan for <TD> and <TH>
  2. <META ...> tag callback
  3. Remove reliance on libXmu (make with NO_XMU=y or --DNO_XMU on cc)
  4. A double click of <Btn1Down> cuases a word to be selected.
  5. <TBR> <BRANY> tags
  6. <S> </S> tags

HView HTML Widget