Dynamic Object Creation And Deletion

A model can modify its own structure by adding portals (copying a master) and deleting portals from itself.

This is achieved using a table to provide a series of commands to the edit environment. A dispatcher in "Restart Engine/Continue" mode is used to perform the edits.

Dispatchers in this mode restart the model engine whilst preserving the item that triggered them. ALL OTHER ITEMS in the model are deleted - the run is
stopping and restarting at time = 0.  The item at the dispatcher survives the restart and will continue through its flow after the changes to the model have been effected.

To enable the dynamic object mode, the Dispatcher "Enable Edit Command Table" option must be selected. This option is only available once the dispatcher is in "Restart Engine/Continue" mode. When this is enabled a new context menu option enables the dispatcher to be associated with a table via a reference.

The following columns must exist in the table. The order doesn't matter and other columns can exist (and will be untouched) by the dynamic object system.

_command
_original_id
_new_id
_new_objpanel or _new_panel
_x
_y
_result
_new_name (optional)

Additional columns can exist in the table and if the name of Title of the column matches the name of a portal attribute, the portal attribute will be set with the cells value.

Each row is processed according to its _command. The following codes are  implemented:

_command = 1: COPY Object

_original_id is the object label of the original object to copy

_new_id will be set to the new id of the object. If non zero,
Planimate will attempt to use the index specified but if it is in
use, a new index will be allocated and _new_id will be set to it

_new_objpanel (object label) or _new_panel (panel label) specifies the panel where the object will be placed. If _new_objpanel is used, it must be a portal, then its subsystem will be used. If its 0, the top level panel is used.

_x,_y specify the lower left co-ord that the object will be placed at
_result will be set to a result code by Planimate.

_new_name, if present, enables the object name to be specified. The text in the cell is used as the name. It may be modified if the name is already used.

_command = 2: DELETE Object

_original_id is the object label of the object to delete

_result will be set to the result code of the delete operation

All other columns must be present as for Add, but will be ignored and can be 0 filled.

If a row attempts to delete the panel (or an owner of the panel) that
is currently visible, the delete will fail.

If a row attempts to delete an object which would cause the deletion
of the dispatcher executing the table, the delete will fail.

_command = 3 REPLACE object

In this mode, _original_id specifies the object ID of the original to copy and _new_id must be set to specify the object ID of the object that will
be replaced. The new object will hence get the ID _new_id.

The _x,_y and _new_panel columns are ignored in this mode.

Currently Defined _Result Codes (may be extended)

This code is reported in the _result column.

0: No Error / Nothing to report. The operation was successful
1: Something unexpected happened (coding error)
2: The panel id provided was not for a dynamic panel
3: The panel id provided was not for any kind of panel
4: No source object was provided for copy/delete
5: The command code was not a recognised value, the row was ignored
6: An attempt was made to delete an object which cannot be deleted
for reasons outlined above or because it is part of a network
structure.