List Group Interface. An instance of this object is created for each set of objects that are to be grouped together.

class ListGroup :   object

Superclass Tree   (in declaration order)


Subclass Tree  


Global Objects  


Summary of Properties  

groupDisplaysSublist  minGroupSize 

Summary of Methods  

createGroupSublister  groupCardinality  groupNounPhraseCount  showGroupItem  showGroupItemCounted  showGroupList 



Determine if showing the group list will introduce a sublist into an enclosing list. This should return true if we will show a sublist without some kind of grouping, so that the caller knows to introduce some extra grouping into its enclosing list. This should return nil if the sublist we display will be clearly set off in some way (for example, by being enclosed in parentheses).

The minimum number of elements for which we should retain the group in a listing. By default, we need two elements to display a group; any group with only one element is discarded, and the single element is moved into the 'singles' list. This can be overridden to allow single-element groups to be retained. In most cases, it's undesirable to retain single-element groups, but when grouping is used to partition a list into two or more fixed portions, single-element groups become desirable.


createGroupSublister (parentLister)lister.t[1999]

Create the group sublister.

In most cases, when a group displays a list of the items in the group as a sublist, it will not want to use the same lister that was used to show the enclosing group, because the enclosing lister will usually have different prefix/suffix styles than the sublist. However, the group list and the enclosing list might share many other attributes, such as the style of name to use when displaying items in the list. The default sublister we create, GroupSublister, is a hybrid that uses the enclosing lister's attributes except for a few, such as the prefix and suffix, that usually need to be changed for the sublist.

This can be overridden to use a completely customized Lister object for the group list, if desired.

groupCardinality (lister, lst)lister.t[1968]
Determine the cardinality of the group listing, grammatically speaking. This is the number of items that the group seems to be for the purposes of grammatical agreement. For example, if the group is displayed as "$1.38 in change", it would be singular for grammatical agreement, hence would return 1 here; if it displays "five coins (two copper, three gold)," it would count as five items for grammatical agreement.

For languages (like English) that grammatically distinguish number only between singular and plural, it is sufficient for this to return 1 for singular and anything higher for plural. For the sake of languages that make more elaborate number distinctions for grammatical agreement, though, this should return as accurate a count as is possible.

By default, we return the number of items to be displayed in the list group. This should be overridden when necessary, such as when the group message is singular in usage even if the list has multiple items (as in "$1.38 in change").

groupNounPhraseCount (lister, lst)lister.t[1980]
Get the number of noun phrases this group will display. This differs from the cardinality in that it doesn't matter how many *objects* the phrases represent; it only matters how many phrases are displayed. For example, "five coins" has cardinality 5 but only displays one noun phrase.

By default, we simply return the number of items in the group, since most groups individually list their items.

showGroupItem (sublister, obj, options, pov, infoTab)lister.t[1909]
Show an item in the group's sublist. The sublister calls this to display each item in the group when the group calls the sublister to display the group list. By default, we simply let the sublister handle the request, which gives items in our group sublist the same appearance they would have had in the sublist to begin with. We can customize this behavior to give our list items a different appearance special to the group sublist.

Note that the same customization could be accomplished by creating a specialized subclass of GroupSublister in createGroupSublister(), and overriding showListItem() in the specialized GroupSublister subclass. We use this mechanism as a convenience, so that a separate group sublister class doesn't have to be created simply to customize the display of group items.

showGroupItemCounted (sublister, lst, options, pov, infoTab)lister.t[1919]
Show a counted item in our group list. This is the counted item equivalent of showGroupItem.

showGroupList (pov, lister, lst, options, indent, infoTab)lister.t[1890]
Show a list of items from this group. All of the items in the list will be members of this list group; we are to display a sentence fragment showing the items in the list, suitable for embedding in a larger list.

'options', 'indent', and 'infoTab' have the same meaning as they do for showList().

Note that we are not to display any separator before or after our list; the caller is responsible for that.

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3