Defining your Menu

There are two functions that you use to define your menu. These are addEntry and addChild. You will find examples of these in the initialise function (In general, the initialise function is where you will define all your outline entries).

Adding Entries to the Menu

addEntry adds an entry to the menu at a specified position and returns an ID number for the new item.

theMenu.addEntry (menuItem, entryIcon, entryText, URL, statusText);

Adding Children to an Existing Entry

addChild is just like addEntry except that instead of adding the new entry after and at the same level as menuItem, it adds the entry as a child of menuItem. If menuItem already has child entries, the new entry is added after the last one.

theMenu.addChild (menuItem, entryIcon, entryText, URL, statusText);

Modifying Properties of an Existing Entry

Once you have added a menu entry, there are a number of extra properties you can set. Full details of these can be found in the Properties and Methods section of the documentation. Note that the data type of each property is shown in brackets.

To modify a property of a menu item, you should insert a line like this:

theMenu.entry[entryID].propertyName = propertyValue;

Where entryID is the ID of the menu entry returned by the addEntry or addChild function used to create it. For example, the following code creates a new menu entry called 'The Basics', stores it's ID in the variable "level1ID" and then sets it's initial state to open.

level1ID = theMenu.addEntry(-1, "Folder", "The Basics", "", "");
theMenu.entry[level1ID].isopen = true;

Note: target, CSSClass, onClick, onMouseOver, onMouseOut and onToggle are strings and must be supplied within quotation marks. e.g.

theMenu.entry[level1ID].target = "_top";
theMenu.entry[level1ID].onClick = "alert('Thank you for visiting.');";

A Note about the Example Code

The example initialise function that ships with Joust builds the menu for this documentation. This code makes use of three variables: level1ID, level2ID, and level3ID. These are temporary variables that are used to hold the ID of a new entry only for as long as it is needed. For example:

level1ID = theMenu.addEntry(-1, "Folder", "Level 1, Entry 1", ...

adds a new entry to the empty menu and stores it's ID (which will be 0) in level1ID. The next line adds a new child entry to the entry we just created above:

level2ID = theMenu.addChild(level1ID, "Document", "Level 2, Entry 1", ...

The first parameter tells the addChild where to add the new entry. In this case we add the new entry to the entry pointed to by level1ID (Level 1, Entry 1). Because we are going to need to remember level1ID for later, we store the ID of this latest entry in the variable level2ID. Now, let's add another child to "Entry 1":

level2ID = theMenu.addEntry(level2ID, "Document", "Level 2, Entry 2", ...

We use the addEntry function this time to add a new entry after the entry pointed to by level2ID (Level 2, Entry 1). Because we are not going to add children to "Level 2, Entry 1", we don't need to remember its ID anymore so we have reused the level2ID variable.

After we have finished adding all the children to "Level 1, Entry 1" we will add a new entry after it and at the same level;

level1ID = theMenu.addEntry(level1ID, "Folder", "Level 1, Entry 2", ...

Once this command has completed, we don't need to know the ID of "Level 1, Entry 1" any more so we can reuse level1ID to store the ID of "Level 1, Entry 2".

The choice of variable names and the order in which the entries are defined is entirely up to you. As long as you supply a valid ID of an existing entry in the first parameter of the addEntry and addChild functions, Joust does not care what order you add your entries.

The Joust Outliner