---

ISyncUIHelper Protocol Reference

Overview

ISyncUIHelper is an informal protocol that an object implements to provide presentation details for custom schemas to the iSync user interface. If you created a custom sync schema and want more control over the display of your records in the iSync user interface—specifically, the data change alert and conflict resolver user interfaces—then add a class that implements this protocol to your schema bundle.

You specify the class that conforms to this protocol in the sync schema using the UIHelperClass key. When the sync schema bundle is loaded, an instance of the UIHelperClass class is created to handle the presentation requests. The UIHelperClass class must inherit from NSObject or one of its subclasses. The methods in this protocol are optional.

Implement the attributedStringForPropertiesWithNames:... method to change the presentation of individual records. Implement the attributedStringForIdentityPropertiesWithNames:... method to change the presentation of a custom schema above the record in the user interface. For example, return an NSAtrributedString object with a picture using NSTextAttachement or color the text.

Read Creating a Sync Schema in Sync Services Programming Guide for a complete description of a sync schema.

Tasks

Customizing the Presentation of Schemas and Records

• – attributedStringForPropertiesWithNames:inRecord:comparisonRecords:defaultAttributes:
• – attributedStringForIdentityPropertiesWithNames:inRecord:comparisonRecords:firstLineAttributes:secondLineAttributes:

Instance Methods

attributedStringForIdentityPropertiesWithNames:inRecord:comparisonRecords:firstLineAttributes:secondLineAttributes:

Provides a custom presentation of a schema to the data change alert and conflict resolver user interfaces.

- (NSAttributedString *)attributedStringForIdentityPropertiesWithNames:(NSArray *)propertyNames inRecord:(NSDictionary *)record comparisonRecords:(NSArray *)comparisonRecords firstLineAttributes:(NSDictionary *)firstLineAttributes secondLineAttributes:(NSDictionary *)secondLineAttributes

Parameters

propertyNames

The names of the identity properties of record.

record

The record to be displayed.

comparisonRecords

An array of record dictionaries. The records are those displayed alongside this record in the user interface. If the data change alert invokes this method, this array always contains 0 or 1 records—0 if the type of change is an add or delete and 1 if the type of change is a modify. If the conflict resolver invokes this method, the array contains n-1 records where n is the number of clients involved in the conflict including this client.

firstLineAttributes

The recommended NSAttributedString attributes to apply to the first line of the returned attributed string.

secondLineAttributes

The recommended NSAttributedString attributes to apply to the second line of the returned attributed string.

Return Value

An NSAttributedString object for display of a schema in the data change alert or conflict resolver user interface.

The object returned should contain two lines. The first line should have the recommended attributes specified by firstLineAttributes, and the second line should have the attributes specified by secondLineAttributes.

If this method returns a value other than nil when multiple names are in propertyNames, the returned string is used to represent all the identity properties. Only one value is displayed for all the properties, next to the localized display name of the first property.

If this method returns nil when propertyNames contains more than one property, this method is invoked once for each identity property in propertyNames.

Availability

• Available in Mac OS X v10.5 and later.

attributedStringForPropertiesWithNames:inRecord:comparisonRecords:defaultAttributes:

Provides a custom presentation of a record to the data change alert and conflict resolver user interfaces.

- (NSAttributedString *)attributedStringForPropertiesWithNames:(NSArray *)propertyNames inRecord:(NSDictionary *)record comparisonRecords:(NSArray *)comparisonRecords defaultAttributes:(NSDictionary *)defaultAttributes

Parameters

propertyNames

The names of the properties of record to be displayed.

This array contains only one property name unless the property has dependent properties as defined in the schema. If it has dependent properties, the property along with its dependent property names is in this array.

record

The record to be displayed.

comparisonRecords

An array of record dictionaries. The records are those displayed along side this record in the user interface. If the data change alert invokes this method, this array always contains 0 or 1 records—0 if the type of change is an add or delete and 1 if the type of change is a modify. If the conflict resolver invokes this method, the array contains n-1 records where n is the number of clients involved in the conflict including this client.

defaultAttributes

The recommended NSAttributedString attributes that should be applied to the returned NSAttributedString object.

Return Value

An NSAttributedString object for display of a record in the data change alert or conflict resolver user interface.

If the length of the NSAttributedString object is greater than 0, the string is displayed as is. If the length of the NSAttributedString object equals 0, the standard localized string for properties with no value is displayed. If this method returns nil, the default string is used.

If this method returns a value other than nil when multiple names are in propertyNames, the returned string is used to represent all the dependent properties. Only one value is displayed for all the properties, next to the localized display name of the first property.

If this method returns nil when propertyNames contains more than one property, this method is invoked once for each dependent property in propertyNames.

Availability

• Available in Mac OS X v10.5 and later.

---