Writing a File Format Addin

This guide assumes that you have set up a basic add-in as described in [Writing an Add-in] (https://github.com/PintaProject/Pinta/wiki/Getting-Started:-Writing-an-Addin).

This guide will demonstrate how to write a custom file format add-in for Pinta. We'll be writing an add-in to support importing and exporting the [WebP image format] 1. The full source code for this example is available at https://github.com/PintaProject/WebPAddin, and the add-in can be installed from Pinta's add-in repository.

The Basics

Ensure that the add-in description file (.addin.xml) has the category set to File Formats. This will make it easier for users to find your brush in the Add-in Gallery. The add-in description file should now look like:

<?xml version="1.0" encoding="UTF-8" ?>
<Addin id="WebP" version="0.1" category="File Formats">    
    <Header>
        <Name>WebP</Name>
        <Description>Provides support for the WebP image format.</Description>
        <Author>Pinta Project</Author>
        <Url>https://github.com/PintaProject/WebPAddin</Url>
    </Header>
    <Dependencies>
        <Addin id="Pinta" version="1.5" />
    </Dependencies>
</Addin>

All file format importers inherit from IImageImporter. There are two required methods that you must implement:

• Import is responsible for loading an image and creating a new document with the contents of the image. In addition to the filename parameter, the current parent window is also given. This allows you to properly create a modal dialog if, for example, you need to display an error message.
• LoadThumbnail is called by the Open Image dialog, and returns a Gdk.Pixbuf containing a thumbnail of the given image. For some file formats (such as the [OpenRaster] 2 format) it is possible to load a thumbnail more efficiently than when loading the full image. Otherwise, you can reuse most of your code from the Import method when implementing this method. The maxWidth and maxHeight parameters provide a suggested width and height to use when loading the thumbnail. If your image format does not allow you to take advantage of this information, you can return a full-size image and Pinta will resize it for you in order to fit in the Open Image dialog.

All file format exporters inherit from IImageExporter. There is only one required method that you must implement:

• Export is responsible for saving a Pinta.Core.Document to the specified filename. As with the IImageImporter methods, the current parent window is passed as a parameter. This allows you to properly create a modal dialog if you need to display an error message or ask the user to choose settings (such as the image quality).

Your file format add-in does not need to provide both an importer and an exporter - for example, an ASCII art add-in would likely only want to provide an exporter.

Let's create a skeleton implementation of our importer and exporter:

using System;
using Gdk;
using Pinta.Core;

namespace WebPAddin
{
    public class WebPImporter : Pinta.Core.IImageImporter
    {
        public void Import (string filename, Gtk.Window parent)
        {
            throw new NotImplementedException ();
        }

        public Pixbuf LoadThumbnail (string filename, int maxWidth, int maxHeight, Gtk.Window parent)
        {
            throw new NotImplementedException ();
        }
    }

    public class WebPExporter : Pinta.Core.IImageExporter
    {
        public void Export (Document document, string fileName, Window parent)
        {
            throw new NotImplementedException ();
        }
    }
}

Other Examples

For other examples, you can take a look at the file format importers and exporters that are shipped with Pinta: https://github.com/PintaProject/Pinta/tree/master/Pinta.Core/ImageFormats