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 in need of a rebuild. It has some issues and doesn't expand itself when new objects are added (because it's hard coded from before there were LST objects). It also has problems with certain objects.

Project Goals

• Any new object would at least give a text field, even if PCGen didn't recognize the object.
• 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 multiple instances are running then only the first will be editable. 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 object type selected then all the lst files currently associated with that file are available plus 'new' and 'all'.
• If an object type is selected then the list of files associated with the pcc file that can contain that object, 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 - Object Selection

The object type tab consists of three parts:

1. The main object area: this lists all the top level objects 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 object area are fixed. The full list of top level objects 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 object type selected are visible.
• If no object type 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 object type is selected and a lst file other than 'all' is selected.
• Note if the PCC entry is selected in the object 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 - Tag Entry

The secondary object tab consists of 7 parts:

1. The object type area (Ability in the example above): this gives the object type and name as selected in tab 1.
2. The objects area: this lists all the objects associated with the object type, it also includes a value of 'all' so that all the tags can be seen.
3. The tag list: this lists all the tags of the selected object associated with the object type.
4. The editor area: this allows input of the data associated with the tag.
5. Add button: for adding new tags.
6. Parse button: for parsing the input.
7. Auto Parse check box: When this is checked the current token is parsed as it is edited.
8. The message area: this will display any messages associated with parsing the object.

Use

• The contents of the primary and secondary object areas are determined by what is selected in tab 1.
• The secondary object list contains the actual data associated with the secondary object selected.
• The editor area is initially a text field but for some objects, e.g. an integer object, a smart editor appears here.
• The add button is only enabled if there is no current object of the selected type or multiple objects 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 object focus.
• After parsing each object 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 - Editor

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.