|
|
|
|
| CaseSensitivity | DefineColors | DefineFileMarkers | |
| DefineWindowMotion | ExitInformation | OptimizePerformance | ShowHyperText |
type optType is (sizeOpt,
speedOpt);
procedure OptimizePerformance
(optMethod : in optType);
--*
-- OptimizePerformance - Optimize operation for memory or speed.
--
--
-- This procedure allows the user to set the method of optimization
-- for the next hypertext session. By default, it is optimized for
-- speed and will allocate sufficient available buffers for that
-- purpose. If requested to be optimized for memory size, minimal
-- size memory buffers are allocated from the heap during operation.
-- In the later case, the speed of execution will slow down but
-- hypertext will remain functional.
--
-- CALLING SEQUENCE -
--
-- OptimizePerformance (optMethod)
--
-- ENTRY -
--
-- optMethod : optType
-- The method of optimization to perform during the next
-- hypertext session. Set to 'sizeOpt' if miminum memory
-- is to be used. By default, this parameter is set to
-- 'speedOpt'.
--
procedure CaseSensitivity
(upperLowerCase : in boolean);
--*
-- CaseSensitivity - Set case sensitivity for links.
--
--
-- This procedure sets the upper/lower case sensitivity for
-- the link references within the hypertext source file.
-- If 'upperLowerCase' is set to TRUE, 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 DefineColors
(Normal : in ModSys.S_Natural;
highlightIn : in ModSys.S_Natural;
highlightOut : in ModSys.S_Natural;
searchFound : in ModSys.S_Natural;
Header : in ModSys.S_Natural;
footer : in ModSys.S_Natural;
sides : in ModSys.S_Natural;
Bold : in ModSys.S_Natural;
Help : in ModSys.S_Natural;
helpBorder : in ModSys.S_Natural);
--*
-- DefineColors - Redefine 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 highlight link outside cursor
-- searchFound 14 yellow 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 & 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, helpBorder)
--
-- ENTRY -
--
-- normal : ModSys.S_natural
-- Color of the normal text of a chapter.
--
-- highlightIn : ModSys.S_natural
-- Color of the highlighted part of a link when the cursor is in that
-- link area.
--
-- highlightOut : ModSys.S_natural
-- Color of the highlighted part of a link when the cursor is not in
-- that link area.
--
-- searchFound : ModSys.S_natural
-- Color of the portion of the string within the text which matches
-- the string search.
--
-- header : ModSys.S_natural
-- The color of the general information at the top of the display
--
-- footer : ModSys.S_natural
-- The color of general information at the bottom of the display.
--
-- sides : ModSys.S_natural
-- The color of the border at both sides of the display.
--
-- bold : ModSys.S_natural
-- The color of the text when bold is required.
--
-- help : ModSys.S_natural
-- The color of the help area (when presented).
--
-- helpBorder : CHAR
-- The color of the help area border on the top and bottom.
--
procedure DefineFileMarkers
(chapterChar : in character;
linkChar : in character;
fileChar : in character;
searchChar : in character;
highlightStart : in character;
highlightEnd : in character;
prefixChar : in character;
boldStart : in character;
boldEnd : in character);
--*
-- DefineFileMarkers - Define signal characters for 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 highlight start
-- highlightEnd ']' char. designating 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 : character
-- 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 : character
-- 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 : character
-- 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 : character
-- 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 : character
-- The character which designates the beginning of the area which
-- should be highlighted when a link is shown.
--
-- highlightEnd : character
-- The character which designates the end of the area which should
-- be highlighted when a link is shown.
--
-- prefixChar : character
-- The character which precedes certain special effects characters
-- (such as boldStart). If this character is to be used in the
-- text "as is", then it may be entered twice (e.g. ^^).
--
-- boldStart : character
-- The character which, when following the 'prefixChar', indicates
-- the beginning of bold text.
--
-- boldEnd : character
-- The character which, when following the 'prefixChar', indicates
-- the end of bold text.
--
procedure DefineWindowMotion
(topRowChange : in ModSys.S_Integer;
leftColumnChange : in ModSys.S_Integer;
heightChange : in ModSys.S_Natural;
widthChange : in ModSys.S_Natural;
minimumHeight : in ModSys.S_Natural;
minimumWidth : in ModSys.S_Natural);
--*
-- 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 -
--
-- DefineWindowMotion (topRowChange, leftColumnChange, heightChange,
-- widthChange, minimumHeight, minimumWidth);
--
-- ENTRY -
--
-- topRowChange : ModSys.S_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. E.g., if the original
-- window was defined to be positioned on row 1 and this value is
-- +2, then the first selected link would show a window which was
-- positioned beginning at row 3; a link selected from that
-- chapter would display in a window beginning at row 5, etc.
--
-- leftColumnChange : ModSys.S_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 to the left; positive, to the right.
--
-- heightChange : ModSys.S_natural
-- The number of rows that the window size will be REDUCED BY with
-- each successive link selection.
--
-- widthChange : ModSys.S_natural
-- The number of columns that the window size will be REDUCED BY
-- with each successive link selection.
--
-- minimumHeight : ModSys.S_natural
-- The minimum number of rows to which the window should be allowed
-- to shrink.
--
-- minimumWidth : ModSys.S_natural
-- The minimum number of columns to which the window should be
-- allowed to shrink.
--
procedure ExitInformation
(currentChapter : in out string;
nextChapter : in out string;
exitFunction : out ModSys.S_Natural);
--*
-- 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 : string
-- The chapter in which the user was resident when the
-- hypertext session was terminated.
--
-- nextChapter : string
-- The next chapter to which the user would have gone
-- if a forward reference were requested instead of
-- a hypertxt exit.
--
-- exitFunction : ModSys.S_natural
-- 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 ShowHyperText
(FileName : in string;
chapterName : in string;
firstLine : in ModSys.S_Natural;
lastLine : in ModSys.S_Natural;
leftColumn : in ModSys.S_Natural;
rightColumn : in ModSys.S_Natural;
successful : in out 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. Be sure to leave enough space 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 '[' char. designating highlight start
-- highlightEnd ']' char. designating highlight end
-- prefixChar '^^' Prefix character for special effects
-- boldStart 'B' Start of bold (follows prefixChar)
-- boldEnd 'b' End of bold (follows prefixChar)
--
-- 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 headings were shown:
--
-- <ff>* Sample HyperText Chapters
-- <ff>SubjectA
--
-- The name of the first chapter is "*". Notice that a blank acts as
-- a delimiter. The text which follows the "*" is part of the text.
-- The name of the second chapter shown is "SubjectA", and because no
-- 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 a file named "DFILE". When the chapter is located, the first
-- occurrence of "select" will be found, highlighted, and the cursor
-- positioned there. The user will be shown the link as the high-
-- lighted 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.
--
-- If a link contains a reference to another file but the name
-- of the chapter to link to is left empty, then the file will
-- be assumed to be an unmarked file and treated accordingly.
--
-- CALLING SEQUENCE -
--
-- ShowHyperText (fileName, chapterName, firstLine, lastLine,
-- leftColumn, rightColumn, successful)
--
-- ENTRY -
--
-- fileName : string
-- Name of hypertext file.
--
-- chapterName : string
-- The name of the first chapter to be shown of the given file.
-- 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 exist.
--
-- firstLine : ModSys.S_natural
-- Top line of screen where text should appear (1..n).
--
-- lastLine : ModSys.S_natural
-- Bottom line of screen where text should appear (firstLine..n).
--
-- leftColumn : ModSys.S_natural
-- Left-most column on screen where text should appear (1..80).
--
-- rightColumn : ModSys.S_natural
-- Right-most column on screen where text should appear
-- (leftColumn..80).
--
-- EXIT -
--
-- successful : boolean
-- Access and processing of file was successful (TRUE).
--
-- EXAMPLE -
--
-- with CmndLine;
-- with HyperTxt;
-- with Display;
--
-- procedure HyperT is
-- fileName : SageSpec.LongPathType := (others => ASCIIX.nul);
-- done : boolean := false;
-- begin
-- CmndLine.GetCommandField (1,fileName,done);
-- if done then
-- Display.DefineFunctionKey (8, character'val(0),character'val(59));
-- Display.DefineFunctionKey (21,character'val(0),character'val(68));
-- Display.DefineFunctionKey (22,character'val(27),character'val(0));
-- HyperTxt.DefineWindowMotion (2,4,2,5,20,0);
-- HyperTxt.ShowHyperText (fileName,"",1,24,1,80,done);
-- end if;
-- end HyperT;
--
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance