Documentation of SetState and GetState and BASE documentation update.

-- SetState documented.
-- GetState documented.
-- BASE main documentation.
-- Test mission updated and documentation.

Moose Development/Moose/Core/Base.lua

@@ -115,6 +115,19 @@
 --   * @{#BASE.GetClassName}(): Gets the name of the object, which is the name of the class the object was instantiated from.
 --   * @{#BASE.GetClassNameAndID}(): Gets the name and ID of the object.
 -- 
+-- ## 1.5) All objects derived from BASE can have "States"
+-- 
+-- A mechanism is in place in MOOSE, that allows to let the objects administer **states**. 
+-- States are essentially properties of objects, which are identified by a **Key** and a **Value**.
+-- The method @{#BASE.SetState}() can be used to set a Value with a reference Key to the object.
+-- To **read or retrieve** a state Value based on a Key, use the @{#BASE.GetState} method.
+-- 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 @{#BASE.SetState}() and @{#BASE.GetState} methods
+-- receive as the **first parameter the object for which the state needs to be set**.
+-- 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.
+-- 
 -- ## 1.10) BASE Inheritance (tree) support
 -- 
 -- The following methods are available to support inheritance:
@@ -706,25 +719,41 @@ function BASE:onEvent(event)
 	end
 end
 
-function BASE:SetState( Object, StateName, State )
+--- Set a state or property of the Object given a Key and a Value.
+-- Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.
+-- @param #BASE self
+-- @param Object The object that will hold the Value set by the Key.
+-- @param Key The key that is used as a reference of the value. Note that the key can be a #string, but it can also be any other type!
+-- @param Value The value to is stored in the object.
+-- @return The Value set.
+-- @return #nil The Key was not found and thus the Value could not be retrieved.
+function BASE:SetState( Object, Key, Value )
 
   local ClassNameAndID = Object:GetClassNameAndID()
 
   self.States[ClassNameAndID] = self.States[ClassNameAndID] or {}
-  self.States[ClassNameAndID][StateName] = State
+  self.States[ClassNameAndID][Key] = Value
-  self:T2( { ClassNameAndID, StateName, State } )
+  self:T2( { ClassNameAndID, Key, Value } )
   
-  return self.States[ClassNameAndID][StateName]
+  return self.States[ClassNameAndID][Key]
 end
 
-function BASE:GetState( Object, StateName )
+
+--- Get a Value given a Key from the Object.
+-- Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.
+-- @param #BASE self
+-- @param Object The object that holds the Value set by the Key.
+-- @param Key The key that is used to retrieve the value. Note that the key can be a #string, but it can also be any other type!
+-- @param Value The value to is stored in the Object.
+-- @return The Value retrieved.
+function BASE:GetState( Object, Key )
 
   local ClassNameAndID = Object:GetClassNameAndID()
 
   if self.States[ClassNameAndID] then
-    local State = self.States[ClassNameAndID][StateName] or false
+    local Value = self.States[ClassNameAndID][Key] or false
-    self:T2( { ClassNameAndID, StateName, State } )
+    self:T2( { ClassNameAndID, Key, Value } )
-    return State
+    return Value
   end
   
   return nil

Moose Test Missions/ZON - Zones/ZON-510 - Send message if Clients fly the first time in the Polygon Zones/ZON-510 - Send message if Clients fly the first time in the Polygon Zones.lua

@@ -12,19 +12,27 @@
 -- 
 -- 
 
+-- MOOSE wraps each Group alive in the mission into a GROUP class object. The GROUP class object is a wrapper object, wrapping
+-- the Group object from DCS and adding methods to it.
+-- Get the GROUP wrapper objects that were created by MOOSE at mission startup, by using the GROUP:FindByName() method.
+-- The Group name is the parameter to be searched for.
+-- Note that late activated groups are also "alive" and have a corresponding GROUP object in the running mission.
 local PolyZoneGroup1 = GROUP:FindByName("PolyZone1")
 local PolyZoneGroup2 = GROUP:FindByName("PolyZone2")
 
+-- Create 2 Polygon objects, using the ZONE_POLYGON:New constructor.
+-- The first parameter gives a name to the zone, the second is the GROUP object that defines the zone form.
 local PolyZone1 = ZONE_POLYGON:New( "PolyZone1", PolyZoneGroup1 )
 local PolyZone2 = ZONE_POLYGON:New( "PolyZone2", PolyZoneGroup2 )
 
+-- Create a SET of Moose CLIENT wrapper objects. At mission startup, a SET of Moose client wrapper objects is created.
+-- Note that CLIENT objects don't necessarily need to be alive!!! 
+-- So this set contains EVERY RED coalition client defined within the mission.
 local RedClients = SET_CLIENT:New():FilterCoalitions("red"):FilterStart()
 
 
 
-SchedulerInit, SchedulerInitID = SCHEDULER:New( nil, 
+RedClients:ForEachClient( 
-  function()
-    RedClients:ForEachClient( 
   function( MooseClient )
   
     -- Here we register the state of the client in which step he is in.
@@ -37,8 +45,6 @@ SchedulerInit, SchedulerInitID = SCHEDULER:New( nil,
     BASE:E( { "Alive Init", Client = MooseClient } )
     MooseClient:Alive( ResetClientForZone )
   end
-    )
-  end, {}, 1
 )
 
 Scheduler, SchedulerID = SCHEDULER:New( nil, 

docs/Documentation/Base.html

@@ -202,6 +202,19 @@ The <a href="Core.Event.html##(EVENTDATA)">Core.Event#EVENTDATA</a> structure co
     <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>. 
+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.
+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>
 
 <p>The following methods are available to support inheritance:</p>
@@ -520,9 +533,9 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
 </td>
 		</tr>
 		<tr>
-		<td class="name" nowrap="nowrap"><a href="##(BASE).GetState">BASE:GetState(Object, StateName)</a></td>
+		<td class="name" nowrap="nowrap"><a href="##(BASE).GetState">BASE:GetState(Object, Key, Value)</a></td>
 		<td class="summary">
-
+<p>Get a Value given a Key from the Object.</p>
 </td>
 		</tr>
 		<tr>
@@ -544,9 +557,9 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
 </td>
 		</tr>
 		<tr>
-		<td class="name" nowrap="nowrap"><a href="##(BASE).SetState">BASE:SetState(Object, StateName, State)</a></td>
+		<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>
@@ -1746,26 +1759,42 @@ is the Child class from which the Parent class needs to be retrieved.</p>
 <dt>
 
 <a id="#(BASE).GetState" >
-<strong>BASE:GetState(Object, StateName)</strong>
+<strong>BASE:GetState(Object, Key, Value)</strong>
 </a>
 </dt>
 <dd>
 	
+<p>Get a Value given a Key from the Object.</p>
 
 	
+<p>Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.</p>
+
 		<h3>Parameters</h3>
 		<ul>
 				<li>
 				
-<p><code><em> Object </em></code>: </p>
+<p><code><em> Object </em></code>: 
+The object that holds the Value set by the Key.</p>
 
 				</li>
 				<li>
 				
-<p><code><em> StateName </em></code>: </p>
+<p><code><em> Key </em></code>: 
+The key that is used to retrieve the value. Note that the key can be a #string, but it can also be any other type!</p>
+
+				</li>
+				<li>
+				
+<p><code><em> Value </em></code>: 
+The value to is stored in the Object.</p>
 
 				</li>
 		</ul>
+		<h3>Return value</h3>
+				
+
+<p>The Value retrieved.</p>
+
 </dd>
 </dl>
 		<dl class="function">
@@ -1839,31 +1868,52 @@ Child</p>
 <dt>
 
 <a id="#(BASE).SetState" >
-<strong>BASE:SetState(Object, StateName, State)</strong>
+<strong>BASE:SetState(Object, Key, Value)</strong>
 </a>
 </dt>
 <dd>
 	
+<p>Set a state or property of the Object given a Key and a Value.</p>
 
 	
+<p>Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.</p>
+
 		<h3>Parameters</h3>
 		<ul>
 				<li>
 				
-<p><code><em> Object </em></code>: </p>
+<p><code><em> Object </em></code>: 
+The object that will hold the Value set by the Key.</p>
 
 				</li>
 				<li>
 				
-<p><code><em> StateName </em></code>: </p>
+<p><code><em> Key </em></code>: 
+The key that is used as a reference of the value. Note that the key can be a #string, but it can also be any other type!</p>
 
 				</li>
 				<li>
 				
-<p><code><em> State </em></code>: </p>
+<p><code><em> Value </em></code>: 
+The value to is stored in the object.</p>
 
 				</li>
 		</ul>
+		<h3>Return values</h3>
+			<ol>
+				<li>
+				
+
+<p>The Value set.</p>
+
+				</li>
+				<li>
+				
+<p><em>#nil:</em>
+The Key was not found and thus the Value could not be retrieved.</p>
+
+				</li>
+			</ol>
 </dd>
 </dl>
 		<dl class="function">

docs/Documentation/Cargo.html

@@ -2413,7 +2413,6 @@ The UNIT carrying the package.</p>
 		<dl class="function">
 <dt>
 
-		<em></em>
 <a id="#(AI_CARGO_UNIT).CargoCarrier" >
 <strong>AI_CARGO_UNIT.CargoCarrier</strong>
 </a>

docs/Documentation/Spawn.html

@@ -2171,7 +2171,7 @@ when nothing was spawned.</p>
 		<dl class="function">
 <dt>
 
-		<em>#number</em>
+		<em></em>
 <a id="#(SPAWN).SpawnMaxGroups" >
 <strong>SPAWN.SpawnMaxGroups</strong>
 </a>
@@ -2188,7 +2188,7 @@ when nothing was spawned.</p>
 		<dl class="function">
 <dt>
 
-		<em>#number</em>
+		<em></em>
 <a id="#(SPAWN).SpawnMaxUnitsAlive" >
 <strong>SPAWN.SpawnMaxUnitsAlive</strong>
 </a>