<spanid="evennia-contrib-utils-tree-select-tree-select"></span><h1>evennia.contrib.utils.tree_select.tree_select<aclass="headerlink"href="#module-evennia.contrib.utils.tree_select.tree_select"title="Permalink to this headline">¶</a></h1>
<p>Easy menu selection tree</p>
<p>Contrib - Tim Ashley Jenkins 2017</p>
<p>This module allows you to create and initialize an entire branching EvMenu
instance with nothing but a multi-line string passed to one function.</p>
<p>EvMenu is incredibly powerful and flexible, but using it for simple menus
can often be fairly cumbersome - a simple menu that can branch into five
categories would require six nodes, each with options represented as a list
of dictionaries.</p>
<p>This module provides a function, init_tree_selection, which acts as a frontend
for EvMenu, dynamically sourcing the options from a multi-line string you provide.
For example, if you define a string as such:</p>
<blockquote>
<div><p>TEST_MENU = ‘’’Foo
Bar
Baz
Qux’’’</p>
</div></blockquote>
<p>And then use TEST_MENU as the ‘treestr’ source when you call init_tree_selection
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">dashcount</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">entry</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#dashcount"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.dashcount"title="Permalink to this definition">¶</a></dt>
<dd><p>Counts the number of dashes at the beginning of a string. This
is needed to determine the depth of options in categories.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>entry</strong> (<em>str</em>) – String to count the dashes at the start of</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>dashes (int)</em>– Number of dashes at the start</p>
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">is_category</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">treestr</span></em>, <emclass="sig-param"><spanclass="n">index</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#is_category"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.is_category"title="Permalink to this definition">¶</a></dt>
<dd><p>Determines whether an option in a tree string is a category by
whether or not there are additional options below it.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>treestr</strong> (<em>str</em>) – Multi-line string representing menu options</p></li>
<li><p><strong>index</strong> (<em>int</em>) – Which line of the string to test</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>is_category (bool)</em>– Whether the option is a category</p>
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">parse_opts</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">treestr</span></em>, <emclass="sig-param"><spanclass="n">category_index</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#parse_opts"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.parse_opts"title="Permalink to this definition">¶</a></dt>
<dd><p>Parses a tree string and given index into a list of options. If
category_index is none, returns all the options at the top level of
the menu. If category_index corresponds to a category, returns a list
of options under that category. If category_index corresponds to
an option that is not a category, it’s a selection and returns True.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>treestr</strong> (<em>str</em>) – Multi-line string representing menu options</p></li>
<li><p><strong>category_index</strong> (<em>int</em>) – Index of category or None for top level</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>kept_opts (list or True)</em>–</p>
<dlclass="simple">
<dt>Either a list of options in the selected</dt><dd><p>category or True if a selection was made</p>
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">index_to_selection</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">treestr</span></em>, <emclass="sig-param"><spanclass="n">index</span></em>, <emclass="sig-param"><spanclass="n">desc</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#index_to_selection"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.index_to_selection"title="Permalink to this definition">¶</a></dt>
<dd><p>Given a menu tree string and an index, returns the corresponding selection’s
name as a string. If ‘desc’ is set to True, will return the selection’s
description as a string instead.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>treestr</strong> (<em>str</em>) – Multi-line string representing menu options</p></li>
<li><p><strong>index</strong> (<em>int</em>) – Index to convert to selection key or description</p></li>
</ul>
</dd>
</dl>
<dlclass="simple">
<dt>Options:</dt><dd><p>desc (bool): If true, returns description instead of key</p>
</dd>
</dl>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>selection (str)</em>– Selection key or description if ‘desc’ is set</p>
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">go_up_one_category</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">treestr</span></em>, <emclass="sig-param"><spanclass="n">index</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#go_up_one_category"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.go_up_one_category"title="Permalink to this definition">¶</a></dt>
<dd><p>Given a menu tree string and an index, returns the category that the given option
belongs to. Used for the ‘go back’ option.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>treestr</strong> (<em>str</em>) – Multi-line string representing menu options</p></li>
<li><p><strong>index</strong> (<em>int</em>) – Index to determine the parent category of</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>parent_category (int)</em>– Index of parent category</p>
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">menunode_treeselect</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">caller</span></em>, <emclass="sig-param"><spanclass="n">raw_string</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#menunode_treeselect"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.menunode_treeselect"title="Permalink to this definition">¶</a></dt>
<dd><p>This is the repeating menu node that handles the tree selection.</p>
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">CmdNameColor</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#CmdNameColor"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">key</code><emclass="property"> = 'namecolor'</em><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor.key"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">func</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#CmdNameColor.func"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor.func"title="Permalink to this definition">¶</a></dt>
<dd><p>This is the actual executing part of the command. It is
called directly after self.parse(). See the docstring of this
module for which object properties are available (beyond those
<codeclass="sig-name descname">aliases</code><emclass="property"> = []</em><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor.aliases"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">help_category</code><emclass="property"> = 'general'</em><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor.help_category"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">lock_storage</code><emclass="property"> = 'cmd:all();'</em><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor.lock_storage"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">search_index_entry</code><emclass="property"> = {'aliases': '', 'category': 'general', 'key': 'namecolor', 'no_prefix': ' ', 'tags': '', 'text': '\n Set or remove a special color on your name. Just an example for the\n easy menu selection tree contrib.\n '}</em><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.CmdNameColor.search_index_entry"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.contrib.utils.tree_select.tree_select.</code><codeclass="sig-name descname">change_name_color</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">caller</span></em>, <emclass="sig-param"><spanclass="n">treestr</span></em>, <emclass="sig-param"><spanclass="n">index</span></em>, <emclass="sig-param"><spanclass="n">selection</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/contrib/utils/tree_select/tree_select.html#change_name_color"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.contrib.utils.tree_select.tree_select.change_name_color"title="Permalink to this definition">¶</a></dt>
<dd><p>Changes a player’s name color.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>caller</strong> (<em>obj</em>) – Character whose name to color.</p></li>
<li><p><strong>treestr</strong> (<em>str</em>) – String for the color change menu - unused</p></li>
<li><p><strong>index</strong> (<em>int</em>) – Index of menu selection - unused</p></li>
<li><p><strong>selection</strong> (<em>str</em>) – Selection made from the name color menu - used
