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.