ADC Home > Reference Library > Reference > Apple Applications > Final Cut Pro/Final Cut Express > FxPlug Reference

 


FxParameterCreationAPI

Declared In:

Introduction

Defines the methods provided by the host application to create parameters.

Discussion

This is version 1 of the FxParameterCreationAPI protocol.
A plug-in uses the methods defined in this protocol (along with those defined in FxOptionalParameterAPI.h) to populate its parameter list. Each parameter is created with a unique numeric parameter ID. The host application uses this parameter ID to identify a parameter, and stores the parameter ID in a saved project file. If a new version of a plug-in removes a parameter, the host application will then ignore any saved parameter data for that obsolete parameter in a project that was saved while using the old version of the plug-in. This implies that a new version plug-in should never change the ID of a given parameter unless it intentionally wants to obsolesce old value data in saved projects. Similarly, it should not introduce a new parameter with an ID that has already been obsolesced.



Methods

-addAngleSliderWithName:parmId:defaultValue:parameterMin:parameterMax:parmFlags:
Creates an angle slider parameter and adds it to the plug-in's parameter list.
-addColorParameterWithName:parmId:defaultRed:defaultGreen:defaultBlue:defaultAlpha:parmFlags:
Creates an RGBA color value and adds it to the plug-in's parameter list.
-addColorParameterWithName:parmId:defaultRed:defaultGreen:defaultBlue:parmFlags:
Creates an RGB color parameter and adds it to the plug-in's parameter list.
-addCustomParameterWithName:parmId:defaultValue:parmFlags:
Creates a custom parameter and adds it to the plug-in's parameter list.
-addFloatSliderWithName:parmId:defaultValue:parameterMin:parameterMax:sliderMin:sliderMax:delta:parmFlags:
Creates a floating point slider parameter and adds it to the plug-in's parameter list.
-addImageReferenceWithName:parmId:parmFlags:
Creates an image reference parameter and adds it to the plug-in's parameter list.
-addIntSliderWithName:parmId:defaultValue:parameterMin:parameterMax:sliderMin:sliderMax:delta:parmFlags:
Creates an integer slider parameter and adds it to the plug-in's parameter list.
-addPointParameterWithName:parmId:defaultX:defaultY:parmFlags:
Creates a position point parameter and adds it to the plug-in's parameter list.
-addPopupMenuWithName:parmId:defaultValue:menuEntries:parmFlags:
Creates a popup menu parameter and adds it to the plug-in's parameter list.
-addToggleButtonWithName:parmId:defaultValue:parmFlags:
Creates a checkbox toggle button parameter and adds it to the plug-in's parameter list.
-endParameterSubGroup
Closes current parameter subgroup. You should always pair this with a preceding startParameterSubGroup message.
-startParameterSubGroup:parmId:parmFlags:
Starts a new parameter subgroup. All subsequent parameter additions are placed in this group until you send an endParameterSubGroup message.

addAngleSliderWithName:parmId:defaultValue:parameterMin:parameterMax:parmFlags:


Creates an angle slider parameter and adds it to the plug-in's parameter list.

- (BOOL)addAngleSliderWithName:(NSString *)name parmId:(UInt32)parmId defaultValue:(double)defaultValue parameterMin:(double)min parameterMax:(double)max parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultValue
Initial angle value for the parameter, in counter-clockwise degrees.
min
Minimum value for the parameter, in counter-clockwise radians.
max
Maximum value for the parameter, in counter-clockwise radians.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates an angle slider parameter; NO otherwise.

Discussion

The min and max values are expressed in radians, while the defaultValue is expressed in degrees. Angle parameter values should be retrieved using the -getFloatValue: (rather than the deprecated getAngle: method), and are expressed in counter-clockwise degrees.
Prior to FxPlug 1.2, the documentation for this method had the units (degrees and radians) reversed. However, the implementation has not changed.


addColorParameterWithName:parmId:defaultRed:defaultGreen:defaultBlue:defaultAlpha:parmFlags:


Creates an RGBA color value and adds it to the plug-in's parameter list.

- (BOOL)addColorParameterWithName:(NSString *)name parmId:(UInt32)parmId defaultRed:(double)red defaultGreen:(double)green defaultBlue:(double)blue defaultAlpha:(double)alpha parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
red
Initial red value of the parameter in float ( 0.0 - 1.0 ) space.
green
Initial green value of the parameter in float ( 0.0 - 1.0 ) space.
blue
Initial blue value of the parameter in float ( 0.0 - 1.0 ) space.
alpha
Initial alpha value of the parameter in float ( 0.0 - 1.0 ) space.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates an RGBA color parameter; NO otherwise.


addColorParameterWithName:parmId:defaultRed:defaultGreen:defaultBlue:parmFlags:


Creates an RGB color parameter and adds it to the plug-in's parameter list.

- (BOOL)addColorParameterWithName:(NSString *)name parmId:(UInt32)parmId defaultRed:(double)red defaultGreen:(double)green defaultBlue:(double)blue parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
red
Initial red value of the parameter in float ( 0.0 - 1.0 ) space.
green
Initial green value of the parameter in float ( 0.0 - 1.0 ) space.
blue
Initial blue value of the parameter in float ( 0.0 - 1.0 ) space.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates an RGB color parameter; NO otherwise.


addCustomParameterWithName:parmId:defaultValue:parmFlags:


