Most programmers and many users will be familiar with the use of Web Browsers
such as Internet Explorer. Such browsers display information that has been
encoded as ASCII files containing Hypertext Markup Language (HTML). A subset of
HTML forms the basis for ClearWin+ hypertext windows.
Hypertext windows provide a way of building very easy to use GUI applications.
A hypertext window contains text with hypertext links, that enable users to
switch between pages (by clicking on highlighted text and images) or to
initiate parts of your program. A hypertext window is created using %ht and can
be surrounded by other controls as required.
For example, the format %70.20ht[introduction] would create a hypertext window
of a width sufficient to display 70 average width characters and 20 rows. The
text would be supplied by a prior call to add_hypertext_resource@ with the name
of a hypertext resource, say 'start', containing the required initial topic
called 'introduction'. This would be defined as a resource thus:
start HYPERTEXT "myfile.htm"
You must use the Silverfrost resource compiler SRC for hypertext files, rather
than the Microsoft compiler RC. By default, SRC is automatically invoked when a
program containing the WINAPP directive is compiled.
The file called browse.htm, that is built into the ClearWin+ browser
program, is available as an example program and is an excellent illustration of
a hypertext file. Note that hypertext resources are stored in a compressed
format, which is not accessible to your users if they choose to binary edit
your program file.
The HTML text is displayed in the window that is both left and right justified
with scroll bars if necessary. The %ht format may be preceded by a pivot format
(%pv) so that the text area changes size as the window is adjusted by the user.
Mark-up codes are contained within diamond brackets < >. For example, a
paragraph end is marked using <P>. Mark-up codes are case
insensitive. Some codes define a condition that pertains until cancelled by a
corresponding mark-up starting with a '/' character. For example, bold face
text is preceded by <B> and followed by </B>. Special
characters (such as the diamond brackets used to define mark-up codes) are
encoded as follows:
< or < produces '<'
> or > produces '>'
& or & produces '&'
Hypertext files may contain portions of text that are included conditionally,
under program control. This is called conditional hypertext. The
browse program uses this feature to change the text depending on the
programming language selected from the corresponding menu item.
The following HTML codes are currently available in ClearWin+:
<TITLE> ... </TITLE>
This supplies a title to a topic. The title will be placed in the caption of
the format window using %ht.
<H1> ... </H1>
Supplies a principle heading to the text. The text will be enlarged and
centred. Although the other heading styles (H2 .. H6) may be used, they
currently operate in the same way as H1. This may change in future versions of
<HTML> ... </HTML>
In standard HTML these codes are almost redundant. They optionally enclose the
entire text. However they are vital for ClearWin+ hypertext as they are used to
delimit separate topics. Each topic should be surrounded by these tags and
contain a DOC tag.
This defines the topic name, and has no analogue in non-ClearWin+ HTML. Each
topic should have a distinct name enclosed in double quotation marks as shown.
<a HREF="/ftn95-help/clearwinp/html/name"> ... </a>
This is an HTML anchor that encloses text (or an image) that will be
highlighted in blue and will react to a left mouse click. Note that standard
HTML anchors have a somewhat more general syntax. The name will usually be
another topic name (defined by DOC). If the name does not correspond to a topic
and a call-back function is supplied with %ht, then the call-back function will
be called. The function can determine the text on the anchor by calling
clearwin_string@('CURRENT_TEXT_ITEM'). In this way, it is possible to execute
code in response to a mouse click.
Hypertext can also contain Uniform Resource Locators (URL's) that link to the
web, for example <a href="http://www.salford.co.uk"> or to local
files, for example <a href="/ftn95-help/clearwinp/html/file:///c:/myproj/test.aspx">. Local files
must have the .HTM or .HTML extension. Alternatively, if the file has a .EXE
extension, it will be executed (see also USE_URL@
and INTERNET_HYPERLINK standard
call-back function). By using file URLs, it is possible to create complex webs
of inter-related documents without having all the information stored in the
Marks the end of paragraph. Subsequent text will start on a fresh line with a
small gap separating it from the previous text.
Forces a line break with no extra gap.
Rules a horizontal line across the page.
<B> ... </B>
Creates bold text.
<U> ... </U>
Creates underlined text.
<I> ... </I>
Creates italic text.
<RED> ... </RED>
Sets the text colour. Other available colours are BLUE, BLACK, GREEN, WHITE,
and YELLOW. Hypertext links are coloured blue by default so you may want
to avoid the use of this text colour (although the colour of a link can be
changed by nesting a colour change inside the link). These are not standard
<FONT SIZE="font_size" FACE="font_face"> ... </FONT>
Sets the font SIZE and/or FACE.
<IMG SRC="name" ALIGN="align_option">
Using this mark-up you can insert a bitmap into your text. name should
be the name of a BITMAP resource you have added in the list of included
resources (quotation marks are required), and align_option should be one
of TOP, MIDDLE, BOTTOM. The alignment specification is optional and the default
is BOTTOM. This determines the way in which the image is aligned with the
surrounding text. By embedding an image in an anchor construct you can display
an image that responds to mouse clicks. GIF files may be used in this
context (see %gi - GIF, for further information).
JPEG files may also be used where name should be the name of an
<UL> ... </UL>
Text embedded between these mark-up codes is considered to form an unordered
list. Each list item is preceded by a <LI> mark-up and will start
on a fresh line with a bullet mark. Lists embedded in lists will nest to the
<OL> ... </OL>
Produces an ordered list numbered from 1.
<IF name> ... </IF> - See conditional hypertext
Sets a page break for use with HTML_PRINTER_OPEN, see
Selecting a printer.
A format window can contain at most one hypertext control. It may also contain
other controls, menus, etc. as desired. It is, however, possible to embed
several child windows, each containing hypertext, within a single parent
window. Only one hypertext control per window is allowed because the window
provides certain services to the control. Thus the containing window will be
displayed with vertical scroll bars if the hypertext is too long for the space
provided. Note that this happens entirely automatically. It is an error to
attempt to attach vertical scroll-bars (%vs) to a window containing hypertext.
Horizontal scroll bars are never needed, since hypertext is always adjusted to
fit the width available.
A standard call-back function 'PREVIOUS_TEXT' is available within a window
containing hypertext. This would normally be attached to a menu item and causes
the hypertext window to 'go back' one topic. A menu item attached to this
call-back will be automatically greyed if the hypertext is at the top level.
A call-back function 'TEXT_HISTORY' is available. When invoked it displays a
history box associated with a hypertext control in the window. The user can
choose to switch to any previously viewed hypertext topic. It is an error to
invoke this call-back from a window that does not contain hypertext.
A call-back function 'COPY_TEXT' is also available. When invoked it copies all
of the text in the current topic to the clipboard.
By default, hypertext windows are given a grey background, although this can
be changed using %`bg. In most cases it is desirable to give the parent window
a matching grey background using %bg[GREY].
The title of a window containing hypertext will consist of any explicit title
(%ca) followed by the title of the current hypertext topic (as supplied by the
<TITLE>) mark-up separated by a hyphen (-).
If there are syntax errors in your mark-up codes, such errors will be reported
at run time rather than when the resource is compiled. A error dialog box will
appear showing the offending code together with a few lines of the text that
If a call-back function is supplied to %ht, this function will be called when
a jump is made to a topic that has not been defined. Alternatively, a grave
accent (`) is supplied in order to ensure that the call-back will be called the
first time and each time the hypertext topic changes. The call-back function
can then interrogate the following clearwin_string@ parameters:
Equation character strings, that follow the rules for %eq (see
Mathematical equation), may also be used in hypertext documents. Equation
strings are embedded between <equation> and </equation>.
The string between these delimiters is treated as a pure equation - no mark-up
codes are recognized in this context. So, for example, the '<' symbol should
be written as it is.
Here is a list of other standard markups that are accepted: