MCell Automation interface

Go back to MCell Home

 

Automation interface implemented in MCell makes it possible for one application to control MCell through exposed methods and properties. Nearly every 32-bit programming language can be used to write applications controlling MCell. The most popular ones are Visual Basic, Visual C++, Borland Delphi, Borland C++ Builder, Microsoft Word and Excel (through macros).

 

Quick start

The following simple example shows an MS Word Basic macro that starts MCell, creates a new pattern, activates the Game of Life rule, draws 60 cells in a line and runs the created pattern.

Dim objApp As Object
Dim objUni As Object
Dim objWin As Object
  Public Sub RunLineOfCells()
  'create Automation objects, start MCell
  Set objApp = CreateObject("MCell.theApplication")
  Set objUni = CreateObject("MCell.theUniverse")
  Set objWin = CreateObject("MCell.theWindow")
  'prepare an empty universe
  objUni.Clear
  'activate the Conway's Game of Life rule
  objUni.Game = "Life"
  objUni.Rule = "23/3"
  'add 60 cells in a line
  Dim i As Integer
  For i = -29 To 30
    Call objUni.SetCell(i, 0, 1)
  Next i
    'redisplay the board
  objWin.Refresh
  'run
  objUni.Run
End Sub

To test this example start MSWord, open a new document and select "Tools/Macro/Visual Basic editor". In the newly opened window select "Insert/Module" and paste the above text into it. You are ready to run your example - click on the Run button.

MCell Type Library

Writing MCell add-ins is much easier using the provided MCell.tlb (type library) file, what adds on-line properties/methods preview and syntax checking to modern compilers. It also allows for early binding, what results in faster execution of applications. MCell.tlb can be found in \MCell\System\Programming\ folder. It's recommended to copy the MCell.tlb file to the Windows folder. The way of integrating MCell.tlb with the programming interface depends to the tool used. Here are some examples:

MS Word, MS Excel
Select Tools/References, check MCell Library (if MCell Library is not available in the list, use the "Browse" button to show the location of the MCell.tlb file).

Visual Basic
Select Project/References, check MCell Library (if MCell Library is not available in the list, use the "Browse" button to show the location of the MCell.tlb file).

Borland Delphi / C++ Builder
Select Project/Import type library, highlight MCell Library and press OK (if MCell Library is not available in the list, use the "Add" button to show the location of the MCell.tlb file).

If a type library is used, MCell objects are available as known data types, so first 3 lines of the previous example can be rewritten as:

Dim objApp As MCell.theApplication
Dim objUni As MCell.theUniverse
Dim objWin As MCell.theWindow

Now the compiler's environment knows what type are objApp, objUni and objWin and suggests available properties, methods, and their parameters while typing the code.

 

Object "theApplication"

This top-level objects gives access to the basic properties and methods of MCell.

the Application - properties (name, type, access, description)

Caption, String, Read/Write
Sets or returns the title of the application window.

DefaultFilePath, String, Read/Write
Sets or returns the default path specification used by the application for opening files

FullName, String, Read only
Returns the file specification for the application, including path. For example, "C:\MyProgs\MCell.exe".

Height, Integer, Read/Write
Sets or returns the distance between the top and bottom edge of the main application window.

IsSoundOn, Boolean, Read/Write
Enables/disables sounds emitted by the application

Left, Integer, Read/Write
Sets or returns the distance between the left edge of the physical screen and the main application window.

Name, String, Read only
Returns the name of the application, such as "Mirek's Cellebration".

Version, String, Read only
Returns the application's version as a string in "major.minor.revision" format, for example "3.01.460".

Path, String, Read only
Returns the path specification for the application's executable file. For example, "C:\MyProgs" if the .exe file is "C:\MyProgs\MCell.exe"

Top, Integer, Read/Write
Sets or returns the distance between the top edge of the physical screen and main application window.

Visible, Boolean, Read/Write
Sets or returns whether the application is visible to the user.

Width, Integer, Read/Write
Sets or returns the distance between the left and right edges of the main application window.

the Application - methods (name, parameters, return value, description)

procedure Activate
Brings the application's window to the top.

procedure AddToUndo
Adds current universe state to the Undo list.

procedure Quit
Exits the application.

procedure Redo
Reverts to the state before last Undo was done.

procedure Refresh
Repaints the application, rescans files in the File Manager.

procedure Undo
Reverses the previous action that modified the universe.

 

Object "theUniverse"

This object gives access to the current universe. The universe handles the lattice, cells and rules; it contains no information about the visual representation of the pattern. For changes in the visible aspects of the universe refer to theWindow object.

theUniverse - properties (name, type, access, description)

CellsInState[state: Short], Integer, Read only
Returns the count of cells in the whole universe having the specified state.

ChangedCells, Integer, Read only
Returns the count of cells modified in the last pass.

Coloring, Short, Read/Write
Sets or returns the coloring mode of the rules without history:
1 - standard coloring,
2 - alternate coloring.

FullName, String, Read only
Returns the file specification of the pattern, including the path.

Game, String, Read/Write
Sets or returns the active game (family of rules). Current version supports the following games:
"Life"
"Generations"
"Weighted Life"
"Vote for Life"
"Rules table"
"Cyclic CA"
"1-D totalistic"
"1-D binary"
"Neumann binary"
"General binary"
"Larger than Life"
"Margolus"
"User DLL"
"Special rules"

Generation, Integer, Read/Write
Returns the age (ordinal number) of the current generation. With every pass the universe gets one generation older.

Height, Integer, Read only
Returns the height of the universe (vertical count of cells).

IsModified, Boolean, Read/Write
Returns False if the pattern has never been saved, but has not changed since it was created. Returns False if it has been saved and has not changed since last saved. Returns True if it has never been saved and has changed since it was created; or if it was saved, but has changed since last saved.

Left, Integer, Read only
Returns the minimal cell index at the left edge of the universe.

Name, String, Read only
Returns the name and extension portion of pattern file specification.

Path, String, Read only
Returns the path specification for the pattern, not including the file name or file name extension.

Population, Integer, Read only
Returns the count of alive (non-zero) cells in the current pattern.

Rule, String, Read/Write
Sets or returns the active rule as a string.

States, Integer, Read/Write
Sets or returns the count of states (colors). The specified count includes the 0 state.

Top, Integer, Read only
Returns the minimal cell index at the top edge of the universe.

Width, Integer, Read only
Returns the width of the universe (horizontal count of cells).

Wrap, Boolean, Read/Write
Sets or returns the universe wrapping state.

theUniverse - methods (name, parameters, return value, description)

procedure Clear;
Clears the universe - removes all cells from it.

function GetCell(x: Integer; y: Integer): Short;
Returns the state of the cell at (x,y) coordinates.

procedure New;
Starts a new pattern: clears the universe and resets the pattern name to "Noname".

procedure Open(const Name: String);
Opens an existing document, specified by its full path.

procedure Run;
Starts an animation. The animation will be running until it's stopped programmatically or manually with the user interface.

procedure RunNCycles(Count: Integer; RedrawEvery: Integer);
Runs the animation for 'Count' steps. 'RedrawEvery' allows to specify how often (after how many steps) the universe should be redisplayed.

procedure Run1Cycle;
Runs the animation for 1 step.

procedure Save;
Saves changes to the file specified in the pattern's FullName property.

procedure SaveAs(const Name: String; const format: String);
Saves changes to a file. The 'Name' argument can include an optional path specification. 'format' specifies the CA file format and should be one of:
"OPTIMAL"
"MCL"
"RLE"
"LIF105"
"LIF106"

procedure SaveAsBitmap(ifRectangle: Boolean; left, top, width, height: Integer; const name: String);
Saves the whole universe or a portion of it to a file as a bitmap.
ifRectangle - rectangle flag.
If ifRectangle = True, the defined rectangle is saved using the current cell size and grid settings.
if ifRectangle = False, the whole universe is saved to a bitmap where each pixel represents one cell; left, top, width, height parameters are ignored.
left, top, width, height - rectangle definition.
name - bitmap file path, e.g., "c:\test\myfile.bmp".
Warning! In order to save a portion of a universe the MCell's window cannot be obscured by any other windows - execute theApplication.Activate first and hide your application temporarily.

procedure SetCell(x: Integer; y: Integer; state: Short);
Sets the cell at (x,y) to state 'state'.

procedure SetSize(Width: Integer; Height: Integer);
Sets the size of the universe. Note that the specified size will be adjusted to multiples of 20.

procedure Stop;
Stops the running animation.

 

Object "theWindow"

This object gives access to the view window on the universe. To access the universe itself refer to theUniverse object.

theWindow - properties (name, type, access, description)

ActiveState, Short, Read/Write
Sets or returns the active state (color).

BoldGridLinesStep, Integer, Read/Write
Sets or returns the distance between bold grid lines.

CellShape, Integer, Read/Write
Sets or returns the shape of cells. The shape is expressed as an integer number, where:
1 - big squares,
2 - small squares,
3 - filled circles,
4 - rectangles.

CursorMode, Integer, Read/Write
Sets or returns the cursor mode. The mode is expressed as an integer number, where:
0 - editing cursor,
1 - selecting cursor,
2 - zooming cursor,
3 - panning cursor,
4 - color picking cursor.

