Autofill Field Element

The AutoFill Field Element uses a list of keywords to guess and fill in the phrase that the user is trying to type. This list of words can be loaded at launch time using the Autofill list file specified in the project file, or it can be added dynamically at runtime using the AutoFill Command. The Autofill keyword lists have a name, allowing you to have several different lists in a project.

To create a list that will be loaded at Launch, open the project file, and specify a location and file name in the URL field under the AutoFill line in the ZebraTools section, then click on the Create button. This will create a file in that location that is formated correctly. You will need to replace the list of words in the file with the words that you need.

See also the Autofill project setting for related functionality and documentation.

Def Text Element

The Def Text Element is used to display definitions for words in a Zebra Text element. It loads its data from the result of a Zebra Text definitions query.

See also Zebra Text Element, ZT Def Data, Defs project setting and Definitions Engine for related functionality and documentation.

Map Image Element

The Map Image Element is used in project maps. It browses to a screen when a user clicks on that screen's thumbnail, presenting a zoombox when it does so, to give the impression of the thumbnail enlarging. It will keep track of which screens have been visited and gives a check mark for those screens. It also presents a zoombox from the entire screen down to the thumbnail when the user goes to the map from another screen. The Map Image Element has one attribute that you need in to know about: The CoordListName attribute is the name of the Coordinate List in the map data file that represents this image. Also, since the map data file only specifies the bounding box for a thunbnail, if you have non-rectangular shpaes, you should also alter the hotspot of the map image element to block out disabled areas of the image, so that they cannot receive clicks.

When the user clicks on a thumbnail, if it represents a screen to go to, the map Image will broadcast the message "ZT Map Goto Screen" with the absolute URL to go to in the Message In. If the thunbnail represents a collection of screens, and is to bring up a pop-up, then the map image broadcasts the message "ZT Map Load Submap" with the name of the subscreen document as the message in.

Subscreens should be iShell documents containing the sub-map image element. In the map data file, the collection of map data for the main map should be called "background", the others can be named whatever.

The Map Image Element draws the necessary information for its behavior from the Map Data File specified in the Project file. This file has a very specific format, and can be created using the ZebraTools MapCreator program. This will create a file that has all of the necessary info, and is written in key code, so you can open in it a text editor, and make changes. Each screen in the Map Data file is specified with the following code:

cZTMapItem with
      X is 189; Y is 113; Width is 108; Height is 71; -- blendtweener
      CheckMarkX is 278; CheckMarkY is 129; Visited is false; Popup is false;
      URL is "Media/BlendTweener/BlendTweener.xd";
end,

• The X, Y, Width and Height specify the bounding box of anything that can be clicked on in the Map Image Element to go to that screen (thumbnail, text description, etc). These are all measured in pixels, and are relative to the top left corner of the Map image Element, not the screen.
• CheckMarkX and CheckMarkY specify the location of the checkmark for screen visited.
• Visited stores which screens have been visited, and should initially be set as false.
• Popup specifies whether that thumbnail is to bring up a sub-map of a collection of screens. The MapCreator will not specify which items bring up a sub-map. To specify these, you will need to open the file in a text editor, and change Popup to true. The sub-map needs to be an additional Map Image Element in it's own document. The MapCreator program will create a collection in the Map Data File for each Map Image Element.
• The URL field is the url relative to the project file that should be browsed to if the user clicked on the thumbnail (if popup is false) or the name of the .xd file that should be loaded (if popup is true).

We strongly recommend that if you are creating a project map, you start with the sample map included within the demo project.

See also the Map Creator program for related functionality and documentation.

Menu Box Element

A Menu Box Element handles the drawing of a box around the Menu Item Elements following it.

See also Menu Item Element and Menu Command for related functionality and documentation.

Menu Item Element

Menu Item Elements are used for the individual items in a drop-down menu. Each element has Text, which will show up as the text in the menu, and a URL for the link when that menu item is clicked on. The position of each Menu Item is calculated automatically based on the position of the menu and the size of the text.

A drop-down menu should start with a Menu Item Element specified as a "Root menu object", with the starting coordinates of the pull-down menu specified. All other coordinates will be calculated from this.

If a Menu Item Element contains other Menu Item Elements, they will automatically show up as a sub-menu of that Menu Item.

See also Menu Box Element and Menu Command for related functionality and documentation.

Password Element

The Password Element is a modified field, where the text is displayed on-screen as a series of dots. The actual text typed can be accessed with a Get Attribute [Password Text] command.

