as.dat.gui.html

<!DOCTYPE html>

<html>
<head>
  <title>as.dat.gui.js</title>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
  <link rel="stylesheet" media="all" href="docco.css" />
</head>
<body>
  <div id="container">
    <div id="background"></div>
    
    <ul class="sections">
        
          <li id="title">
              <div class="annotation">
                  <h1>as.dat.gui.js</h1>
              </div>
          </li>
        
        
        
        <li id="section-1">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-1">&#182;</a>
              </div>
              <p> ABM.DatGUI creates a minimal user interface for
 an ABM.Model using dat.gui.</p>
<p> (requires <a href="http://workshop.chromeexperiments.com/examples/gui/">dat.gui.js</a>)</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>
(<span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{
  ABM.DatGUI = (<span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{</pre></div></div>
            
        </li>
        
        
        <li id="section-2">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-2">&#182;</a>
              </div>
              <p> The constructor accepts either</p>
<ol>
<li>an <a href="fbui.html">ABM.FirebaseUI</a> or</li>
<li>an ABM.Model and a ui object, like:  <pre><code> {
   <span class="hljs-string">"Setup"</span>: {
     type: <span class="hljs-string">"button"</span>,
     setter: <span class="hljs-string">"setup"</span>
   },
   <span class="hljs-string">"Background"</span>: {
     type: <span class="hljs-string">"choice"</span>,
     vals: [<span class="hljs-string">"image"</span>,<span class="hljs-string">"aspect"</span>,<span class="hljs-string">"slope"</span>],
     val: <span class="hljs-string">"image"</span>,
     setter: <span class="hljs-string">"setBackground"</span>
   },
   <span class="hljs-string">"Neighborhood"</span>: {
     type: <span class="hljs-string">"slider"</span>,
     min: <span class="hljs-number">1</span>,
     max: <span class="hljs-number">10</span>,
     step: <span class="hljs-number">1</span>,
     val: <span class="hljs-number">3</span>,
     smooth: <span class="hljs-literal">false</span>,
     setter: <span class="hljs-string">"setNeighborRadius"</span>
   },
   <span class="hljs-string">"refreshLinks"</span>: {
     type: <span class="hljs-string">"switch"</span>,
     val: <span class="hljs-literal">true</span>
   }
 }
</code></pre></li>
</ol>

            </div>
            
        </li>
        
        
        <li id="section-3">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-3">&#182;</a>
              </div>
              <p>If you pass in a FirebaseUI object, all instances of
the model interface in all browsers will be in sync.</p>

            </div>
            
        </li>
        
        
        <li id="section-4">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-4">&#182;</a>
              </div>
              <p>TODO: Allow a subset of ui elements to remain in sync.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>
    <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">DatGUI</span><span class="hljs-params">(fbuiOrModel, uiObject)</span> </span>{
      ABM.Util.mixin(<span class="hljs-keyword">this</span>, <span class="hljs-keyword">new</span> ABM.Evented())
      <span class="hljs-keyword">this</span>.gui = <span class="hljs-keyword">new</span> dat.GUI();
      <span class="hljs-keyword">this</span>.datGuiModel = {};
      <span class="hljs-keyword">this</span>.datGuiControllers = {};

      <span class="hljs-keyword">var</span> model, ui, fbui;
      <span class="hljs-keyword">if</span> (<span class="hljs-built_in">arguments</span>.length == <span class="hljs-number">2</span>) {
        model = <span class="hljs-keyword">this</span>.model = fbuiOrModel;
        ui = <span class="hljs-keyword">this</span>.ui = uiObject;
      }
      <span class="hljs-keyword">else</span> {
        fbui = <span class="hljs-keyword">this</span>.fbui = fbuiOrModel;
        ui = <span class="hljs-keyword">this</span>.ui = fbui.ui;
      }

      <span class="hljs-keyword">this</span>.initUIElements(ui, <span class="hljs-keyword">this</span>.gui);
    }

    DatGUI.prototype.initUIElements = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(ui, folder)</span> </span>{
      <span class="hljs-keyword">var</span> self = <span class="hljs-keyword">this</span>;
      <span class="hljs-keyword">for</span> (<span class="hljs-keyword">var</span> name <span class="hljs-keyword">in</span> ui) {
        <span class="hljs-keyword">if</span> (ui.hasOwnProperty(name)) {
          <span class="hljs-keyword">var</span> uiEl = ui[name];
          
          <span class="hljs-keyword">if</span> (isFolder(uiEl)) {</pre></div></div>
            
        </li>
        
        
        <li id="section-5">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-5">&#182;</a>
              </div>
              <p>You can group ui elements into folders by nesting objects. E.g.:</p>

            </div>
            
        </li>
        
        
        <li id="section-6">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-6">&#182;</a>
              </div>
              <pre><code>{
  <span class="hljs-string">"Moose stuff"</span>: {
    <span class="hljs-string">"Create a moose"</span>: {
      type: <span class="hljs-string">"button"</span>
    },
    <span class="hljs-string">"Moose color"</span>: {
      type: <span class="hljs-string">"choice"</span>,
      vals: [<span class="hljs-string">"brown"</span>, <span class="hljs-string">"dark brown"</span>]
    }
  },
  <span class="hljs-string">"Goat stuff"</span>: {
    <span class="hljs-string">"Look for a goat"</span>: {
      type: <span class="hljs-string">"button"</span>
    },
    <span class="hljs-string">"Goat size"</span>: {
      type: <span class="hljs-string">"slider"</span>,
      min: <span class="hljs-number">1</span>,
      max: <span class="hljs-number">9000</span>
    }
  }
}
</code></pre>
            </div>
            
        </li>
        
        
        <li id="section-7">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-7">&#182;</a>
              </div>
              <p>Element names should still be unique across folders.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>
            <span class="hljs-keyword">var</span> subFolder = folder.addFolder(name);
            <span class="hljs-keyword">this</span>.initUIElements(uiEl, subFolder);
            <span class="hljs-keyword">continue</span>;
          }
          
          <span class="hljs-keyword">if</span> (uiEl.type != <span class="hljs-string">'button'</span>) {</pre></div></div>
            
        </li>
        
        
        <li id="section-8">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-8">&#182;</a>
              </div>
              <p>The state of all non-button elements is stored in <code>this.datGuiModel</code>.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>            <span class="hljs-keyword">this</span>.datGuiModel[name] = uiEl.val;

            <span class="hljs-keyword">if</span> (<span class="hljs-keyword">typeof</span> fbui != <span class="hljs-string">'undefined'</span>) {
              fbui.refs[name].child(<span class="hljs-string">'val'</span>).on(<span class="hljs-string">'value'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(valSnap)</span> </span>{
                self.datGuiModel[<span class="hljs-keyword">this</span>.name] = valSnap.val();
                self.updateGui();
              }.bind({ name: name }));
            }
          }

          <span class="hljs-keyword">var</span> ctrl = <span class="hljs-literal">null</span>;</pre></div></div>
            
        </li>
        
        
        <li id="section-9">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-9">&#182;</a>
              </div>
              <p>A uiEl can be of type <code>&quot;button&quot;</code>, <code>&quot;choice&quot;</code>, <code>&quot;switch&quot;</code>, or <code>&quot;slider&quot;</code>.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>          <span class="hljs-keyword">switch</span>(uiEl.type) {
            <span class="hljs-keyword">case</span> <span class="hljs-string">'button'</span>:
              <span class="hljs-keyword">this</span>.datGuiModel[name] = self.fbui ?
                <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{ 
                  self.fbui.setUIValue(<span class="hljs-keyword">this</span>.name, <span class="hljs-literal">true</span>); 
                }.bind({ name: name }) :
                <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{
                  self.setModelValue(<span class="hljs-keyword">this</span>.name, <span class="hljs-literal">null</span>, <span class="hljs-keyword">this</span>.setter);
                }.bind({ name: name, setter: ui[name].setter });
              folder.add(<span class="hljs-keyword">this</span>.datGuiModel, name);
            <span class="hljs-keyword">break</span>;
            <span class="hljs-keyword">case</span> <span class="hljs-string">'choice'</span>:
              ctrl = folder.add(<span class="hljs-keyword">this</span>.datGuiModel, name, uiEl.vals);
            <span class="hljs-keyword">break</span>;
            <span class="hljs-keyword">case</span> <span class="hljs-string">'switch'</span>:
              ctrl = folder.add(<span class="hljs-keyword">this</span>.datGuiModel, name);
            <span class="hljs-keyword">break</span>;
            <span class="hljs-keyword">case</span> <span class="hljs-string">'slider'</span>:
              ctrl = folder.add(<span class="hljs-keyword">this</span>.datGuiModel, name, uiEl.min, uiEl.max).step(uiEl.step);
            <span class="hljs-keyword">break</span>;
          }

          <span class="hljs-keyword">if</span> (ctrl) {
            <span class="hljs-keyword">var</span> callback;
            <span class="hljs-keyword">if</span> (self.fbui) {
              callback = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(value)</span> </span>{
                self.fbui.setUIValue(<span class="hljs-keyword">this</span>.name, value);
              }.bind({ name: name });
            }
            <span class="hljs-keyword">else</span> {
              callback = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(value)</span> </span>{
                self.setModelValue(<span class="hljs-keyword">this</span>.name, value, <span class="hljs-keyword">this</span>.setter);
              }.bind({ name: name, setter: ui[name].setter });
            }</pre></div></div>
            
        </li>
        
        
        <li id="section-10">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-10">&#182;</a>
              </div>
              <p>A slider can be <code>&quot;smooth&quot;</code>, in which case
the setter is called during a drag.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>            <span class="hljs-keyword">if</span> (uiEl.smooth) {
              ctrl.onChange(callback);
            }</pre></div></div>
            
        </li>
        
        
        <li id="section-11">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-11">&#182;</a>
              </div>
              <p>Otherwise, the setter is called at the end
of the drag.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>            <span class="hljs-keyword">else</span> {
              ctrl.onFinishChange(callback);
            }
            <span class="hljs-keyword">this</span>.datGuiControllers[name] = ctrl;
          }
        }
      }
    }

    DatGUI.prototype.setModelValue = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(name, value, setter)</span> </span>{
      <span class="hljs-keyword">if</span> (setter) {
        <span class="hljs-keyword">this</span>.model[setter](value);
      }</pre></div></div>
            
        </li>
        
        
        <li id="section-12">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-12">&#182;</a>
              </div>
              <p>If you don’t specify a setter, we assume the ui element name is
the name of a model variable.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">else</span> {
        <span class="hljs-keyword">this</span>.model[name] = value;
      }</pre></div></div>
            
        </li>
        
        
        <li id="section-13">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-13">&#182;</a>
              </div>
              <p>ABM.DatGUI will emit a <code>&#39;change&#39;</code> event
whenever part of its model changes.</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">this</span>.emit(<span class="hljs-string">'change'</span>, { name: name, value: value });
    }</pre></div></div>
            
        </li>
        
        
        <li id="section-14">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-14">&#182;</a>
              </div>
              <p>Use <code>update</code> to set the current state of the UI. E.g.:</p>

            </div>
            
            <div class="content"><div class='highlight'><pre>    DatGUI.prototype.update = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(uiObject)</span> </span>{</pre></div></div>
            
        </li>
        
        
        <li id="section-15">
            <div class="annotation">
              
              <div class="pilwrap ">
                <a class="pilcrow" href="#section-15">&#182;</a>
              </div>
              <pre><code>myUI.update({
  <span class="hljs-string">"Moose color"</span>: <span class="hljs-string">"brown"</span>,
  <span class="hljs-string">"Goat size"</span>: <span class="hljs-number">500</span>
})
</code></pre>
            </div>
            
            <div class="content"><div class='highlight'><pre>      <span class="hljs-keyword">for</span> (<span class="hljs-keyword">var</span> name <span class="hljs-keyword">in</span> uiObject) {
        <span class="hljs-keyword">var</span> curCtrl = <span class="hljs-keyword">this</span>.datGuiControllers[name];
        <span class="hljs-keyword">if</span> (curCtrl) {
          curCtrl.setValue(uiObject[name]);
          <span class="hljs-keyword">var</span> changeFun = curCtrl.__onChange || curCtrl.__onFinishChange;
          changeFun(<span class="hljs-keyword">this</span>.datGuiModel[name]);
        }
      }
    }

    DatGUI.prototype.updateGui = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{
      <span class="hljs-keyword">for</span> (<span class="hljs-keyword">var</span> i <span class="hljs-keyword">in</span> <span class="hljs-keyword">this</span>.gui.__controllers) {
        <span class="hljs-keyword">this</span>.gui.__controllers[i].updateDisplay();
      }
    }

    <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">isFolder</span><span class="hljs-params">(obj)</span> </span>{
      <span class="hljs-keyword">return</span> <span class="hljs-keyword">typeof</span> obj.type == <span class="hljs-string">'undefined'</span>;
    }
        
    <span class="hljs-keyword">return</span> DatGUI;

  })();

}).call(<span class="hljs-keyword">this</span>);</pre></div></div>
            
        </li>
        
    </ul>
  </div>
</body>
</html>