ivtools FAQ

Others see "warning: drawing version 0 newer than idraw version 0" when they load my drawing into their copy of idraw.

The idraw version format number was incremented from 10 to 11 with ivtools-0.6.7. The intent of this new version number was to add support for more of the features of PostScript (and X11) that can be generated by utilities like plotutils: floating-point line width, cap-styles, join-styles.

From ivtools-0.6.7 to ivtools-0.7.2 the only change in the idraw format was the addition of some calls to closepath in the PostScript, to ensure ellipses and circles are closed. This change was embedded in the PostScript prologue of the idraw document, and the result can still be read by older versions of idraw.

But the change in version number is detected by older versions of idraw, and a warning is printed out. Problem is, there has always been a bug in the warning message output (floats were treated as ints), so you see the not-so-helpful message of "warning: drawing version 0 newer than idraw version 0". This problem has been fixed since ivtools-0.6.7. This patch could be applied to any other distribution of InterViews to alleviate the problem in those copies of idraw.

Others see "warning: drawing version 0 newer than idraw version 0" then a segfault when they load my drawing into their copy of idraw.

First off, read the previous FAQ entry to understand why the warning message isn't more helpful.

Secondly, the document you gave them has more than just a different version number. It probably makes use of some sort of backward-incompatible extension to the format. From its inception the idraw format versioning system was designed to be forward- if not backward-compatible. Which means you can always read older documents with newer versions of idraw, but the opposite is not guaranteed (hence the warning message). Sometimes it works, sometimes it doesn't.

The idraw format version 11 introduced by ivtools-0.6.7 is the first new version number since the InterViews 3.1 tar file was published in 1993. But up until ivtools-0.7.3 nothing of a backward-incompatible nature had been done with the new format number. And with ivtools-0.7.3 most all uses of the format are still 100% backward compatible.

But now there is a chance that you might generate, using a yet-to-be released copy of plotutils or some other approach, a version 11 idraw PostScript document with non-integer floating point line widths. This is handled smoothly by the idraw of ivtools-0.7.3 (and will be handled smoothly by the rest of the drawing editors of ivtools come 0.7.4), but presenting a version 11 idraw format with non-integer line widths to any version of idraw prior to ivtools-0.6.7 will cause the above warning message to be printed, possibly followed by a segfault. Presenting a version 11 idraw format with non-integer line widths to any version of idraw from ivtools-0.6.7 to ivtools-0.7.2 will not generate a warning message or cause a segfault, but neither will the document be read in.

To clear up all this confusion, the forthcoming version of ivtools (0.7.4) will increment the idraw format version number once again, from 11 to 12, and it will be recommended that non-integer line widths not be used in conjunction with format version 11 (although there is some support for it). In that way users of an idraw from ivtools-0.6.7 (i.e. users of Debian 2.1) will be warned of a version incompatibility if there is one, given a hint why their document did not open in idraw.

source building questions

I run "make World" or "make Makefiles", and see an error message like this

Making Makefiles for in
/proj/ivtools-0.7/src/IV-common/
/bin/sh: test: argument expected


Looks like you need set the value of CPU in config/config.mk. The configure script should have written the value of "make CPU" in that file, i.e. "CPU = LINUX". Run "make CPU" again by hand to see what it should be. "grep ArchitectureName config/arch.defs" to get a complete list of supported operating systems.

How should CPU be set in config.mk for Solaris?

Set the CPU make variable to SUN4.

I just can't get ivtools built on anything but Linux or FreeBSD. What do I do?

Unique challenges are present for building ivtools on any commercial version of Unix, problems that just don't exist with open-source free software Unix'es. But don't despair, read through the following list of pointers and try again. It's only the build process that's frustrating. Once you get it built you'll find most of the code is very old and very stable on a wide variety of platforms.

Even before reading this list, see if you have CPU defined in config/config.mk. If you have no config/config.mk, do a ./configure. If it is undefined in config/config.mk, test what the value should be with "make CPU".

I just installed gcc-2.8.1, and when I rebuild ivtools I see this:
/tmp/cca09221.s: Assembler messages:
/tmp/cca09221.s:193: Error: invalid character (0x8) before first operand

You need to turn on optimization to work-around bugs in non-optimized compilation. Add these lines to ivtools-0.7/config/local.def:

/*
 * What you need to turn on optimizing (a good idea)
*/ #undef TurnOnOptimizing
#define TurnOnOptimizing YES


And "make Makefiles;make clean;make". This will be included by default in ivtools-0.7.4.

I supplied a --prefix argument to configure, but "make install" does not use this prefix consistently?

This was fixed in ivtools-0.7.4.

"make install" doesn't install the Unidraw include files.

This was fixed in ivtools-0.7.4.

programming and debugging questions

How do I set up a stand-alone program or source tree on top of ivtools for development purposes?

