<spanid="evennia-utils-evform"></span><h1>evennia.utils.evform<aclass="headerlink"href="#module-evennia.utils.evform"title="Permalink to this headline">¶</a></h1>
<p>EvForm - a way to create advanced ASCII forms</p>
<p>This is intended for creating advanced ASCII game forms, such as a large pretty character sheet or
info document.</p>
<p>The system works on the basis of a readin template that is given in a separate Python file imported
into the handler. This file contains some optional settings and a string mapping out the form. The
template has markers in it to denounce fields to fill. The markers map the absolute size of the
field and will be filled with an <strong>evtable.EvCell</strong> object when displaying the form.</p>
<p>Example of input file <strong>testform.py</strong>:</p>
<p>The first line of the <strong>FORM</strong> string is ignored if empty. The forms and table markers must mark out
complete, unbroken rectangles, each containing one embedded single-character identifier (so the
smallest element possible is a 3-character wide form). The identifier can be any character except
for the <strong>FORM_CHAR</strong> and <strong>TABLE_CHAR</strong> and some of the common ASCII-art elements, like space, <strong>_</strong><strong>|</strong>
<strong>*</strong> etc (see <strong>INVALID_FORMCHARS</strong> in this module). Form Rectangles can have any size, but must be
separated from each other by at least one other character’s width.</p>
<p>The form can also replace literal markers not abiding by these rules. For example, the <strong>v&</strong> in the
bottom right corner could be such literal marker. If a literal-mapping for ‘v&’ is provided, all
occurrences of this marker will be replaced. This will happen <em>before</em> any other parsing, so in
principle this could be used to inject new fields/tables into the form dynamically. This literal
mapping does not consider width, but it will affect to total width of the form, so make sure what
you inject does not break things. Using literal markers is the only way to inject 1 or 2-character
<spanclass="c1"># EvForm can also take a dictionary instead of a filepath, as long</span>
<spanclass="c1"># as the dict contains the keys FORMCHAR, TABLECHAR and FORM</span>
<spanclass="c1"># form = EvForm(form=form_dict)</span>
<spanclass="c1"># add data to each tagged form cell</span>
<spanclass="n">form</span><spanclass="o">.</span><spanclass="n">map</span><spanclass="p">(</span><spanclass="n">cells</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="mi">1</span><spanclass="p">:</span><spanclass="s2">"Tom the Bouncer"</span><spanclass="p">,</span>
<codeclass="sig-name descname">table_options</code><emclass="property"> = {'align': 'l', 'enforce_size': True, 'pad_bottom': 0, 'pad_left': 0, 'pad_right': 0, 'pad_top': 0, 'valign': 't'}</em><aclass="headerlink"href="#evennia.utils.evform.EvForm.table_options"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py method">
<dtid="evennia.utils.evform.EvForm.__init__">
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">data</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">cells</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tables</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">literals</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/evform.html#EvForm.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.evform.EvForm.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Initiate the form</p>
<dlclass="field-list simple">
<dtclass="field-odd">Keyword Arguments</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>data</strong> (<em>str</em><em> or </em><em>dict</em>) – Path to template file or a dict with
“formchar”, “tablechar” and “form” keys (not case sensitive, so FORM etc
also works, to stay compatible with the in-file names). While “form/FORM”
is required, if FORMCHAR/TABLECHAR are not given, they will default to
‘x’ and ‘c’ respectively.</p></li>
<li><p><strong>cells</strong> (<em>dict</em>) – A dictionary mapping <strong>{id: str}</strong></p></li>
<li><p><strong>tables</strong> (<em>dict</em>) – A dictionary mapping <strong>{id: EvTable}</strong>.</p></li>
<li><p><strong>literals</strong> (<em>dict</em>) – A dictionary mapping <strong>{id: str}</strong>. Will be replaced
after width of form is calculated, but before cells/tables are mapped.
All occurrences of the identifier on the form will be replaced. Note
that there is no length-restriction on the remap, you are responsible
for not breaking the form.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>Other kwargs are fed as options to the EvCells and EvTables
(see <strong>evtable.EvCell</strong> and <strong>evtable.EvTable</strong> for more info).</p>
</dd></dl>
<dlclass="py method">
<dtid="evennia.utils.evform.EvForm.reload">
<codeclass="sig-name descname">reload</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/evform.html#EvForm.reload"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.evform.EvForm.reload"title="Permalink to this definition">¶</a></dt>
<dd><p>Creates the form from a filename or data structure.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>data</strong> (<em>str</em><em> or </em><em>dict</em>) – Can be used to update an existing form using
the same cells/tables provided on initialization or using <strong>.map()</strong>.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>Kwargs are passed through to Cel creation.</p>
</dd></dl>
<dlclass="py method">
<dtid="evennia.utils.evform.EvForm.map">
<codeclass="sig-name descname">map</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">cells</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">tables</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">data</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">literals</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/evform.html#EvForm.map"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.evform.EvForm.map"title="Permalink to this definition">¶</a></dt>
<dd><p>Add mapping for form. This allows for updating an existing
evform.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>cells</strong> (<em>dict</em>) – A dictionary of {identifier:celltext}. These
will be appended to the existing mappings.</p></li>
<li><p><strong>tables</strong> (<em>dict</em>) – A dictionary of {identifier:table}. Will
be appended to the existing mapping.</p></li>
<li><p><strong>data</strong> (<em>str</em><em> or </em><em>dict</em>) – A path to a evform module or a dict with
the needed “FORM”, “TABLE/FORMCHAR” keys. Will replace
the originally initialized form.</p></li>
<li><p><strong>literals</strong>–</p></li>
</ul>
</dd>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><p><strong>will be appended to the existing cell/table options.</strong> (<em>These</em>) –</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>kwargs will be forwarded to tables/cells. See
<strong>evtable.EvCell</strong> and <strong>evtable.EvTable</strong> for info.</p>
