FxFactory Developer

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:

• File extension: supply a list of valid file extensions, separated by space.
• Conformance to UTI: supply a list of valid UTIs (uniform type identifiers), separated by space.

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 should only contain references to assets embedded in the FxPack. In previous versions of macOS it was also possible to reference external files, by entering file or directory paths beginning with a forward slash character (“/“), or by a tilde (“~”), which gets expanded to the current user’s home directory at runtime. Beginning with macOS 10.15 Catalina, using these file paths poses the danger of running against file access restrictions. To avoid this problem, please make sure your default file list only contains references to assets embedded in the product.

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:

• String – associated with a string value. It can optionally default to the filename, so that when creating a slideshow from existing files on disc the filename can be used as the initial title (awaiting further customization on behalf of the user)
• Boolean – associated with a boolean value, edited by the user through a checkbox.
• Number – associated with a numeric value, edited by the user through a slider or a text field. You can use a slider only when the range is well defined (i.e. minimum and maximum values have been specified).
• Popup Menu – associated with an index value, edited by the user through a popup menu. The popup menu can use image previews, which are created by referencing image assets in the FxPack. The index of the current menu selection is fed to the composition inside the named structure corresponding to each file.
• Font – associated with a font name, edited by the user through a popup menu.
• File Size – displays the size (in bytes) to the user. This value is calculated from the file, and it is not editable by the user.
• Image Dimensions – displays the size (width x height) in pixel dimensions. This value is calculated from the image file on disc and it is thus valid only for files that are representable as an image. For efficiency reasons, the dimensions are not fed to the composition. This attribute is only available for “cosmetic” reasons. However a valid “Structure Key” must still be specified for internal consistency.
• Color Picker – associated with a color picker, whose value is fed to the composition as a named structure with members “red”, “green”, “blue” and “alpha”. Use the “RGB Color” patch to convert these values to a color output.

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.