GridMinZoom, Integer, Read/Write
Sets or returns the minimal zoom step at which the grid can be displayed.

Height, Integer, Read only
Returns the distance between the top and bottom edge of the view window.

Left, Integer, Read/Write
Returns the index of the leftmost cell visible in the view window.

ShowBoldGridLines, Boolean, Read/Write
Sets or returns the visibility state of the grid bold lines.

ShowGrid, Boolean, Read/Write
Sets or returns the visibility state of the grid.

Top, Integer, Read/Write
Returns the index of the topmost cell visible in the view window.

Width, Integer, Read only
Returns the distance between the left and right edge of the view window.

theWindow - methods (name, parameters, return value, description)

procedure CenterCell(x: Integer; y: Integer; Redraw: Boolean);
Shifts (pans) the pattern so that the given (x,y) cell is placed in the center of the view window. 'Redraw' parameter allows to specify if the pattern should be redrawn after the operation.

procedure DrawCell(x: Integer; y: Integer; state: Integer; mode: Integer);
Draws the cell in state 'state' at (x,y) coordinates. Parameter 'mode' allows to specify the drawing mode, one of:
1 - draw mode,
2 - XOR mode.

procedure Fit(Redraw: Boolean);
Zooms and pans the pattern so that it's perfectly visible in the current view window. 'Redraw' parameter allows to specify if the pattern should be redrawn after the operation.

procedure PickState;
Activates the 'color picker' that selects the active state by picking one of cells in the pattern.

procedure Refresh;
Repaints the pattern.

procedure ZoomIn(Redraw: Boolean);
Zooms in the pattern by 1 step. 'Redraw' parameter allows to specify if the pattern should be redrawn after the operation.

procedure ZoomOut(Redraw: Boolean);
Zooms out the pattern by 1 step. 'Redraw' parameter allows to specify if the pattern should be redrawn after the operation.

 

Object "thePalette"

This object gives access to the current color palette.

thePalette - properties (name, type, access, description)

Name, String, Read/Write
Sets or returns the active color palette name.

RGBBoldGrid, Integer, Read/Write
Sets or returns the color of bold grid lines. Color is expressed as integer RGB.

RGBGrid, Integer, Read/Write
Sets or returns the color of grid lines. Color is expressed as integer RGB.

RGBState[index: Integer], Integer, Read/Write
Sets or returns the color of cells in state 'index', where 0 <= index <= 255. Color is expressed as integer RGB.

thePalette - methods (name, parameters, return value, description)

procedure Load(const Name: String);
Loads and activates the specified palette. The 'Name' parameter should not contain the palette path - palettes are loaded from \MCell\System\ folder.

procedure RebuildMenu;
Rescans available palettes in the \MCell\System\ folder and updates the menu.

procedure SaveAs(const Name: String);
Saves the active color palette to the \MCell\System\ folder with the specified name.

 

Object "theSeeding"

This object gives access to the seeding (randomizing) parameters.

theSeeding - properties (name, type, access, description)

Density, Double, Read/Write
Sets or returns the density of random seeding. The value must be in a range 0.0 to 100.0.

Interior, Boolean, Read/Write
Sets or returns the "seed interior" flag.

Mode, Integer, Read/Write
Sets or returns the seeding mode:
1 - mono seeding using MonoState,
2 - color seeding using all available states,
3 - seeding using the SeedingFile pattern.

MonoState, Short, Read/Write
Sets or returns the state used in mono seeding mode.

SeedingFile, String, Read/Write
Sets or returns the name of the pattern-file used as seeding. The name should not contain the path - seeding files are loaded from \MCell\System\Seed folder.

Shape, Integer, Read/Write
Sets or returns the seeding shape:
1 - rectangle (see property WhatRectangle),
2 - circle.

ShouldClear, Boolean, Read/Write
Sets or returns the "clear before seeding" flag. If False, new cells are appended to the existing universe.

ShouldResetName, Boolean, Read/Write
Sets or returns the "reset pattern name after seeding" flag.

StatisticalDistribution, Boolean, Read/Write
Sets or returns the "statistical distribution" flag. If False, the exact distribution is used.

UniformFill, Boolean, Read/Write
Sets or returns the "uniform color seeding" flag.

WhatRectangle, Integer, Read/Write
Sets or returns the rectangular area subtype:
1 - the whole lattice
2 - the visible part of the universe
3 - the specified rectangle
4 - the specified area.

theSeeding - methods (name, parameters, return value, description)

procedure Apply;
Performs seeding using current parameters.

