# evennia.utils.evform

EvForm - a way to create advanced ASCII forms

This is intended for creating advanced ASCII game forms, such as a large pretty character sheet or info document.

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 evtable.EvCell object when displaying the form.

Example of input file testform.py:

    FORMCHAR = "x"
    TABLECHAR = "c"

    FORM = '''
    .------------------------------------------------.
    |                                                |
    |  Name: xxxxx1xxxxx    Player: xxxxxxx2xxxxxxx  |
    |        xxxxxxxxxxx                             |
    |                                                |
     >----------------------------------------------<
    |                                                |
    | Desc:  xxxxxxxxxxx    STR: x4x    DEX: x5x     |
    |        xxxxx3xxxxx    INT: x6x    STA: x7x     |
    |        xxxxxxxxxxx    LUC: x8x    MAG: x9x     |
    |                                                |
     >----------------------------------------------<
    |          |                                     |
    | cccccccc | ccccccccccccccccccccccccccccccccccc |
    | cccccccc | ccccccccccccccccccccccccccccccccccc |
    | cccAcccc | ccccccccccccccccccccccccccccccccccc |
    | cccccccc | ccccccccccccccccccccccccccccccccccc |
    | cccccccc | cccccccccccccccccBccccccccccccccccc |
    |          |                                     |
    -------------------------------------------------
    '''

The first line of the FORM string is ignored. 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 FORM_CHAR and TABLE_CHAR and some of the common ASCII-art elements, like space, _ | * etc (see INVALID_FORMCHARS in this module). Form Rectangles can have any size, but must be separated from each other by at least one other character’s width.

Use as follows:

    from evennia import EvForm, EvTable

    # create a new form from the template
    form = EvForm("path/to/testform.py")

    (EvForm can also take a dictionary holding
     the required keys FORMCHAR, TABLECHAR and FORM)

    # add data to each tagged form cell
    form.map(cells={1: "Tom the Bouncer",
                    2: "Griatch",
                    3: "A sturdy fellow",
                    4: 12,
                    5: 10,
                    6:  5,
                    7: 18,
                    8: 10,
                    9:  3})
    # create the EvTables
    tableA = EvTable("HP","MV","MP",
                               table=[["**"], ["*****"], ["***"]],
                               border="incols")
    tableB = EvTable("Skill", "Value", "Exp",
                               table=[["Shooting", "Herbalism", "Smithing"],
                                      [12,14,9],["550/1200", "990/1400", "205/900"]],
                               border="incols")
    # add the tables to the proper ids in the form
    form.map(tables={"A": tableA,
                     "B": tableB})

    print(form)

This produces the following result:

    .------------------------------------------------.
    |                                                |
    |  Name: Tom the        Player: Griatch          |
    |        Bouncer                                 |
    |                                                |
     >----------------------------------------------<
    |                                                |
    | Desc:  A sturdy       STR: 12     DEX: 10      |
    |        fellow         INT: 5      STA: 18      |
    |                       LUC: 10     MAG: 3       |
    |                                                |
     >----------------------------------------------<
    |          |                                     |
    | HP|MV|MP | Skill      |Value      |Exp         |
    | ~~+~~+~~ | ~~~~~~~~~~~+~~~~~~~~~~~+~~~~~~~~~~~ |
    | **|**|** | Shooting   |12         |550/1200    |
    |   |**|*  | Herbalism  |14         |990/1400    |
    |   |* |   | Smithing   |9          |205/900     |
    |          |                                     |
     ------------------------------------------------

The marked forms have been replaced with EvCells of text and with EvTables. The form can be updated by simply re-applying form.map() with the updated data.

When working with the template ASCII file, you can use form.reload() to re-read the template and re-apply all existing mappings.

Each component is restrained to the width and height specified by the template, so it will resize to fit (or crop text if the area is too small for it). If you try to fit a table into an area it cannot fit into (when including its borders and at least one line of text), the form will raise an error.

class `evennia.utils.evform.``EvForm`(filename=None, cells=None, tables=None, form=None, **kwargs)

  Bases: `object`

  This object is instantiated with a text file and parses it for rectangular form fields. It can then be fed a mapping so as to populate the fields with fixed-width EvCell or Tables.

  `__init__`(filename=None, cells=None, tables=None, form=None, **kwargs)

    Initiate the form

    Keyword Arguments

      - filename (str) – Path to template file.

      - cells (dict) – A dictionary mapping {id: text}

      - tables (dict) – A dictionary mapping {id: EvTable}.

      - form (dict) – A dictionary {“FORMCHAR”:char, “TABLECHAR”:char, “FORM”:templatestring}. If this is given, filename is not read.

    Notes

    Other kwargs are fed as options to the EvCells and EvTables (see evtable.EvCell and evtable.EvTable for more info).

  `map`(cells=None, tables=None, **kwargs)

    Add mapping for form.

    Parameters

      - cells (dict) – A dictionary of {identifier:celltext}

      - tables (dict) – A dictionary of {identifier:table}

    Notes

    kwargs will be forwarded to tables/cells. See evtable.EvCell and evtable.EvTable for info.

  `reload`(filename=None, form=None, **kwargs)

    Creates the form from a stored file name.

    Parameters

      - filename (str) – The file to read from.

      - form (dict) – A mapping for the form.

    Notes

    Kwargs are passed through to Cel creation.