Creates a custom parameter and adds it to the plug-in's parameter list.

- (BOOL)addCustomParameterWithName:(NSString *)name parmId:(UInt32)parmId defaultValue:(id<NSCoding>)defaultValue parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultValue
Initial entry for the parameter.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates a custom parameter; NO otherwise.

Discussion

The defaultValue argument is an instance, created by the plug-in, of the custom parameter's class, which must conform to the NSCoding protocol. NSCoding is used for serialized and unserializing the custom parameter's value object for saving and loading.


NOTE: Your implementation of the NSCoding methods (-encodeWithCoder: and -initWithCoder:) must use keyed coding.


addFloatSliderWithName:parmId:defaultValue:parameterMin:parameterMax:sliderMin:sliderMax:delta:parmFlags:


Creates a floating point slider parameter and adds it to the plug-in's parameter list.

- (BOOL)addFloatSliderWithName:(NSString *)name parmId:(UInt32)parmId defaultValue:(double)defaultValue parameterMin:(double)min parameterMax:(double)max sliderMin:(double)sliderMin sliderMax:(double)sliderMax delta:(double)sliderDelta parmFlags:(FxParameterFlags)flags;
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultValue
Initial value for the parameter.
min
Minimum value for the parameter.
max
Maximum value for the parameter.
sliderMin
Minimum value for the parameter's slider control.
sliderMax
Maximum value for the parameter's slider control.
sliderDelta
Step value added or removed when the slider is moved.
flags
Flags that encode various state values for the parameter. Use kFxParameterFlag_IGNORE_MINMAX to create a slider with unbounded range. In this case, the min, max, sliderMin, and sliderMax values are ignored.
Return Value

Returns YES if the application successfully creates a floating point slider parameter; NO otherwise.


addImageReferenceWithName:parmId:parmFlags:


Creates an image reference parameter and adds it to the plug-in's parameter list.

- (BOOL)addImageReferenceWithName:(NSString *)name parmId:(UInt32)parmId parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates an image reference parameter; NO otherwise.


addIntSliderWithName:parmId:defaultValue:parameterMin:parameterMax:sliderMin:sliderMax:delta:parmFlags:


Creates an integer slider parameter and adds it to the plug-in's parameter list.

- (BOOL)addIntSliderWithName:(NSString *)name parmId:(UInt32)parmId defaultValue:(int)defaultValue parameterMin:(int)min parameterMax:(int)max sliderMin:(int)sliderMin sliderMax:(int)sliderMax delta:(int)sliderDelta parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultValue
Initial value for the parameter.
min
Minimum value for the parameter.
max
Maximum value for the parameter.
sliderMin
Minimum value for the parameter's slider control.
sliderMax
Maximum value for the parameter's slider control.
sliderDelta
Step value added or removed when the slider is moved.
flags
Flags that encode various state values for the parameter. Use kFxParameterFlag_IGNORE_MINMAX to create a slider with unbounded range. In this case, the min, max, sliderMin, and sliderMax values are ignored.
Return Value

Returns YES if the application successfully creates an integer slider parameter; NO otherwise.


addPointParameterWithName:parmId:defaultX:defaultY:parmFlags:


Creates a position point parameter and adds it to the plug-in's parameter list.

- (BOOL)addPointParameterWithName:(NSString *)name parmId:(UInt32)parmId defaultX:(double)defaultX defaultY:(double)defaultY parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultX
Initial x value of the position parameter in float ( 0.0 - 1.0 from bottom-left ) space
defaultY
Initial y value of the position parameter in float ( 0.0 - 1.0 from bottom-left ) space
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates a position parameter; NO otherwise.


addPopupMenuWithName:parmId:defaultValue:menuEntries:parmFlags:


Creates a popup menu parameter and adds it to the plug-in's parameter list.

- (BOOL)addPopupMenuWithName:(NSString *)name parmId:(UInt32)parmId defaultValue:(UInt32)defaultValue menuEntries:(NSArray *)entries parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultValue
Index of the initial entry for the parameter.
entries
Array of NSStrings representing the entries in the menu.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates a popup menu; NO otherwise.


addToggleButtonWithName:parmId:defaultValue:parmFlags:


Creates a checkbox toggle button parameter and adds it to the plug-in's parameter list.

- (BOOL)addToggleButtonWithName:(NSString *)name parmId:(UInt32)parmId defaultValue:(BOOL)defaultValue parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
defaultValue
Initial value for the parameter.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates a toggle parameter; NO otherwise.


endParameterSubGroup


Closes current parameter subgroup. You should always pair this with a preceding startParameterSubGroup message.

- (BOOL)endParameterSubGroup; 
Return Value

Returns YES if the application successfully closes the current parameter sub group; NO otherwise.


startParameterSubGroup:parmId:parmFlags:


Starts a new parameter subgroup. All subsequent parameter additions are placed in this group until you send an endParameterSubGroup message.

- (BOOL)startParameterSubGroup:(NSString *)name parmId:(UInt32)parmId parmFlags:(FxParameterFlags)flags; 
Parameters
name
Name of the parameter in the user interface.
parmId
Unique identifier for a parameter. Used to retrieve, set, or validate the parameter.
flags
Flags that encode various state values for the parameter.
Return Value

Returns YES if the application successfully creates a parameter sub group; NO otherwise.


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.
Last Updated: 2008-06-05