procedure LoadConfigFile(const Name: String);
Loads the configuration file that describes all seeding parameters. The 'Name' parameter should not contain the path - seeding configuration files are loaded from \MCell\System\Random folder.

procedure SetArea(Left: Integer; Top: Integer; Width: Integer; Height: Integer);
Initializes the rectangular seeding area parameters.

procedure SetCircle(x: Integer; y: Integer; r: Integer);
Initializes the circular seeding area parameters.

procedure SetRectangleSize(Width: Integer; Height: Integer);
Initializes the rectangular seeding box parameters.

 

Object "theSelection"

This objects gives access to the selection (marking) feature of MCell.

theSelection - properties (name, type, access, description)

CountOfCells, Integer, Read only
Returns the count of cells found in the current selection.

Height, Integer, Read only
Returns the height (in cells) of the current selection.

IsOn, Boolean, Read/Write
Sets or returns the "On" flag. Set this property to False to drop the selection at the current position.

Left, Integer, Read only
Returns the coordinates (in cells) of the selection left edge.

Top, Integer, Read only
Returns the coordinates (in cells) of the selection top edge.

Width, Integer, Read only
Returns the width (in cells) of the current selection.

theSelection - methods (name, parameters, return value, description)

procedure AddCell(x: Integer; y: Integer; state: Short; checkExists: Boolean);
Adds one cell with state 'state' to the selection.
(x,y) are coordinates relative to the selection left-top corner (e.g., use (0,0) to add the cell exactly in the left-top corner.
'checkExists' parameter allows to optimize the speed of adding many cells when there is no need of checking if such a cell is already present in the selection. Set it to False if you are sure a cell can be added without checking.

procedure Clear;
Removes all cells from the selection. The selection remains active.

procedure ClearOutside;
Removes all cells from the Universe that are located outside of the selection frame.

procedure DropAt(x: Integer; y: Integer);
Drops the selection at the specified coordinates.

procedure Fill;
Fills the whole selection with cells in the current state.

procedure FillRandom;
Fills the selection randomly using current seeding parameters.

function GetCell(x: Integer; y: Integer): Short;
Returns the state of the cell (x,y) from the selection.

procedure Hide;
Hides the selection temporarily. All cells remain selected.

procedure Invert;
Inverts cells in the selection (dead cells become alive, alive cells are removed).

procedure MoveTo(x: Integer; y: Integer);
Moves the selection's left-top corner to the given coordinates. All cells remain selected and the universe is not modified.

procedure MirrorX;
Mirrors all selected cells horizontally.

procedure MirrorY;
Mirrors all selected cells vertically.

procedure Rotate90;
Rotates all selected cells counterclockwise by 90°.

procedure Rotate180;
Rotates all selected cells counterclockwise by 180°.

procedure Rotate270;
Rotates all selected cells clockwise by 90°.

procedure SetFrame(Left: Integer; Top: Integer; Width: Integer; Height: Integer);
Creates a new selection - selects the cells in the universe inside the specified area.

procedure Show;
Shown (unhides) the selection temporarily hidden using the Hide method.

procedure StampAt(x: Integer; y: Integer);
Places a copy of selected cells at the specified coordinates. The selection remains intact.

 

Object "theUndo"

This object gives access to the Undo system of MCell.

theUndo - properties (name, type, access, description)

ClearOnNew, Boolean, Read/Write
Sets or returns the "Reset Undo on starting/opening new patterns" flag.

Count, Integer, Read only
Returns the count of snaps present in the Undo list.

EventActive[index: Integer], Boolean, Read/Write
Sets or returns the activity of a specified event:
0 - run
1 - run 1 step
2 - run n steps
3 - specified running time over
4 - specified count of cycles done
5 - pattern is edited
6 - selection is edited
7 - pattern is moved (event not available yet)
8 - pattern is filled randomly
9 - universe undone
10 - game/rule changed
11 - open pattern
12 - new pattern
13 - pattern added to undo manually

IsOn, Boolean, Read/Write
Sets or returns the "Undo enabled" flag.

MaxCells, Integer, Read/Write
Sets or returns the maximal count of cells in a snap that be added to Undo.

MaxCount, Integer, Read/Write
Sets or returns the maximal count of snaps that can be stored in Undo.

SnapCycles, Integer, Read/Write
Sets or returns the count of cycles after which the universe should be snapped to Undo.

SnapTime, Integer, Read/Write
Sets or returns the count of seconds after which the universe should be snapped to Undo.

theUndo - methods (name, parameters, return value, description)

procedure Clear;
Clears the whole Undo list.

 

Object "theTransitions"

This objects gives access to the transitions analysis.

Properties (name, type, access, description)

Cycles, Integer, Read only
Returns the count of measured cycles.

Enabled, Boolean, Read/Write
Sets or returns the "Enabled" flag.

ItemsCount, Integer, Read only
Returns the maximal count of different transitions (at the moment 9).

x, Integer, Read/Write
X coordinate of the site being tested.

y, Integer, Read/Write
Y coordinate of the site being tested.

TransItemEnabled[index], Boolean, Read/Write
Sets or returns the "Enabled" flag for item 'index', where 1 <= index <= 9.

TransItemFrom[index], Integer, Read/Write
Sets or returns the "From" state for item 'index', where 1 <= index <= 9.

TransItemTo[index], Integer, Read/Write
Sets or returns the "To" state for item 'index', where 1 <= index <= 9.

TransItemTransCount[index], Integer, Read/Write
Returns the count of matched transitions for item 'index', where 1 <= index <= 9.

Methods (name, parameters, return value, description)

procedure ShowDialog
Shows the Transitions dialog.

procedure HideDialog
Hides the Transitions dialog.

procedure UpdateFormDisplay
Updates the display of the form.

procedure LoadConfigFile(const Name: WideString)
Loads transitions settings from a disk file. The 'Name' parameter should not contain the path or an extension - transitions configuration files are loaded from \MCell\System\Transitions\ folder and have a fixed ".trn" extension.

procedure ResetCounters
Resets all counters to 0.

 

Object "theCorrelations"

This objects gives access to the correlations analysis.

Properties (name, type, access, description)

Cycles, Integer, Read only
Returns the count of measured cycles.

Enabled, Boolean, Read/Write
Sets or returns the "Enabled" flag.

ItemsCount, Integer, Read only
Returns the maximal count of different correlations (at the moment 9).

x1, Integer, Read/Write
X coordinate of the first site being tested.

y1, Integer, Read/Write
Y coordinate of the first site being tested.

x2, Integer, Read/Write
X coordinate of the second site being tested.

y2, Integer, Read/Write
Y coordinate of the second site being tested.

CorrelItemEnabled[index], Boolean, Read/Write
Sets or returns the "Enabled" flag for item 'index', where 1 <= index <= 9.

CorrelItem1State[index], Integer, Read/Write
Sets or returns the state of the first site for item 'index', where 1 <= index <= 9.

CorrelItem2State[index], Integer, Read/Write
Sets or returns the state of the second site for item 'index', where 1 <= index <= 9.

CorrelItem1Count[index], Integer, Read/Write
Returns the count of state matches at the first site for item 'index', where 1 <= index <= 9.

CorrelItem2Count[index], Integer, Read/Write
Returns the count of state matches at the second site for item 'index', where 1 <= index <= 9.

CorrelItemCount[index], Integer, Read/Write
Returns the count of state matches at both sites at once for item 'index', where 1 <= index <= 9.

Methods (name, parameters, return value, description)

procedure ShowDialog
Shows the Correlations dialog.

procedure HideDialog
Hides the Correlations dialog.

procedure UpdateFormDisplay
Updates the display of the form.

procedure LoadConfigFile(const Name: WideString)
Loads correlations settings from a disk file. The 'Name' parameter should not contain the path or an extension - correlations configuration files are loaded from \MCell\System\Correlations\ folder and have a fixed ".crl" extension.

procedure ResetCounters
Resets all counters to 0.

 

Borland C++ Builder simple example

The following example assumes that MCell's Type Library has been imported.

#include <vcl.h>
#pragma hdrstop

#include "u_Main.h"
#include <Mcell_tlb.h>

#pragma package(smart_init)
#pragma resource "*.dfm"
TfrmMain *frmMain;

ItheApplicationDisp objApp;
ItheUniverseDisp objUni;
ItheWindowDisp objWin;

//----------------------------------------------------------------
__fastcall TfrmMain::TfrmMain(TComponent* Owner): TForm(Owner)
{
}
//----------------------------------------------------------------
void __fastcall TfrmMain::btnAutomationClick(TObject *Sender)
{
  objApp.BindDefault();
  objUni.BindDefault();
  objWin.BindDefault();

  objApp.Activate();          // activate MCell
  objUni.New();               // start new pattern
  objUni.SetCell(10, 10, 1);  // draw one cell
  objWin.Refresh();           // refresh the window
}
//----------------------------------------------------------------
Webmaster: Mirek Wojtowicz

globe http://www.mirekw.com

MCell mirrors:
 globe USA  http://psoup.math.wisc.edu/mcell/
globe Europe  http://www.mirwoj.opus.chelm.pl

Last update: 10 Mar 2002