ActionScript - Adding Integrated Help

ActionScript - Adding Integrated Help
Table of Contents

The propietary built-in Flash help viewer is pretty clunky and not particularly useful. However, it is fairly easy to add basic support.

The propietary viewer has 4 parts

Section	Location	Comment
Main help display	On the right	Displays an html file
Search field	On left, Top	This has a Text Field, Search button, and a Clear button
Book Selector	On left, below Search Field	This ComboBox displays the contents of categories.xml
Tree View	On left, lower part of the frame	This is the main navigation aid - controlled by the help_toc.xml files, one per directory

In case you haven't guessed, I don't think much of propietary viewers ... but this one does have a nice tree view. By the way, the search is terrible ... really third rate.

Controlling the Tree Display | categories.xml | help_toc.xml - book tag level tags | Simple Procedure

Controlling the Tree Display

On my system, the Flash built in help is located at

C:\Documents and Settings\All Users\Application Data\Adobe\Flash CS3
  \en\Configuration\HelpPanel

The Book Selector ComboBox (used to select which sections to see) is defined in

categories.xml

The text displayed in the Tree View is specified in the

help_toc.xml

files - one for each subdirectory / section / book.

categories.xml

categories.xml controls what is displayed in the Book Selector ComboBox. When one of the options is selected, the keyword is used to control what is displayed in the Tree View just below it.

This file is fairly simple to understand - the following example is based on the actual file.

<?xml version="1.0" encoding="UTF-8"?> <helppanel> <category title="ActionScript 3.0 Components" keyword="components3"></category> <category title="3rd Party" keyword="3rdparty"></category> </helppanel>

title	This is displayed in the Book Selector ComboBox
keyword	This is used to limit the contents of the Tree View

help_toc.xml

Every top level help directory contains a help_toc.xml file that specifies

What is shown in the Tree View
What order the entries are in
What html file should be displayed

For all practical purposes, help_toc.xml has 2 sections

The book tag - describes the main entry and controls when it will be displayed
The level tags - one for each additional entry

help_toc.xml - book tag

The book tag (the second line) controls what is displayed at the top level of the help tree display. (The following example is formatted to improve readability.)

<book 
  title      = "ActionScript 3.0 Language and Components Reference" 
  directory  = "ActionScriptLangRefV3" 
  categories = "languagereferences,as3,components3" 
  language   = "en" 
  version    = "3.0" 
  sort       = "mm_3"
>

title	This is displayed at the top level of the Tree View
directory	Just the directory your files are located in
categories	These control what is displayed when a category is selected from the ComboBox - they match the keywords in categories.xml. When you create a directory, add 3rdparty
sort	This controls the position of the entry in the Tree View - the existing directories use "mm_1" through "mm_16", "mm_a" will be first
...	The rest are self explanitory

help_toc.xml - level tags

Under the main heading, the level tags define the tree structure. Levels are numbered 1 thru 4 (and perhaps higher) and contain 2 parameters

name	This is displayed in the Tree View
href	The name of the associated html file

Example (from "ActionScriptLangRefV3\help_toc.xml" - slightly modified to be more readable)

Because this is xml, you can add spaces and tabs between elements as you see fit ... they will be ignored.

Because the parameters are named, their order is not important.

Based on

The code I've seen
The lack of formatting in some xml files
The use of Tabs in some xml files
The fact that the parameter order varies

I assume that Adobe is using some kind of help generation program to automatically generate these files from tags inside their *.as files and a different tool for help not specific to classes.

Simple Procedure

To add your own help

Create a directory
Create (copy and modify) an help_toc.xml file
Create html files

The xml files are only read when Flash starts ... you must restart Flash to see the changes.

Author: Robert Clemenzi - clemenzi@cpcug.org