Porting from 1.0.5 to 1.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.

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.

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. (*)