| << Prev | - Up - |
The Help module provides two classes and one procedure.
The Hyperlink class manage pages and tags definitions, and is able to fill a Tk or QTk entry with the interpreted contents of a page.
The DefaultBind procedure defines all default tag bindings described in the previous chapter.
The HelpClass extends the Hyperlink class to support a complete GUI for help files, including an automatically built tree and search facilities.
The Hyperlink class manages pages :
store pages (in a dictionary)
store tags definitions (in a dictionary)
parse a text page definition into an inner format
parse text file with several pages
The format used for storing pages is a list composed of two different types of elements :
string
record of the form tagname(1:Param1 2:Param2 ...)
For example the default parser will transform : Hello <b>world</f|times 20> into "Hello "|f|"world"|'/f'(1:"times 20")|nil. As shown, all tags have been transformed into records whose features are the parameters of the tags. The list is composed of strings that are the text to insert and of these records that are the tags notification.
The tags definition are also stored in a dictionary. The name of the tag is used as the key in the dictionary. The definition of a tag may have three different forms (single tag, starting tag of paired tags, ending tag of paired tags) :
alone(cmd:P) : Define a not paired tag. P is a one parameter procedure specifying the action to execute when this tag is met (see below).
on(cmd:P) : Define the starting tag of paired tags. P is a one parameter procedure specifying the action to execute when this tag is met (see below) (not required).
off(cmd:P on:R) : Define the ending tag of paired tags. P is a one parameter procedure specifying the action to execute when this tag is met (see below) (not required). R is the label of the starting tag (required) corresponding to this ending tag.
The procedure defined by the tags are called when the tag is met. The parameter of this procedure is bound to a record providing the following informations :
widget : a handle to the QTk text widget displaying the help text (see QTk documentation).
toplevel : a handle to the QTk toplevel window where the help text is displayed (see QTk documentqtion).
id : a unique identifier that can be specified when opening the text window (see global reference).
ctags : a list of all currently appliable tags.
tag : a QTk text tag for the text between the tags (see QTk documentation).
X : where X is an integer. Bound to the Xth specified parameter of the tag, if any.
The Hyperlink class implements the following methods :
init : constructor method. Do not set a default binding for tags.
reinit : empties all data structures of the object
put(K D) : stores a page named K, with definition D.
get(K $) : returns the definition of the page named K.
remove(K) : removes the page named K from the object.
entries($)) : returns a list of pair pagename#pagedefinition for all pages.
keys($) : returns a list of all page names.
items($) : returns a list of all page definitions.
parseText(Txt $) : parses the text Txt and returns the equivalent page definition. Overwrite this method if you want to change the default text parser.
putText(K Txt) : stores a page named K with the definition parsed from the string Txt.
parseHelpFile(Filename) : loads the file Filename, separates it into several pages (two pages are separated by two blank lines), get the page name from the first line and page definition from the pending lines and call the putText method to store it. Overwrite this method if you want to change the way a text file is split into pages.
saveHelpFile(Filename) : writes all stored pages into the specified file Filename.
loadHelpFile(Filename) : stores all pages that are in the file Filename.
setFormat(T F) : sets the tag definition F for the tag T.
getFormat(T $) : returns the tag definition of the tag T.
fillEntry(K T id:ID) : fills a Tk or QTk text entry T with the contents of the page K. An ID can also be specified : when a tag defines a command, the parameter of the command is a record with a feature id that is set to the value of ID. ID is usefull if you want to associate a context to the tags.
getQTk(K id:ID $) : returns a QTk definition of the page named K. An ID can also be specified : when a tag defines a command, the parameter of the command is a record with a feature id that is set to the value of ID. ID is usefull if you want to associate a context to the tags.
getText(K $) : returns a string that is the text contents of the page named K (the tags are removed).
The DefaultBind takes a Hyperlink object as parameter and binds default commands for tags. The previous chapter lists all these bindings. However these bindings are different :
<link> and </link|...> : sets the text in blue and underlined, change the mouse cursor to a finger when over the text, but do nothing if the text is clicked (no default action defined).
<oz>, <toz> and </toz> are not defined at all.
The HelpClass class inherits from the Hyperlink class and extends it to offer a complete GUI. This class voerwrites and implements the following methods :
init : constructor method, it sets the default bindings for the tags.
openHelpWindow(K) : opens a help window and displays the page named K.
| << Prev | - Up - |