FlightControl-Master/MOOSE
1
0
Fork 0
mirror of https://github.com/FlightControl-Master/MOOSE.git synced 2025-10-29 16:58:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation refinement of Core Classes

Browse Source
This commit is contained in:
FlightControl
2017-03-07 20:58:53 +01:00
parent 343de7fe69
commit 0bfbf042b5
25 changed files with 219 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/Documentation/Base.html
View File

@@ -72,40 +72,78 @@
<div id="content">
<h1>Module <code>Base</code></h1>
<p>This module contains the BASE class.</p>
<p><strong>Core</strong> - BASE forms <strong>the basis of the MOOSE framework</strong>.</p>
<p>Each class within the MOOSE framework derives from BASE.</p>
<p><img src="..\Presentations\BASE\Dia1.JPG" alt="Banner Image"/></p>
<hr/>
<h1>1) <a href="##(BASE)">#BASE</a> class</h1>
<p>The <a href="##(BASE)">#BASE</a> class is the super class for all the classes defined within MOOSE.</p>
<p>It handles:</p>
<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 child classes.</li>
<li>The tracing of objects during mission execution within the <strong>DCS.log</strong> file, under the <strong>"Saved Games\DCS\Logs"</strong> folder.</li>
<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: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes.</p>
<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, must use the <a href="Base.html##(BASE).New">Base#BASE.New</a> method how this is done.</p>
<h2>1.2) BASE Trace functionality</h2>
<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.
Note that these trace methods are inherited by each MOOSE class interiting BASE.
As such, each object created from derived class from BASE can use the tracing functions to trace its execution.</p>
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>
<h3>1.2.1) Tracing functions</h3>
<p>Any type of information can be passed to these tracing methods. See the following examples:</p>
<p>There are basically 3 types of tracing methods available within BASE:</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>: Trace the beginning 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>: 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>: Trace an exception within a function giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file. An exception will always be traced.</li>
<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>
@@ -131,10 +169,11 @@ These tracing levels were defined to avoid bulks of tracing to be generated by l
<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.
<h3>1.2.4) Check if tracing is on.</h3></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>
@@ -146,7 +185,7 @@ and handled through lua scripting. MOOSE provides an encapsulation to handle the
<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 functions which you use to subscribe to or unsubscribe from an event.</p>
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>
@@ -201,20 +240,22 @@ about the event that occurred.</p>
<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>.
States are essentially properties of objects, which are identified by a <strong>Key</strong> and a <strong>Value</strong>.
The method <a href="##(BASE).SetState">BASE.SetState</a>() can be used to set a Value with a reference Key to the object.
To <strong>read or retrieve</strong> a state Value based on a Key, use the <a href="##(BASE).GetState">BASE.GetState</a> method.
These two methods provide a very handy way to keep state at long lasting processes.
<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) BASE Inheritance (tree) support</h2>
<h2>1.10) Inheritance</h2>
<p>The following methods are available to support inheritance:</p>
<p>The following methods are available to implement inheritance</p>
<ul>
<li><a href="##(BASE).Inherit">BASE.Inherit</a>: Inherits from a class.</li>