iOS Developer Library

Developer

UIKit Framework Reference UILocalizedIndexedCollation Class Reference

Options
Deployment Target:

On This Page
Language:

UILocalizedIndexedCollation

The UILocalizedIndexedCollation class is a convenience for organizing, sorting, and localizing the data for a table view that has a section index. The table view’s data source then uses the collation object to provide the table view with input for section titles and section index titles.

Table views with section indexes are ideal for displaying and facilitating the access of data composed of many items organized by a sequential ordering scheme such as the alphabet. Users tap an index title to jump to the corresponding section. The initial table view of the Phone/Contacts application on the iPhone is an example. Note that the section titles can be different than the titles of the index.

To prepare the data for a section index, your table-view controller creates a indexed-collation object and then, for each model object that is to be indexed, calls sectionForObject:collationStringSelector:. This method determines the section in which each of these objects should appear and returns an integer that identifies the section. The table-view controller then puts each object in a local array for its section. For each section array, the controller calls the sortedArrayFromArray:collationStringSelector: method to sort all of the objects in the section. The indexed-collation object is now the data store that the table-view controller uses to provide section-index data to the table view, as illustrated in Listing 1.

Listing 1Data source using indexed-collation object to provide data to table view

Swift

  • func tableView(tableView: UITableView!, titleForHeaderInSection section: Int) -> String! {
  • let currentCollation = UILocalizedIndexedCollation.currentCollation() as UILocalizedIndexedCollation
  • let sectionTitles = currentCollation.sectionTitles as NSArray
  • return sectionTitles.objectAtIndex(section) as String
  • }
  • func sectionIndexTitlesForTableView(tableView: UITableView!) -> NSArray! {
  • let currentCollation = UILocalizedIndexedCollation.currentCollation() as UILocalizedIndexedCollation
  • return currentCollation.sectionIndexTitles as NSArray
  • }
  • func tableView(tableView: UITableView!, sectionForSectionIndexTitle title: String!, atIndex index: Int) -> Int {
  • let currentCollation = UILocalizedIndexedCollation.currentCollation() as UILocalizedIndexedCollation
  • return currentCollation.sectionForSectionIndexTitleAtIndex(index)
  • }

Objective-C

  • - (NSString *)tableView:(UITableView *)tableView titleForHeaderInSection:(NSInteger)section
  • {
  • return [[[UILocalizedIndexedCollation currentCollation] sectionTitles] objectAtIndex:section];
  • }
  • - (NSArray *)sectionIndexTitlesForTableView:(UITableView *)tableView
  • {
  • return [[UILocalizedIndexedCollation currentCollation] sectionIndexTitles];
  • }
  • - (NSInteger)tableView:(UITableView *)tableView sectionForSectionIndexTitle:(NSString *)title atIndex:(NSInteger)index
  • {
  • return [[UILocalizedIndexedCollation currentCollation] sectionForSectionIndexTitleAtIndex:index];
  • }

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.0 and later.
  • Returns a indexed-collation instance for the current table view.

    Declaration

    Swift

    class func currentCollation() -> AnyObject!

    Objective-C

    + (id)currentCollation

    Return Value

    A UILocalizedIndexedCollation object or nil if there was a problem creating the object.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns an integer identifying the section in which a model object belongs.

    Declaration

    Swift

    func sectionForObject(_ object: AnyObject, collationStringSelector selector: Selector) -> Int

    Objective-C

    - (NSInteger)sectionForObject:(id)object collationStringSelector:(SEL)selector

    Parameters

    object

    A model object of the application that is part of the data model for the table view.

    selector

    A selector that identifies a method returning an identifying string for object that is used in collation. The method should take no arguments and return an NSString object. For example, this could be a name property on the object.

    Return Value

    An integer that identifies the section in which the model object belongs. The numbers returned indicate a sequential ordering.

    Discussion

    The table-view controller should iterate through all model objects for the table view and call this method for each object. If the application provides a Localizable.strings file for the current language preference, the indexed-collation object localizes each string returned by the method identified by selector. It uses this localized name when collating titles. The controller should use the returned integer to identify a local “section” array in which it should insert object.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Sorts the objects within a section by their localized titles.

    Declaration

    Swift

    func sortedArrayFromArray(_ array: [AnyObject], collationStringSelector selector: Selector) -> [AnyObject]

    Objective-C

    - (NSArray *)sortedArrayFromArray:(NSArray *)array collationStringSelector:(SEL)selector

    Parameters

    array

    An array containing the model objects for a section.

    selector

    A selector that identifies a method returning an identifying string for each object in array. The index-collation object uses this string for sorting the objects in the array. The method should take no arguments and return an NSString object. For example, this could be a name property on the object.

    Return Value

    A new array containing the items in array), sorted.

    Discussion

    The table-view controller creates the array of objects for a section (array) as part of iterating through its model objects with calls to the sectionForObject:collationStringSelector: method. This method should be called on each local section array.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns the list of section titles for the table view. (read-only)

    Declaration

    Swift

    var sectionTitles: [AnyObject] { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *sectionTitles

    Discussion

    This property contains the localized list of section titles sorted according to the specified ordering (for example, A through Z in US English). In its implementation of tableView:titleForHeaderInSection:, the data source can call this method on the indexed-collation object, passing in the section index and returning the result.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns the list of section-index titles for the table view (read-only)

    Declaration

    Swift

    var sectionIndexTitles: [AnyObject] { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *sectionIndexTitles

    Discussion

    This property contains the localized list of section-index titles sorted according to the specified ordering (for example, A through Z in US English). In its implementation of sectionIndexTitlesForTableView:, the data source can call this method on the indexed-collation object and pass back the result.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns the section that the table view should scroll to for the given index title.

    Declaration

    Swift

    func sectionForSectionIndexTitleAtIndex(_ indexTitleIndex: Int) -> Int

    Objective-C

    - (NSInteger)sectionForSectionIndexTitleAtIndex:(NSInteger)indexTitleIndex

    Parameters

    indexTitleIndex

    An integer identifying a section-index title by its position in the array of such titles.

    Return Value

    An integer identifying the table-view section associated with indexTitleIndex.

    Discussion

    This method allows the table view to map between a given item in the section index and a given section even when there isn't a one-to-one mapping. In its implementation of tableView:sectionForSectionIndexTitle:atIndex:, the data source can call this method on the indexed-collation object specifying as an argument the passed-in index integer; it then returns the result to the table view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.