If you are writing a stand-alone program that will exist in a single directory, simply copy an appropriate Imakefile and main.c from a InterViews or ivtools example program directory, modify accordingly, then use "ivmkmf -a" to generate the Makefile. Make sure you are using a fresh ivmkmf that corresponds to your installation of ivtools. An example of this is the comtop sample program, a stand-alone program separate from ivtools that builds on top of the comterp command interpreter mechanism.

If you are setting up an entire source tree with both class libraries and executable programs, you will want to get started by replicating an equivalent source tree (i.e. vhclmaps) and change or rename all directories or files as appropriate.

How do I add a new tool to the toolbar of a drawing editor derived from ivtools?

First locate an existing tool (some subclass of Tool) that closely matches your requirements. Create a new derivative or cloned class, which involves specifying a new ::InterpretManipulator method (and maybe a new ::CreateManipulator method). You might also want to create a new class id by copying the implementation of another Tool's ::IsA method. Then plug it into your drawing editor by adding an entry for it in the ::MakeToolBar method of a class derived from OverlayKit. More information about the design involved can be found in Unidraw documentation. The OverlayKit object is an ivtools enhancement to Unidraw. It is an object used by the Editor (the OverlayEditor) to construct itself. In this fashion virtual methods can be applied to the editor construction process, one of the more central activities in constructing a Unidraw based drawing editor.

How do I add a new pull-down command to a drawing editor derived from ivtools?

First locate an existing command (some subclass of Command) that closely matches your requirements. Create a new derivative or cloned class, which involves specifying a new ::Execute method. You might also want to create a new class id by copying the implementation of another Command's ::IsA method. Then plug it into your drawing editor by adding an entry for it in the appropriate ::Make*Menu method of a class derived from OverlayKit. More information about the design involved can be found in Unidraw documentation. See the item above for more details on the OverlayKit object.

How do I possibly begin to program with a source tree that has so little documentation?

First off, maybe you can program what you want by using the command interpreter embedded into the ivtools drawing editors and networked servers. It is a fully-programmable function-based interpreter with syntax no more complicated than that of C expressions. Designed to appeal to engineers and scientists, it could have what you're looking for in terms of easily programmable manipulation of spatial data. And it can be extended easily by C programmers, without requiring the mastery of an object-oriented application framework.

Secondly, there really is a lot of documentation. Read all this, then come back and ask the question again.

Finally, the whole field of design patterns was launched, after the fact, in an attempt to document the inner workings of frameworks like these. If a single man page per class was an adequate approach you wouldn't have five or six textbooks and numerous technical papers published to date on the subject. Here's the book that started it all, by the notorious Gang of Four, Design Patterns, Elements of Reusable Object-Oriented Software.

However, reading documentation alone will never make you a capable programmer with application frameworks of this complexity. Just as in mathematical proofs and circuit design, there is no substitute for direct study of the underlying logic if you wish to acquire competence in this discipline. On the other hand, there is no need to study the parts that work for you without further investigation, but any real-world use of these class libraries will inevitably bring you up with a segfault in a debugger staring at code you've never seen before. At this point you have two choices: a) you can welcome this learning opportunity, and start reading the source code with the debugger, treating it as a scientific experiment where you are attempting to discover the information you need to make things work the way you want, or b) switch to using some other toolkit, either one with a more constrained programming language (like Visual Basic or Tcl/Tk) or one with a more extensively-documented set of objects (like MFC or Java Swing) where the hope is you can resolve problems by reading documentation instead of debugging. Each choice has its pros and cons.

Further reading:

Whenever I attempt to debug a derived Tool's InterpretManipulator method (or some other event handling software) it hangs my X server

Try adding -synchronous to the run command line in gdb. Or debug with print statements.

I can't inspect the value of a local variable in gdb. What do I do?

Recompile without optimization (without -O), or try to infer the information you need from other variables.

The value of an argument to a method or function (as displayed by gdb) gets corrupted halfway through the execution of the function/method. Otherwise things work fine. Should I worry about this?

No, not particularily. The stack memory associated with an input variable can be recycled by the compiler after that value is no longer needed.

I'm having trouble debugging a heap memory management problem. I get a segfault in malloc or free, and I can't trace what's wrong in the debugger. What do I do?

You can relink your program with this source version of malloc.c, and debug as normal. To add it to a program, add an entry for malloc.c right after the entry for any main.c in the corresponding Imakefile, then do a "make Makefiles" and "make" to rebuild.

Malloc debugging tips:

set conditional breakpts at the end of malloc or the start of free

there is a 4 byte offset between a memchunk and a regular pointer

use the display command in gdb to watch a variable while single-stepping

Printing out the contents of a ComValue in gdb is troublesome, because of the number of static class variables of type ComValue. How can I work around this?

