- Development UI
- Standard Parameters
- Unique Parameters
- Data Structures
The File List parameter lets the user choose multiple files that match a given criteria, and it is ideal to provide input images for slideshows. The list of files is fed to your composition as an indexed structure. Each member of the indexed structure is itself a named structure which contains attributes about the file, such as its POSIX file path.
Because of the complexity of the File List parameter, each sub-section of its configuration is treated separately.
The File List parameter allows the user to choose files based on the filtering criteria that you define for the parameter. The available filtering options are:
The recommended filtering option is “Conformance to UTI”, because it is based on a more future-proof technique than file extensions. To allow any file type, enter “public.item”. To allow all image files, enter “public.image”. More information on Uniform Type Identifiers can be found on Wikipedia.
The “Files” section lets you choose an initial list of files that will be used by the parameter. The files you reference in this list are fed to the composition when the plug-in is first applied.
The list can contain references to assets embedded in the FxPack, as well as references to external files. References to external files begin with a forward slash character (“/“), or by a tilde (“~”). The tilde is expanded to the current user’s home directory at runtime.
At the bottom of the Files section is the Display assets above when list is edited for the first time option, which controls whether the default files are displayed to the user when he/she clicks on the “Choose” button.
When the Display assets above when list is edited for the first time option is off and the user applies the effect, your composition will be fed the default assets so that it can render something meaningful. However those files will not be used to populate the file selection UI. When implementing a slideshow you may want the generator to immediately produce a meaningful output, hence you need a valid initial file list. However when the user clicks the “Choose” button you want the user to immediately pick his/her own media, rather than having to manipulate the default assets. For these reasons, the “Display assets above when list is edited for the first time” option is off by default.
The main design goal of the File List parameter is to feed a list of files to your composition. The list of files is fed to the composition as an indexed structure (an array) whose members are named structures (dictionaries) containing attributes. There are two default attributes which are always fed to the composition, the POSIX-style file path as well as the URL-encoded file path. In addition to those implicit attributes, you can define any number of attributes via the following user interface:
Attributes serve the same function as plug-in parameters, but in a different scope. Whereas parameters have a “global” scope, and affect the entire plug-in, file list attributes are defined for each file in the list.
Attributes are created and configured in a manner similar to parameters: a list on the left-hand side lets you see which attributes have already been defined. New attributes can be created by clicking the “+” button below the list.
Some attributes are implicit: they cannot be removed and use pre-defined keys inside the named structure. For instance, each named structure associated with a file in the list always contains a value for the “path” structure key (the POSIX-style path to the file on disc). Within your Quartz composition, this value can be accessed using the “Structure Key Member” patch.
Custom attributes can be assigned their own “Structure Key” so that, for instance, you can define multiple “String” attributes that each map to a different member in the named structure corresponding to the file (“text0”, “text1”, etc.).
Where appropriate, you can also define a default value for the attribute, so that when the user first adds a new file to the list all of its attribute values will be set to these defaults.
The user sets the value for each attribute through a table-based user interface in the host. Each attribute corresponds to a column in the table. Each type of attribute is edited via the appropriate user interface, which may be a text field, a popup menu, a slider, etc.
The following attribute types are supported:
More options are available for deciding the appearance of the file list:
The File Display option controls whether each file will be displayed by its preview and/or its filename. Filenames are not editable, and if the plug-in requires a title (e.g. a slideshow) it is preferable to have a “String” attribute instead.
The Preview using method controls the underlying API used to generate the image previews. “QuickLook”, the default option, is able to generate previews for a larger number of files, and it can optionally add a frame and drop shadow to the previews. “Contents of file” will only work for image file types. “Finder Icon” will only display an icon corresponding to the file type, and it is the fastest method.
The Preview width and Preview height values represent the maximum dimensions of each preview. Larger images are scaled down proportionally to fit within these dimensions.