mfGraph Library version 0.3 (June 10, 2005)

Copyright 2003-2005 Michael Fötsch

Homepage: http://www.geocities.com/foetsch/

Mail: foetsch@users.sourceforge.net

Table of Contents

Revision History

• 0.1.0 (Sep 21, 2003):
  • Initial version
• 0.2.0 (Oct 8, 2003):
  • Added pymfg (Python bindings)
• 0.3.0 (June 10, 2005):
  • Ported to GNU Automake
  • Various code fixes for GNU/Linux
  • mfGraphUI bug fixes
  • Added MFC demo
  • Added wxPython demo

License

The mfGraph Library, pymfg, and VCL components are distributed under the terms of the Lesser General Public License. The file lgpl_license.html contains the license terms.

The mfGraph UI Sample Application is distributed under the terms of the General Public License. The file gpl_license.html contains the license terms.

Package Contents

(not all files shown)

  mfgraph-0.3/
    contrib/                 - additional files for users of Microsoft Windows
      bcb_demo/              - mfGraph UI Sample Application (Borland C++Builder)
      bcb_pymfg/             - Python extension DLL project for Borland C++Builder
      mfc_demo/              - MFC-based demo application
      pymfg_demo/            - wxPython demo application
      windows_lib/           - mfGraph library project files for Visual C++ 6.0
      windows_pymfg/         - Python extension DLL project for Visual C++ 6.0
      mfc_demo.exe           - precompiled MFC demo for Windows
      mfgraphui.exe          - precompiled mfGraphUI Sample App for Windows
    doc/
      html/
        index.html           - source code documentation
    pymfg/                   - Python extension library sources
    src/                     - mfGraph library sources
    test/                    - simple C++ test application
    INSTALL                  - generic installation instructions for Automake-based build    

Optional and Required Third-Party Packages

You might need the following additional packages:

• Doxygen - if you want to rebuild the source code documentation

• Flex/Bison - if you want to modify the parser sources

• Python - if you want to build the Python extensions

• Swig - if you want to modify the Python extension sources

• wxPython - if you want to run pymfg_demo

These are the software versions that I tested with:

Build Instructions GNU/Linux

In the mfgraph-0.3 directory, run these shell commands:

mkdir build
cd build
../configure
make
make install

As usual, run ../configure --help for help on additional settings.

The following items will be installed:

• C++ header files to the specified include path
• libmfgraph shared library to the specified library path
• Python package "mfGraph" (the pymfg extension library) to the Python path

Build Instructions Windows

You need the following software to be able to rebuild the library and sample applications:

• Visual C++ or C++Builder for the mfGraph Library
• C++Builder 5 or later for the mfGraph UI Sample Application
• flex.exe and bison.exe if you wish to rebuild the DOT language parser

  • You can get bison.exe here: http://gnuwin32.sourceforge.net/packages/bison.htm

  • You can get flex.exe here: http://gnuwin32.sourceforge.net/packages/flex.htm

  • I tested with Flex version 2.5.4a and Bison version 1.875
  • If you do not want to run Flex and Bison, deactivate the Custom-Build Step for the files mfg_flex.ll and mfg_bison.yy in the project contrib\windows_lib\mfgraph_lib.dsp.

• swig.exe (http://www.swig.org) to rebuild the Python wrapper code.

  • Important: To avoid problems with Visual C++ 6.0, don't use the latest version and download version 1.3.21 instead.

  • If you do not want to run Swig, deactivate the Custom-Build Step for file swig.i in the project contrib\windows_pymfg\pymfg.dsp.

Microsoft Visual C++-Specific

1. Optionally, add the paths to flex.exe, bison.exe, and swig.exe in "Tools" -> "Options" -> "Directories"

2. Optionally, add the path to Python.h (typically C:\Python2x\include) in "Tools" -> "Options" -> "Directories"

3. Optionally, add the path to python2x.lib (typically C:\Python2x\libs) in "Tools" -> "Options" -> "Directories"

4. Open the workspace contrib\mfc_demo\mfc_demo.dsw and build the project "mfc_demo". This will also build the mfGraph DLL in contrib\windows_lib.

   • Note: "Rebuild All" requires Flex/Bison to be installed, unless you check "Exclude from Build" in the options of the files mfg_flex.ll and mfg_bison.yy.

5. To build the Python extension DLL, open the workspace contrib\windows_pymfg and build the project

   • Note: "Rebuild All" requires Swig to be installed, unless you check "Exclude from Build" in the options of the file swig.i.

6. To install the Python extension DLL, run "setup.py install"

Issues:

• The GNU/Linux Automake build creates files with a .cc extension when flex/bison is run. Visual C++ 6.0 does not know how to handle such files. As I don't know how to tell Automake to name these files .cpp, I simply copied the generated files to contrib\windows_lib and changed the extension to .cpp. (More precisely, there's a make rule "dist-hook" in the Automake build that does this automatically.)
  • There's a (minor) problem with this:
    • The "#line" directives in the files still refer to the original .cc file. When there's a compiler error, the IDE won't be able to open that file to present you the source of the error.

Borland C++Builder-Specific

Before you can build or run the mfGraph UI Sample Application, you must

• Download and install GraphViz from http://www.research.att.com/sw/tools/graphviz/download.html

• Make sure that the path to DOT.EXE is in the PATH environment variable

To build the mfGraphUI Sample Application:

1. Open the project group contrib\bcb_demo\ProjectGroup1.bpg

2. Build the project "mfgraph_lib"
3. Build and install the package "mf"; new VCL components will be registered
4. Build the project "mfgraphui"

To build the Python extension DLL:

1. Convert the Python import library python23.lib (typically in C:\Python23\libs) to OMF format, e.g.:

   • > cd C:\Python23\libs
     > C:\Program Files\Borland\CBuilder5\bin\coff2omf.exe python23.lib python23_omf.lib

2. Open the project group contrib\bcb_pymfg\ProjectGroup1.bpg

3. If Python is not installed in C:\Python23 (for example, because you are using a different version), you will have to modify the paths in the Project Options accordingly
4. If python23_omf.lib is not in C:\Python23\libs, remove python23_omf.lib from the project and re-add it from its actual location
5. Build the project "_pymfg"
6. To install the Python extension DLL, run "setup.py install"

Issues:

• When building mf_release.bpk from a fresh (unpatched) version of BCB 5, I get this linker error:

  • [Linker Error] Unresolved external '__fastcall Graphics::TMetafileCanvas::TMetafileCanvas(
    Graphics::TMetafile *, int)' referenced from C:\PROGRAM FILES\BORLAND\CBUILDER5\LIB\RELEASE\VCLE50.LIB|_t_Graph

    A workaround is to modify the VCL header graphics.hpp:

    Change this:
        __fastcall TMetafileCanvas(TMetafile* AMetafile, HDC ReferenceDevice);
    To this:
        __fastcall TMetafileCanvas(TMetafile* AMetafile, unsigned int ReferenceDevice);

    This is a known bug in BCB. Search the newsgroup archives for more info.
• When you open the project mfgraphui_release.bpr, you might get this error:

  • Error creating form: Error reading mfGraph1->DotListing.Strings: DOT.EXE could not be run..

    Solution: Before you open the project, make sure that DOT.EXE is on the path.

mfGraph Library Usage Example

(Those parts that make use of class mfg::GraphDrawer are specific to Microsoft Windows.)

This is a simple usage example to demonstrate

• using the mfg::DrawGraph class to manipulate graphs in memory

• invoking DOT.EXE to convert DOT listings into the XDOT format

• using the mfg::GraphDrawer class to draw graphs to device contexts

We would like to render the following graph:

    digraph G {
        a -> x [color=red]
        subgraph {
            b [style=filled fillcolor=green]
        }
        a -> b
    }

Step 1. Create a new application and either add mfgraph_lib.lib or add all CPP files in the mfGraph root directory.

Step 2. Create the graph using the mfg::DrawGraph class as follows:

   1     #include "mfg_draw_graph.h"
   2     #include "mfg_graph_drawer.h"
   3     using namespace mfg;
   4     ...
   5     DrawGraph g;
   6     Node* a = g.CreateNode();
   7     Node* x = g.CreateNode();
   8     Edge* ax = g.CreateEdge(a, x);
   9     ax->Attribs()["color"] = "red";
  10     Subgraph* s = g.CreateSubgraph();
  11     Node* b = g.CreateNode(s);
  12     b->Attribs()["style"] = "filled";
  13     b->Attribs()["fillcolor"] = "green";
  14     Edge* ab = g.CreateEdge(&g, &a, &b);

Step 3. Write the graph to a DOT file on disk. (We could have written the DOT listing to a file directly, but it's more interesting this way.)

   1     #include <iostream>
   2     ...
   3     std::ofstream dot("temp.dot");
   4     g.PrintAsDot(dot);

Step 4. Have DOT.EXE convert the DOT listing to XDOT format. (This is the format that contains information about the graphic primitives such as ellipses and Bézier curves.)

   1     system("dot.exe -Txdot -otemp.xdot temp.dot");
   2         // requires the GraphViz package

Step 5. Windows only. Load the XDOT graph from the newly created file and have mfg::GraphDrawer render the graph:

   1     HDC hdc;    // assumed to contain a valid device context
   2     ...
   3     std::ifstream xdot("temp.xdot");
   4     g.LoadFromXdot(xdot);
   5     GraphDrawer::DrawGraph(hdc, &g);

Run the application.

mfGraph UI Sample Application Usage

Before you can use the mfGraph UI Sample Application, you must

• Download and install GraphViz from http://www.research.att.com/sw/tools/graphviz/download.html

• Either make sure that DOT.EXE is on the search path
• Or place DOT.EXE into the same directory as the mfGraph UI executable

In addition to those attributes defined by DOT.EXE, mfGraph UI supports the following special node, edge, and graph attributes (mfc_demo and pymfg_demo support these as well):