Cast the ComValue to an AttributeValue before printing in gdb. An AttributeValue has most all the member values of a ComValue (at least the ones that matter for everyday debugging of comterp applications), and none of the static member variables. _AV is a shorthand typedef for AttributeValue you can use from within gdb.

What if I want to use insure++/insight to compile ivtools on an Alpha?

Bruno Delfosse of Thompson CSF contributed this patch to modify the config files as necessary.

What changes, if any, have been made to the API of InterViews and Unidraw?

In a few places, as needed, a member variable or method has been promoted from private to protected, or protected to public, to facilitate derivation from a class and reuse of the implementation of their methods. The designers of InterViews seemted to have been pursuing a somewhat black-box theory of object-oriented programming, but we've found you have to be able to look inside these boxes whenever and whereever you need. This is a change to the API that doesn't even require recompilation.

In a few other places small utility methods have been added as needed, most of them non-virtual. These extend the API without compromising backward compatibility, which has been tested by building sizeable packages like TargetJr and MiXViews on top of ivtools.

Then, in a few specific places new mechanism has been added to the original classes of InterViews and Unidraw. The Session class has been altered to support a wider variety of X applications. The Graphic class has been extended with mechanism to hide/show a graphic, disable/enable its sensitivity to mouse events, and cache point lists for efficiency in memory usage and ASCII serialization. These changes are easily propogated to any third party software by recompilation only, requiring no source changes.

But the balance of widgets, glyphs, and Unidraw component classes have remained untouched. New capability has been created by setting up new class libraries, and populating them with derived classes. For example, IVGlyph is a class library of specialized glyphs and dialog boxes that build on the observer-observable design pattern. OverlayUnidraw is a layer on top of both Unidraw and idraw classes that adds or integrates several things to the original capability: double-buffering, switchable look-and-feel, an alternate serialization of components, etc..

It is possible that in the future a derivative work of ivtools could abandon this backward compatibility, refactoring the existing mechanisms to reduce the footprint of applications, to better separate the component-based server programming from the component-based drawing editors, and better facilitate cross-platform development. The document formats and scripting languages of ivtools could be preserved through such a refactoring, and there probably would be a writeup on how to manually upgrade third-party applications from one to the other. And the original architecture can be used indefinitely as well.

miscellaneous questions

What about Fresco and fdraw?

Fresco is the software development project undertaken by some of the team that built InterViews. Fresco unifies structured graphics and structured documents (glyphs), has an OS-portable widget representation, and offers embeddability via CORBA. Thomas Hiller as been one of the principle maintainers, and put out a Fresco97 and Fresco98 tar file available at http://radagast.ti5.tu-harburg.de/fresco/. More details at http://www.vectaport.com/ivtools/interviews.html.

fdraw is the example drawing editor, somewhat like idraw, that comes with Fresco. An evolved fdraw is the basis of vistool, a user interface in the IUE and Target Jr image understanding software distributions. fdraw was the starting point for a Fujitsu proprietary Fresco GUI builder as well.

Have you fixed any documented memory leaks that were in InterViews 3.1?

If you are referring to these: ftp://ftp.informatik.uni-kiel.de/pub/graphics/X/InterViews/bug-fixes/memory_leaks.gz, no, they seem due to the construction of permanent tables in the InterViews and Unidraw frameworks, ones that never shrink at run-time, so why worry about their destruction, when an exit() works just as well? We'd be interested in any other Purify like information about these source trees. You can forward that or any other comments and questions about the package to ivtools-info@vectaport.com.

What happened to Doc? Where can I find Lexi?

Doc is a document editor, written by Paul Calder. It showed how flyweight graphic objects (glyphs) could be used down to the single character level in a TeX-like structured document. Lexi is the Doc-based editor described in Chapter 2 of the Design Patterns textbook, where Vlissides, et.al. take the lessons learned on Unidraw and other GUI frameworks and apply them to the case study of rebuilding Doc. You can get the source code for Doc from the original InterViews tar file (InterViews ftp site at Stanford ). It should build on top of ivtools without modification to any source files. No source code seems available for Lexi.

Why is this only version 0.7.*?

Although some of the code in ivtools is very old (giving users a unique form of patent protection), some of the code is always new. In 1994 when the effort on ivtools began (two years before we even considered directly incorporating the InterViews 3.1 classes) an original version number of 0.3 was chosen, to reflect that this was roughly the third time our programming team had created and distributed a value-added layer on top of InterViews. Since then the version number has increased by .1 a year. It is thought that a 1.0 version of ivtools will happen when other programmers get a chance to really test it out, evaluate the completeness of coverage, and contribute their two cents to the overall architecture. See this list of ivtools things to do to get an idea of what remains. The core is solid, the entire skeleton still needs fleshing out.

All that said, don't let the less than 1.0 version number stop you from using ivtools if you have the need. We've been using it for five years, and have had little problem upgrading our customers as we go, given the nature of source-based development with C++.

other FAQs