To generate an application bindings library for the canvas example (whether for Qt 3 or Qt 4), we must put the following code in the Buildsub file:

var canvasWrapperHeaders = ["canvas.h"];
var canvasWrapperLib = wrapperLib("canvas",
    canvasWrapperHeaders, stdIncs, ".");

First we define an array which lists all the header files that we want squishidl to create wrappers for. In this case we want to wrap the API defined in the canvas.h file.

To create the wrapper library, the build tool will call the wrapperLib function. The first argument to this function must be the name which we want to use for the wrapper library. Usually this is the application's or component's name without a suffix (i.e. no .exe or .dll on Windows). The second argument is an array that lists the files that we want wrapped: We pass the array that we created in the previous line for this purpose. The third parameter specifies the include paths which should be used, and for this we use the build tool's predefined stdIncs array which contains all the standard include paths. The last parameter specifies the directory where we want the wrapper library to be built. Here we have just said to build it in the current directory.

If the files you want to wrap include files from other directories, you must add the directories where those files can be found to the include paths. For example:

var all_includes = stdIncs.concat(["/my/include/path"]);

And instead of passing the stdIncs array as the third parameter, pass your own array (here, all_includes), as the third argument to the wrapperLib function.

Now that the Buildsub file has all the information it needs, we can run the build tool in the directory that contains the Buildsub file. This will result in the bindings library being generated.

linux-g++*:LIBS += -rdynamic

13.23.1.1.2. Symbols on Windows

For Windows, exporting the symbols is a little more involved. Essentially we have to do the same to the application as we would do when we create a DLL. We must mark each class that we want to be exported with the __declspec(dllexport) attribute. This will generate an import library with the application's exported symbols which we must link into the wrapper library (this last part is automatically handled by the build tool).

The first part is to modify the application's build system to export the symbols and to create the import library.

If you are using qmake to build your application, these lines must be added to the application's project (.pro) file:

win32:DEFINES += TEST_EXPORT=__declspec(dllexport)
unix:DEFINES += TEST_EXPORT=

If you don't use qmake, but use nmake directly to compile your application, add the following to the NMakefile file's CXXFLAGS variable:

/DTEST_EXPORT=__declspec(dllexport)

If you also use make on Unix you can add a corresponding line to the Unix Makefile's CXXFLAGS variable:

-DTEST_EXPORT=

Now the export macro is defined correctly. But one more step is required so that the Windows linker will create the desired import library with the exported symbols: You must use the export macro in the code which should be exported.

In our canvas example we have the following class definitions defined in canvas.h which we want to create bindings for:

class CanvasInterface : public Qt
{
    //...
};

class CanvasItem : public CanvasInterface
{
    //...
};

class CanvasRect : public CanvasItem
{
    //...
};

class CanvasModel : public QObject, public CanvasInterface
{
    //...
};

class CanvasView : public QScrollView
{
    //...
};

To let the Windows linker know that we want to export the symbols of these classes, we must mark them with the export macro we have just defined. So we modify the file by adding the TEST_EXPORT to the class definitions as shown below:

class TEST_EXPORT CanvasInterface : public Qt
{
    //...
};

class TEST_EXPORT CanvasItem : public CanvasInterface
{
    //...
};

class TEST_EXPORT CanvasRect : public CanvasItem
{
    //...
};

class TEST_EXPORT CanvasModel : public QObject, public CanvasInterface
{
    //...
};

class TEST_EXPORT CanvasView : public QScrollView
{
    //...
};

	Qt Designer .ui files
	If the class is defined in a Qt .ui XML file, open the file in Qt Designer, double click on the name property in the Properties tab of the Object Explorer. Enter the TEST_EXPORT macro into the export macro field that will appear, and save the .ui file. From now on the uic tool will automatically add the macro to the generated C++ classes.

	Windows-specific
	On Windows, the squishidl tool creates introspection and automation code only for classes, global functions, and variables which are exported using the TEST_EXPORT macro. This is to avoid problems with unresolved symbols in the generated libraries.

If you now rebuild your application, an import library with the exported symbols called <appname>.lib will be created.

The next step is to extend the wrapper library's Buildsub file to import the application's exported symbols. To do this we must add the following code to the Buildsub file:

JavaScript

var importMacro;
if (windows)
    importMacro = "TEST_EXPORT=__declspec(dllimport)";
else
    importMacro = "TEST_EXPORT=";
setDefines(canvasWrapperLib, [importMacro]);

This defines a macro called TEST_EXPORT to import exported symbols. Also, it adds it as a define to the canvasWrapper library's complier line.

Now when using build to create the wrapper library, the bindings library will be correctly generated.

// create an array property if it doesn't exist
if (!canvasWrapperLib.extras)
    canvasWrapperLib.extras = [];
// push a new element onto the end of the array
canvasWrapperLib.extras.push("MyUtils.lib");

Here's an example test script which inserts three rectangles into the canvas. To verify that the rectangles were inserted correctly, we use the functions, CanvasView::canvasModel, CanvasModel::numItems, CanvasModel::item (taking an integer index) and CanvasItem::rect. All of these functions are available through the bindings library we created.

Here is the example script's code. The complete example test suite can be found in examples/qt4/suite_canvas for Qt 4. (A very similar example for Qt 3, that only has a Python test script, is in examples/qt3/suite_canvas).

def checkRectangle(item, x, y, width, height):
    test.compare(item.rect().x, x)
    test.compare(item.rect().y, y)
    test.compare(item.rect().width, width)
    test.compare(item.rect().height, height)

def main():
    snooze(1.5)
    sendEvent("QMoveEvent", ":Canvas_QMainWindow", 572, 471, 538, 402)

    # insert 3 rectangular items
    mouseClick(":Canvas.CanvasView_CanvasView", 90, 56, 1, Qt.LeftButton)
    mouseClick(":Canvas.CanvasView_CanvasView", 170, 173, 1, Qt.LeftButton)
    mouseClick(":Canvas.CanvasView_CanvasView", 271, 96, 1, Qt.LeftButton)
    snooze(0.5)
    
    # retrieve reference to the canvas model
    canvas = waitForObject(":Canvas.CanvasView_CanvasView")
    model = canvas.canvasModel()
    
    # check that it contains 3 items
    test.compare(model.numItems(), 3)
    
    # for each item, check that it has the correct geometry
    checkRectangle(model.item(0), 90, 56, 50, 70)
    checkRectangle(model.item(1), 170, 173, 50, 70)
    checkRectangle(model.item(2), 271, 96, 50, 70)

    # close and exit
    sendEvent("QCloseEvent", ":Canvas_QMainWindow")

function checkRectangle(item, x, y, width, height)
{
    test.compare(item.rect().x, x);
    test.compare(item.rect().y, y);
    test.compare(item.rect().width, width);
    test.compare(item.rect().height, height);
}

function main()
{
    snooze(1.5);
    sendEvent("QMoveEvent", ":Canvas_QMainWindow", 572, 471, 538, 402);

    // insert 3 rectangular items
    mouseClick(":Canvas.CanvasView_CanvasView", 90, 56, 1, Qt.LeftButton);
    mouseClick(":Canvas.CanvasView_CanvasView", 170, 173, 1, Qt.LeftButton);
    mouseClick(":Canvas.CanvasView_CanvasView", 271, 96, 1, Qt.LeftButton);
    snooze(0.5);
    
    // retrieve reference to the canvas model
    var canvas = waitForObject(":Canvas.CanvasView_CanvasView");
    var model = canvas.canvasModel();
    
    // check that it contains 3 items
    test.compare(model.numItems(), 3);
    
    // for each item, check that it has the correct geometry
    checkRectangle(model.item(0), 90, 56, 50, 70);
    checkRectangle(model.item(1), 170, 173, 50, 70);
    checkRectangle(model.item(2), 271, 96, 50, 70);

    // close and exit
    sendEvent("QCloseEvent", ":Canvas_QMainWindow");
}

sub checkRectangle
{
    my ($item, $x, $y, $width, $height) = @_;
    test::compare($item->rect()->x, $x);
    test::compare($item->rect()->y, $y);
    test::compare($item->rect()->width, $width);
    test::compare($item->rect()->height, $height);
}

sub main
{
    snooze(1.5);
    sendEvent("QMoveEvent", ":Canvas_QMainWindow", 572, 471, 538, 402);

    # insert 3 rectangular items
    mouseClick(":Canvas.CanvasView_CanvasView", 90, 56, 1, Qt::LeftButton);
    mouseClick(":Canvas.CanvasView_CanvasView", 170, 173, 1, Qt::LeftButton);
    mouseClick(":Canvas.CanvasView_CanvasView", 271, 96, 1, Qt::LeftButton);
    snooze(0.5);
    
    # retrieve reference to the canvas model
    my $canvas = waitForObject(":Canvas.CanvasView_CanvasView");
    my $model = $canvas->canvasModel();
    
    # check that it contains 3 items
    test::compare($model->numItems(), 3);
    
    # for each item, check that it has the correct geometry
    checkRectangle($model->item(0), 90, 56, 50, 70);
    checkRectangle($model->item(1), 170, 173, 50, 70);
    checkRectangle($model->item(2), 271, 96, 50, 70);

    # close and exit
    sendEvent("QCloseEvent", ":Canvas_QMainWindow");
}

proc checkRectangle {item x y width height} {
    test compare [property get [invoke $item rect] x] $x
    test compare [property get [invoke $item rect] y] $y
    test compare [property get [invoke $item rect] width] $width
    test compare [property get [invoke $item rect] height] $height
}

proc main {} {
    snooze 1.5
    sendEvent "QMoveEvent" ":Canvas_QMainWindow" 572 471 538 402

    # insert 3 rectangular items
    invoke mouseClick ":Canvas.CanvasView_CanvasView" 90 56 1 [enum Qt LeftButton]
    invoke mouseClick ":Canvas.CanvasView_CanvasView" 170 173 1 [enum Qt LeftButton]
    invoke mouseClick ":Canvas.CanvasView_CanvasView" 271 96 1 [enum Qt LeftButton]
    snooze 0.5
    
    # retrieve reference to the canvas model
    set canvas [waitForObject ":Canvas.CanvasView_CanvasView"]
    set model [invoke $canvas canvasModel]
    
    # check that it contains 3 items
    test compare [invoke $model numItems] 3
    
    # for each item, check that it has the correct geometry
    checkRectangle [invoke $model item 0] 90 56 50 70
    checkRectangle [invoke $model item 1] 170 173 50 70
    checkRectangle [invoke $model item 2] 271 96 50 70

    # close and exit
    sendEvent "QCloseEvent" ":Canvas_QMainWindow"
}

Squish provides a simple stand-alone GUI application for exploring wrappers. The application is called wrapperexpl and is in Squish's bin directory. Run this application from the command line—or click or double-click it from Windows Explorer or choose it in the Mac OS X Finder, as appropriate for your operating system.

As soon as the wrapperexpl starts up it presents its Open Wrapper Libraries dialog. This dialog lists the built-in wrappers supplied with Squish (e.g., “squishqtwrapper”). Check the checkbox for any of these that you want to explore. If you want to add your own wrapper libraries, for each one, simply click the Add... button and choose the relevant .so, .dylib or .dll file (depending on platform) from the file chooser dialog, and make sure that the library's checkbox is checked after it has been added.

The Open Wrapper Libraries Dialog

Note that you must make sure that you only select wrapper libraries—they are easy to identify, since their filenames always contain the string “wrapper”.

After choosing Add..., the library will be added to the list in the Open Wrapper Libraries dialog.

The Open Wrapper Libraries Dialog with a Custom Library

The list of wrapper libraries that are shown are remembered for future use, but you can remove any you are not interested in, by clicking them and then clicking the Remove button.

Click the OK button to load all the checked libraries into the Wrapper Explorer.

After selecting one or more libraries in the Open Wrapper Libraries dialog, a new window replaces the dialog—the Wrapper Explorer window. This window displays the classes from the wrappers, presenting them using a hierarchical tree view.

The Wrapper Explorer

Expanding a class will show its parent class or classes, and any public enums, constructors, properties, and member functions that it has available.

For faster navigation, there is a Filter text field at the bottom of the window. When text is entered here, it will be used to filter the tree's entries. If all the text is in lowercase, the filter is applied case insensitively; but if the text has upper- and lowercase the filter is applied case sensitively. If Classes is selected in the bottom right combobox, the filter is only applied to class names—this is very useful for quickly finding a particular class. For fast navigation amongst class members, change the bottom right combobox to Members.

Selected items can be copied to the clipboard as text, with the indention that is used in the tree preserved. Items are selected by clicking them, and selections can be extended to include multiple items. For example, on Windows™, second and subsequent items can be selected by pressing the Ctrl key when clicking additional items. Alternatively, a range of items can be selected by clicking one (which selects it), and then pressing the Shift key while clicking another—this will result in the two clicked items being selected, along with all the items in between them. It is also possible to select all the items by clicking the Edit|Select All menu item.

	Lazy Discovery
	For efficiency, child items are only discovered the first time an item is expanded. This means that selecting all items will produce different results depending on which items have been expanded.