2 Tutorial Example : using the default configuration

functor 
 
import 
   Help(helpClass:HelpClass)
   Application
 
define 
    
   Hlp={New HelpClass init}
 
   {Hlp parseHelpFile("Help.txt")}
   {Hlp openHelpWindow(home)}
 
   {Application.exit 0}
end

Assuming Help.txt contains :

home
<title|Home help page>This is a sample help file. 
Lets try  <b>bold</b>, <i>italic</i>, <bi>bolditalic</bi>, <b>bold <i> italic </i> <u>und</b>erlined</u>. 
This is a link : <link>link</link|link>. This is normal text. 
<bitmap|warning><link>Font test page</link|fonts> 
<blink>Blinking text</blink> 
Normal text. 
<p> 
<p> 
<right>Right centered</right> 
<center><blink><u><f>Center centered</f|times 30></blink></u></center> 
<left>Left centered</left> 
<link>Link to this page</link|home> 
<link>Mozart link</link|http://www.mozart-oz.org> 
 
 
link
<title|Link help page>This is a link ! 
<foreground|yellow><background|red>This page should display in red ! 
<blink>BLURPS</blink>

Compiling and running the above program :

2.1 Oz code

The Oz code is straightforward to understand :

• A HelpClass object is created.

• The parseHelpFile method loads the specified file and parse it.

• The openHelpWindow method opens up the help window, displaying the specified help page.

In the simplest case were you don't want to redifine help text parsing, the action of the tags, or have advanced control over the help window, you just have to do this. If you have further need, check the reference documentqtion.

2.2 Help.txt file

The Help.txt file is structured in two pages : home and link. Each pages starts by the page name on the first line, the page definition on the following lines. A page terminates by two blank lines, the next page starting right after these two blank lines.

The page definition is composed of text and tags. The text is inserted as is, the way it is displayed can be modified by tags. Tags come in two flovours :

• Single tags : <title> and <background> for example are single tags modifying a global state of the help window. <bitmap> is another example of single tags, which have a ponctual action.

• Paired tags : <b> and </b> for example are paired tags. They have a local effect on the text comprised between them. Usually, the closing tag is like the opening tag with a "/" right after "<".

Tags may have parameters. In such a case, all parameters follow the tag name using "|" as separator : <tag|param1|param2|...> The different tags in this example are :

• <title|...> : Specifies a title to set for the help window. It is a good habit to always start a page definition by this tag.

• <b>...</b> : Sets the text in bold.

• <i>...</i> : Sets the text in italic.

• <bi>...</bi> : Sets the text in bold and italic.

• <u>...</u> : Underlines the text.

• <link>...</link|...> : Defines a link. The text included by the tags will be displayed in blue and underlined and the mouse cursor is changed to a finger when placed over it. Clicking on the text does the following actions, depending on the parameter given to the </link|...> tag :

  • parameter of the form http://... : a web browser is started, displaying the specified url

  • parameter of the form file://... : a web browser is started, displaying the specified file

  • other forms : the specified help page is displayed

• <bitmap|....> : displays a built-in bitmap.

• <blink>...</blink> : Sets the text to blink.

• <right>...</right> : Right justify the text.

• <center>...</center> : Center justify the text.

• <left>...</left> : Left justify the text.

• <f>...</f|...> : Sets the text in the font specified by the </f|..> tag parameter.

• <foreground|...> : Sets the foreground to the specified color.

• <background|...> : Sets the background to the specified color.

• <p> : Inserts a new line. With <p>, pages with two blank lines can be created.