VList operates in two modes, and it can be used both as a Scripting and as an Asset Xtra. Scripting Xtras are used to extend the Lingo language with new functions and datatypes, and vList operates in this mode when it is working with files as its storage medium. But vList can also store its contents directly in vList castmembers (assets), which are saved with your movie and operate like any other built-in Director member type. Each approach has distinct advantages, and we will explain this in more detail in a moment.

However, our first step is to download and install the vList Xtra, following the instructions in the installation page. Now that vList is installed, let's verify that the installation was successful. If you are using DirectorMX or later you should see the vList entry in the Scripting Xtras context menu, appearing at the top of the message window. Selecting the VLIST submenu and the "put interface" entry will output a list of all commands understood by vList in the message window. You can also use the following command

Lingo:

put the xtralist

JavaScript syntax:

trace(_player.xtraList)

to verify which Xtras are installed, including the version number for each one.

We will now try a simple scripting session using vList and the message window. Some of vList functions are available as global Lingo keywords, so there is no need to create an instance of the Xtra in order to use them. For example:

Lingo:

mystring = vList_Version()

put mystring

--"2.0.0"

JavaScript syntax:

var mystring = vList_Version()

trace(myresult)

That's it. You just confirmed that vList Xtra is installed correctly, and its functions are available and ready to be used.

CREATING A NEW VLIST CAST MEMBER

vList Xtra can save a list to an external file or to a vList cast member. You create a vList cast member by doing Insert -> Tabuleiro Xtras -> vList from Director's menu.

You can also create a new member by using the Lingo new member command and passing it type #vlist like so:

memberRef = new(#vList)

When you create a vList cast member by using Insert -> Database -> vList, the following vList member properties dialog appears:

You can view a vList member's properties at any time via this dialog by highlighting the vList member in the cast window, clicking on the Info button at the top of the cast window, and then clicking on the Options button in the Info Window, or by double-clicking the vList member in the cast window. Items that are dimmed cannot be set from the dialog for that particular member.

Number of entries

Number of items in the list contained by the vList member. 1 if the content is not a list.

Value Type

The type of the data contained by the vList member. Corresponds to the vList member contentType property.

Size in Memory

Size of the data contained by the vList member when loaded into memory. Corresponds to the vList member size property.

Size on Disk

Size of the data contained by the vList member when written out to a file. Corresponds to the vList member sizeOnDisk property.

Compression Ratio

Percentage of disk space saved by compression. 0 if compression has not been activated for the member. Corresponds to the vList member compressionRatio property.

Created with Director

Version of Director the data contained by the vList member was created under. Corresponds to the vList member dirVersion property.

Platform of Creation

Platform (Mac or Windows) the list contained by the vList member was created under. Corresponds to the vList member platform property.

Modification Date

Last date the vList member contents were changed.

Lingo Value Type

The type of data to initialize the vList contents with. This can be changed at any time simply by writing new data to the member. This property is only set-able through the dialog at member creation. After that, the radio buttons show the type of data currently being stored.

Linear - puts [ ] into the member at member creation. Indicates that the member contains a linear list when viewed after member creation.

Property - puts [ : ] into the member at member creation. Indicates that the member contains a property list when viewed after member creation.

Empty - puts Void into the member at member creation. Indicates that the member contains no value when viewed after member creation.

Unique Value - puts Void into the member at member creation. Indicates that the member contains some Lingo value other than a list when viewed after member creation.

Content Attributes

Sorted - Sorts the member contents and sets the member's sorted flag if pressed. Indicates the current sorted state of the member. Corresponds to the vList member sorted property.

Compressed - Activates compression for the member if pressed. Not available if the member is encrypted because compression has to be applied before encryption. Indicates the current compressed state of the member. Corresponds to the vList member compressed property.

Binary Content - Activates binaryMode for the member. If binaryMode is on, characters in string data will not be cross-mapped when read by vList on the opposite platform (Mac to Win, Win to Mac)

Encrypted - Read-only. Shows whether or not the current contents of the member are encrypted. Cannot be set from the dialog.

Import button

Displays a file picker dialog for choosing a vList list storage file, then imports the contents of the file into the member. Corresponds to the importFile command.

STORING A LIST INSIDE A CAST MEMBER

The most important property of a vList member is its content property. Setting the content property of a vList member to a list in memory writes the list out to the member. Setting a variable to the content property of a vList member puts the list contained by the member into the variable.

newMember = new(#vList)

member(newMember).content = [1,2,3]

variable = member(newMember).content

put variable

-- [1,2,3]

When you save a movie that has vList members in its castlib, the list data contained by the vList member is saved with the movie. When you save an external castlib with vList members in it, you also preserve their list contents. You can save movies and castlibs on the fly with the following Lingo commands:

saveMovie

save castlib "castlibName

When you save a movie or castLib to Shockwave format, the vList members are also compressed using the standard Director compression algorithm, similar to the one used in ZIP archivers.

SAVING A LIST TO A FILE

In order to read from list storage files or write a list out to a file you must first make a file connection to the file by making a new instance of vList xtra and passing it the path to the file, like so:

myFile = new xtra ("vList","C:\TEMP\STORE.LST")

The instance variable myFile at this point is linked to file "STORE.LST". You pass it to either the read or write methods to retrieve and store lists to the file like so:

myFile = new xtra ("vList","C:\TEMP\STORE.LST")

listVar = [1,2,3]

myFile.write(listVar)

anotherVar = myFile.read()

put anotherVar

-- [1,2,3]

REGISTRATION

If you have purchased a registration for the vList Xtra you received a serial number. Make the vList_Register registration call in the first movie that uses vList commands. Make sure you do it before using any other vList commands. The code can be in any type of script.

The startMovie handler is the most convenient place to put it because it will execute before any other code that might try to use vList functions. Remember that a startMovie handler must reside in a movie type of script. You must call the registration command once at the beginning of every Director session where you will be using vList. Once you have registered, the registration stays in memory for the length of the session, even if you go to a movie other than the one that made the registration call.

on startMovie

vList_Register([111,222,333])

-- notice that the parameter to vList_Register is a list, not a string!

end

Previous versions of vList had two levels of registration, Basic and Full, and some Free commands. vList 2 and later do not have these limitations: all functions are available only in the registered version.

LIMITED EVALUATION MODE

In unregistered mode most vList functions will cause a warning dialog to display the first time they are used. A limited set of vList utility commands are free to use and do not display a demonstration dialog. Unlike previous versions, all functions that read and store data display a warning when running in trial mode.