The external interface consists of the showList() method, which displays a formatted list of objects according to the rules of the lister subclass.
The rest of the methods are an internal interface which lister subclasses can override to customize the way that a list is shown. Certain of these methods are meant to be overridden by virtually all listers, such as the methods that show the prefix and suffix messages. The remaining methods are designed to allow subclasses to customize detailed aspects of the formatting, so they only need to be overridden when something other than the default behavior is needed.
Lister : object
Note that this only matters for objects listed in the top-level list. We'll always show the contents separately for an object that isn't listed in the top-level list (i.e., an object for which isListed(obj) returns nil).
'groupTab' is an empty LookupTable, and 'groups' is an empty Vector; we'll populate these with the grouping information. 'singles' is an empty Vector that we'll populate with the single items not part of any group.
The group list returned is in order from most general to most specific. For example, if an item is grouped with coins in general and silver coins in particular, the general coins group would come first, then the silver coin group, because the silver coin group is more specific.
'pov' is the point of view, which is usually an actor (and usually the player character actor).
'obj' is the item whose contents we are to display.
'options' is the set of flags that we'll pass to showList(), and has the same meaning as for that function.
'infoTab' is a lookup table of SenseInfo objects giving the sense information for all of the objects that the actor to whom we're showing the contents listing can sense.
'pov' is the point of view of the listing, which is usually an actor (and usually the player character actor).
'parent' is the parent (container) of the list being shown. This should be nil if the listed objects are not all within a single object.
'lst' is the list of items to display.
'options' gives a set of ListXxx option flags.
'indent' gives the indentation level. This is used only for "tall" lists (specified by including ListTall in the options flags). An indentation level of zero indicates no indentation.
'infoTab' is a lookup table of SenseInfo objects for all of the objects that can be sensed from the perspective of the actor performing the action that's causing the listing. This is normally the table returned from Thing.senseInfoTable() for the actor from whose point of view the list is being generated. (We take this as a parameter rather than generating ourselves for two reasons. First, it's often the case that the same information table will be needed for a series of listings, so we can save the compute time of recalculating the same table repeatedly by having the caller obtain the table and pass it to each lister. Second, in some cases the caller will want to synthesize a special sense table rather than using the actual sense information; taking this as a parameter allows the caller to easily customize the table.)
'parentGroup' is the ListGroup object that is showing this list. We will not group the objects we list into the parent group, or into any group more general than the parent group.
This routine is not usually overridden in lister subclasses. Instead, this method calls a number of other methods that determine the listing style in more detail; usually those other, simpler methods are customized in subclasses.
'lst' is the full list of equivalent items. By default, we pick one of these arbitrarily to show, since they're presumably all the same for the purposes of the list.
'lst' is the entire list, which some languages need for grammatical agreement. This is passed as a named argument, so an overrider can omit it from the parameter list if it's not needed.
This will never be called with an itemCount of zero, because we will instead use showListEmpty() to display an empty list.
This generic routine is further parameterized by properties for the individual types of separators. This default implementation distinguishes the following separators: the separator between the two items in a list of exactly two items; the separator between adjacent items other than the last two in a list of more than two items; and the separator between the last two elements of a list of more than two items.
'prevCnt' is the number of items already displayed, if anything has already been displayed for this list. This should be zero if this will display the entire list.
For each item in the given list, we show the item's contents if the item is either marked as unlisted, or it's marked as showing its contents separately. In the former case, we know that we cannot have shown the item's contents in-line in the main list, since we didn't show the item at all in the main list. In the latter case, we know that we didn't show the item's contents in the main list because it's specifically marked as showing its contents out-of-line.