Joe Maller: FXScript Reference: Input Controls
The 11 input types and the pre-code definition section of FXScripts for Final Cut Pro.
Input controls define the actual values that a filter will work with. Each input is also a variable, and each one needs a unique name. Values set with input variables can be controlled with keyframes when the finished script is run in Final Cut Pro.
Data types specific to each input are discussed on the FXScript Variables page. Final Cut Pro includes 11 types of filter inputs which are described below.
Human Interface Guidelines
The inputs you choose affect how users will understand and use your scripts. Certain controls make some things more difficult to understand because they hide choices or require multiple clicks for simple selections. Apple still has the original Macintosh Human Interface Guidelines online plus the additions for the platinum appearance introduced with OS 8. Reading some of these will not only help in creating effective FXScript controls, but will also give you some insight into how and why the Macintosh interface works so well (and also point out how many things are broken in FCP and OSX). Direct links to each relevant section accompany each input example below.
Checkboxes have a value of 0 (unchecked) or 1 (checked). The code input by the FXBuilder menu looks like this:
Sliders have a start and end value and return whatever value the little nub is at. Brackets seem to indicate optional attributes, although it's confusing since they are also the syntax for Arrays. Optional attributes do not need to be separated by commas. FXBuilder's code looks like this (without the line breaks):
Optional values (ramp, label, detent/snap) should not be separated by commas for the Slider Input, but must appear in the correct order to be recognized by Final Cut Pro.
The commands and definitions for Angles are the same as for Sliders. FXBuilder code looks like this (no line breaks):
I didn't find any mention of a maximum number, I tried values as high as 8 digits (tens of millions) and all of them worked fine.
Apple has no entry for Angle input controls in the Human Interface Guidelines.
Popups are menus of predefined choices. FXScript identifies the result as the numerical index of the selection, starting with 1 and increasing with each item (numbers go up, menu items go down). Commands are very similar to the previous Input types. The FXBuilder code is:
The commands and definitions for Radio Groups are exactly the same as
This, of course, is the color picker. The FXBuilder code is:
Colors are 100% at 255 and 0% at 0. Alpha is completely transparent at 0 and completely opaque at 255. Most of the included filters specified it as 255, and I've been doing the same. If I need a transparent color, there are other ways to get it.
Ironically, turning down the arrow next to the color picker reveals HSB (Hue, Saturation, Brightness) sliders, there appears to be no way to change that to RGB or YUV and no other way to directly specify HSB colors in a script. There is probably a simple mathematical way to convert RGB to HSB, but haven't looked for it yet.
Apple has no entry for Color selectors in the Human Interface Guidelines.
Clips are selected by dragging them into the little Question Mark Clip icon. I haven't used these much, but FXScript uses these as extra clips, though these need to be incremented by the script or else they only show the first frame.
FXBuilder's source is:
Apple has no entry for Clip selectors in the Human Interface Guidelines although these are similar to Image Wells.
Points are two dimensional coordinates. The code from FXBuilder is:
Apple has no entry for Point selectors in the Human Interface Guidelines.
Labels are useful for dividing up the controls of a filter into more digestible clumps. They don't do anything other than place type into the stack of controls.
One important thing to note about labels is that they still need unique variable names. Duplicating the named variable on two separate Label inputs always reports an out of memory error.
All attributes of the Label source code were covered in previous Input definitions. The FXBuilder code is:
Apple's Human Inter Guidelines for Static Text Fields.
Final Cut Pro is limited to TrueType fonts, so a fontlist will be limited to whatever TrueType fonts are installed on the system. The Value returned appears to be a text string of the font name.
The FXBuilder code is:
Fontlists work on the same Human Interface principles as Popup menus.
Detents and Snaps
Slider and Angle inputs include the optional parameter of Snaps of Detents. These optional settings change the way the control works and can be used to help users arrive at clean values or to force the input to use a restricted set of values. Any given input control can include either snaps or detents, but not both. This makes sense since nothing but snap values could be selected anyway.
A detent value will cause the input to "stick" at the specified value. Adding the detents 0, 90, 180, 270, 360 to an angle slider will make those values sticky and make it easier for users to select those values. With detents, middle values can be selected but selecting values adjacent to detent values is somewhat difficult. Because of this, I've shied away from using them very often.
Snaps constrain the input control to only the defined values. A slider with snap values set to 1,2,3,4 & 5 will only be able to select those numbers. Snaps are useful when a script needs whole numbers or specific values from an input.
There doesn't seem to be a maximum number of detents or snaps which can be specified, but defining them is kind of tedious. A simple looping AppleScript can be used to generate simple strings of comma delimited numbers very quickly, depending on your degree of laziness and whether or not that is actually easier for you.
Try the following AppleScript for generating 21 comma delimited numbers which can be used as the detents of a slider input. Copy the result from Script Editor's log window back into your FXScript.
That AppleScript returns:
Almost perfect, and much better than typing all that out manually.
Variables defined by one input can not be used to define another input, so there is no way to update one input based on the value of another.
Input controls can occur in any order, but must appear above the