User Selection Walkthrough
Overview
When CDOM Objects are added to a Player Character, some may require additional actions to complete addition of the object (and all of the characteristics of that object). This document describes the user selection process for those additional choices.
Note that this is for user selections that are independent of the CHOOSE: token provided in PCGen. Generally, the user selections discussed here are part of the ADD: token, but there are other tokens that behave in a similar fashion (e.g. REMOVE, SKILLLIST, KIT). A good (but not comprehensive) method to find tokens that provide user selections is to search for tokens that are also Choice Actors.
Components
A user selection has a series of objects that are involved in the process of selecting and applying the object selected.
Primitive Choice Sets
Primitive Choice Sets serve as a foundation that stores the objects that provide the foundation set from which the Player Character is allowed to select one (or more) of the options. The Primitive Choice Sets are constructed during LST load based on the contents of the token.
ChoiceSet
The ChoiceSet object wraps the Primitive Choice Set, and stores some additional information. The ANY/ALL usage (see the Weakness in LST usage of ANY/ALL) is a static value known by the Token constructing the ChoiceSet and is stored within the ChoiceSet, as is a name for the ChoiceSet. The name is typically the owning token name, as it is used internally to distinguish appropriate token and persistence behavior. The name is not intended to be displayed to the user.
In PCGen 5.17, the ChoiceSet additionally stores the displayed Title for the Chooser from which the user will make a selection. This was transitioned to the ChoiceSet (and away from the TransitionChoice), so that the CHOOSE token can share the Primitive Choice Set and ChoiceSet infrastructure without using the TransitionChoice class).
ChoiceSet can be found in pcgen.cdom.base
TransitionChoice
The TransitionChoice object holds a ChoiceSet, plus some additional information. The TransitionChoice holds a Formula for storing the number of selections the user may make. The TransitionChoice also holds any requirement or stacking rules regarding the selection (e.g. the STACKS options to ADD:FEAT).
The TransitionChoice also stores a Choice Actor, which controls which of the items in the Primitive Choice Set are allowed (and thus which are presented in the Chooser dialog), as well as what action is required to apply the selection to the PlayerCharacter.
In PCGen 5.16, the TransitionChoice additionally stores the displayed Title for the Chooser from which the user will make a selection.
A specialized version of TransitionChoice, called PersistentTransitionChoice, serves to hold user selections which use a PersistentChoiceActor.
TransitionChoice and PersistentTransitionChoice can be found in pcgen.cdom.base
Driving a user Selection
When a CDOM Object is added to a Player Character, there are various keys within the CDOM Object (both ObjectKey and ListKey) which may contain TransitionChoice objects. Each of these is tested (as appropriate), and if any TransitionChoice objects are found, then a user selection is driven.
To drive a user selection from a TransitionChoice, the driveChoice method on CDOM Object is called. This, in turn, triggers two actions:
- TransitionChoice driveChoice(): This method calculates the value in the Formula identifying the number of selections to be made, determines which of the objects contained within the Primitive Choice Set are allowed (based on the response of the Primitive Choice Set and the stacking settings in the TransitionChoice) and displays a Chooser dialog to the user.
- TransitionChoice act(): This method acts on the user selections made in the Chooser dialog displayed during the driveChoice method. The processing for the act call is delegated to the applyChoice method of the Choice Actor contained within the TransitionChoice.
History
This user selection process was added to PCGen in revision 5.16.
The user selection process was modified in PCGen 5.17.
