Ipelib: Ipelets written in C++

Ipelib

- Main Page
- Modules
- Classes

# Ipelets written in C++

As in Ipe 6, it is possible to write ipelets entirely in C++. Different from Ipe 6, however, the labels of the ipelet and its functions must now be specified in a short Lua wrapper with some boilerplate code. This Lua code will invoke your C++ methods.

## C++ ipelet framework

The C++ code is in a dynamically loaded library (DLL), that you place on Ipe's C++ ipelet path. The DLL has to be written in C++, and must export a function `newIpelet` that creates an object derived from the class `Ipelet` (defined in ipelet.h). Here is a minimal ipelet implementation:

    #include "ipelet.h"

    class MyIpelet : public ipe::Ipelet {
    public:
      virtual int ipelibVersion() const { return IPELIB_VERSION; }
      virtual bool run(int function, ipe::IpeletData *data, ipe::IpeletHelper *helper);
    };

    bool MyIpelet::run(int function, ipe::IpeletData *data, ipe::IpeletHelper *helper)
    {
      // this is where you do all the work
    }

    IPELET_DECLARE ipe::Ipelet *newIpelet()
    {
      return new MyIpelet;
    }

When the ipelet is executed, Ipe hands it a structure with some information about the document, in particular a pointer to the current page. The ipelet can examine the selected objects, and modify the page in any way it wishes. (It is not possible to modify the document outside the current page, as this would interfere with the undo stack). It can also request services from the Ipe application through the `IpeletHelper` object, for instance to display a message in the status bar, to pop up message boxes and to obtain input from the user.

The run method must return true if it modified the document page. This is used to create an item on the undo stack so that this change can be undone. If the run method returns false, then no undo stack item is created. In this case, the ipelet must not modify the page.

## The Lua wrapper

You need to provide a small Lua wrapper that declares the names of the ipelet and its methods, and that calls your C++ code when an ipelet method is invoked. This wrapper will look as follows:

    -- Lua wrapper for C++ ipelet "myipelet"

    label = "My Ipelet"

    about = "This ipelet is for explanation only"

    -- this variable will store the C++ ipelet when it has been loaded
    ipelet = false

    function run(ui, num)
      if not ipelet then ipelet = assert(loadIpelet("myipelet"))
      ui:runIpelet(ipelet, mum)
    end

    methods = { { label = "First function of my ipelet" },
                { label = "Second function of my ipelet" }
              }

If the ipelet contains only a single method, then the `methods` table is omitted.

The Lua wrapper needs to be placed in Ipe's ipelet directory. When Ipe starts up, it automatically loads all ipelets from this directory. Note that the wrapper above does not immediately load the C++ ipelet (using `loadIpelet`) when the Lua wrapper is loaded by Ipe, but only when the first method of the ipelet is called. This is considered good style.

## An example ipelet

Kgon is a minimal ipelet that you can use as the basis for your own development. It defines only a single function, and makes no use of the function argument to `run`.

    // --------------------------------------------------------------------
    // Ipelet for creating regular k-gons
    // --------------------------------------------------------------------

    #include "ipelet.h"
    #include "ipepath.h"
    #include "ipepage.h"

    using namespace ipe;

    // --------------------------------------------------------------------

    class KGonIpelet : public Ipelet {
    public:
      virtual int ipelibVersion() const { return IPELIB_VERSION; }
      virtual bool run(int, IpeletData *data, IpeletHelper *helper);
    };

    // --------------------------------------------------------------------

    bool KGonIpelet::run(int, IpeletData *data, IpeletHelper *helper)
    {
      Page *page = data->iPage;
      int sel = page->primarySelection();
      if (sel < 0) {
        helper->message("No selection");
        return false;
      }
      const Path *p = page->object(sel)->asPath();
      if (p == 0 || p->shape().countSubPaths() != 1 ||
          p->shape().subPath(0)->type() != SubPath::EEllipse) {
        helper->message("Primary selection is not a circle");
        return false;
      }

      String str;
      if (!helper->getString("Enter k (number of corners)", str))
        return false;
      int k = Lex(str).getInt();
      if (k < 3 || k > 1000)
        return false;

      const Ellipse *e = p->shape().subPath(0)->asEllipse();
      Matrix m = p->matrix() * e->matrix();

      Vector center = m.translation();
      Vector v = m * Vector(1,0);
      double radius = (v - center).len();

      Curve *sp = new Curve;
      double alpha = 2.0 * IpePi / k;
      Vector v0 = center + radius * Vector(1,0);
      for (int i = 1; i < k; ++i) {
        Vector v1 = center + radius * Vector(Angle(i * alpha));
        sp->appendSegment(v0, v1);
        v0 = v1;
      }
      sp->setClosed(true);
      Shape shape;
      shape.appendSubPath(sp);
      Path *obj = new Path(data->iAttributes, shape);
      page->append(ESecondarySelected, data->iLayer, obj);
      helper->message("Created regular k-gon");
      return true;
    }

    // --------------------------------------------------------------------

    IPELET_DECLARE Ipelet *newIpelet()
    {
      return new KGonIpelet;
    }

    // --------------------------------------------------------------------

The Lua wrapper would look like this:

    ----------------------------------------------------------------------
    -- kgon ipelet description
    ----------------------------------------------------------------------

    label = "Regular k-gon"

    about = [[
    Constructs a regular k-gon from a circle.

    This ipelet is part of Ipe.
    ]]

    -- this variable will store the C++ ipelet when it has been loaded
    ipelet = false

    function run(model)
      if not ipelet then ipelet = assert(ipe.Ipelet(dllname)) end
      model:runIpelet(label, ipelet)
    end

    -- define a shortcut for this function
    shortcuts.ipelet_1_kgon = "Alt+Ctrl+K"

    ----------------------------------------------------------------------

## Compiling ipelets on Unix

The ipelet must be compiled as a shared library and must be linked with the Ipe library ``libipe.so''. C++ mandates that it must be compiled with the same compiler that was used to compile Ipe. Have a look at the ipelet sources in the Ipe source distribution, and their makefiles for details on compiling them.

## Compiling ipelets on Windows

The ipelet must be compiled as a DLL and must be linked with the Ipe library ``ipe.dll''. C++ mandates that it must be compiled with the same compiler that was used to compile Ipe. If you use the binary Ipe distribution for Windows, that means you have to use the MinGW compiler. (If you haven't used it before: MinGW is a port of g++ for Windows).

The Ipe Windows distribution contains the necessary header files and the library to compile ipelets, as well as the source of the ``kgon'' and ``goodies'' ipelets as examples. To compile the ``kgon'' example, open a command shell, make sure MinGW g++ is on your path, and say:

      g++ -c -O2 -DWIN32 -fno-exceptions -fno-rtti -Iinclude kgon.cpp
      g++ -Wl,-enable-stdcall-fixup -Wl,-enable-auto-import \
      -Wl,-enable-runtime-pseudo-reloc -Wl,-s -shared -o kgon.dll kgon.o \
      -Llib -lipe

Place the resulting kgon.dll in the ipelets subdirectory, and restart Ipe.