Article

Adding Parameters to Plug-ins

Create standard and custom user-facing parameters for your plug-in that will appear in the inspector.

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 -addParametersWithError: method. This method is declared in the FxBaseEffect protocol, which is inherited by the FxTileableEffect 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 -addParametersWithError: 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 FxParameterCreationAPI_v5 protocol.

For example, the following code shows an -addParametersWithError: method from a simple opacity filter:

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 FxCustomParameterViewHost_v2.

Interact with Parameters

When a user changes a parameter control for an FxPlug plug-in, the host application calls the -parameterChanged:atTime:error: 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 -parameterChanged:atTime:error:.

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 FxCustomParameterViewHost_v2 protocol. An example of this can be found in the FxSimpleColorCorrector sample plug-in.

In your plug-in, custom parameters conform to the FxParameterViewHost protocol by implementing a -createViewForParameterID: 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 FxCustomParameterActionAPI_v4 host API startAction: method before your plug-in accesses any parameter values, and then call the -endAction: 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 FxVersioningAPI 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 versionAtCreation and check for a version number of 1.

Topics

Parameter APIs

FxParameterCreationAPI_v5

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

FxParameterRetrievalAPI_v6

Defines the functions the application provides to retrieve parameter values.

FxParameterSettingAPI_v5

Defines the functions the application provides to set parameter values.

FxDynamicParameterAPI_v3

Allows your plugin to create parameters on-the-fly.

Custom & Optional Parameters

FxOptionalParameterCreationAPI

The FxOptionalParameterCreationAPI protocol defines the methods implemented by the host application for creating parameters of optional types.

FxOptionalParameterRetrievalAPI_v2

The FxOptionalParameterRetrievalAPI_v2 protocol defines the methods the host application provides to retrieve parameter values.

FxCustomParameterViewHost_v2

Defines the methods a plug-in needs to implement to associate a custom NSView with one of its parameters.

FxCustomParameterActionAPI_v4

Defines the methods the host application provides to support a custom parameter view.

FxCustomParameterInterpolation_v2

Defines the methods a plug-in needs to implement to support keyframing custom parameters.

Constants

FxParameterFlags

These constants specify the characteristics of parameters display.

FxHistogramChannel

Constants used to identify which channel a histogram operation should apply to.

See Also

User Interface

Adding Onscreen Controls to Plug-ins

Simplify user interaction by using onscreen controls for your FxPlug plug-in.

FxPathAPI_v3

An API that defines the methods to retrieve information about paths, shapes, and masks the user has drawn on an object.

FxUndoAPI

An API that defines the methods implemented by the host application to allow a plug-in to manage the host application's undo queue.