Book Contents Previous Chapter Next Chapter
This chapter describes two of the most fundamental families of classes defined by Magic Cap: linkable objects that are part of a chain of objects, such as a view chain, and arrays, indexed collections of elements. Before reading this chapter, you should be familiar with viewables.
Although this chapter describes linkables and arrays, those two class families are not related in any particular way. They are combined in this chapter for convenience because they are both fundamental data structures commonly used in Magic Cap.
This section describes the features of linkable objects.
Objects of class Linkable can be connected in a doubly-linked list. Many Magic Cap objects are linkable, including all viewable objects, because class Viewable inherits from class Linkable. Some operations defined by class Linkable are commonly used and are described in this chapter.
Every linkable object refers to the next and previous objects in the list. The first element has nilObject as its previous object, and the last element in the list has nilObject for its next object. The objects in the list are arranged so that the list is linear. That is, each object can be linked to no more than two other objects: it can be the previous object of one and the next object of another.
Note that although linkable objects are connected to form a list, there's no object that represents the list itself. All manipulation of the list is done by working with its elements, the linkable objects themselves.
Class Linkable is abstract, so you'll never directly instantiate a linkable object, and you probably won't ever create a direct subclass of it. Instead, you'll probably create a subclass of one of the built-in linkable subclasses.
All viewable objects are linkable, and class Linkable implements the basic features of view lists, which are lists of visible objects. For more information, see this book's Viewables and Touching chapter.
You can use linkable operations to add objects to the list, remove objects from the list, or change the way the objects are connected in the list.
This section describes common operations you might call that are defined by class Linkable
Class Linkable provides operations that let you add and remove list elements. Because there is no single object that represents the list, these operations act upon the list that the responder (the self parameter) belongs to.
You can call AddAfter to add a new object to the list in the position immediately following the responder. Call AddBefore to add the given object to the list in the position immediately preceding the responder. You can call AddFirst to add the given object to the head of the list, or call AddLast to make the object the last one in the list.
You can call Remove to delete the given object from the list.
Class Linkable provides operations that return the first and last objects in the list. Call First to get the object at the head of the list and Last to get the object at the tail.
You can call operations that let you move through the list, getting objects before and after the responder. Call Previous to get the object immediately before the responder in the list, or call Next to get the object immediately after the responder.
You can call At to get the object at a given position in the list. The first object in the list is at position 1; there is no position zero.
Call Count to determine the number of objects in the list that the responder belongs to.
You can call Each if you want to invoke a function repeatedly for every member of the list. If you call Each, you must also define the iterative function to be called for each list object, then pass a pointer to this function in the proc parameter. If you want to send any parameters to your iterative function, pass a pointer to the parameters in params when you call Each.
Each keeps calling the iterative function as long as the iterative function returns nilObject and there are still objects in the list that have not been processed. When the iterative function returns an object ID, Each stops calling the iterative function and exits. This feature is useful if you want to stop iterating when your iterative function fulfills some condition, such as successfully completing a search.
The routine that's called for each member of the list should be declared like this:
Private ObjectID IterativeProc (ObjectID theObject, void *params)
WARNING: You must use the Private specifier when you declare your iterative function. If you fail to do so, you'll get no warning from any tools during the build process, but your package will fail in an unpredictable way.
The theObject parameter contains the list element that is currently being processed. Each passes the params parameter unchanged each time IterativeProc is called.
For more information on the Each operation, see the Contexts and Callback Functions section in this book's Object Runtime chapter.
Magic Cap defines many significant subclasses of class Linkable. The most important subclasses is Viewable, making all viewable objects linkables as well. In addition, class Image is a subclass of Linkable, which allows images to be linked in lists.
For much more information on viewables, see this book's Viewables and Touching chapter.
This section describes class Array, defined by Magic Cap to represent indexed groups of elements.
Magic Cap uses objects of class Array to hold indexed runs of same-size elements. Class Array is most prominently used in Magic Cap as the parent of the text formatter classes.
Class Array provides the fundamental behavior for classes that represent indexed collections of elements that are all the same size. You'll rarely instantiate any objects of class Array. Instead, you'll instantiate and use objects created from concrete array subclasses.
This section describes the operations you might call that are defined by class Array.
This section describes operations you can call to perform some action on the entire array, such as removing all its elements, copying them to another array, or replacing them with other data.
You can call Clear or DeleteElems to empty the array by setting its length to zero. Both Clear and DeleteElems perform exactly the same action. DeleteElems is provided in case you want to create a subclass of array and perform some additional action when the array is emptied, such as deleting the elements themselves. To perform this additional action, override DeleteElems in your array subclass.
You can call CopyElems to create a new array and copy all the elements to the newly created array.
Call ReplaceElems to replace all the elements in the array with another array of elements. You pass the new array of elements as a parameter when you call ReplaceElems.
You can call ReplaceElemsWithData to replace all the elements of the array with data elements that aren't already in an array. You pass a parameter that points to the data you want to replace the current array elements when you call ReplaceElemsWithData.
This section describes operations you can call to perform some action on a subset of the elements in the array, such as removing some of its elements, copying some elements to another array, or replacing some elements with other data.
Many of the operations in this section take a parameter of type ArrayRange, which specifies the elements in the array that will be used by the operation. Magic Cap defines type ArrayRange (and a related type, ArrayPoint) as follows:
typedef ulong ArrayPoint;
typedef struct
{
ArrayPoint start;
ulong length;
} ArrayRange;
You can call DeleteElemRange to empty some of the elements of the array by setting their values to zero. Pass the range of elements to be emptied when you call DeleteElemRange.
Call CopyElemRange to create a new array and copy some of its elements to the newly created array. Pass the range of elements to be copied when you call CopyElemRange. The newly created array is passed back as the function return value.
Call ReplaceElemRange to replace some of the elements in the array with all the elements from another array. Pass the range of elements to be replaced and the new array of elements as parameters when you call ReplaceElemRange.
You can call ReplaceElemData to copy elements into the array from some other data structure. Pass a parameter that points to the bytes to be copied into the array and another parameter that specifies how many elements to move. The copied elements replace the elements in the specified range, and the old elements at those locations are lost.
Call FillWithBytes to fill a specified range in the array with a given pattern of bytes. Pass parameters that point to the bytes to be inserted, the length of the pattern of bytes, and the range in the array to be filled.
You can call CopyToBytes to copy a range of elements from the array to another data structure. Pass parameters that indicate which elements to copy and where they should be copied.
This section describes operations you can call to insert and append new elements to the array.
You can call AppendElems to add all the elements of another array to the end of the responder. Pass the array containing elements to be appended as a parameter. The new elements are added to the array following its last element.
You can call InsertElems to insert all the elements of another array into the responder. Pass as parameters the array containing elements to be inserted and the array point at which the elements will be inserted.
Call AppendData to add data from another data structure to the end of the responder. Pass a pointer to the elements to be appended as a parameter when you call AppendData. The new elements are added to the array following its last element.
Call InsertData to insert data from another data structure into the responder. Pass as parameters a pointer to the data to be inserted and the array point at which the data will be inserted.
For more information, see the following topics in Magic Cap Class and Method Reference:
class Linkable
operations and attributes:
AddAfter AddBefore AddFirst AddLast Count Each First GetAt Last Next Previous
Remove
class Array
operations and attributes:
AppendData AppendElems Clear CopyElemRange CopyElems CopyToBytes DeleteElemRange DeleteElems FillWithBytes InsertData InsertElems ReplaceElemData ReplaceElemRange ReplaceElems
ReplaceElemsWithData
Book Contents Previous Chapter Next Chapter