LST Editor

Introduction

The LST editor for PCGEN is designed to simplify the editing of LST files which are the data files that determine how PCGEN works.

State

• Currently the editor for LST files built into PCGen is a in need of a rebuild. It has some issues and doesn't expand itself when new tokens are added (because it's hard coded from before there were LST tokens). It also has problems with certain tokens.

Project Goals

• Any new token would at least give a text field, even if PCGen didn't recognize the token.
• Allows edit both during runtime (meaning you can copy existing objects, but can't modify the ones that already exist) and in a "edit in place" mode (allow editing of the LST files in full, as a stand-alone program, vs. embedded in PCGen).

User Interface

Overview

The user interface is able to be run in stand-alone mode or inside PCGEN. More than one instance can be run at a time to allow copying/inspection of data. If the editor is run from within PCGEN then it's title bar indicates this plus there is a different colour border around the tabbed area to indicate this.

Dialog

The dialog is split into two areas, the file selection area and the editor area which has multiple tabs. All controls have tool tips and hitting F1 at any time will give more detailed help.

File Selection Area

This consists of three parts:

1. The pcc file area: this allows the user to select the pcc file that controls which lst files are to be edited.
2. The selected file area: this indicates the file that current edits will be saved in.
3. The context load area: this brings up a load screen so that the user can load the context.

Use

The pcc file area is totally under user control, however if a standard file is selected the user will be warned and asked if he wants to continue in read-only mode. If the answer is no a warning will be given and confirmation asked for before continuing, this allows the user to examine the file and use cut and paste into another version of the editor. When the editor is run from within PCGEN the default file will be the 'custom edit file' but other files can be accessed. If the 'custom edit file' is used then the user will have the option when saving to load the data into the main application.

The contents of the selected file area are determined by the pcc file selected and the selection in the editor area.

• If there is no pcc file given then it will be blank.
• If a pcc file is given and no primary token selected then all the lst files currently associated with that file are available plus 'new' and 'all'.
• If a primary token is selected then the list of files associated with the pcc file that can contain that token, plus 'new' and 'all' are available.
• The save button saves the data in the selected tab.
• If the lst file selected is 'new' then the user is asked for a file name to save the data in, the user is also asked if the file should be added to the pcc file.

Tab 1

The primary token tab consists of three parts:

1. The main token area: this lists all the top level tokens in the system.
2. The item selection area: this allows the user to select an item to edit.
3. The new entry button.

Use

• The contents of the main token area are fixed. The full list of top level tokens will be visible.
• The contents of the item selected area is determined by the other areas.
• If no lst file or 'new' is chosen then it is empty.
• If a lst file is chosen then all entries in that file of the primary token selected are visible.
• If no primary token is selected then all entries in the file are visible.
• Double clicking or CTRL-Right will move focus to tab 2 with that entry selected.
• The new entry button is only available if a primary token is selected and a lst file other than 'all' is selected.
• Note if the PCC entry is selected in the token list then processing is different as this refers to the pcc file, not a lst file. In this case the lst file area is disabled changes will be made to the pcc file.

Tab 2

The secondary token tab consists of 7 parts:

1. The primary token area: this gives the token type and name as selected in tab 1.
2. The secondary token area: this lists all the secondary tokens types associated with the primary one, it also includes a value of 'all' so that all the tokens can be seen.
3. The secondary token list: this lists all the secondary tokens of the selected type associated with the primary token.
4. The editor area: this allows input of the data associated with the secondary token.
5. Add button: for adding new secondary tokens.
6. Parse button: for parsing the input.
7. The message area: this will display any messages associated with parsing the token.

Use

• The contents of the primary and secondary token areas are determined by what is selected in tab 1.
• The secondary token list contains the actual data associated with the secondary token selected.
• The editor area is initially a text field but for some tokens, e.g. an integer token, a smart editor appears here.
• The add button is only enabled if there is no current token of the selected type or multiple tokens of that type can be used and 'all' is not the selected type.
• When the data is parsed the message area shows any errors from the parsing. Double clicking on an error give the errant token focus.
• After parsing each token which is in error will also be coloured red in the list so that it is quick to see where problems lie.
• When the save button is hit the file will be parsed and if it fails the user will be warned of this and asked if the file should still be saved. This allows partially completed updates to be saved.

Tab3

The editor tab is an editable area, this has standard text editing abilities, e.g. copy, cut and paste, search and replace. This area also has some smart editing features, though not as powerful as the editor area in tab 2. If an item is selected CTRL-Left on the item will move focus to tab 2 with that entry selected, it will also populate tab 1 accordingly. The file in this editor will be that in area 3 of the first tab.

Interaction between areas

The editor shows the contents of the selected lst file or pcc file. The switch button will change it's text according to whether the pcc file or lst file is displayed. The reload button reloads the file and so can be used to undo changes that have not been saved.