Incubator/ConsistDataHandler/Detailed specifications

From TrainzOnline
< Incubator | ConsistDataHandler
Revision as of 23:59, 3 February 2010 by Windwalkr (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

ConsistDataHandler detailed specifications - v4 - 16.11.2008

Consist databundle handler definition
databundle handler type rule
databundle handler name ConsistDataHandler
databundle used definition
databundle short string token sdbConsist
databundle description string Standard consist databundle
databundle KUID icon string null (not implemented in current version)
soup data Consist databundle data soup is compatible with ConsistHelperInfo class data soup used by ConsistHelperInfo SetProperties() and GetProperties(), which is also the data soup returned by World.GetSurveyorSavedConsist(name). So it should be quite easy for a client rule to get surveyor saved consist data in surveyor mode and send it later in driver mode to ConsistDataHandler processing.

The consist databundle supports an optional additive named tag "ConsistName" that can be used to define the consist name to display under the ConsistDataHandler small movable GUI for consist placement.

operations supported
CreateConsistOnRoute Priority level : 128

Operation mode : asynchronous

String return code : "" if operation correctly launched

Error code 1 : "1 - consist datahandler called not in driver mode"

Error code 2 : "2 - Some vehicles in consist databundle not available in current world"

CheckConsist Priority level : 128

Operation mode : synchronous

String return code : "" if consist available in current world

Error code 2 : "2 - Some vehicles in consist databundle not available in current world"

messages used
Messages Consist placement is de facto an asynchronous operation. The script returns to its client as soon as the operation is started. To enable clients to know what is doing the consist data handler, a few messages are broadcast from the consist data handler :


"ConsistDataHandler", "OperationsComplete" is emited when the consist data handler closes its placement window and so finishing current consist placement. Message source is the consist data handler rule.


"ConsistDataHandler", "NewConsistCreated" is emited when the consist data handler has just craeted a new consist. Message source is the new consist so that scripts waiting for this message can get a reference to the new consist created.


"ConsistDataHandler", "ConsistDeleted" is emited if the user decides to delete the just created consist. Message source is the consist about to be deleted.

other complentary information
Others So, to call the ConsistDataHandler processing, you need in your script to include the dbhelper.gs file for accessing to the DataBundleHelper library procedure calls and you will use :

dbhelper.ExecuteOperation("CreateConsistOnRoute,prioritylevel,consist databundle soup)

priority level needs to be 128 or more to authorize ConsistDataHandler processing which is at chaining priority level 128. consist databundle soup is a consist databundle soup as described above.

the string return code should be "" if the operation succeeds or contains a self explaning string if the operation has not been done for any reason. You should notice that ConsistDataHandler processing is available only in driver mode. When called in surveyor mode, you receive the error string "1 - ConsistDataHandler called not in driver mode".

As described on the summary, CreateConsistOnRoute processing displays a small movable GUI with the consist name if present in the databundle and a consist summary. the GUI includes a toggle button with a green "placement active" indication or a red "placement inactive" indication.

ConsistDataHandler dialog1.jpg

When placement is active, user can left click on a track and the consist will be created at the selected track position. After creating the consist, the small movable GUI will toggle to "placement inactive" indication and will have two more buttons : one "Delete last consist" to delete the consist created if the position does not meet your requirement and one "Reverse last consist" to reverse the consist created order. When you have finished positioning the consist, you can either close the small GUI browser or click on the activate toggle button, the last one making everything ready for a new consist placement.

ConsistDataHandler dialog2.jpg

There is only one CreateConsistOnRoute operation at a time, so if another script calls the consist datahandler interface, the new consist databundle will replace the previous one and operations will continue with the new consist databundle.

Personal tools