Change a button image

Overview

By default, when Loupedeck needs to draw a button image, it uses the display name of the command that is assigned to this button.

However, the plugin can change this behavior so that any image can be used for that. To inform Loupedeck that a custom image should be used, GetCommandImage method of the PluginDynamicCommand class must be overridden.

Moreover, if the plugin wants to change a button image at runtime (when the command state changes), the plugin can call ActionImageChanged method to inform Loupedeck about that.

In this example, we will create a simple dynamic command that toggles its state when the user presses a button. When the command state changes, the command requests redrawing the button image.

Steps

1. First, create a ToggleSwitchButton simple dynamic command that toggles the internal boolean _toggleState flag on every button press. See Add a simple command for more information about creating simple dynamic commands.

namespace Loupedeck.DemoPlugin
{
    using System;

    public class ToggleSwitchButton : PluginDynamicCommand
    {
        private Boolean _toggleState = false;

        public ToggleSwitchButton() : base("Toggle Switch", null, "Tests")
        {
        }

        protected override void RunCommand(String actionParameter)
        {
            this._toggleState = !this._toggleState;
        }
    }
}

1. Add two images for "on" and "off" states to the plugin project. They must be in PNG format and have 80x80 pixels size. Build action for these files must be set to "Embedded Resource". In this example, "ToggleSwitchButton0.png" and "ToggleSwitchButton1.png" images are used.

2. Add 2 string class members that will hold the image resource paths. In the constructor, set these members to the full path of these files. Note that call to EmbeddedResources.FindFile() method eliminates the need to know the exact path to these files.

private readonly String _image0ResourcePath;
private readonly String _image1ResourcePath;

public ToggleSwitchButton() : base("Toggle Switch", null, "Tests")
{
    this._image0ResourcePath = EmbeddedResources.FindFile("ToggleSwitchButton0.png");
    this._image1ResourcePath = EmbeddedResources.FindFile("ToggleSwitchButton1.png");
}

1. Override GetCommandImage method to return the right image based on the command state:

protected override BitmapImage GetCommandImage(String actionParameter, PluginImageSize imageSize)
{
    if (this._toggleState)
    {
        return EmbeddedResources.ReadImage(this._image0ResourcePath);
    }
    else
    {
        return EmbeddedResources.ReadImage(this._image1ResourcePath);
    }
}

1. Call the ActionImageChanged method when the command state changes:

protected override void RunCommand(String actionParameter)
{
    this._toggleState = !this._toggleState;
    this.ActionImageChanged();
}

Note that calling this.ActionImageChanged(null) will redraw all the buttons currently shown on the device.

Full code

namespace Loupedeck.DemoPlugin
{
    using System;

    public class ToggleSwitchButton : PluginDynamicCommand
    {
        private Boolean _toggleState = false;

        private readonly String _image0ResourcePath;
        private readonly String _image1ResourcePath;

        public ToggleSwitchButton() : base("Toggle Switch", null, "Tests")
        {
            this._image0ResourcePath = EmbeddedResources.FindFile("ToggleSwitchButton0.png");
            this._image1ResourcePath = EmbeddedResources.FindFile("ToggleSwitchButton1.png");
        }

        protected override void RunCommand(String actionParameter)
        {
            this._toggleState = !this._toggleState;
            this.ActionImageChanged();
        }

        protected override BitmapImage GetCommandImage(String actionParameter, PluginImageSize imageSize)
        {
            if (this._toggleState)
            {
                return EmbeddedResources.ReadImage(this._image0ResourcePath);
            }
            else
            {
                return EmbeddedResources.ReadImage(this._image1ResourcePath);
            }
        }
    }
}

Adding background image and text to button

Here is an example.

Note that MyImage.png file must be added to the plugin project as an embedded resource.

protected override BitmapImage GetCommandImage(String actionParameter, PluginImageSize imageSize)
{
    using (var bitmapBuilder = new BitmapBuilder(imageSize))
    {
        bitmapBuilder.SetBackgroundImage(EmbeddedResources.ReadImage("MyPlugin.EmbeddedResources.MyImage.png"));
        bitmapBuilder.DrawText("My text");

        return bitmapBuilder.ToImage();
    }
}