Navigation (HowTo)

Search the wiki

Making Your Effect Configurable
Most effects and adjustments allow the user to customize settings to achieve the desired effect.

This guide builds on the effect written in Writing an Effect. In that sample, the effect removed the blue channel from the user's image. This guide will expand that effect to be configurable, so the user can choose to remove the blue, green, or red channel.

Supporting Configuration

There are 2 members to override on BaseEffect that determines if your effect is configurable. Override IsConfigurable and return true, and then performs your configuration in LaunchConfiguration.

public override bool IsConfigurable { get { return true; } }

public override bool LaunchConfiguration ()
    // Return true if the user accepted the configuration.
    // Return false if the user cancelled.
    return true;

In LaunchConfiguration, you can do whatever is needed for configuring your effect. Generally this entails showing a dialog with options for the user to manipulate.

Making it Easier

Most effects use the same types of options, like value ranges, checkboxes, and combo boxes. Rather than create a new dialog from scratch for each effect, Pinta has something called the SimpleEffectDialog that can construct the dialog for you based on the options the effect supports.

For our sample, we said we wanted the user to be able to turn on or off the Red, Green, or Blue components. To do this, we'll create a class that inherits from EffectData that has our 3 options.

public class RemoveColorData : EffectData
    public bool Blue;
    public bool Red;
    public bool Green;

In the effect's constructor, we create a new data class and assign it to the BaseEffect.EffectData property.

public MyEffect ()
    EffectData = new RemoveColorData ();

Next, we call EffectHelper.LaunchSimpleEffectDialog in LaunchConfiguration to tell Pinta we want to use the SimpleEffectDialog system.

public override bool LaunchConfiguration ()
    return EffectHelper.LaunchSimpleEffectDialog (this);

Finally, we'll update our Render algorithm to look at our settings class and render appropriately.

protected override ColorBgra Render (ColorBgra color)
    if ((EffectData as RemoveColorData).Blue)
        color.B = 0;

    if ((EffectData as RemoveColorData).Red)
        color.R = 0;

    if ((EffectData as RemoveColorData).Green)
        color.G = 0;

    return color;

Now if we compile and launch our effect, we will see that the following option dialog is created and displayed for us.


As you click the options, you will see that the canvas shows a live preview of your effect. Clicking Ok will apply the effect, while clicking Cancel will cancel the effect.

Another Example

The sample above is pretty trivial, but the SimpleEffectDialog can be used to create complex dialogs. For example, the following settings class from the Polar Inversion effect:

public class PolarInversionData : BaseEffect
    [MinimumValue(-4), MaximumValue(4)]
    public double Amount = 0;

    [MinimumValue (1), MaximumValue (5)]
    public int Quality = 2;

    public Gdk.Point CenterOffset;

    public WarpEdgeBehavior EdgeBehavior = WarpEdgeBehavior.Wrap;		

Produces the following dialog:


For a complete reference of the supported data types, see SimpleEffectDialog Reference.
  Name Size
- effect-dialog.png 13.77 KB
- polar.png 14.72 KB

Last modified on Apr 02, 2011 17:21 by jpobst