NET:Tutorials:LavishScript Object Wrappers

From Lavish Software Wiki
Jump to: navigation, search

Overview

This tutorial will assume you have already read and understood the LavishScriptAPI.LavishScriptObject page to some degree. With that bit of knowledge in mind, we can begin to wrap LavishScript objects. I will use C#, but any .NET language can of course be used to create a wrapper.

I will demonstrate the basic process using real LavishScript objects from LavishNav.

Deriving the base class

First, derive a class from LavishScriptObject, and create a copy constructor. All your constructor should do is call the copy constructor from the base class. The black box data will simply be re-referenced in this new object. Your object will be instantiated by using the new keyword with a call to this copy constructor.

   public class LavishNav : LavishScriptObject
   {
       public LavishNav(LavishScriptObject Obj)
           : base(Obj)
       {
       }
   }

Any LavishScriptObject instance can be converted to this type, because the type is abstracted. LavishScript knows the real type, and whether type A has a member called X or a method called Y. Therefore, simply use the copy constructor to perform a safe typecast.

Instantiating a LavishNav object in .NET
       static public LavishNav GetLavishNav()
       {
           return new LavishNav(LavishScript.Objects.GetObject("LavishNav"));
       }

LavishScript Members

LavishScript object members always result in a new object (or null), and can accept parameters. Therefore, we have two ways of implementing members at our disposal. Simple members -- those that have no parameters -- can be implemented as a property get.

       public float Version
       {
           get
           {
               return GetMember<float>("Version");
           }
       }

Members that have parameters should be implemented as a method.

       public LavishNavRegionGroup AddRegionGroup(string Name)
       {
           return new LavishNavRegionGroup(GetMember("AddRegionGroup", new string[] { Name }));
       }

A GetMember method is called to retrieve the given object -- or in the case of the generic versions of the method, the given object's ToString value converted to the given type.

LavishScript Methods

LavishScript object methods never result in a new object, but rather a pass or fail, and can accept parameters. Some methods are a simple set value operation, and these can therefore be implemented as a property set if they use only a single parameter.

This particular code is the only example not actually usable in LavishNav, as there is no such method
public float X
{
    set
    {
        ExecuteMethod("SetX", new string[] { value.ToString() });
    }       
}

Methods that are not a set value operation should be implemented as a method.

       bool Clear()
       {
           return ExecuteMethod("Clear");
       }
       bool ImportXML(string Filename)
       {
           return ExecuteMethod("Import", new string[] { Filename });
       }
       bool ImportLSO(string Filename)
       {
           return ExecuteMethod("Import", new string[] { "-lso", Filename });
       }

An ExecuteMethod method is called to execute the method.

ToString

The LavishScriptObject class maps the .NET object to the LavishScript object's ToString value (which is implemented as GetValue<T>).

       public override string ToString()
       {
           return GetValue<string>();
       }

This can of course be overridden by your class to produce any other result, including members of the class or other objects entirely.

Examples

C#

The following code is not complete and may not reflect the actual LavishNav API. It is just here to serve as additional samples.
   public class LavishNavUniverse : LavishNavRegion
   {
       public LavishNavUniverse(LavishScriptObject Obj)
           : base(Obj)
       {
       }
   }

   public class LavishNavBox : LavishNavRegion
   {
       public LavishNavBox(LavishScriptObject Obj)
           : base(Obj)
       {
       }

       public float X1
       {
           get
           {
               return GetMember<float>("X1");
           }
       }

       public float X2
       {
           get
           {
               return GetMember<float>("X2");
           }
       }

       public float Y1
       {
           get
           {
               return GetMember<float>("Y1");
           }
       }

       public float Y2
       {
           get
           {
               return GetMember<float>("Y2");
           }
       }

       public float Z1
       {
           get
           {
               return GetMember<float>("Z1");
           }
       }

       public float Z2
       {
           get
           {
               return GetMember<float>("Z2");
           }
       }
   }

   public class LavishNavRegion : LavishScriptObject
   {
       public LavishNavRegion(LavishScriptObject Obj)
           : base(Obj)
       {
       }

      public string Type
       {
           get
           {
               return GetMember<string>("Type");
           }
       }
   }

   public class LavishNavRegionGroup : LavishScriptObject
   {
       public LavishNavRegionGroup(LavishScriptObject Obj)
           : base(Obj)
       {
       }
   }

   public class LavishNav : LavishScriptObject
   {
       public LavishNav(LavishScriptObject Obj)
           : base(Obj)
       {
       }

       static public LavishNav GetLavishNav()
       {
           return new LavishNav(LavishScript.Objects.GetPermanentObject("LavishNav"));
       }

       public float Version
       {
           get
           {
               return GetMember<float>("Version");
           }
       }
       public LavishNavUniverse Tree
       {
           get
           {
               return new LavishNavUniverse(GetMember("Tree"));
           }
       }
       public bool IsValidName(string Name)
       {
           return GetMember<bool>("IsValidName", new string[] { Name });
       }

       public LavishNavRegionGroup AddRegionGroup(string Name)
       {
           return new LavishNavRegionGroup(GetMember("AddRegionGroup", new string[] { Name }));
       }

       static LavishNavRegion FindRegion(string FQN)
       {
           return new LavishNavRegion(LavishScript.Objects.GetObject("LNavRegion", new string[] { FQN }));
       }
   }