Updated documentation

This commit is contained in:
FlightControl
2017-03-24 14:47:51 +01:00
parent de87e1f557
commit 3e8824b89b
20 changed files with 2285 additions and 2757 deletions

View File

@@ -82,187 +82,7 @@
<hr/>
<h1>1) <a href="##(BASE)">#BASE</a> class</h1>
<p>All classes within the MOOSE framework are derived from the <a href="##(BASE)">#BASE</a> class. </p>
<p>BASE provides facilities for :</p>
<ul>
<li>The construction and inheritance of MOOSE classes.</li>
<li>The class naming and numbering system.</li>
<li>The class hierarchy search system.</li>
<li>The tracing of information or objects during mission execution for debuggin purposes.</li>
<li>The subscription to DCS events for event handling in MOOSE objects.</li>
</ul>
<p>Note: The BASE class is an abstract class and is not meant to be used directly.</p>
<h2>1.1) BASE constructor</h2>
<p>Any class derived from BASE, will use the <a href="Base.html##(BASE).New">Base#BASE.New</a> constructor embedded in the <a href="Base.html##(BASE).Inherit">Base#BASE.Inherit</a> method.
See an example at the <a href="Base.html##(BASE).New">Base#BASE.New</a> method how this is done.</p>
<h2>1.2) Trace information for debugging</h2>
<p>The BASE class contains trace methods to trace progress within a mission execution of a certain object.
These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution.</p>
<p>Any type of information can be passed to these tracing methods. See the following examples:</p>
<pre><code>self:E( "Hello" )
</code></pre>
<p>Result in the word "Hello" in the dcs.log.</p>
<pre><code>local Array = { 1, nil, "h", { "a","b" }, "x" }
self:E( Array )
</code></pre>
<p>Results with the text [1]=1,[3]="h",[4]={[1]="a",[2]="b"},[5]="x"} in the dcs.log. </p>
<pre><code>local Object1 = "Object1"
local Object2 = 3
local Object3 = { Object 1, Object 2 }
self:E( { Object1, Object2, Object3 } )
</code></pre>
<p>Results with the text [1]={[1]="Object",[2]=3,[3]={[1]="Object",[2]=3}} in the dcs.log.</p>
<pre><code>local SpawnObject = SPAWN:New( "Plane" )
local GroupObject = GROUP:FindByName( "Group" )
self:E( { Spawn = SpawnObject, Group = GroupObject } )
</code></pre>
<p>Results with the text [1]={Spawn={....),Group={...}} in the dcs.log. </p>
<p>Below a more detailed explanation of the different method types for tracing.</p>
<h3>1.2.1) Tracing methods categories</h3>
<p>There are basically 3 types of tracing methods available:</p>
<ul>
<li><a href="##(BASE).F">BASE.F</a>: Used to trace the entrance of a function and its given parameters. An F is indicated at column 44 in the DCS.log file.</li>
<li><a href="##(BASE).T">BASE.T</a>: Used to trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file.</li>
<li><a href="##(BASE).E">BASE.E</a>: Used to always trace information giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file.</li>
</ul>
<h3>1.2.2) Tracing levels</h3>
<p>There are 3 tracing levels within MOOSE. <br/>
These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.</p>
<p>As such, the F and T methods have additional variants to trace level 2 and 3 respectively:</p>
<ul>
<li><a href="##(BASE).F2">BASE.F2</a>: Trace the beginning of a function and its given parameters with tracing level 2.</li>
<li><a href="##(BASE).F3">BASE.F3</a>: Trace the beginning of a function and its given parameters with tracing level 3.</li>
<li><a href="##(BASE).T2">BASE.T2</a>: Trace further logic within a function giving optional variables or parameters with tracing level 2.</li>
<li><a href="##(BASE).T3">BASE.T3</a>: Trace further logic within a function giving optional variables or parameters with tracing level 3.</li>
</ul>
<h3>1.2.3) Trace activation.</h3>
<p>Tracing can be activated in several ways:</p>
<ul>
<li>Switch tracing on or off through the <a href="##(BASE).TraceOnOff">BASE.TraceOnOff</a>() method.</li>
<li>Activate all tracing through the <a href="##(BASE).TraceAll">BASE.TraceAll</a>() method.</li>
<li>Activate only the tracing of a certain class (name) through the <a href="##(BASE).TraceClass">BASE.TraceClass</a>() method.</li>
<li>Activate only the tracing of a certain method of a certain class through the <a href="##(BASE).TraceClassMethod">BASE.TraceClassMethod</a>() method.</li>
<li>Activate only the tracing of a certain level through the <a href="##(BASE).TraceLevel">BASE.TraceLevel</a>() method.</li>
</ul>
<h3>1.2.4) Check if tracing is on.</h3>
<p>The method <a href="##(BASE).IsTrace">BASE.IsTrace</a>() will validate if tracing is activated or not.</p>
<h2>1.3 DCS simulator Event Handling</h2>
<p>The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator,
and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently.</p>
<h3>1.3.1 Subscribe / Unsubscribe to DCS Events</h3>
<p>At first, the mission designer will need to <strong>Subscribe</strong> to a specific DCS event for the class.
So, when the DCS event occurs, the class will be notified of that event.
There are two methods which you use to subscribe to or unsubscribe from an event.</p>
<ul>
<li><a href="##(BASE).HandleEvent">BASE.HandleEvent</a>(): Subscribe to a DCS Event.</li>
<li><a href="##(BASE).UnHandleEvent">BASE.UnHandleEvent</a>(): Unsubscribe from a DCS Event.</li>
</ul>
<h3>1.3.2 Event Handling of DCS Events</h3>
<p>Once the class is subscribed to the event, an <strong>Event Handling</strong> method on the object or class needs to be written that will be called
when the DCS event occurs. The Event Handling method receives an <a href="Event.html##(EVENTDATA)">Event#EVENTDATA</a> structure, which contains a lot of information
about the event that occurred.</p>
<p>Find below an example of the prototype how to write an event handling function for two units: </p>
<pre><code> local Tank1 = UNIT:FindByName( "Tank A" )
local Tank2 = UNIT:FindByName( "Tank B" )
-- Here we subscribe to the Dead events. So, if one of these tanks dies, the Tank1 or Tank2 objects will be notified.
Tank1:HandleEvent( EVENTS.Dead )
Tank2:HandleEvent( EVENTS.Dead )
--- This function is an Event Handling function that will be called when Tank1 is Dead.
-- @param Wrapper.Unit#UNIT self
-- @param Core.Event#EVENTDATA EventData
function Tank1:OnEventDead( EventData )
self:SmokeGreen()
end
--- This function is an Event Handling function that will be called when Tank2 is Dead.
-- @param Wrapper.Unit#UNIT self
-- @param Core.Event#EVENTDATA EventData
function Tank2:OnEventDead( EventData )
self:SmokeBlue()
end
</code></pre>
<p>See the <a href="Event.html">Event</a> module for more information about event handling.</p>
<h2>1.4) Class identification methods</h2>
<p>BASE provides methods to get more information of each object:</p>
<ul>
<li><a href="##(BASE).GetClassID">BASE.GetClassID</a>(): Gets the ID (number) of the object. Each object created is assigned a number, that is incremented by one.</li>
<li><a href="##(BASE).GetClassName">BASE.GetClassName</a>(): Gets the name of the object, which is the name of the class the object was instantiated from.</li>
<li><a href="##(BASE).GetClassNameAndID">BASE.GetClassNameAndID</a>(): Gets the name and ID of the object.</li>
</ul>
<h2>1.5) All objects derived from BASE can have "States"</h2>
<p>A mechanism is in place in MOOSE, that allows to let the objects administer <strong>states</strong>. <br/>
States are essentially properties of objects, which are identified by a <strong>Key</strong> and a <strong>Value</strong>. </p>
<p>The method <a href="##(BASE).SetState">BASE.SetState</a>() can be used to set a Value with a reference Key to the object. <br/>
To <strong>read or retrieve</strong> a state Value based on a Key, use the <a href="##(BASE).GetState">BASE.GetState</a> method. </p>
<p>These two methods provide a very handy way to keep state at long lasting processes.
Values can be stored within the objects, and later retrieved or changed when needed.
There is one other important thing to note, the <a href="##(BASE).SetState">BASE.SetState</a>() and <a href="##(BASE).GetState">BASE.GetState</a> methods
receive as the <strong>first parameter the object for which the state needs to be set</strong>.
Thus, if the state is to be set for the same object as the object for which the method is used, then provide the same
object name to the method.</p>
<h2>1.10) Inheritance</h2>
<p>The following methods are available to implement inheritance</p>
<ul>
<li><a href="##(BASE).Inherit">BASE.Inherit</a>: Inherits from a class.</li>
<li><a href="##(BASE).GetParent">BASE.GetParent</a>: Returns the parent object from the object it is handling, or nil if there is no parent object.</li>
</ul>
<p>The <a href="##(BASE)">#BASE</a> class is the core root class from where every other class in moose is derived.</p>
<hr/>
@@ -302,7 +122,9 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="#BASE">BASE</a></td>
<td class="summary">
<h1>1) #BASE class</h1>
<p>All classes within the MOOSE framework are derived from the BASE class.</p>
</td>
</tr>
<tr>
@@ -366,12 +188,6 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<td class="name" nowrap="nowrap"><a href="##(BASE).EventRemoveAll">BASE:EventRemoveAll()</a></td>
<td class="summary">
<p>Remove all subscribed events</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(BASE).Events">BASE.Events</a></td>
<td class="summary">
</td>
</tr>
<tr>
@@ -591,12 +407,6 @@ place: Object that the unit landed on.</p>
<td class="name" nowrap="nowrap"><a href="##(BASE).SetState">BASE:SetState(Object, Key, Value)</a></td>
<td class="summary">
<p>Set a state or property of the Object given a Key and a Value.</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(BASE).States">BASE.States</a></td>
<td class="summary">
</td>
</tr>
<tr>
@@ -665,12 +475,6 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
<td class="name" nowrap="nowrap"><a href="##(BASE)._F">BASE:_F(Arguments, DebugInfoCurrentParam, DebugInfoFromParam)</a></td>
<td class="summary">
<p>Trace a function call.</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(BASE)._Private">BASE._Private</a></td>
<td class="summary">
</td>
</tr>
<tr>
@@ -714,6 +518,191 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</dt>
<dd>
<h1>1) #BASE class</h1>
<p>All classes within the MOOSE framework are derived from the BASE class.</p>
<p>
BASE provides facilities for :</p>
<ul>
<li>The construction and inheritance of MOOSE classes.</li>
<li>The class naming and numbering system.</li>
<li>The class hierarchy search system.</li>
<li>The tracing of information or objects during mission execution for debuggin purposes.</li>
<li>The subscription to DCS events for event handling in MOOSE objects.</li>
</ul>
<p>Note: The BASE class is an abstract class and is not meant to be used directly.</p>
<h2>1.1) BASE constructor</h2>
<p>Any class derived from BASE, will use the <a href="Base.html##(BASE).New">Base#BASE.New</a> constructor embedded in the <a href="Base.html##(BASE).Inherit">Base#BASE.Inherit</a> method.
See an example at the <a href="Base.html##(BASE).New">Base#BASE.New</a> method how this is done.</p>
<h2>1.2) Trace information for debugging</h2>
<p>The BASE class contains trace methods to trace progress within a mission execution of a certain object.
These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution.</p>
<p>Any type of information can be passed to these tracing methods. See the following examples:</p>
<pre><code>self:E( "Hello" )
</code></pre>
<p>Result in the word "Hello" in the dcs.log.</p>
<pre><code>local Array = { 1, nil, "h", { "a","b" }, "x" }
self:E( Array )
</code></pre>
<p>Results with the text [1]=1,[3]="h",[4]={[1]="a",[2]="b"},[5]="x"} in the dcs.log. </p>
<pre><code>local Object1 = "Object1"
local Object2 = 3
local Object3 = { Object 1, Object 2 }
self:E( { Object1, Object2, Object3 } )
</code></pre>
<p>Results with the text [1]={[1]="Object",[2]=3,[3]={[1]="Object",[2]=3}} in the dcs.log.</p>
<pre><code>local SpawnObject = SPAWN:New( "Plane" )
local GroupObject = GROUP:FindByName( "Group" )
self:E( { Spawn = SpawnObject, Group = GroupObject } )
</code></pre>
<p>Results with the text [1]={Spawn={....),Group={...}} in the dcs.log. </p>
<p>Below a more detailed explanation of the different method types for tracing.</p>
<h3>1.2.1) Tracing methods categories</h3>
<p>There are basically 3 types of tracing methods available:</p>
<ul>
<li><a href="##(BASE).F">BASE.F</a>: Used to trace the entrance of a function and its given parameters. An F is indicated at column 44 in the DCS.log file.</li>
<li><a href="##(BASE).T">BASE.T</a>: Used to trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file.</li>
<li><a href="##(BASE).E">BASE.E</a>: Used to always trace information giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file.</li>
</ul>
<h3>1.2.2) Tracing levels</h3>
<p>There are 3 tracing levels within MOOSE. <br/>
These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.</p>
<p>As such, the F and T methods have additional variants to trace level 2 and 3 respectively:</p>
<ul>
<li><a href="##(BASE).F2">BASE.F2</a>: Trace the beginning of a function and its given parameters with tracing level 2.</li>
<li><a href="##(BASE).F3">BASE.F3</a>: Trace the beginning of a function and its given parameters with tracing level 3.</li>
<li><a href="##(BASE).T2">BASE.T2</a>: Trace further logic within a function giving optional variables or parameters with tracing level 2.</li>
<li><a href="##(BASE).T3">BASE.T3</a>: Trace further logic within a function giving optional variables or parameters with tracing level 3.</li>
</ul>
<h3>1.2.3) Trace activation.</h3>
<p>Tracing can be activated in several ways:</p>
<ul>
<li>Switch tracing on or off through the <a href="##(BASE).TraceOnOff">BASE.TraceOnOff</a>() method.</li>
<li>Activate all tracing through the <a href="##(BASE).TraceAll">BASE.TraceAll</a>() method.</li>
<li>Activate only the tracing of a certain class (name) through the <a href="##(BASE).TraceClass">BASE.TraceClass</a>() method.</li>
<li>Activate only the tracing of a certain method of a certain class through the <a href="##(BASE).TraceClassMethod">BASE.TraceClassMethod</a>() method.</li>
<li>Activate only the tracing of a certain level through the <a href="##(BASE).TraceLevel">BASE.TraceLevel</a>() method.</li>
</ul>
<h3>1.2.4) Check if tracing is on.</h3>
<p>The method <a href="##(BASE).IsTrace">BASE.IsTrace</a>() will validate if tracing is activated or not.</p>
<h2>1.3 DCS simulator Event Handling</h2>
<p>The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator,
and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently.</p>
<h3>1.3.1 Subscribe / Unsubscribe to DCS Events</h3>
<p>At first, the mission designer will need to <strong>Subscribe</strong> to a specific DCS event for the class.
So, when the DCS event occurs, the class will be notified of that event.
There are two methods which you use to subscribe to or unsubscribe from an event.</p>
<ul>
<li><a href="##(BASE).HandleEvent">BASE.HandleEvent</a>(): Subscribe to a DCS Event.</li>
<li><a href="##(BASE).UnHandleEvent">BASE.UnHandleEvent</a>(): Unsubscribe from a DCS Event.</li>
</ul>
<h3>1.3.2 Event Handling of DCS Events</h3>
<p>Once the class is subscribed to the event, an <strong>Event Handling</strong> method on the object or class needs to be written that will be called
when the DCS event occurs. The Event Handling method receives an <a href="Event.html##(EVENTDATA)">Event#EVENTDATA</a> structure, which contains a lot of information
about the event that occurred.</p>
<p>Find below an example of the prototype how to write an event handling function for two units: </p>
<pre><code> local Tank1 = UNIT:FindByName( "Tank A" )
local Tank2 = UNIT:FindByName( "Tank B" )
-- Here we subscribe to the Dead events. So, if one of these tanks dies, the Tank1 or Tank2 objects will be notified.
Tank1:HandleEvent( EVENTS.Dead )
Tank2:HandleEvent( EVENTS.Dead )
--- This function is an Event Handling function that will be called when Tank1 is Dead.
-- @param Wrapper.Unit#UNIT self
-- @param Core.Event#EVENTDATA EventData
function Tank1:OnEventDead( EventData )
self:SmokeGreen()
end
--- This function is an Event Handling function that will be called when Tank2 is Dead.
-- @param Wrapper.Unit#UNIT self
-- @param Core.Event#EVENTDATA EventData
function Tank2:OnEventDead( EventData )
self:SmokeBlue()
end
</code></pre>
<p>See the <a href="Event.html">Event</a> module for more information about event handling.</p>
<h2>1.4) Class identification methods</h2>
<p>BASE provides methods to get more information of each object:</p>
<ul>
<li><a href="##(BASE).GetClassID">BASE.GetClassID</a>(): Gets the ID (number) of the object. Each object created is assigned a number, that is incremented by one.</li>
<li><a href="##(BASE).GetClassName">BASE.GetClassName</a>(): Gets the name of the object, which is the name of the class the object was instantiated from.</li>
<li><a href="##(BASE).GetClassNameAndID">BASE.GetClassNameAndID</a>(): Gets the name and ID of the object.</li>
</ul>
<h2>1.5) All objects derived from BASE can have "States"</h2>
<p>A mechanism is in place in MOOSE, that allows to let the objects administer <strong>states</strong>. <br/>
States are essentially properties of objects, which are identified by a <strong>Key</strong> and a <strong>Value</strong>. </p>
<p>The method <a href="##(BASE).SetState">BASE.SetState</a>() can be used to set a Value with a reference Key to the object. <br/>
To <strong>read or retrieve</strong> a state Value based on a Key, use the <a href="##(BASE).GetState">BASE.GetState</a> method. </p>
<p>These two methods provide a very handy way to keep state at long lasting processes.
Values can be stored within the objects, and later retrieved or changed when needed.
There is one other important thing to note, the <a href="##(BASE).SetState">BASE.SetState</a>() and <a href="##(BASE).GetState">BASE.GetState</a> methods
receive as the <strong>first parameter the object for which the state needs to be set</strong>.
Thus, if the state is to be set for the same object as the object for which the method is used, then provide the same
object name to the method.</p>
<h2>1.10) Inheritance</h2>
<p>The following methods are available to implement inheritance</p>
<ul>
<li><a href="##(BASE).Inherit">BASE.Inherit</a>: Inherits from a class.</li>
<li><a href="##(BASE).GetParent">BASE.GetParent</a>: Returns the parent object from the object it is handling, or nil if there is no parent object.</li>
</ul>
<hr/>
</dd>
@@ -735,10 +724,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
<h2><a id="#(Base)" >Type <code>Base</code></a></h2>
<h2><a id="#(BASE)" >Type <code>BASE</code></a></h2>
<p>The BASE Class</p>
<h3>Field(s)</h3>
<h3>Field(s)</h3>
<dl class="function">
<dt>
@@ -935,20 +921,6 @@ A #table or any field.</p>
<p><em><a href="##(BASE)">#BASE</a>:</em></p>
</dd>
</dl>
<dl class="function">
<dt>
<em></em>
<a id="#(BASE).Events" >
<strong>BASE.Events</strong>
</a>
</dt>
<dd>
</dd>
</dl>
<dl class="function">
@@ -1902,20 +1874,6 @@ The Key was not found and thus the Value could not be retrieved.</p>
</li>
</ol>
</dd>
</dl>
<dl class="function">
<dt>
<em></em>
<a id="#(BASE).States" >
<strong>BASE.States</strong>
</a>
</dt>
<dd>
</dd>
</dl>
<dl class="function">
@@ -2190,20 +2148,6 @@ A #table or any field.</p>
</li>
</ul>
</dd>
</dl>
<dl class="function">
<dt>
<em></em>
<a id="#(BASE)._Private" >
<strong>BASE._Private</strong>
</a>
</dt>
<dd>
</dd>
</dl>
<dl class="function">