In this section:
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 (Hypertext) 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 (Pivot)) 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 the software.
<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.
<DOC name="doc_name">
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="https://www.silverfrost.com"> 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 executable file.
<P>
Marks the end of paragraph. Subsequent text will start on a fresh line with a small gap separating it from the previous text.
<BR>
Forces a line break with no extra gap.
<HR>
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 HTML mark-ups.
<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 IMAGE resource.
<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 right.
<OL> ... </OL>
Produces an ordered list numbered from 1.
<IF name> ... </IF> - See conditional hypertext below.
<PB>
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 (%vx (Vertical Scrollbar)) 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 follows it.
If a call-back function is supplied to %ht (Hypertext), 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:
CURRENT_TEXT_ITEM
CURRENT_TEXT_DOCUMENT
CURRENT_TEXT_TITLE
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:
<body>
<listing>
<li>
<pre>
<cite>
<strong>
<em>
<var>
<xmp>
<code>