|
|
|
|
| CaseSensitivity | DefineColors | DefineFileMarkers | DefineWindowMotion |
| ExitInformation | OptimizePerformance | STRExitInformation | STRShowHyperText |
| 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); overload; stdcall;
exports 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) name 'HyperTxt_ShowHyperText';
//*
// 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 begin
// 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 ShowHyperText
(const FileName : string;
const chapterName : string;
const firstLine : cardinal;
const lastLine : cardinal;
const leftColumn : cardinal;
const rightColumn : cardinal;
var successful : boolean); overload; stdcall;
exports ShowHyperText (const FileName : string;
const chapterName : string;
const firstLine : cardinal;
const lastLine : cardinal;
const leftColumn : cardinal;
const rightColumn : cardinal;
var successful : boolean) name 'HyperTxt_STRShowHyperText';
//*
// STRShowHyperText - See documentation of ShowHyperText.
//
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); stdcall;
exports DefineFileMarkers name 'HyperTxt_DefineFileMarkers';
//*
// 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); stdcall;
exports DefineColors name 'HyperTxt_DefineColors';
//*
// 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); stdcall;
exports DefineWindowMotion name 'HyperTxt_DefineWindowMotion';
//*
// 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); stdcall;
exports OptimizePerformance name 'HyperTxt_OptimizePerformance';
procedure CaseSensitivity
(const upperLowerCase : boolean); stdcall;
exports CaseSensitivity name 'HyperTxt_CaseSensitivity';
//*
// 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); overload; stdcall;
exports ExitInformation (var currentChapter : array of char;
var nextChapter : array of char;
var exitFunction : cardinal) name 'HyperTxt_ExitInformation';
//*
// 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
//
procedure ExitInformation
(var currentChapter : string;
var nextChapter : string;
var exitFunction : cardinal); overload; stdcall;
exports ExitInformation (var currentChapter : string;
var nextChapter : string;
var exitFunction : cardinal) name 'HyperTxt_STRExitInformation';
//*
// STRExitInformation - See documentation of ExitInformation.
//
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance