6. Porting from 1.0.5 to 1.1

6.1. Major changes

The major changes which are likely to affect existing users are the following:

• Addition of a new library class "gui" which replaces the existing "tkobjc" library.

• All direct references to any Tcl/Tk code such as the "globalTkInterp" variable have been completely removed from any library code and should not be used in any application.

• Splitting of simtools into two separate libraries: simtools and simtoolsgui. Classes that intrinsically depend on a GUI toolkit being present (either Tcl/Tk or Java AWT) were put into simtoolsgui. This allows a user who never intends to use a GUI toolkit, to be able to compile, link and run Swarm applications without any GUI toolkit installed at all. This was not previously possible.

• The above change has been made possible by the fact that the dependency of Tcl/Tk in the Probing mechanism has been completely removed. It has been replaced by the libffi/ffcall libraries. Other than the fact that the user will need to install this new library if they are not using a binary distribution, this new dependence should not break any user code.

• The header file to the random library is no longer included in simtools.h you need to explicitly import random.h when you use a default random number generator.

• The XColormap class is now just Colormap to divorce it from its association with X-Windows. Similarly, BLTGraph is now just Graph.

• The class named Histo is now named Histogram.

• Certain classes now enforce their defining by the protocol method. For example an instance of the Raster class must be defined as (id <Raster> r) rather than (Raster * r).

• Backwardly-compatible references to the old swarmobject library are no longer supported. You should always use objectbase.

6.2. Porting guide

• Always use the "gui" protocol when calling doing any GUI events:

  • Replace all occurences of tkobjc.h with gui.h

  • never explicitly reference any Tcl/Tk-specific code, in particular module with a call to globalTkInterp will no longer compile.

• Using simtools/simtoolsgui:

  • Add the header file simtoolsgui.h to your list of imports whenever you are referencing any of the following classes:

    ActionCache, ControlPanel, SimpleProbeDisplay, ActionHolder, GUIComposite, VarProbeWidget, ActiveGraph, GUISwarm, ClassDisplayWidget, MessageProbeWidget, CommonProbeDisplay, ProbeDisplay, CompleteProbeDisplay, ProbeDisplayManager

• Explictly import the header when you are subclassing from a given class:

  • You also need to import the header file for any class for which you are subclassing. In particular, when you are creating a GUISwarm you are subclassing from GUISwarm so you need to explicitly import both <simtoolsgui.h> AND <simtoolsgui/GUISwarm.h>. The same is true for <objectbase/SwarmObject.h> and <objectbase/Swarm.h>

• Colormap class name change:

  • Change all references of XColormap to Colormap as it is no longer specific to X11.

  • Change all method references to set the Colormap for the Value2dDisplay class ([Value2dDisplay -Colormap]) to lowercase ([Value2dDisplay -colormap]) to avoid namespace conflicts with Colormap class. For example, in heatbugs:

    [heatDisplay setDisplayWidget: worldRaster Colormap: colormap]; should now be: [heatDisplay setDisplayWidget: worldRaster colormap: colormap];

• Ensure that all required classes conform to their protocol:

  • Make all occurences of (Raster *) to the protocol i.e. (id <Raster>)

  • Similarly change any references to Colormap, ZoomRaster, InFile and OutFile.

• Import random.h explicitly:

  • The header file <random.h> is no longer included by <simtools.h> should always explicitly reference the random library if you use it in a given module (.m) file. This again reduces the inter-library dependence, if you don't need to use the random library in your application, you shouldn't be including it.

• ActionCache and ControlPanel:

  • Make all references to -doTkEvents and -waitForControlEvent be to actionCache NOT controlPanel.

6.3. Porting example: heatbugs

To help users port their applications to 1.1, I have included a checklist of changes that were required to update heatbugs from 1.0.5 to 1.1. This may help some users as a kind of "template" for changes they may require for their applications. The ChangeLog entries in in the heatbug-1.1 distribution also provide further specific information.

Heatbug.h

• Replace <tkobjc/Raster.h> with <gui.h> (*)

• Make all occurences of (Raster *) to the protocol (id <Raster>) (*)

Heatbug.m

• Make all occurences of (Raster *) to the protocol (id <Raster>) (*)

• Removed <simtools.h> altogether - not used. (*)

• Added <random.h> - no longer included by <simtools.h> - should always explicitly reference the random library if you use it in your code. (*)

HeatbugBatchSwarm.h

• Changed <swarmobject.h> to <objectbase.h> (*)

HeatbugBatchSwarm.m

• Removed redundant <collections.h> (x)

HeatbugModelSwarm.h

• Removed <tkobjc.h> irrelevant in this context - tkobjc should never be included directly in any case, if required use <gui.h> (*)

• Changed <swarmobject.h> to <objectbase.h>. (*)

• Note we need to separately include <objectbase/Swarm.h> since you always need to the header file for a class if you need to subclass from it. (*)

HeatbugModelSwarm.m

• Include <random.h> explicitly since we use the default random number generators. (*)

HeatbugObserverSwarm.h

• Change <simtools.h> to <simtoolsgui.h> since we are using GUI widgets (*)

• Explicitly import <simtoolsgui/GUISwarm.h> since we subclass from it (*)

• Remove: <swarmobject.h> <space.h> <activity.h> <collections.h> all are irrelevant in the header file. (x)

• <tkobjc.h> has been relocated to the (.m) file as no gui classes are referenced directly in the header (.h) file. It is now changed to <gui.h>. (*)

• Change all references of XColormap to Colormap and use protocol form: (*)

  XColormap * colormap TO id <Colormap> colormap

• Make ZoomRaster conform to protocol, ie: (*)

  ZoomRaster * worldRaster TO id <ZoomRaster> worldRaster

HeatbugObserverSwarm.m

• Change swarmobject to objectbase (*)

• Import the <gui.h> in the implementation file - since it is not referenced in the header file (*)

• Change XColormap to Colormap - no longer specific to X11 - so name should not suggest so. (*)

• Message to set colormap for worldRaster changed name from (uppercase) Colormap to (lowercase) colormap.(*)

• Call -enableDestroyNotification method on worldRaster after createEnd. (x)

main.m

• Need to import <simtoolsgui.h> in addition to <simtools.h> since we reference GUISwarm methods. (*)