View Description List Files

 
Starting with Director 8, developers can customize tabs in the Property Inspector by editing the VDL (View Description List) files in the props folder. You can also create new VDL files and add them to the props folder.


View Description List File Syntax

Overview

The VDL (View Description List) file format is used by the Property Inspector to display the tabs that appear in the Property Inspector when a particular type of object is targeted. The VDL file describes the name of the view that appears on the tab, the properties of the targeted object, and layout information defining the types of controls that appear in the view and their arrangement.

The following sections provide information about the location and format of VDL files, as well as sample a VDL file for reference purposes.

 
VDL file location

In order to be recognized and parsed when Director is launched, all VDL files must be located in the props folder at the root of the Director application folder. Their full location within the props folder determines how they are used in the Property Inspector. Inside the props folder, there are there are sub-folders representing types of objects that can be targeted by the Property Inspector: Sprite, Member, Movie, and Cast. There is also a Publish folder, that is not relevant to this discussion.

Inside each sub-folder, there is a special default.txt VDL file. This VDL file is always read in when Director is launched, and is instantiated whenever an object of the specific type is targeted. For example, selecting a cast member of any type in the cast window will instantiate the VDL Props:Member:default.txt file.

You can specify additional tabs/views for a particular member type by placing a VDL file with the appropriate filename in the Props:Member folder. For example, to specify additional tabs for bitmap members, you would create a VDL file called Props:Member:bitmap.txt.

 
VDL file format

At the top level, the VDL file format is a lingo property list. This top-level list is called a View Description List. Each item in the VDL is a single view that will appear when that VDL is instantiated.

The VDL file syntax consists of a property name, a series of property lists: viewDescription, propertyDescriptionList, and itemDescriptionList.

 
The property name
The property name of the view is a symbol used to identify the view. For example, a bitmap VDL file that has a Bitmap tab and a Compression tab, might look like this:

[ #bitmapTab: <bitmap viewDescription>,
#compressionTab: <compression viewDescription> ]

 
The viewDescription property list
The viewDescription property list describes the general properties of a tab in the Property Inspector. For example, the viewDescription property list for the bitmap tab might look like this:

[ #comment: "bitmap", <note: this can be localized>
#symbol: #bitmap,
#propertyDescriptionList: <bitmap PDL>,
#itemDescriptionList: <item descriptionList> ]

The following table lists the properties of viewDescription.

Property Description
#comment

A string identifying the name of the view to appear on the tab in the Property Inspector.

#symbol

A symbol identifier used to locate the view internally, or used by the Property Inspector to match VDL files in the props folder to internally implemented views. When the user tries to view cast member properties, the Property Inspector looks for the view with the symbol that matches the member type. If you have defined multiple views in your VDL file, make sure the primary view's symbol matches the type symbol of the member it targets.

#propertyDescriptionList

A property list (PropList) that describes the properties of the targeted object t visible on this tab. See below

#itemDescriptionList

A property list (PropList) that describes the user interface items that appear when this tab is selected. See below.

#picture

A glyph id specifying the glyph used on the tab for the view. The glyph can be a straight glyph ID, or a lingo list consisting of a resource ID and an index into the resource ID.


 
The propertyDescriptionList property list
The propertyDescriptionList uses a format that is similar to the format used by the Behavior Inspector. If the format in the propertyDescriptionList is different from the actual format of the property, the Property Inspector will attempt to convert it. For lingo types that are not in this list, do not specify a format property: the Property Inspector will show the value by its lingo representation, and try to choose the correct value when the user sets the property value. If the format is any of the special types defined by the Behavior Inspector (member type symbols, cursor, palette, transition, graphic, etc.) the Property Inspector selects the appropriate value type, and sets the range to the default generator. The range can be overridden.

Each item in the propertyDescriptionList is identified by the symbol of the property of the target object being described. The item itself is a lingo property list, specifying the properties listed in the following table.

Property Description
#format

A symbol identifying the type/format of the property. This can be one of the standard types defined by the Behavior Inspector (BI), or an extended type that provides additional formatting: #string, #integer, #filename (a string), #boolean (can be an integer() symbol, member, memory (an integer), float, color, percent (an integer() ink (an integer() point, cursor(an integer).

#comment

A string describing the property. used as a data tip in the table view of the Property Inspector.

#range

A symbol or lingo list. You can specify the ranges provided by the Behavior Inspector, or if the range specified is in the form [#min: #max], you can specify #granularity which indicates how much to step the slider by.

The Behavior Inspector accepts a lingo list as a list of possible values for a range. The Property Inspector also accepts a property list, where each property name is a format type, and the property value is a lingo value.

#editable

A Boolean specifying whether or not the property can be edited in the Director program. If not specified, this property defaults to true.

#getprop:

A Boolean specifying whether or not the Property Inspector retrieves the property value to display it regularly. For large or slow properties, or properties with no meaningful representation, specifying false for this property forces the Property Inspector to show a placeholder string instead of retrieving the value every time it updates. In this case the Property Inspector only retrieves the value for the data tip if the user mouses over the placeholder string. If not specified this property defaults to true.

#title

A Boolean flag instructing the Property Inspector. Specify true to instruct the Property Inspector use #comment to display a descriptive title entry in the property table. This property can be used to group properties logically. If not specified this property defaults to false.


The itemDescriptionList properties

The itemDescriptionList describes the items that appear in the view when the Property Inspector is set to graphical (non-table) mode. Like a propertyDescriptionList, an itemDescriptionList is a lingo property list where each entry is a single item in the view. The name of the property is a symbol used to identify the item. The value of the entry is a lingo property list describing the item. The following table lists the properties of a single item descriptor.

Property Description
#property

A symbol specifying the name/identifier of the property associated with a specific control/item. If a property is specified, the Property Inspector attempts to synchronize the value of the control and the value of the target property. This property is optional.

#type

A symbol specifying the type of the control/item to be created. Possible values include: #button (creates a simple text-pushbutton), #label (creates a static text item, #field (creates an editable text field), #picture (creates a simple picture icon), #line (creates an etched separator line), #checkbox (creates a boolean checkbox), #radio (creates a radio button), and #list: creates a drop-list.

#loc

A point specifying the location of the control/item in the view.

#size

A point specifying the size of the control/item in the view.

#comment

A string used as the tooltip message for the item.


If both #type and #property are specified, the Property Inspector attempts to convert the format of the data between the property and the item. If #property, but not #type is specified, the Property Inspector attempts to select the type of the item according to the following rules:

If the specified property has a symbol or list type range, the control is a drop-list.
If the property has a min/max type range, the control is a slider.
If the property is a Boolean, the control is a check box.
If the property is a color, the control is a color chip.

For any other type, if the property is editable, the control is an edit-text field; if it is not editable, it will be a static text label.

In addition to properties listed in the previous table, you can specify the properties in the following table for specific item types.

Property Interface item type Description
#text

Button, radio button, checkbox or label for field

A string of text for the interface item.

#picture

Button, checkbox, picture

A glyph ID representing the icon used for the interface an item control. Buttons and checkboxes that specify a picture property, are created as icon buttons or toggles, if the picture property is not specified, they appear as traditional buttons/checkboxes.

The picture property can be a full glyph id, or a lingo list consisting of a picture resource id and an index into the resource. Pictures must be of standard size and spacing (20w by 18h icons with a 4 pixel strip in between).

#scroll

Field

The scroll property on a field item determines whether it is single- or multi-line entry. By default, it is single line.

#range

Drop-list

The range property for drop-list items should be a lingo list with an equal number of items as the range on their associated property description. When a drop-list is displayed, it finds the current property value in the property range, and displays the corresponding item in its own range. For example, if the purePriority cast member property has a range of [3, 2, 1, 0], the itemDescription for the purgePrority drop list has a range of: ["3 - Normal", "2-next","1-last","0-never"]. If the purgePriority of a cast member is currently 1, the drop list recognizes that '1' is the 3rd item in the property range, and displays the 3rd item in its display range, "1-last." When the user selects a value from the drop-list, it reverses the process and sets the current prop value to the appropriate value in the property range.

#range

Radio button

The range property for radio button items should be a single lingo value which is used to determine the state of the radio button. When the Property Inspector updates the radio button, it compares the value of the associated property to the range value of the radio button. If they match, the radio button is highlighted.

#alignment

Label, field, or button

Sets the alignment of the text attached to the item. Valid values for the alignment property are: #left, #center, and #right. The default setting is left for labels and fields is #left, and #right for buttons.


 
Sample View Description List (VDL) file

The following is a sample VDL file for a vectorShape member. The path of the VDL file is: (Application Path):Props:Member:VectorShape.txt

[ 
#vectorProps: 
	[  
	#comment: "vector", 
	#propertyDescriptionList:    
		[ 
		#strokeColor: 
			[ 
			#format: #color, 
			#comment: "line color", 
			#range: [rgb(0,0,0),rgb(255,0,0),rgb(0,255,0),rgb(0,0,255)]    
			] ,
		#strokeWidth: 
			[ 
			#format: #float, 
			#comment: "stroke width", 
			#range: [ #min:0.0,#max:10.0,#granularity:    .5] 
			] ,
		#closed: 
			[ 
			#format: #boolean, 
			#comment: "closed" 
			] ,
		#vertexList: 
			[ 
			#format:    #string, 
			#comment: "vlist" 
			] 
		], 
	#itemDescriptionList: 
		[ 
		#strokeColor: 
			[ 
			#type:    #editable, 
			#property: #strokeColor, 
			#loc: Point(30,30), 
			#size: Point(150,16)	   
			] ,
		#strokeWidthSlider: 
			[ 
			#property: #strokeWidth, 
			#loc: Point(30,45), 
			#size:    Point(180,12) 
			] ,
		#strokeWidthValue: 
			[ 
			#type: #label, 
			#property: #strokeWidth,    
			#loc: Point(215,45), 
			#size: Point(40,12) 
			] 
		] 
	] 
]


Copyright © 1999-2007 Adobe Macromedia Software LLC, Inc.