[Previous] [Up] [Next]
Go backward to Ipe user macros distributed with Ipe
Go up to Ipe user macros
Go forward to Writing Ipe user macros

How Ipe calls a user macro

If you want to call an Ipe user macro from Ipe, it has to be listed in your X resources. The X resources can contain the name of the executable, possibly some argument, some flags, a keyboard shortcut and an entry for the menus.

  When Ipe calls a Ium it first writes a file (the interface file) describing the currently selected objects. It then looks for the executable in the directories listed as iumDirectories in the X resources. If a file of the given name exists, Ipe calls this executable with two or three arguments. The first argument is the name of the temporary file where Ipe has stored the current selection. The second argument is an argument given in the resources entry. It has no further meaning for Ipe. It is the Ium's responsibility to interpret this argument. Usually, different values select different functions implemented in the same executable. It is also possible to use this to set debug flags, verbose flags, or to trigger special modes. The third argument can be used when the Ium needs a parameter: Ipe can be instructed to prompt the user for a string (or even for a file name), and this string is then passed as the third argument of the Ium.n

The Ium reads the interface file, processes the objects, and writes a description of its output back into the same file. When the Ium call returns to Ipe with non-zero exit status, Ipe supposes that the Ium has messed up. A fatal error message is displayed, and the output file is not read. Use this feature only if something serious is wrong.

Otherwise, Ipe reads the file written by the Ium, and handles the objects described in the file as demanded by the user macro (using a parameter in the file, see the next section).

  While the user macro is running, Ipe is in a mode that resembles the normal drawing modes. In particular, you can interrupt the Ium by pressing M-ESC. This is implemented by sending a SIGINT signal to the Ium. If the Ium creates any temporary files, it should catch this signal and do the necessary clean-up.

The flags set in the X resources entry can be used to modify Ipe's standard way of calling Iums.

If the -nodata flag is given, then Ipe will write an interface file without any objects (but which still contains the current settings of Ipe). This feature is used by the precise box user macro, for instance.

If the -nofile flag is given, then Ipe does not even write an interface file. This feature is used by Iums that only import objects.

If the -norawbits flag is set, then Ipe will not write raw bitmaps to the Ium. (Normally, to speed up the calling of Iums, all bitmaps are written in raw format.) Note that Ipe will recognize Postscript style bitmaps as well as raw bitmaps in the output file of the Ium.


[Previous] [Up] [Next]