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:

Tag	Attributes	Notes
A /A	HREF="<url>" NAME="<text>"	Anchor
ADDRESS /ADDRESS	none	Address style - causes a switch to italic font
B /B	none	Bolds the current font, looks for best fit among available fonts
BLOCKQUOTE /BLOCKQUOTE	none	Indents 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 /DL	COMPACT	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	none	Sample 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	none	Subscript. 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	none	Superscript. 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 TD	Table 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	none	Variable 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