Class PropertyObject

From TrainzOnline
Revision as of 02:22, 10 February 2010 by Windwalkr (Talk | contribs)

Jump to: navigation, search


This class provides an interface that allows an object to implement properties that can be saved or loaded to a session and edited by the user through a browser window in Surveyor. To enable this for an asset, it must inherit from PropertyObject (or from a derived child class such as ScenarioBehavior or MeshObject).

PropertyObject operates by way of a series of predefined callback methods which are designed to be overridden by the script writer to allow Trainz to access an object's properties.

Properties are referred to in the class methods by their propertyID. Trainz determines this by reference to links in the object browser in the form live://property/propertyID.

When Trainz is saving a session, it asks each object to save its respective state into a Soup database. Trainz doesn't know what your object needs to save, but it does know that it can request an object's state via callbacks. Trainz relies on the script programmer to give careful thought to how the asset is constructed.

Depending on circumstances, not all callback methods have to be implemented. For example, you don't need to override GetPropertyElementList() if there are no list-selection properties.

Contents

Callback Sequences

The precise sequence of callback method calls will vary with the content of the browser and the user's input but the following gives a general idea:

  • When the Property Browser is opened TRS calls:
  • When the user clicks on a URL, the propertyID is extracted from the link and these calls are made:
    • GetPropertyType() to establish what type of property is to be edited.
    • for "link" properties:
      • LinkPropertyValue() which should contain all the instructions necessary to complete the task.
    • for "string", "int" and "float" properties:
      • GetPropertyValue() to establish the property's current contents.
      • GetPropertyDescription() to obtain a caption.
      • TRS then provides a pop-up edit box with the caption and current value filled in and waits for the user to edit the property.
    • for "list" properties:
  • Once the user has carried out any edits:
    • The appropriate variant of SetPropertyValue() is called to update the value of the property.
    • GetDescriptionHTML() is called again to refresh the contents of the Browser window, updating any variables that the script writer might have set.
  • When all edits are complete:
    • If the user confirms the changes by using the green tick to close the dialogue:
      • SetProperties() is called with the modified Soup to update the session database.
    • If the user cancels the changes by using the red cross to close the dialogue:
      • SetProperties() is called with the original unaltered Soup to restore the database to the state that was current before the last editor session.


Throughout the above sequences TRS is only concerned with the loading and saving of properties.

  • Wherever a change in a property requires an update to the appearance of the object or to the contents of its variables it is the responsibility of the script writer to implement these changes at the appropriate time.
  • In general changes should be implemented in SetProperties() since this will help to ensure that changes can be reversed if they are cancelled or when the game's UNDO command is invoked.


GetDescriptionHTML

public string GetDescriptionHTML(void)
Parameters
  • None
Returned Value;
  • HTML formatted string to be loaded into the Property Browser.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
public string GetDescriptionHTML(void) {
   return inherited()
   + "<font size=5><br>"
   + "Forename: <a href=live://property/forename>" + foreName + "</a><br>"
   + "Surname: <a href=live://property/surname>" + surName + "</a><br>"
   + "</font>";
   return html;
}
Description
  • This method is called by Trainz from Surveyor to retrieve the properties of the object as HTML code for display in a Browser window.
  • Refer to the MiniBrowser page for details of supported HTML tags.
  • Link URLs should be included in the form live://property/propertyID, where propertyID is the name of the property.
  • When the user clicks on a link Trainz will use the appropriate callback methods to establish the action that needs to be taken to enable the property to be edited.
  • To allow for translation, text should be extracted from the asset's StringTable rather than being included in code as a literal string. This allows translated string table data to be substituted in foreign language installations if it is available.


GetProperties

public Soup GetProperties(void)
Parameters
  • None
Returned Value
  • Soup object containing session file data assigned to the current object.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
public Soup GetProperties(void) {
   Soup soup = inherited();
   soup.SetNamedTag("forename",foreName);
   soup.SetNamedTag("surname",surName);
}
Description
  • This method is used to save current properties into the session database.
  • Care must be taken to ensure it writes data in the same tag format that SetProperties() is expecting.
  • When overriding this method to handle your own properties, always call through to the overridden parent by using inherited().


GetPropertyDescription

string GetPropertyDescription(string propertyID)
Parameters
  • propertyID = Name of property.
Returned Value
  • Description to be used as a caption for the edit box presented to the user, allowing the current property to be edited.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
string GetPropertyDescription(string propertyID) {
   string result = inherited(propertyID);
   if (propertyID == "forename") result = "Enter Forename";
   else if (propertyID == "surname") result = "Enter Surname";
   return result;
}


GetPropertyElementList

public string[ ] GetPropertyElementList(string propertyID)
Parameters
  • propertyID = Name of property.
Returned Value
  • String array to be presented to the user for a new selection to be made.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
public string[] GetPropertyElementList(string propertyID) {
   string[] result = inherited(propertyID);
   if (propertyID == "junctions") {
      Junction[] junctions = World.GetJunctionList();
      int n;
      for (n = 1; n < junctions.size(); n++) {
         result[result.size()] = junctions[n].GetName();
      }
   }
   return result;
}
Description
  • Retrieves a list of elements the user can select from for the named property.
  • If a property is of type "list", as returned by GetPropertyType(), Trainz will display these items in a pop-up window for user selection.
  • The script programmer is free to fill the returned elements array from the current game environment and can create this dynamically if necessary (eg a list of industries in the current route).


GetPropertyHandler

public HTMLPropertyHandler GetPropertyHandler(void)
Parameters
  • None
Returned Value
  • A reference to the current Property Handler for this object, or null if none has been set.
Description
  • A PropertyObject can be overridden by assigning an HTMLPropertyHandler which allows more sophisticated processing.
  • This method returns a reference to such an object if it has been assigned.
  • If this method returns null then no HTMLPropertyHandler is assigned and the default PropertyObject methods described on this page will apply.


GetPropertyName

string GetPropertyName(string propertyID)
Parameters
  • propertyID = Name of property.
Returned Value
  • The name of the current property.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
string GetPropertyName(string propertyID) {
   string result = inherited(propertyID);
   if (propertyID == "forename") result = "Forename";
   else if (propertyID == "surname") result = "Surname";
   return result;
}


GetPropertyType

string GetPropertyType(string propertyID)
Parameters
  • propertyID = Name of property.
Returned Value
  • The type of the current property.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
string GetPropertyType(string propertyID) {
   string result = inherited(propertyID);
   if (propertyID == "forename" or propertyID == "surname") result = "string";
   return result;
}
Description
  • This method is used by Trainz to determine the type of the named property.
  • The type of a property is defined using a string describing what type of data the property holds as well as extra information about the range, size and incremental count.
  • The minimum and maximum range of the value and incremental steps are optional parameters.
  • Lists may be sorted or unsorted.
  • Property types supported are as set out below:
"string" a string value
"string,5,25" a string value between 5 and 25 characters in length
"int" an integer value
"int,0,100,5" an integer betwen 0 and 100 with incremental steps of 5
"float" a floating point value
"float,0,10,0.5" a float beween 0 and 10 in 0.5 steps
"list" an unsorted list
"list,1" a sorted list
"link" no additional information required


GetPropertyValue

public string GetPropertyValue(string propertyID)
Parameters
  • propertyID = Name of property.
Returned Value
  • A string representation of the value of the current property.
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
public string GetPropertyValue(string propertyID) {
   string result = inherited(propertyID);
   if (propertyID == "forename") result = foreName;
   else if (propertyID == "surname") result = surName;
   return result;
}
Description
  • Returns a string representation of the current value of the selected property.


LinkPropertyValue

void LinkPropertyValue(string propertyID)
Parameters
  • propertyID = Name of property.
Returned Value
  • None
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
void LinkPropertyValue(string propertyID) {
   string result = inherited(propertyID);
   if (propertyID == "doors") {
      doorsOpen = !doorsOpen;
      SetMeshAnimationState("doors",doorsOpen);
   }
}
Description
  • Trainz calls this method when the user has clicked on a property URL which is defined as a "link"
  • No further information will be available to the game.
  • Link properties are most frequently used to toggle boolean values.


PropertyBrowserRefresh

public void PropertyBrowserRefresh(Browser browser)
Parameters
  • browser = Reference to browser object displaying properties.
Returned Value
  • None
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
public void PropertyBrowserRefresh(Browser browser) {
   inherited(browser);
   refreshed++;
   Interface.Print("Browser has been refreshed " + refreshed + " times");
}
Description
  • A callback method which the script writer can override to specify tasks to be carried out whenever the Browser is refreshed.


SetProperties

public void SetProperties(Soup soup)
Parameters
  • soup = reference to soup to be saved to session.
Returned Value
  • None
Syntax
  • This is a callback method which should be overridden to suit the calling asset.
Implementation 
public void SetProperties(Soup soup) {
   inherited(soup);
   foreName = soup.GetNamedTag("forename");
   surName = soup.GetNamedTag("surname");
}
Description
  • Instructs the current object to initialise its properties from data held in the session files.
  • The data is passed to the method via the soup parameter.
  • If the database is empty, as it will be when an object is first placed, then the object should initialise itself with sensible defaults.
  • When overriding this method to handle your own properties, always call through to the overridden parent by using inherited(soup)
  • This ensures that any data required by any parent class is made available.


SetPropertyHandler

public void SetPropertyHandler(HTMLPropertyHandler handler)
Parameters
  • handler = Handler to assign to this property object.
Returned Value
  • None
Description
  • A PropertyObject can be overridden by assigning an HTMLPropertyHandler which allows more sophisticated processing.
  • This method allows PropertyObject methods to be processed by such an object.
  • Once SetPropertyHandler() has been used to assign a Property Handler the default methods in this class will be replaced by the corresponding methods defined in the handler.


SetPropertyValue

void SetPropertyValue(string propertyID, string value, int index)
void SetPropertyValue(string propertyID, string value)
void SetPropertyValue(string propertyID, float value)
void SetPropertyValue(string propertyID, int value)

Parameters
  • propertyID = Name of property.
  • value = int, float or string value to assign to the property.
  • index = list index value to assign to the property.
Returned Value
  • None
Syntax
  • These are callback methods which should be overridden to suit the calling asset.
Implementation 
void SetPropertyValue(string propertyID, string value) {
   if (propertyID == "forename") foreName = value;
   else if (propertyID == "surname") surName = value;
   else inherited(propertyID);
}
Description
  • Sets a new value for the named property.


Related Methods

Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_PropertyObject&oldid=1113"
Personal tools