Joe Maller: FXScript Reference: Input Controls

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.

CheckBox

Checkboxes have a value of 0 (unchecked) or 1 (checked). The code input by the FXBuilder menu looks like this:

input varName, "UIName", CheckBox, value

• varName

  the name of the variable defined by the input. Variable names should be unique.

• "UIName"

  the label appearing next to the control. This can be any text string, but longer strings will probably get clipped in thin columns, so I try to keep mine as short as possible.

• Checkbox

  Defines the type of input.

• value

  This is the initial value, either zero or one, a value of one means the box is checked.

Apple's Human Interface Guidelines for Checkboxes (original).

Slider

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):

input varName, "UIName", Slider, value, min, max [ramp value] [label "Units"] [detent/snap v1, v2, ...]

• varName and "UIName"

  Same definition as the Checkbox above.

• Value, Min, Max

  These are the initial value, the minimum value and the maximum value separated by commas. These should be numbers, decimal amounts less than one need to start with a zero (0.1).

• [ramp value]

  Ramp values compress a slider so one side contains a tighter concentration of values than the other. It's sort of like using Curves in Photoshop, the lower values occupy an area larger than they would if the ramp was linear. Values must be positive numbers between 1 and 100. Higher values compress more, a ramp value of 100 will completely compress the slider so the whole slider will be the minimum value except for the very last position which will be the maximum amount.

• [label "Units"]

  A text label can be added to the numeric entry box on the right side of the slider. Any text string can be used, but strings longer than 4 character will be clipped.

• [detent/snap v1, v2, ...]

  Detents and Snaps are values on the slider which are either sticky or restricted. See the note at the bottom of this page for more about detents and snaps.

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.

Apple's Human Interface Guidelines for Sliders (original).

Angle

The commands and definitions for Angles are the same as for Sliders. FXBuilder code looks like this (no line breaks):

input varName, "UIName", Angle, value, min, max [label "Units"] [detent/snap v1, v2, ...]

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.

Popup

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:

input varName, "UIName", Popup, value, label1, label2, ..., labelN

• Value

  refers to the initial selection. The first menu item would be numbered one.

• label1, label2, ..., labelN

  The labels represent the contents of the menu. These should be quoted text strings. A sample list would look like:
"dog", "cat", "turtle", "headphones"

Apple's Human Interface Guidelines for Pop-Up Menus (original).

Radio Group

The commands and definitions for Radio Groups are exactly the same as Popup covered above, the two can be switched back and forth by changing RadioGroup to Popup and vice versa. The main advantage of a Radio Group is that all choices are visible to the user. FXBuilder code looks like:

input varName, "UIName", RadioGroup, value, label1, label2, ..., labelN

Apple's Human Interface Guidelines for Radio Buttons (original).

Color

This, of course, is the color picker. The FXBuilder code is:

input varName, "UIName", Color, alpha, red, green, blue

• alpha, red, green, blue

  These are the four channels that combine to make a color in Final Cut Pro, represented as numbers between 0 and 255. The values are listed in the order they appear, alpha first, blue last. To mix red, enter 255, 255, 0, 0

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.

Clip

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:

input varName, "UIName", Clip

Apple has no entry for Clip selectors in the Human Interface Guidelines although these are similar to Image Wells.

Text

• A simple box for entering text. I haven't been able to discover a maximum number of characters yet. The FXBuilder code looks like this:

input varName, "UIName", Text, "string" [TextHeight h]

• "String"

  Defines the initial text.

• [TextHeight h]

  This attribute is optional. It defines the number of rows that will be displayed in the filter controls. This does not limit the amount of text, it only restricts what is visible.

Apple's Human Interface Guidelines for Text Fields (original).

Point

Points are two dimensional coordinates. The code from FXBuilder is:

input varName, "UIName", Point, x, y

• x,y

  The format of point data was different than I expected. Instead of returning the actual numeric coordinates of the point, it defines position in the frame as a set of percent values between -50% and +50%. The center of the frame is {0,0}, and everything is measured out from there. Standard geometric rules apply, -x is left, + x is right, -y is up and +y is down.

  While it might seem ridiculous at first, these values are actually very helpful. Final Cut Pro seems to calculate each filter twice, on the screen preview and once on the video output (this is discussed more on the FXScript Constants page). Because of this, pixel values which are not described as percents will not match up between the screen and the monitor. Returning point values as percents saves us the step of converting them before using point data. I built Joe's Point Value Tester to help understand how these values work.

Apple has no entry for Point selectors in the Human Interface Guidelines.

Label

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:

input varName, "UIName", Label, "string"

Apple's Human Inter Guidelines for Static Text Fields.

Fontlist

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:

input varName, "UIName", FontList [, "InitialFont"]

• [, "InitialFont"]

  This wonderfully unique option includes a comma which is needed for the InitialFont attribute to work correctly. The InitialFont string is case-insensitive and can be any font name. If the specified font is on the system, it will be the font initially selected.

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.

set x to "detent "

repeat with h from -20 to 20 by 2

set x to x & h & ", " as text

end repeat

log x

That AppleScript returns:

(*detent -20, -18, -16, -14, -12, -10, -8, -6, -4, -2, 0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, *)

Almost perfect, and much better than typing all that out manually.

Notes

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 Code line of the script.