Zebra Text Element

The Zebra Text Element is a text element that automates handling definitions and/or expanding text with headers.

Headers are specified in the text file by the presence of struck-through text starting and ending with the header tags <<< and >>>, such as <<<This is a Header>>> . The headers should be on their own line in the RTF, i.e. they should have a paragraph return both before and after them, and should be followed by the text to be included under that header. This element will automatically display the text with the first header expanded (but gives you the option to collapse all headers instead), and will automatically expand each header when clicked on.

See also Switch Header Command and Header Changed Event for related functionality and documentation.

The ZebraText element also has an attribute for "Show Defs". If this is checked, when the user clicks on a word, ZebraText will try and determine what word the author determined should be defined. There is no formatting required in the RTF files for definitions to work for single words, although if phrases are to be defined, then the entire phrase will need to be struck-through. I.e. the text "head to toe" would look for definitions for "head", "to", or "toe", depending on which word was clicked on; the text "head to toe" would look for a definition for the entire phrase "head to toe". The Definitions engine then attempts to find a defintion for the phrase, and if one is found, it will broadcast the message "Nav Load Defs", to initiate the loading of the Definitions sub-document. To build the list of definitions, we have provided a much more in depth discussion of the Definition engine here .

See also Def Text Element, ZT Def Data, Defs project setting and Definitions Engine for related functionality and documentation.

ReOrderable Column Data Kind

If you change a table the is set to a column kind to a ReOrderable Column Kind, it will behave identically, except that it you click and drag a cell, it will let you release the cell elsewhere in the list, and it will re-order the table to match.

TextTrack Data Kind

The TextTrack Data kind will take a specially formatted table, such as this one...

