Create standard and custom user-facing parameters for your plug-in that will appear in the inspector.
Framework
- Fx
Plug
Overview
Once a plug-in is invoked by a host application, the host application asks for the plug-in’s parameter list by calling the -
add
method. This method is declared in the Fx
protocol, which is inherited by the Fx
protocol. The host application then displays the parameters in its inspector.
Add a Parameter
The FxPlug SDK includes methods for adding these standard types of parameters:
Floating-point slider
Integer slider
Angle slider
Toggle button (checkbox)
RGB color
RGBA color
Point
Popup menu
Image Reference
Group start
Group end
String
Histogram
Gradient
In the -
add
method, a plug-in first calls the apiForProtocol: method (defined by the PluginManager framework) to get the host API object that implements the protocol. It then adds parameters, one by one, using methods in the Fx
protocol.
For example, the following code shows an -add
method from a simple opacity filter:
Important
Parameter IDs must be in the range of [1, 9998]
. IDs outside of this range are invalid.
enum
{
kOpacityID = 1
};
- (BOOL)addParametersWithError:(NSError**)error
{
id<FxParameterCreationAPI_v5> paramAPI = [apiManager apiForProtocol:@protocol(FxParameterCreationAPI_v5)];
BOOL success =[paramAPI addFloatSliderWithName:@"Opacity"
parameterId:kOpacityID
defaultValue:1.0
parameterMin:0.0
parameterMax:100.0
sliderMin:0.0
sliderMax:10.0
delta:0.1
parameterFlags:kFxParameterFlag_DEFAULT];
return success;
}
Create a Custom Parameter
In addition to the standard parameter types, you can use the following method to create a custom parameter with an opaque data type:
-addCustomParameterWithName:parameterID:defaultValue:parameterFlags
Each custom parameter must be associated with a custom parameter view, which is defined by the methods in Fx
.
Interact with Parameters
When a user changes a parameter control for an FxPlug plug-in, the host application calls the -
parameter
plug-in method. This is useful for a plug-in that changes the state of other parameters. For example, if the user changes a toggle button, the plug-in can hide or reveal other parameters during -
parameter
.
Handle User Interaction for Custom UI Parameters
Custom UI parameters let developers draw directly to a custom UI and create their own controls in a space that the host application makes for them in the inspector. The host application handles user interaction for custom parameters in a different way than standard UI parameters. For example, when you develop custom parameters, they must conform to the Fx
protocol. An example of this can be found in the Fx
sample plug-in.
In your plug-in, custom parameters conform to the Fx
protocol by implementing a -
create
method that provides an NSView
subclass to the host app. Like any other NSView
subclass, this custom view draws itself in a window and receives notification of any user actions such as mouse, key, and tablet events. In response to user events, the custom view sets parameter values. Usually it sets the value of a custom parameter. The host application notices that a parameter value has changed and calls the plug-in to render with the new parameter values.
The plug-in can create a custom view object programmatically or retrieve it from a XIB
file (created in Xcode’s Interface Builder and placed in your plug-in’s Resources
folder).
Your plug-in’s custom view methods must call the Fx
host API —
start
method before your plug-in accesses any parameter values, and then call the -
end
method after it has finished accessing the parameter values. This lets the host application set up and restore the internal state.
Update Versioning for Your Plug-in
As you develop plug-ins over time, you may need to deprecate, add, or update your parameters, like changing a default value or range.
To ensure that projects using your older plug-ins still function correctly, use Fx
to find out the version of the plug-in that’s used with a project. With this information, you can branch your parameter code, update your project, and handle special cases as needed.
For example, if you create a version 1 brightness filter with a floating point slider and apply it to a project, the project saves the plug-in’s version number along with the slider value. On subsequent launches of the project, you can query version
and check for a version number of 1
.
Tip
If you later update the brightness filter to use a second parameter, update the version of your plug-in. Then, on subsequent launches, do a version check and add a second path for a version number of 2
.