Defining Keys for a Dictionary Class

The Keys sheet of the Define Class dialog is displayed after you have specified your class and membership options for a subclass of the dictionary class and you then select the Keys sheet of the dialog.

You must specify your membership options before you can specify key options.

Mapped properties (that is, properties that have a mapping method) from a RootSchema class cannot be used as dictionary keys.

Only changes to keys are propagated to dictionary subclasses.

The Keys sheet that is displayed for an External Key Dictionary differs slightly to that displayed for a Member Key Dictionary. For details about key paths, see "Maintaining Dictionary Key Paths", later in this chapter.

The following image shows an example of the Keys sheet.

To specify the keys for a dictionary subclass

For a MemberKeyDictionary class, select the property that is to be a key of the dictionary subclass in the Keys list box. The listed properties are those of the class specified in the Membership sheet. (A property that is a key of a dictionary class is displayed in the Properties List of the Class Browser with the key icon to the left of the property.)

To reorder keys, hold down the Ctrl key while you use the mouse to drag and drop a key to a new position in the Keys List window.

For an ExtKeyDictionary class, specify the required key name in the Key Name text box (beginning with a lowercase character) and then select the appropriate key type from the Type combo box.
If you are defining an External Key Dictionary class and you specified a Binary or String primitive type for class membership on the Membership sheet, specify the length of the string or binary keys in the Length text box, if required. The default value is 30, but you can specify any value in the range 1 through 512, inclusive.

Conversely, if you selected a Decimal primitive type for membership of an external key dictionary in the Type combo box in step 1, specify the length of the decimal collection members in the Length text box, if required. The default value is 12.
If you are defining an External Key Dictionary class and you selected a Decimal primitive type for class membership in the Type combo box in step 1, specify the scale factor of the decimal collection members in the Scale Factor text box, if required. The default value is zero (0).
Check the Descending check box if you want the selected key to be sorted in descending order. By default, keys are sorted in ascending order.
If you specified a String primitive type, select the required sort order in the Sort Order combo box, if required. The default sort order is binary, but you can select the sort order of any locale available in the system. You are not restricted to the locales supported by the current schema.

Select the (Latin1) locale instead of (Binary) when you also require case-insensitivity. The (Latin1) locale implements the ISO 8859-1 standard, which you can use as an alternative to the (Binary) sort order.

For string comparisons of key values when locales and case-sensitivity are a consideration, call the Dictionary class stringKeyCompareGeq, stringKeyCompareGtr, stringKeyCompareLeq, or stringKeyCompareLss method.
Check the Case Insensitive check box if the key is not dependent on specific capitalization. By default, keys are case-sensitive. This check box is enabled only if you selected a String primitive type in step 1.

When you select the (Binary) value in the Sort Order combo box in step 5, the Case Insensitive check box is disabled (and unchecked, if it was checked).
Click the Add button to add the selected key to the new dictionary subclass. Alternatively, click the:
- Change button, if you want to change the case sensitivity or the descending or ascending sort order.
  
  The Change button is enabled when you select a dictionary key, change one or more of the values that apply to that key, and then click the key attributes displayed in the list above the Duplicates Allowed check box.
- Remove button, if you want to remove a key that you previously selected.
You can also double-click to add or remove a selected key.
Check the Duplicates Allowed check box if duplicate entries are to be permitted for the dictionary. By default, duplicate entries are not allowed.

In a dictionary that allows duplicate keys, entries are inserted in <key><oid> order. Duplicate key entries therefore occur in object creation order within instances of the same class.

If you have subclasses included in your collection, the order within the dictionary is not necessarily in strict creation order, but in creation order within the instances of each subclass.

Regardless of the setting of this check box, you cannot add the same object to the same dictionary twice with the same key. For manually maintained member key and external key dictionaries, you can get the same object in the dictionary twice if it is added with different key values. However, this would generally be considered a logical integrity issue. Member key dictionaries with inverses cannot be set up in this way, as the inverse maintenance will automatically remove the old entry with the old key value.
Click the OK button. Alternatively, click the Cancel button to abandon your selections.

The specified class is then displayed as a subclass of the selected superclass in the Class Browser window. Alternatively, you can select the Lifetime sheet if you want to restrict the lifetime of instances of the class and its subclasses, the Tuning sheet if you want to tune a Collection subclass, or the Volatility sheet if you want to change the volatility of instances of the class.