INTEGER STRING
EndTime theText
60 This is a text
120 track that is driven
180 by a table file.
240 The numbers in the first column
300 of the .tab file determine
360 at what time in ticks the text
420 should display until.
480`

And display the contents of column 2 at the time in ticks specified in column 1.

AutoFill Register Command

The Autofill Register Command adds a list of autofill keywords that can be used by an autofill Field object. You can specify any name, whether it exists or not. The list you are passing in should be a list of strings. The command will sort the list of keywords for you, to ensure the fastest search times.

If the list of words does not need to be created on the fly, it is strongly recommended that you use an Autofill file to enter your lists.

Browse Back To Command

The Browse Back To Command is similar to the Go Back Command, but it goes back to the specified screen. It clears any screens from the back list between the current screen and the new screen.

Data Command

The Data Command is ideal for sorting through large amounts of data on a single search term. It uses the same algorithm that the definitions engine uses, and requires data in the same format. It is only worth using when you are searching a large amount of data (>1000 values) and need a speed boost, since the up front effort to create the data files is significant.

When you use the data Command, you need to tell it what string you are looking for, which index file to look in, and what the size of the data chunks are in the data file (not including the offset and size data). If your index file is callled "whateverIndex.dat", your content file needs to be in the same place and called "whateverContent.dat".

The Data command uses two files to get a result. The index file is a list of values, padded with spaces to make them all a consistent length. The values are sorted, so that the search algorithm can start in the middle of the file, and narrow down the search very quickly. Searching through 100,000 values will take a maximum of 13 disk queries. There is also a hexadecimal value after each value. The first six characters of the hex value represents the offset position of the result data in the content file. The other three characters represent the length of the result data. This means the Content data file is limited to 16 MB in size, and the longest any single result can be is 4kB.

Obviously, the data files are not created manually. The preferred method of creating them is using a php script to pull the values from a database, and calculate the offsets. For an example of this, look at the php scripts for creating and downloading the definitions database

Hit Command

The Hit Command tests to see which object would receive a mouse down command at the coordinates specified, and returns that object as a target.

If Element Command

MD5 Command

To prevent someone looking at your .xd files and figuring out your license generation algorithm, we have also supplied a modified MD5 algorithm that generates unique fingerprints based on your iShell licensee name and ZebraTools license. You can use this for added security, but it means you are restricted to generating matching keys from within iShell. It is also wise to wrap your project to prevent someone reverse engineering it.

Using Password Protection…
Suppose you want a user to create an account, then, on subsequent visits, use their user name and password to log. You need to keep track of whether they should be allowed to log in or not. This means saving something to a file on the hard drive to verifiy their password. If you store the user name and password in a table on the disk, then anyone who finds that file has everything they need to log in. That isn't very secure at all.

If, however, you add the name and password together, and throw in some additional string (just for a bit of added security), MD5 the whole lot, and store the result of the hard drive, then even if someone finds the file, they won’t have any hope of reverse engineering the password. When someone tries to log in, you can add the strings together again, MD5 it, and if the result matches the fingerprint on the disk, you let them in.

Generating Licenses…
If you want to offer some copy protection for your title, you can use MD5 to produce license keys for specific users. This does not stop the user from passing their license around, but since it will only work for their name, it means that you can always trace it back to them, hopefully making them more reluctant to share. Here’s how you do it...

When they buy the software, you can get their name and company name. Make a single string out of all of this info, MD5 it, and give the first 12 characters to them as their license code. To verify their license, have them enter their info and license, and check for a match.

Menu Command

The Menu Command is useful for providing alternative navigation (like keyboard navigation) through the pull-down menu. Go Up/Down/Left/Right can be used to move through the menu, and Goto Menu acts as if the specified Menu Item had been clicked on. The Select Menu option opens the menu to the specified Menu Item.

See also Menu Item Element and Menu Box Element for related functionality and documentation.

Save Globals Command

The Save Globals Command lets you Read/Write the Global variables to a specified location, enabling you to have a different set of Globals per user, per exercise, etc.

Spackle Movies Command

The Spackle Movies Command is used to Hide/Show all Movies on a screen. This is needed when you have Elements (dialog boxes, menus, etc.) that you would like to show up on top of a movie. Additionally, when the Spackle Movies Command is called to Hide Movies, you can specify an Element as "don't show movies unless _____ is hidden", so that the movies will be automatically re-shown once that Element is hidden.

String To Target Command

The String To Target Command searches for any Elements whose name is/contains/begins with/ends with the specified string, and returns any found Elements as Targets. You can chose to search all objects currently loaded, or to look just within the current document, or down the hierarchy from the current element. you can also choose to either return the first or last object found, or to return a list of all objects found.

Switch Header Command

The Switch Header Command is used with a Zebra Tools Text Element. It switches which header of the text is currently expanded. If it is set to <all headers closed>, then all headers will be closed. If a header is specified, then that header will be opened. If the specified header is already open, then it will be closed (unless Don't Collapse is checked, then nothing will happen).

See also Zebra Text Element and Header Changed Event for related functionality and documentation.

Text Command

The Text Command is used to get pixel widths of a Text or Field Element. You can choose to either get the width of the longest line in the element, or to get the width of the line that contains a specific offset.

Write File Command

The Write File Command is used to Open, Write To, and Close a file. It can be used with a file that already exists, or it can be given a new filename and will create the file. The advantage of this command is that itwrites to the file as you go, allowing you to write files of any size without a significan memory overhead.

Zoom Box Command

The Zoom Box Command draws an inverted rectangle frame, zooming from and to the outlines of the objects specified, in the number of steps specified.

ZT Log Command

The ZebraTools Log Command is a Log Command with a second parameter added. Useful for when you want to output a description and a variable, or two variables, etc.

Header Changed Event

The Header Changed Event is called when a Zebra Tools Text Element has a change of header, either by a user clicking on a header, or a Switch Header Command being called. You can specify that the event only occurs when the header change is or is not a specific header, or if no header is specified then the event occurs for each header change. See also Switch Header Command and Zebra Text Element for related functionality and documentation.

ZebraTools Project Settings

Defs

The first pull-down in this line allows you to choose between trying to find definition, or simply displaying a message of your choice.
If From... is selected in the pull-down, then the Defs URL field is shown. If you enter an http URL in this field, then the Definitions Engine will query a webserver for the definition. If the URL is a file URL, then the Definitions Engine will look for the EN_DefsIndex.dat and EN_DefsContent.dat files to get the definition.

See also Def Text Element, Zebra Text Element, ZT Def Data, and the Definitions Engine for related functionality and documentation.

Map

This line is used to specify the URL of the map data file created by the Map Creator. See also Map Image Element for related functionality and documentation.

Autofill

This line is used to specify the URL of the autofill file. Press the "Create" button to begin a new file, then use a text editor to edit this file to add in your words for the Autofill list.

See also Autofill Field Element and Autofill Register Command for related functionality and documentation.

Blend Tweener

ZebraTools adds a Blend option to the Tweener. This is similar to the QuickTime Filter, but it allows for other interaction on the screen to still occur while the blend is taking place (unlike the QuickTime Filter).

Current Mouse XY

These two attributes, Current Mouse X and Current Mouse Y, are attributes of the System, and can be accessed using Get Attribute. The X and Y are integers of the current postion of the mouse on screen.

ZT Def Data

This is an attribute of the runtime, and can be accessed using Get Attribute. It contains the text of the last definition found (if one exists). See Def Text Element, Zebra Text Element, Defs project setting and Definitions Engine for related functionality and documentation.

ZT Is Server

This is an attribute of the runtime, and can be accessed using Get Attribute. It is a boolean, which returns true if project file is on server, and false if it is on a local disk.

Definitions Engine

When you click on a word in a ZebraText object, ZebraTools will determine what word you clicked on, first searching the struckthrough text items, then by calculating the actual word based on the mouse position. Once it knows what word to look for, it will search the database of definitions. This can be done in two ways:

• If the ZebraTools Defs URL (defined the the .xp project file) is an http:// URL, it will append “defs.php” to the URL and attempt to load the result.
• If the ZT Defs URL is a file:// URL, it will look for the file "DefsIndex.dat" in that location, use a binary search to quickly locate the word in that file, then us the associated hexadecimal value to determine the offset and length of the request text in the "DefsContent.dat" file.

If a definition is found using either of these two methods, ZebraTools will broadcast the message “Nav Load Defs” so that you can load the definitions subdocument. In the subdocument, you need to have a ZT DefText object to use the result.

Editting Defs in iShell…

Using the Definitions engine requires that you set up a php/MySQL webserver to edit the defs on, and create the delivery file. We have provided a Set-up Guide for OS X 10.3 that will guide you through the process. Once set-up, you will need to copy the php scripts included in the download to the webswerver, and point the Defs URL in the project file to the location of those file.

If the ZT Defs URL is an http:// URL and Edit Defs is selected in the iShell preferences, then when you click on a word, ZebraTools will broadcast the message “Nav Load Defs Edit” to load the DefsEdit.xd file. In this demo project, with “Edit Defs” selected, you can edit and link definitions from right within iShell. The database is on our server, and you can edit defs in this demo project if you want.

Since the defs are displayed as html text, you can include many formatting options within the def. For instance, the word “experience” uses an unordered list to display the different variations of the word.

Delivering Defs…

Once editing is done and it is time to deliver the final product, you have two options for the defs. You can leave them as using your webserver to deliver the defs, or you can download all of the data to local files using the DownloadDefFiles.xd file.

The advantages of leaving the defs on the webserver are that you can continue to update the defs after your product ships, and your initial download is smaller. The advantages of downloading the defs and running them from the local file are speed and independence from a web connection.

A six thousand word dictionary takes up about 1.1 megs on disk, and zips down to about 300 Kb.

Multiple Language Support …

ZebraTools gives you an easy way to provide definitions in a variety of different languages.

The default dictionary that you work with with is “EN”. The Tables in the MySQL database are called EN_Definitions and EN_Alternates. The files that are downloaded are called EN_DefsIndex.dat and EN_DefsContent.dat. By using the “ZT Defs Language” runtime setter, you can switch between defs databases on the fly, allowing you to give definitions for words in a variety of different languages. This can make your title an excellent resource for ESL (English-as-Second-Language) students.

To create new tables in mySQL you are best to duplicate and rename the EN tables (this can be done in phpMyAdmin, browse the table and select the Operations tab), then empty them out (or translate the definitions). The ZT Defs Language runtime variable controls what dictionary you are editing and downloading as well.

Map Creator

The MapCreator application will help you create the Map Data File for your project Map. Simply Launch the application, and Choose where you want to save your map data file. Once that is done, click on the Load New Image button at the bottom of the screen. Select your background image. Once it is loaded, enter the URL of the first screen on your map, relative to the project file (if you want to just enter the screen name for now, you can replace it later in the generated file). Press return. Next, draw a box around the screen that you are defining. After that is done, Click and hold where you want the checkmark to appear once that screen is visited. Drag until you are happy with the placement. Repeat the process for the next screen.

Once all of the screens are defined, click on Load New Image again, if you need to define the layout for any subscreens. Otherwise click on Save&Quit to finish writing to the file.Once you have quit out of the map creator, you will need to open the file you generated in a text editor, and make a couple of minor changes.

• The name of the main map's list needs to be "background".
• The "Popup" field of any thumbnails that need to bring up submaps need to changed to "true". Also change the URL to the name of the .xd file that the submap is contained in.
• The URL of any coordinate lists that belong to submaps need to be changed to reflect the name of the .xd file that the submap is contained in.