Porting from 1.0.5 to 1.1
Prev | Swarm Changes and Compatibility | Next

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

Prev | Up | Next
Porting from 1.1 to 1.2 | Home | Porting from 1.0.4 to 1.0.5