home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOKeyValueCoding.h < prev    next >
Encoding:
Text File  |  1996-09-11  |  4.3 KB  |  95 lines
  1. // EOKeyValueCoding.h
  2. // Copyright (c) 1994, NeXT Software, Inc.  All rights reserved.
  3. //
  4. // The EOKeyValueCoding categories define methods to initialize an object with
  5. // values stored in a dictionary, and to extract values from an object for a
  6. // set of keys. These keys are usually the internal names of attributes or
  7. // relationships as defined in an EOModel, and are used in both the access
  8. // and interface layers.
  9. //
  10.  
  11. #import <Foundation/Foundation.h>
  12. #import <EOControl/EONull.h>
  13.  
  14. @interface NSObject (EOKeyValueCodingPrimitives)
  15.  
  16. - (void)flushKeyBindings;
  17.     // Invalidates the cached key binding information for the receiver's
  18.     // class.  This method should be invoked whenever a class is modified or
  19.     // removed from the runtime system.  This will be called automatically
  20.     // when bundles are loaded.
  21.  
  22. - (id)valueForKey:(NSString *)key;
  23.     // The default implementation searches first for a selector with
  24.     // the same name as the key, and then for an instance variable with
  25.     // the same name as the key.  Classes can override this method to
  26.     // add custom behavior.
  27.     // Default implementation raises an exception if an unknown key is
  28.     // passed in.
  29.  
  30. - (void)takeValue:(id)value forKey:(NSString *)key;
  31.     // Sets property of the receiver with supplied values.
  32.     // The default implementation searches first for a selector named
  33.     // setKey: (where "Key" is replaced by the key in the dictionary),
  34.     // and then for an instance variable with the same name as the key.
  35.     // Classes can override this method to add custom behavior.
  36.     // Default implementation raises an exception if an unknown key is
  37.     // passed in.
  38.  
  39. + (BOOL)accessInstanceVariablesDirectly;
  40.     // This method can be overridden on a class to disable
  41.     // accessing instance variables when a matching method
  42.     // cannot be found.  Default on NSObject is YES.
  43. @end
  44.  
  45. @interface NSObject (EOKVCPAdditions)
  46. - (id)valueForKeyPath:(NSString *)key;
  47.     // A "key path" is a key of the form "relname.property" (with one or
  48.     // more relationship names).  For example, [emp valueForKeyPath:@"department.name"]
  49.     // will ask the receiving employee for its department object (via valueForKey:)
  50.     // and will in turn ask the department for its name.  This provides attribute
  51.     // "flattening" by navigating the object graph in memory.
  52.  
  53. - (void)takeValue:value forKeyPath:(NSString *)key;
  54.     // Sets the property identified by the given key path.  @"address.street"
  55.     // sent to an employee object will first get the address object (via
  56.     // valueForKey:@"address") and then perform [address setValue:value forKey:@"street"]
  57.  
  58. - (NSDictionary *)valuesForKeys:(NSArray *)keys;
  59.     // aggregate version of valueForKey:
  60.     // Nil values returned from valueForKey: are put in return dictionary
  61.     // as EONull
  62.  
  63. - (void)takeValuesFromDictionary:(NSDictionary *)dictionary;
  64.     // aggregate version of takeValue:forKey:
  65.     // EONull in the input dictionary is passed to object as takeValue:nil
  66.  
  67. @end
  68.  
  69. @interface NSObject (EOKeyValueCodingException)
  70. - (id)handleQueryWithUnboundKey:(NSString *)key;
  71.     // Called by default implementation of valueForKey: when the key
  72.     // does not correspond to a method or instance variable in the
  73.     // receiver.  The default implementation raises an exception.
  74.     // Classes can override this method to be more permissive
  75.     // (perhaps by returing nil).  The return value is passed back
  76.     // from valueForKey:
  77.  
  78. - (void)handleTakeValue:(id)value forUnboundKey:(NSString *)key;
  79.     // Called by default implementation of takeValue:forKey: when the key
  80.     // does not correspond to a method or instance variable in the
  81.     // receiver.  The default implementation raises an exception.
  82.     // Classes can override this method to be more permissive.
  83.     // (perhaps ignoring the error or logging to the console)
  84.  
  85.    
  86. - (void)unableToSetNilForKey:(NSString *)key;
  87.     // Classes can implement this method to determine the behavior
  88.     // when nil is assigned to a property in an EO that requires
  89.     // a C scalar type (such as int or float).  One possible implementation
  90.     // is to call takeValue:forKey: recursively with a special constant
  91.     // value (like [NSNumber numberWithInt:0]) or with an object that will
  92.     // return the desired values to assign for the methods floatValue, intValue,
  93.     // unsignedIntValue, etc.
  94. @end
  95.