home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOAssociation.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  8.8 KB  |  189 lines
  1. // EOAssociation.h
  2. // Enterprise Objects Framework
  3. // Copyright (c) 1995, NeXT Software, Inc.  All rights reserved.
  4.  
  5. #import <EOControl/EOControl.h>
  6. #import <AppKit/AppKit.h>
  7. #import <EOInterface/EODisplayGroup.h>
  8.  
  9. // An EOAssociation acts as the glue between an object (usually a user
  10. // interface widget) and the properties of objects managed by one or
  11. // more displayGroups.  When the contents or selection of one of the displayGroups
  12. // it observes changes, the association updates its object (widget).  Similarly,
  13. // when the association receives an action or delegate message from its object
  14. // that indicates a change in the selection or value, it passes that change on
  15. // to the appropriate displayGroup.
  16. //
  17. // Associations have one or more named "aspects" that can be bound to object
  18. // properties.  For example, the EOControlAssociation has a "value" aspect
  19. // that could be bound to the "firstName" property of an employee displayGroup,
  20. // while the EOPopupAssociation also has an "values" aspect that could be
  21. // bound to the "departmentName" property of all objects in a department
  22. // displayGroup.
  23. //
  24. // Associations are normally created automatically from connections made
  25. // in InterfaceBuilder.  To create an association programmatically:
  26. //    EOControlAssociation *assoc = [[EOControlAssociation alloc] initWithObject:aField];
  27. //    [assoc bindAspect:@"value" displayGroup:aDisplayGroup key:@"firstName"]
  28. //    // possibly other bindings...
  29. //    [assoc establishConnection];  // assoc is retained by its object
  30. //    [assoc release];              // so we don't need to retain it
  31. //
  32. // Associations use the EOObserver mechanism to watch their displayGroups.
  33. // Because associations inherit from EODelayedObserver, all of the changes
  34. // notifications from their displayGroups are automatically coalesced, and
  35. // a single "subjectChanged" message is delivered to each affected association
  36. // at the end of processing the current event.  In subjectChanged the
  37. // association can callback to its displayGroups and query them as to whether
  38. // selectionChanged and/or contentsChanged.
  39. //
  40.  
  41. @interface EOAssociation : EODelayedObserver <NSCoding>
  42. {
  43.     id _object;
  44.  
  45.     unsigned _refs:8;
  46.     unsigned _isConnected:1;
  47.     unsigned _extras:7;
  48.     unsigned subclassFlags:16;  // for use by subclasses?
  49.     
  50.     // extended ivars used to hold key/displayGroup pairs.
  51.     // Subclasses can add ivars, but not extended ivars.
  52. }
  53.  
  54. // implemented by subclasses
  55. + (NSString *)displayName;
  56.     // the name to be used for the class inside InterfaceBuilder.
  57.     // The default is the class name.
  58.  
  59. + (BOOL)isUsableWithObject:(id)object;
  60.     // assoc can say whether it can be used with the given source object
  61.     // This may key off of the class of the source, or possibly look at other
  62.     // factors (e.g. for a matrix, what is the type of the cells -- radio, text?)
  63.     // Default returns NO.
  64.  
  65. + (NSArray *)aspects;
  66.     // returns a list of aspects (sockets) that offered for connection by this
  67.     // association.
  68.     // Default returns an empty array.
  69.  
  70. + (NSArray *)aspectSignatures;
  71.     // Should return an array corresponding to the aspects array containing a string mask
  72.     // identifying the types of properties the positionally corresponding aspect can
  73.     // be connected to.
  74.     // Types are: "A" (attribute), "1" (to-one relationship), "M" (to-many relationship).
  75.     // E.g., the signature "1M" indicates the aspect can be bound to a to-one or to-many
  76.     // relationship.
  77.     // The signature "" indicates the aspect can be bound to a DisplayGroup without
  78.     // specifying a key (@"" is used as the key in the call to bindAspect:...).
  79.     // Default implementation returns an array of "A1M" of the length of aspects.
  80.  
  81. + (NSString *)primaryAspect;
  82.     // the name of the "primary" (or default) aspect.  Usually "value"
  83.     // This is the default selected in the connect inspector when
  84.     // first connecting an association in IB.
  85.     // Default returns nil
  86.  
  87. + (NSArray *)objectKeysTaken;
  88.     // returns a list of features of the control that are taken over by the
  89.     // association (examples: "target", "delegate").  These keys will be dimmed
  90.     // out in the IB connect inspector, indicating that the developer cannot
  91.     // use them when using this association.
  92.  
  93. + (NSArray *)associationClassesSuperseded;
  94.     // Should return a list of associations that this association supercedes.
  95.     // That is, if this association is applicable for a given object
  96.     // then the returned associations will be ommitted from the list
  97.     // of associations in IB for the object.  For example, EOPopupAssociation
  98.     // overrides EOControlAssociation since for popups, the PopupAssociation
  99.     // is always more appropriate.
  100.  
  101. - initWithObject:object;
  102.     // Designated initializer.  Sets up association, but does not activate it.
  103.     // establishConnection must be called to actually activate the association.
  104.  
  105. - initWithCoder:(NSCoder *)coder;
  106.     // Default implementation unarchives the key/destination pairs and then
  107.     // calls initWithObject:
  108. - (void)encodeWithCoder:(NSCoder *)coder;
  109.  
  110. - (void)establishConnection;
  111.     // Activates the association after initWithObject: or initWithCoder:.
  112.     // Default implementation subscribes for change notification on the
  113.     // destination displayGroups.  Subclasses should override to set self
  114.     // as target or delegate of object.
  115.     // The nib file unarchiving calls this automatically for associations
  116.     // read in from a nib file.
  117.     // Once the connection is established the association becomes "owned" by
  118.     // its object (its retain count is bumped) and will automatically have
  119.     // its breakConnection method called when the object is dealloced.
  120.  
  121. - (void)dealloc;
  122.     // this will call breakConnection to unsubscribe from all destinations
  123.     // being observed
  124.  
  125. - (void)breakConnection;
  126.     // removes the association as an observer from it destination and
  127.     // breaks it connection to the parent (causing the retain count to drop).
  128.     // Subclasses may want to override this to unhook delegate connections
  129.     // in the associations object.
  130.  
  131. - (id)object;
  132.     // Returns the object (typically a UI control) managed by the association.
  133.  
  134. - (void)bindAspect:(NSString *)name displayGroup:(EODisplayGroup *)dest key:(NSString *)key;
  135.      // Set the destination for an aspect.  Binding can be eliminated
  136.      // by binding to nil destination.
  137.      // bindAspect: can only be called *before* calling establishConnection.
  138.      // Once the association has been connected, its bindings cannot be changed.
  139.  
  140. - (EODisplayGroup *)displayGroupForAspect:(NSString *)name;
  141. - (NSString *)displayGroupKeyForAspect:(NSString *)name;
  142.  
  143. - (BOOL)canBindAspect:(NSString *)name displayGroup:(EODisplayGroup *)displayGroup key:(NSString *)key;
  144.     // See if this aspect can be bound to the given destination.  Could
  145.     // be used to disable certain aspects in inspector if destination is of wrong type.
  146.     // Default implementation returns YES.
  147.  
  148. // Key methods for association to interact with the displayGroup
  149. - (BOOL)endEditing;
  150.     // called by displayGroup to tell association to push uncommitted edit.
  151.     // returns NO if validation failure (and calls assocation:failedToValidate:...)
  152.     // Default implementation returns YES.
  153.  
  154. - (void)subjectChanged;
  155.     // Called to tell association that something in its world has changed.
  156.     // It should call back its displayGroups to determine what to actually changed
  157.     // (selection, object contents, etc).
  158.     // Default implementation does nothing
  159.  
  160. + (NSArray *)associationClassesForObject:(id)object;
  161.     // called on root class to return an array of association classes suitable
  162.     // for use with the given source.  This is turn calls "usableWithObject:" to
  163.     // all registered association classes.
  164. @end
  165.  
  166.  
  167. @interface EOAssociation (EOExtras)
  168. // Useful methods for use by subclasses
  169. // Calls the object pointed to by the aspect to get info
  170. - (id)valueForAspect:(NSString *)name;
  171.     // retrieves value for key of aspect as destination.
  172. - (BOOL)setValue:value forAspect:(NSString *)name;
  173. - (BOOL)shouldEndEditingForAspect:(NSString *)aspectName invalidInput:(NSString *)string errorDescription:(NSString *)errorDescription;
  174.     // usually called by subclasses in response to validation failure from
  175.     // an NSFormatter (control:didFailToFormatString:errorDescription:)
  176.     // Passes message to displayGroup to determine whether association should
  177.     // allow use to end editing.
  178.  
  179. - (id)valueForAspect:(NSString *)name atIndex:(unsigned)index;
  180.     // retrieves value for key of aspect as destination.
  181. - (BOOL)setValue:value forAspect:(NSString *)name atIndex:(unsigned)index;
  182. - (BOOL)shouldEndEditingForAspect:(NSString *)aspectName invalidInput:(NSString *)string errorDescription:(NSString *)errorDescription index:(unsigned)index;
  183.  
  184. - (void)copyMatchingBindingsFromAssociation:(EOAssociation *)other;
  185.    // makes bindings for all of the aspects in the receive that match
  186.    // those in other.
  187. @end
  188.  
  189.