Book Contents Previous Chapter Next Chapter
This chapter describes Magic Cap lists, a family of classes that allows you to organize groups of similar objects together. Before reading this chapter, you should be familiar with Magic Cap's object runtime.
This section introduces the list family of classes and describes some of the most important members of the family.
Magic Cap provides a family of list classes that manages arbitrary collections of data elements in ordered lists. Magic Cap defines many different list classes, which you can use as object-oriented substitutes for arrays in your packages.
Most of the list classes defined by Magic Cap descend from class AbstractList, an abstract class that defines the basic behavior of a collection of data elements in an ordered list. Class AbstractList descends directly from class Object and provides the foundation for Magic Cap's large family of more specialized list classes. Note that although class AbstractList itself is descended from class Object, the data elements belonging to the list need not be objects themselves.
Magic Cap defines class FixedList as the ultimate ancestor for all list classes that have elements that are all the same size. Virtually all list classes fall into this category.
Class FixedList assumes that all list elements are exactly four bytes long. Because this assumption is correct for many list subclasses, those subclasses descend directly from FixedList. Other list classes have elements that are all the same size, but that size may be something other than four bytes. Magic Cap defines class DataList, a subclass of FixedList, for these classes. Objects of class DataList can have elements of any size, although all elements of a particular list must be the same size.
Because most lists have elements that are all the same size, virtually all list classes in Magic Cap descend from class FixedList.
The size of a single element in a list is called the stride of the list. Various list operations depend on the stride. For example, operations that access an element by its index or that iterate over all list elements use the list's stride to perform their action. Class FixedList defines the concept of a list stride and also defines the operations that require a stride.
Magic Cap includes an important list class, ObjectList, which defines lists that contain objects as their elements. Each object list is an ordered collection of data elements, and each element is a 4-byte object ID. Class ObjectList defines the behavior of such lists and provides the foundation for many other list classes that inherit its capabilities.
Like all lists in Magic Cap, an object list arranges its elements in a well-known order. You can access any element if you know its index, which is an integer value indicating the element's position in the list. The index numbering is one-based. That is, the first element in the list has index value 1, not 0. The list also keeps track of the index of its current element, which is the last one accessed or returned by an operation call.
The distinguishing characteristic of an object list is that all of its elements are object IDs. The objects in the list need not all belong to the same class. For example, the window that appears when you tinker with an object on the screen includes switches, meters, text field objects, other lists, and more. All of these diverse objects are elements of a single object list.
Many of the list family's classes descend from class ObjectList.
This section describes the features of list objects that you can use when you create your own lists or when you operate on system list objects. Unless otherwise noted, all the operations and attributes described in this section are defined by class AbstractList.
You can use the Length or Count operations to find out how many elements are in the list (the two operations are identical). Call SetCount to change the number of elements in the list. If SetCount adds elements, the new elements are set to zero. Call SetLength to change the number of elements in the list at a lower level than SetCount. Calling SetLength merely changes the value in the list's length field to the given value.
Magic Cap provides operations that return particular elements in the list. Note that class AbstractList only defines operations to get the first and last elements. Operations to get a particular element given its index position are defined by subclasses. See the Fixed Lists section below for more information about getting elements in the list.
You can call FirstElem to get the first element in the list, or LastElem to get the last element.
This section describes operations that add elements to the list and remove them from the list.
You can call AddElemFirst to add a given element to the beginning of the list, moving all existing elements back one position. Call AddElemLast to add a new element after the end of the list, making the new element the last one in the list.
Call AddUniqueElem to add an element to a list only if it is not already there. If the list does not already contain an element with the given value, one is added at the end of the list, following the last existing element. If an element with the specified value already exists, AddUniqueElem has no effect on the list.
Call RemoveElem to remove a given element from the list. All elements following the one being removed are moved forward one position in the list. You can call Clear to set the list's count to zero, effectively emptying the list of its elements.
Magic Cap lists define operations that allow you to iterate over all the members of the list to perform some operation. Because iterative operations only work on lists whose elements are all the same size, the operations in this section are defined by class FixedList.
You can call EachElem to apply a given function to every member in the list. When you call EachElem, you pass the function that should be called for each list member, along with any parameters that you want to pass to the function.
You can call EachElemAfter to call a given function for every member in the list located after a given index. You pass the function to be called and any parameters that you want to pass to the function.
Call EachExtraField to apply a function to every field of extra data in the fixed list. This operation provides a convenient way to perform some action for all extra data items in a list.
This section describes operations that let you search through a list for a member containing a particular value. Note that operation FindElem is defined in class AbstractList and so is available in all list classes, while operation FindElemAfter is defined in class FixedList.
You can call FindElem to search the list for an element that matches a given value. FindElem returns the index of the first element in the list with the given value, or zero if no such element is found.
Call FindElemAfter to look through the list for an element that matches a given value, starting at a given index value. FindElemAfter returns the index of the first element in the list after the given position that contains the given value, or zero if no matching element is found.
Magic Cap defines class FixedList as the ultimate ancestor for all list classes that have elements that are all the same size.
The size of a single element in a list is the list's stride. Class FixedList defines the concept of a list stride and also defines the operations that require a stride.
Class FixedList defines operations for adding and removing elements that you can use in addition to the ones defined by class AbstractList. You can call AddElemAt to add a list element at a given index position. Call RemoveAt to delete any given element.
You can replace an existing element with another by calling ReplaceElemAt. When you call ReplaceElemAt, you pass a pointer to the new element and the index of the element to be replaced.
Call Roll if you want to shift some or all of the elements in the list up or down a given number of positions. When you call Roll, you pass the number of elements you want to shift and the number of positions you want to shift them.
Class FixedList defines various operations for getting elements that you can use in addition to the ones defined by class AbstractList. You can call ElementAt to get a list element at the given index position.
Call ElementValue to get the value of a list element, given a pointer to the element in the list. If you want to get the value of a list element and you have the index number of the element, you can call ValueAt, which returns the value of the given element.
You can call Stride to get the size of each element in the list.
Class FixedList assumes that all list elements are exactly four bytes long. Some list classes have elements that are all the same size, but that size may be a value other than four bytes. Magic Cap defines class DataList, a subclass of FixedList, for these classes. Objects of class DataList can have elements of any size, although all elements of a particular list must be the same size.
Objects of class DataList use the Stride attribute to determine the size of each element. Stride is actually defined by class FixedList to always return 4. Class DataList overrides the implementation of Stride to return the value from the list's stride field.
Magic Cap includes an important list class, ObjectList, which defines lists that contain objects as their elements. Each object list is an ordered collection of data elements, and each element is a 4-byte object ID. Class ObjectList defines the behavior of such lists and provides the foundation for many other list classes that inherit its capabilities.
Like all lists in Magic Cap, an object list arranges its elements in a well-known order. You can access any element if you know its index, which is an integer value indicating the element's location within the list. The index numbering is one-based. That is, the first element in the list has index value 1, not 0. The list also keeps track of the index of its current element, which is the last one accessed or returned by an operation call.
All of the elements of an object list are object IDs, but the objects in the list need not all belong to the same class.
For more information, see the following topics in Magic Cap Class and Method Reference:
class AbstractList
operations and attributes:
AddElemFirst AddElemLast Clear Count FindElem FirstElem LastElem Length RemoveElem SetCount
SetLength
class FixedList
operations and attributes:
AddElemAt EachElem EachElemAfter EachExtraField ElementAt ElementValue FindElemAfter RemoveAt ReplaceElemAt Roll Stride
ValueAt
class DataList
class ObjectList
Book Contents Previous Chapter Next Chapter