Defined in Window.Def Inherits from ObjectList
You'll use attribute step lists to manage the Magic Cap system's user interface for step-by-step information entry. An attribute step list object is a sequential list of steps, each of which asks your user for one piece of information. The steps are displayed one or two at a time in an attribute window.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
You'll find the chapters on class AttributeStep and class AttributeWindow invaluable in creating your own attribute step lists. The chapter on class EditAttributeClient describes how you can create classes that control how they're edited by attribute step lists.
To construct an attribute step list, you need the following pieces:
First, you'll need a way to connect the object you want to edit with the attribute step list that edits it. There are a number of ways to do so. For example, class AddressLabel defines an attribute, EditSteps:
attribute EditSteps : ObjectList;
The get method for this attribute returns the indexical of the appropriate step list. This technique is useful if the same attribute step list can be used to edit every object of your class.
If the object you're editing is of a class you've created, you should consider mixing in class EditAttributeClient with your custom class. Class EditAttributeClient gives you control over how attribute steps edit your object.
Next, you need a way to launch the attribute steps and display the attribute window. The method AttributeStepList_EditAttribute is the method that does this for you. You could call this method when a button is tapped, as class AddressCard does. It uses a special action button to create new name cards. See the description of the EditAttribute method for an example of how you might similarly override the Action method of a button. Or you could call EditAttribute whenever the user touches the object you want to edit.
Next, create your steps by adding AttributeStep objects to your object definition file. For more information on attribute steps, see the chapter on class AttributeStep.
Now you're ready to create an attribute step list. Do so by adding an instance to your object definition file and writing an entry field for each step. For example, here's the attribute list used to edit the postal address on a name card:
Instance AttributeStepList 4582;
length: 6;
attributeWindow: iTwoStepAttributeWindow;
entry: nilObject;
entry: (AttributeStep 'Street address' 4591);
entry: (AttributeStep 'City' 4569);
entry: (AttributeStep 'City and State' 4571);
entry: (AttributeStep 'zip code' 4573);
entry: (AttributeStep 'Postal code' 8228);
End Instance;
This attribute step list uses a two-step window, which displays the steps two at a time. If all the steps in your list should be displayed one at a time, use a one-step attribute window. (See the chapter on class AttributeWindow for a list of available windows and information on constructing a custom window.) Here's how a typical one-step window appears:
You can also use a two-step attribute window to display one step at a time. Pad your step list with nil entries, like the following list (used to fill in a work address):
Instance AttributeStepList 4525;
length: 10;
attributeWindow: iTwoStepAttributeWindow;
entry: nilObject;
entry: (AttributeStep 'Job title' 4523);
entry: nilObject;
entry: (AttributeStep 'Company name' 4521);
entry: nilObject;
entry: (AttributeStep 'Street address' 4591);
entry: (AttributeStep 'City' 4569);
entry: (AttributeStep 'City and State' 4571);
entry: (AttributeStep 'zip code' 4573);
entry: (AttributeStep 'Postal code' 8228);
End Instance;
The `Job Title,' `Company name,' and `Street address' steps are each displayed alone in individual steps, while the `City' and `City and State' steps appear together in one step. Here is how the `Job Title' step appears to the user:
And here are the `City' and `City and State' steps together:
The pad step should always be the odd-numbered stepthat is, the top step should be the pad, and the bottom step the real McCoy.
When a step appears by itself, you can use a longer text prompt, since the space normally occupied by the top step is available for text display. Here's an example of a longer text prompt, from the "Street Address" step:
Instance Text 4592;
text: 'Fill in the street address:';
End Instance;
You don't need to do anything special to display the text prompt in the vacated space.
Instantiate: often Subclass: rarely Call its methods: sometimes
You'll probably never subclass class AttributeStepList. You'll call the methods EditAttribute or EditAttributeFromOrigin often.
Class AttributeStepList defines the following methods:
| Method | Description |
|---|---|
| AttributeWindow | Get the step list's attribute window |
| SetAttributeWindow | Set the step list's attribute window |
| EditAttribute | Set up the attribute window and display it |
| EditAttributeFromOrigin | Call EditAttribute using the origin of fromobject as the spout position |
Class AttributeStepList defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from AbstractList | ||
| length | Unsigned | The number of steps in the list |
| Defined by AttributeStepList | ||
| attributeWindow | AttributeWindow | The attribute window used |
operation EditAttribute(target: Object; redrawObject: Viewable; position: Dot), noFail Call: often Override: never
Call EditAttribute to launch the process of editing an object with attribute steps. The target parameter is the object to be edited. The redrawObject parameter is a viewable object that should be notified of the edits and redrawn. And the position parameter is used as the spout position for the attribute window that displays the steps.
EditAttribute sets up the attribute window by setting its spout position and its target, then calling SetUpStep for the first step. It then displays the window, and the user can begin entering information.
Here's an example of how you might call EditAttribute from the Action method of a button:
target = Target(self);
steps = EditSteps(target);
if (steps != nilObject)
{
Dot pos;
Box content;
ContentBox(target, &content);
pos.h = content.left + 80*onePixel;
pos.v = content.top + 32*onePixel;
EditAttribute(steps, target, target, &pos);
}
In this example, target is the object to be edited. (This particular button class would have to inherit from HasTarget.) The target to be edited has an attribute, EditSteps. The EditSteps getter method returns the step list to use to edit the target. The top left corner of the target's content box plus a fudge factor is used as the position of the attribute window. The object to be redrawn after the edits are complete is the target itself.
Here's how class LocationListView uses EditAttribute to edit a phone location:
EditAttribute(editSteps, Selected(self), self, &origin);
The currently selected location is the object to be edited, but the location list view itself is the object that'll need to be redrawn afterward.
If you don't need to have the attribute editing process redraw anything for you, you can use nilObject as your redraw object.
operation EditAttributeFromOrigin(target: Object; redrawObject: Viewable; fromObject: Viewable), safe, noFail Call: sometimes Override: never
Call EditAttributeFromOrigin instead of EditAttribute if you'd like to use the origin of the fromObject parameter as the spout position, instead of computing a spout position yourself.
Here's how you might rewrite the example above to use EditAttributeFromOrigin instead of EditAttribute:
target = Target(self);
steps = EditSteps(target);
if (steps != nilObject)
{
EditAttributeFromOrigin(steps, target, target, target);
}