|  |  | 8 Writing ipelets

# 8 Writing ipelets

An ipelet is a dynamically loaded library (DLL), that you place on Ipe's ipelet search path. Ipe loads all DLLs it can find on that path during start-up. 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 minimal ipelet implementation:

    #include "ipelet.h"

    class MyIpelet : public Ipelet {
    public:
      virtual int IpelibVersion() const { return IPELIB_VERSION; }
      virtual const char *Label() const { return "My label"; }
      virtual void Run(IpePage *page, IpeletHelper *helper);
    };

    void MyIpelet::Run(int function, IpePage *page, IpeletHelper *helper)
    {
      // this is where you do all the work
    }

    IPELET_DECLARE Ipelet *NewIpelet()
    {
      return new MyIpelet;
    }

When the ipelet is executed, Ipe hands it a pointer to the current page of the document. The ipelet can examine the selected objects, and modify the page in any way it wishes. It can also request services from the Ipe application through the `IpeHelper` object, for instance to display a message in the status bar, to pop up a message boxes, to obtain input from the user, etc. Through the `IpeHelper`, it is also possible to access the complete document (for instance to write an ipelet that allows the user to reorganize the pages of the document), or to access some Ipe settings.

Have a look at the ipelet sources in the Ipe source distribution. Kgon is a minimal ipelet that you can use as the basis for your own development. Goodies is an example of an ipelet that contains more than one function--it also needs to implement the member functions `NumFunctions` and `SubLabel`. Note that it is possible for ipelets to define keyboard shortcuts (the Align ipelet does that, for instance), but in general it is not a good idea to do that for ipelets you plan to make available for others.

The ipelet must be compiled as a DLL ("shared library" in Unix-speak), and must be linked with the Ipe library "Ipelib". See the project files of the ipelets in the distribution for details.

The Ipelib documentation in HTML-format is here.

|  |  | 8 Writing ipelets