|
|
|
|
| CaseSensitivity | DefineColors | DefineFileMarkers | DefineWindowMotion |
| ExitInformation | OptimizePerformance | ShowHyperText |
PROCEDURE ShowHyperText
(CONST FileName : ARRAY OF CHAR;
CONST chapterName : ARRAY OF CHAR;
CONST firstLine : CARDINAL;
CONST lastLine : CARDINAL;
CONST leftColumn : CARDINAL;
CONST rightColumn : CARDINAL;
VAR successful : BOOLEAN);
(**
ShowHyperText - Process a hypertext file.
This procedure processes a hypertext file and displays
it on the screen in the defined window area. The hypertext
display area reserves the top line, bottom line, right
most and left most columns for border and command
information. Enough room should therefore be allowed
in the remaining area for text display.
The user is allowed to negotiate the contents of the
hypertext file by selecting links and going forward to linked
chapters, or by returning from a linked chapter to the
previous chapter. In a chapter, any alphanumeric key may
be pressed to provide a quick search and locate and
highlight capability. The Backspace key may be used to reduce
the size of the current search string as shown. Help is
available at anytime by pressing the help key indicated at
the bottom of the displayed chapter.
The keys available to the user in hypertext are tied to the
standard SAGE key definitions and may be change using
"Display.DefineFunctionKey". IF THE EXIT KEY (#21) IS NOT
DEFINED, HYPERTEXT WILL NOT BE ALLOWED TO CONTINUE.
Function # Name Description
---------- ------- -------------------------------
1) forward Scroll right 1 column
2) backward Scroll left 1 column
3) up Scroll up 1 line
4) down Scroll down 1 line
5) tab Move to next highlighted link
6) backtab Move to previous highlighted lnk
8) helpexit Help
10) exitform Progress to the next ref. chapt.
13) bw Black & white toggle
17) copyscreen Copy the current chapter to a file
18) pagedown Scroll down 1 page
19) pageup Scroll up 1 page
21) exit1 Terminate the hypertext session
22) exit2 Return to the previous chapter
23) exit3 Repeat the previous search from current loc.
24) exit4 Return to the first chapter shown
25 .. 30) exit5-exit10 Terminate the hypertext session
31) firstpage Move to top page
32) lastpage Move to bottom page
41 .. 59) exit11-exit28 Terminate the hypertext session
59) exit29 Go to first chapter then prev item's ref.
60) exit30 Go to first chapter then next item's ref.
This procedure reads and processes an ASCII text file
which has been prepared with special markers to designate
chapter beginnings, chapter names, links, highlighted areas
and so forth. This text file normally begins with a table of
contents chapter with links to all major chapters. A forward
link may reference a chapter in the current text file, or
a chapter from another designated text file.
This procedure may also be used to process an unmarked text file.
If the file contains no chapter markings, then the entire file is
assumed to be one chapter. Of course, no forward links to other
chapters will be recognized since they would not exist within an
unmarked file.
By default, the special markers are defined as follows -
character Default Description
-------------- -------- -------------------------------------
chapterChar ASCIIX.ff chapter beginning
linkChar '@' link entry
fileChar '^' file reference in link entry
searchChar '%' search reference in link entry
highlightStart '[' highlight start
highlightEnd ']' highlight end
boldStart "^B" Start of bold
boldEnd "^b" End of bold
The marker characters may be changed using the
"HyperTxt.DefineFileMarkers" procedure supplied with this package.
If a special marker character needs to be used in normal text
of the file, it may be used by entering it twice (e.g. "@@" to
represent a '@' character).
An example of a file with markers which may be processed by this
procedure follows
(<ff> is used to designate the ASCIIX.ff character
in this example) -
--------------------------------------------------------------
<ff>* Sample HyperText Chapters
@SubjectA[Information for Subject A]
@SubjectB[Information for Subject B]
@SubjectC[Information for Subject C]
@SubjectD^DFILE%select[Information for Subject D]
<ff>SubjectA
^BSubject-A Chapter Information^b
This is subject information for "Subject A". For further
information, you may select @MinorSubjectA1[Subject A.1]
or @MinorSubjectA2^HFILE2[Subject A.2].
--------------------------------------------------------------
A description of terminology follows -
Chapter - A section of material which may be paged through as
a complete area within the library. Each chapter
is preceded by the "chapterChar" (ASCIIX.ff by default)
and is assigned a Chapter Name within the text. The
chapter name "*" is used for the chapter which
contains the table of contents (normally the first
chapter). A chapter name may be no longer than 20
characters and may not contain embedded blanks.
A chapter may not contain more than 2000 lines of
text.
In the previous example, two chapter examples are
given as follows -
<ff>* Sample HyperText Chapters
<ff>SubjectA
The name of the first chapter is "*". Notice that a
blank acts as a delimiter and the text which follows the
"*" is part of the chapter's text. The name of the
second chapter shown is "SubjectA" and because not text
follows, the first line of that chapter is blank.
Link - A reference from one chapter to another. This item
is displayed in bold characters and will cause a display
of the associated chapter when selected. One or more
links may be present within a chapter. If no links are
present, the user may only return from a chapter.
In the previous example, one of the links was shown as
follows -
@SubjectD^DFILE%select[Information for Subject D]
In this example, the chapter name is "SubjectD".
It will be found in another file which is named "DFILE".
When the chapter is located, the first occurrence of
"select" will be found, highlighted, and the cursor
located there. The user will be shown the link as
the highlighted string "Information for Subject D".
Note in the example of a page of a hypertext file that
link references may be embedded within the actual
text of a chapter.
CALLING SEQUENCE -
ShowHyperText (fileName, chapterName, firstLine, lastLine,
leftColumn, rightColumn, successful)
ENTRY -
fileName : ARRAY OF CHAR
Name of hypertext file.
chapterName : ARRAY OF CHAR
The name of the first chapter in the given file
to be shown. If this name if a null string or
a blank string, then the chapter named "*" is
located if it exists, or the first chapter
on the file if "*" does not exists.
firstLine : CARDINAL
Top line of the screen where the text should
appear (1 .. n).
lastLine : CARDINAL
Bottom line of the screen where the text should
appear (firstLine .. n).
leftColumn : CARDINAL
Left most column on the screen where the text should
appear (1 .. 80);
rightColumn : CARDINAL
Right most column on the screen where the text should
appear (leftColumn .. 80).
EXIT -
successful : BOOLEAN
Access and processing of file was successful (TRUE).
EXAMPLE -
MODULE HyperT;
IMPORT CmndLine;
IMPORT HyperTxt;
IMPORT Display;
VAR
fileName : SageSpec.LongPathType;
done : BOOLEAN;
BEGIN
GetCommandField (1, fileName, done);
IF (done) THEN
DefineFunctionKey (8, ASCIIX.nul, CHR (59));
DefineFunctionKey (21, ASCIIX.nul, CHR (68));
DefineFunctionKey (22, ASCIIX.esc, ASCIIX.nul);
DefineWindowMotion (2, 4, 2, 5, 20, 0);
ShowHyperText (fileName, "", 1, 24, 1, 80, done);
END;
END HyperT.
*)
PROCEDURE DefineFileMarkers
(CONST chapterChar : CHAR;
CONST linkChar : CHAR;
CONST fileChar : CHAR;
CONST searchChar : CHAR;
CONST highlightStart : CHAR;
CONST highlightEnd : CHAR;
CONST prefixChar : CHAR;
CONST boldStart : CHAR;
CONST boldEnd : CHAR);
(**
DefineFileMarkers - Define the signal characters for the hypertext file.
This procedure allows the redefinition of the special characters
used by the hypertext file designate various available options.
The characters and default characters are as follows -
character Default Description
-------------- -------- -------------------------------------
chapterChar ASCIIX.ff chapter beginning
linkChar '@' link entry
fileChar '^' file reference in link entry
searchChar '%' search reference in link entry
highlightStart '[' char. designating the highlight start
highlightEnd ']' char. designating the highlight end
prefixChar '^' Prefix character for special effects
boldStart 'B' Start of bold (follows prefixChar)
boldEnd 'b' End of bold (follows prefixChar)
CALLING SEQUENCE -
DefineFileMarkers (chapterChar, linkChar, fileChar, searchChar,
highlightStart, highlightEnd, prefixChar,
boldStart, boldEnd)
ENTRY -
chapterChar : CHAR
The character which indicates the beginning of a new chapter
and immediately precedes the chapter name. The chapter
name may be from 1 to 20 characters in length. The special
name "*" will be the first chapter shown and is therefore
normally used for the table of contents.
The first chapter of the text file is not preceded with
a chapterChar.
linkChar : CHAR
The character which immediately precedes the link name
of from 1 to 20 characters in length. The entire
link information area is given in the following example
(using the default special indicator characters)
@linkname^filename%searchname[highlight text]
Note - filename and searchname information is optional
If a file name is given with a blank or empty chapter
link name, then the file will be treated as an "unmarked"
file containing no chapters and presented accordingly.
fileChar : CHAR
The optional character which follows somewhere after the
linkChar and link name and before the beginning of the
link's highlightStart. If given, this designates
the file (other than the current file) where the indicated
link's chapter information may be found.
searchChar : CHAR
The optional character which follows somewhere after the
linkChar and link name and before the beginning of the
link's highlightStart. If given, this character is
followed by a search string. If this "search string"
is found (non case sensitive) in the linked chapter,
the first occurrence will be highlighted when that chapter
is displayed.
highlightStart : CHAR
The character which designates the beginning of the area
which should be highlighted when a link is shown.
highlightEnd : CHAR
The character which designates the end of the area
which should be highlighted when a link is shown.
prefixChar : CHAR
The character which procedes certain special effects
chacters (such as boldStart). If this character is
to be used in the text "as is", then it may be entered
twice (e.g. ^^).
boldStart : CHAR
The character which, when following the 'prefixChar',
indicates the beginning of bold text.
boldEnd : CHAR
The character which, when following the 'prefixChar',
indicates the end of bold text.
*)
PROCEDURE DefineColors
(CONST Normal : CHAR;
CONST highlightIn : CHAR;
CONST highlightOut : CHAR;
CONST searchFound : CHAR;
CONST Header : CHAR;
CONST footer : CHAR;
CONST sides : CHAR;
CONST Bold : CHAR;
CONST Help : CHAR;
CONST helpBorder : CHAR);
(**
DefineColors - Redefine the colors used by HyperText.
This procedure allows the redefinition of the colors
used by the HyperText system. These colors and their
defaults are as follows -
function color description
------------ ------------------ ------------------------------
normal 7 white on black normal text color
highlightIn 112 blank on white highlight link when cursor in
highlightOut 11 cyan on black ighlight link outside cursor
searchFound 14 yello on black string found in search
header 30 yellow on blue header color
footer 31 white on blue color of footer information
sides 48 blank on cyan color of side borders
bold 15 intense white bold color
help 47 white on green help area color
helpBorder 10 green on black help top and bottom border color
For a description of color numbers, reference the
ThorPort.SetAppearance procedure.
CALLING SEQUENCE -
DefineColors (normal, highlightIn, highlightOut, header, footer,
sides, bold, help)
ENTRY -
normal : CHAR
Color of the normal text of a chapter.
highlightIn : CHAR
The color of the highlighted part of a link when the
cursor is in that link area.
highlightOut : CHAR
The color of the highlighted part of a link when the
cursor is not in that link area.
searchFound : CHAR
The color of the portion of the string within the
text which matches the string search.
header : CHAR
The color of the general information at the top of
the display.
footer : CHAR
The color of the general information at the bottom of
the display.
sides : CHAR
The color of the border at both sides of the display.
bold : CHAR
The color of the text when bold is required.
help : CHAR
The color of the help area (when presented).
helpBorder : CHAR
The color of the help area border on the top and bottom.
*)
PROCEDURE DefineWindowMotion
(CONST topRowChange : INTEGER;
CONST leftColumnChange : INTEGER;
CONST heightChange : CARDINAL;
CONST widthChange : CARDINAL;
CONST minimumHeight : CARDINAL;
CONST minimumWidth : CARDINAL);
(**
DefineWindowMotion - Define a changing window.
This procedure defines a changing window for the
hypertext page display as the user moves through each
successive level of links. By default, the window
position and size remain the same as the original.
The window may be defined to change in location
and/or size as the user selects a link. The window
may never be larger than the original definition.
The window will continue to move as the link
selection is stacked until the required size can
no longer fit on the screen.
Using these options, a layered or drop down effect window
may be presented.
CALLING SEQUENCE -
DefineWindowMition (topRowChange, leftColumnChange,
heightChange, widthChange,
minimumHeight, minimumWwidth);
ENTRY -
topRowChange : INTEGER
The amount that the top row of the window
will change with each link selection. If
the number is negative, the window will move
up, positive will move down. For example,
if the original window was defined to be
positioned on row 1 and this value was +2,
then the first selected link would show a
window which was position beginning at
row 3, a link selected from that chapter
would display in a window beginning at row
5, etc.
leftColumnChange : INTEGER
The amount that the left column edge of the
window will change with each link selection.
If the number is negative, the window will
move left, positive will move right.
heightChange : CARDINAL
The number of rows that the windos wize will
be REDUCED BY with each successive link
selection.
widthChange : CARDINAL
The number of columns that the window size
will be REDUCED BY with each successive
link selection.
minimumHeight : CARDINAL
The minimum number of rows to which the window
should be allowed to shrink.
minimumWidth : CARDINAL
The minimum number of columns to which the window
should be allowed to shrink.
*)
PROCEDURE OptimizePerformance
(CONST optMethod : optType);
PROCEDURE CaseSensitivity
(CONST upperLowerCase : BOOLEAN);
(**
CaseSensitivity - Set the case sensitivity for links.
This procedure sets the upper/lower case sensitivity for
the link references within the hypertext source file.
Iff 'upperLowerCase' is set, then the upper and lower
case of ASCII characters for each link reference is
honored (e.g. ABC < Abc < abc in ASCII sort order).
By default, when the 'HyperTxt' library is used,
upper/lower case sensitivity is set to FALSE (all
ASCII characters compare as upper case characters).
CALLING SEQUENCE -
CaseSensitivity (upperLowerCase)
ENTRY -
upperLowerCase : BOOLEAN
Search and compare is upper and lower case sensitive
(TRUE) or all character compare as upper case (FALSE).
*)
PROCEDURE ExitInformation
(VAR currentChapter : ARRAY OF CHAR;
VAR nextChapter : ARRAY OF CHAR;
VAR exitFunction : CARDINAL);
(**
ExitInformation - Return information about the last exit.
This procedure returns information about the last exit
from hypertxt. This information remains in the hypertext
library until again executed.
CALLING SEQUENCE -
ExitInformation (currentChapter, nextChapter, exitFunction)
EXIT -
currentChapter : ARRAY OF CHAR
The chapter in which the user was resident when the
hypertext session was terminated.
nextChapter : ARRAY OF CHAR
The next chapter to which the user would have gone
if a forward reference were requested instead of
a hypertxt exit.
exitFunction : CARDINAL
The type of exit requested. This would normall be
one of the following -
21) exit1 Terminate the hypertext session
22) exit2 Return to the previous chapter
25-30) exit5-exit10 Terminate the hypertext session
41-60) exit11-exit30 Terminate the hypertext session
*)
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance