Defined in Window.Def Mixes in with Object
If you'll be using attribute steps to edit the data of any of your custom classes, you'll want to use the mixin EditAttributeClient. Your subclass doesn't have to inherit from class EditAttributeClient to use attribute steps, but inheriting does give the client more control over how it's edited.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
For an introduction to the complex topic of editing attributes with attribute steps, step lists, and windows, start with the chapter on class AttributeStepList. You will also find useful information in the chapters on classes AttributeStep and AttributeWindow.
You won't use any of the features of mixin EditAttributeClient directly, but you will see their effects when you use attribute windows. For example, any time an attribute step appears with a default value filled in for you, you're reaping the benefits of inheriting from EditAttributeClient.
Instantiate: never Subclass: often Call its methods: sometimes
The methods of class EditAttributeClient do nothing by default. To use this mixin, you'll have to override its methods. In particular, the two methods you're most likely to call and override are AcceptEdit and BeginEdit. BeginEdit allows you to set up a step before it appears to the user. AcceptEdit allows you to process the data the user has just entered and decide whether it's acceptable or not.
Whenever you create a subclass using class EditAttributeClient, you will override some or all of the following methods:
| Method | When to override |
|---|---|
| AcceptEdit | To return whether value of editor is acceptable (default is true) |
| BeginEdit | To set default value of attribute editor |
| Confirm | To do any processing on the accepted attribute data |
| NextStepList | To return the next attribute step list in an edit chain, if there is one |
| PreviousStepList | To return the previous attribute step list in an edit chain, if there is one |
Class EditAttributeClient defines no fields.
operation BeginEdit(editor: Viewable; otherEditor: Viewable; attributeNumber: Unsigned); Call: sometimes Override: often
Override BeginEdit to set the default value of the attribute editor. You can use this method to help your user fill in information if you can make good guesses about what that information will be.
The editor parameter is the control associated with the current step, which could be a text field or a control object. The otherEditor parameter is the control for any other step displayed with the current step in an attribute window, if another step exists. So for two-step attribute windows, the otherEditor parameter is useful. Otherwise, it's nilObject.
Class Telenumber uses its BeginEdit method to set up the attribute editor with some default values and good guesses about what the user is about to enter. Here's a code fragment showing part of what Telenumber_BeginEdit does:
ObjectID telephone = Telephone(self);
/* if there's already a number entered, we don't need to do
anything */
if (HasObject(telephone) && (TextLength(telephone) > 0))
return;
/* suggest the last area code entered */
if ((attributeNumber == operation_Telephone) &&
HasObject(iDefaultAreaCode))
{
ReplaceText(editor, iDefaultAreaCode);
return;
}
The system calls BeginEdit from AttributeWindow_SetUpStep. You probably won't call it yourself unless you are passing along a BeginEdit from your object to a subpiece of the object. For example, class PhoneLabel passes along a BeginEdit call from the phone label itself to the telenumber associated with the label:
ObjectID telenumber = Telenumber(self);
if (telenumber != nilObject)
BeginEdit(telenumber, editor, otherEditor,
attributeNumber);
operation AcceptEdit(editor: Viewable; otherEditor: Viewable; attributeNumber: Unsigned): Boolean Call: sometimes Override: often
Override AcceptEdit to return true if edits should be accepted, and false if they shouldn't. AcceptEdit returns true by default.
The method AttributeWindow_Confirm calls AcceptEdit and sets up its parameters. You're not likely to call it yourself, unless you pass along the AcceptEdit to another object. You'll do so if the piece of information being edited is not a part of your object itself, but belongs to a subpiece of your object.
The editor parameter is the control associated with the current step. The otherEditor is the control for the step displayed along with the current step in an attribute window, if one exists. So for two-step attribute windows, the otherEditor parameter might be useful. You might need to use both controls to determine whether the data is valid. For example, you might need to check both a credit card number and its expiration date. For one-step attribute windows, the otherEditor parameter will be nilObject.
This code fragment shows part of class AddressCard's override of AcceptEdit:
/* handle accepting names */
if (attributeNumber == operation_LastName)
return (TextLength(editor) > 0 ||
TextLength(otherEditor) > 0);
/* need some text in either field to accept */
/* handle accepting the first phone label */
if (((attributeNumber == operation_Telephone) ||
(attributeNumber == operation_Locale)) &&
telenumber != nilObject)
return AcceptEdit(telenumber, editor, otherEditor,
attributeNumber);
If the attribute being edited is the last name, AddressCard_AcceptEdit checks the last name text and the first name text. If either one has text in it, the name is okay and AcceptEdit returns true. Where did that first name come from? The attribute step that edits a last name is displayed in a two-step window with the first name step. So the otherEditor parameter will be the first name step.
If the attribute being edited is a phone label, AddressCard_AcceptEdit passes along the AcceptEdit request to the telenumber itself. If you call AcceptEdit, you'll do so in similar situations.
operation Confirm(), safe, common, noFail; Call: sometimes Override: often
The system calls Confirm from AttributeWindow_Confirm when accepting attribute data, after all the steps have been completed and the user has tapped the "done" button. Override Confirm to do any processing you need on the final attribute data.
For example, class AddressCard overrides Confirm to ask if the new address card should be the current user, if the system doesn't have a current user yet.
operation NextStepList(VAR attributeWindow: Window; lastEditor: Viewable; attributeNumber: Unsigned; currentStepList: Object; reallyStep: Boolean): Object Call: rarely Override: sometimes
Override NextStepList to chain attribute step lists together when you need to.
The lastEditor parameter is the control used to edit the current step. The attribute number is the attribute currently being edited. The currentStepList parameter is the attribute step list currently active.
The reallyStep parameter is true when the next step list should actually be traversed. reallyStep should be false if you're calling this method just to check for the existence of a next step list.
NextStepList should return the next attribute step list in the chain. If there is no next step list, it should return nilObject.
For example, the people picker allows users to add a new name to the name card stack, then immediately send a message or call that person. So class AddressCard overrides NextStepList to chain editing a new name to editing a new electronic mail label, or a new phone label.
The system calls NextStepList from two methods of class AttributeWindow: the GoToNext method, which determines if there's a step after the current step, and the SetUpStep method, which (among other things) determines whether the window should display a "next" button or a "done" button. You are not likely to call NextStepList yourself.
operation PreviousStepList(VAR attributeWindow: Window; currentStepList: Object; reallyStep: Boolean) : Object; Call: rarely Override: sometimes
PreviousStepList is much like NextStepList, only it returns the previous step list in a chain instead of the next.