sproutcore 0.9.23 → 1.0.1003

data/frameworks/sproutcore/mixins/control.js

@@ -1,265 +0,0 @@
-// ========================================================================
-// SproutCore
-// copyright 2006-2008 Sprout Systems, Inc.
-// ========================================================================
-
-/**
-  Indicates a value has a mixed state of both on and off.
-*/
-SC.MIXED_STATE = '__MIXED__' ;
-
-/**
-  @namespace
-
-  A Control is a view that also implements some basic state functionality.
-  Apply this mixin to any view that you want to have standard control
-  functionality including showing a selected state, enabled state, focus
-  state, etc.
-  
-  h2. About Values and Content
-  
-  Controls typically are used to represent a single value, such as a number,
-  boolean or string.  The value a control is managing is typically stored in
-  a "value" property.  You will typically use the value property when working
-  with controls such as buttons and text fields in a form.
-  
-  An alternative way of working with a control is to use it to manage some
-  specific aspect of a content object.  For example, you might use a label
-  view control to display the "name" property of a Contact record.  This 
-  approach is often necessary when using the control as part of a collection
-  view.
-  
-  You can use the content-approach to work with a control by setting the 
-  "content" and "contentValueKey" properties of the control.  The 
-  "content" property is the content object you want to manage, while the 
-  "contentValueKey" is the name of the property on the content object 
-  you want the control to display.  
-  
-  The default implementation of the Control mixin will essentially map the
-  contentValueKey of a content object to the value property of the 
-  control.  Thus if you are writing a custom control yourself, you can simply
-  work with the value property and the content object support will come for
-  free.  Just write an observer for the value property and update your 
-  view accordingly.
-  
-  If you are working with a control that needs to display multiple aspects
-  of a single content object (for example showing an icon and label), then
-  you can override the contentValueDidChange() method instead of observing
-  the value property.  This method will be called anytime _any_ property 
-  on the content object changes.  You should use this method to check the
-  properties you care about on the content object and update your view if 
-  anything you care about has changed.
-  
-  h2. Delegate Support
-  
-  Controls can optionally get the contentDisplayProperty from a 
-  displayDelegate, if it is set.  The displayDelegate is often used to 
-  delegate common display-related configurations such as which content value
-  to show.  Anytime your control is shown as part of a collection view, the
-  collection view will be automatically set as its displayDelegate.
-  
-*/
-SC.Control = {
-  
-  initMixin: function() {
-    this._contentObserver(); // setup content observing if needed.
-    this.isSelectedObserver() ;
-    this.isEnabledObserver() ;
-    this.isFocusedObserver(); 
-  },
-  
-  /** 
-    Set to true when the item is selected. 
-    
-    This property is observable and bindable.
-  */
-  isSelected: false,
-  isSelectedBindingDefault: SC.Binding.OneWayBool,
-
-  /** 
-    Set to true when the item is enabled. 
-    
-    This property is observable and bindable.
-  */
-  isEnabled: true,
-  isEnabledBindingDefault: SC.Binding.OneWayBool,
-  
-  /**
-    The value represented by this control.
-    
-    Most controls represent a value of some type, such as a number, string
-    or image URL.  This property should hold that value.  It is bindable
-    and observable.  Changing this value will immediately change the
-    appearance of the control.  Likewise, editing the control 
-    will immediately change this value.
-    
-    If instead of setting a single value on a control, you would like to 
-    set a content object and have the control display a single property
-    of that control, then you should use the content property instead.
-  */
-  value: null,
-  
-  /**
-    The content object represented by this control.
-    
-    Often you need to use a control to display some single aspect of an 
-    object, especially if you are using the control as an item view in a
-    collection view.
-    
-    In those cases, you can set the content and contentValueKey for the
-    control.  This will cause the control to observe the content object for
-    changes to the value property and then set the value of that property 
-    on the "value" property of this object.
-    
-    Note that unless you are using this control as part of a form or 
-    collection view, then it would be better to instead bind the value of
-    the control directly to a controller property.
-  */
-  content: null,
-  
-  /**
-    The property on the content object that would want to represent the 
-    value of this control.  This property should only be set before the
-    content object is first set.  If you have a displayDelegate, then
-    you can also use the contentValueKey of the displayDelegate.
-  */
-  contentValueKey: null,
-
-  /**
-    Invoked whenever any property on the content object changes.  
-    
-    The default implementation will update the value property of the view
-    if the contentValueKey property has changed.  You can override this
-    method to implement whatever additional changes you would like.
-    
-    The key will typically contain the name of the property that changed or 
-    '*' if the content object itself has changed.  You should generally do
-    a total reset of '*' is changed.
-    
-    @param {Object} target the content object
-    @param {String} key the property that changes
-  */
-  contentPropertyDidChange: function(target, key) {
-    if (!!this._contentValueKey && ((key == this._contentValueKey) || (key == '*'))) {
-      var content = this.get('content') ;
-      var value = (content) ? content.get(this._contentValueKey) : null;
-      if (value != this._contentValue) {
-        this._contentValue = value ;
-        this.set('value', value) ;
-      }
-    }
-  },
-
-  /**
-    Relays changes to the value back to the content object if you are using
-    a content object.
-    
-    This observer is triggered whenever the value changes.  It will only do
-    something if it finds you are using the content property and
-    contentValueKey and the new value does not match the old value of the
-    content object.  
-    
-    If you are using contentValueKey in some other way than typically
-    implemented by this mixin, then you may want to override this method as
-    well.
-  */
-  updateContentWithValueObserver: function() {
-    if (!this._contentValueKey) return; // do nothing if disabled
-
-    // get value.  return if value matches current content value.
-    // this avoids infinite loops where setting the value from the content
-    // in turns sets the content and so on.
-    var value = this.get('value') ;
-    if (value == this._contentValue) return ; 
-
-    var content = this.get('content') ;
-    if (!content) return; // do nothing if no content.
-    
-    // passed all of our checks, update the content (and the _contentValue
-    // to avoid infinite loops)
-    this._contentValue = value ;
-    content.set(this._contentValueKey, value) ;
-    
-  }.observes('value'),
-  
-  /**
-    Default observer for selected state changes
-    
-    The default will simply add either a "mixed" or "sel" class name to the
-    root element of your view based on the state. You can override this with
-    your own behavior if you prefer.
-  */
-  isSelectedObserver: function() {
-    var sel = this.get('isSelected') ;
-    this.setClassName('mixed', sel == SC.MIXED_STATE) ;
-    this.setClassName('sel', sel && (sel != SC.MIXED_STATE)) ;
-  }.observes('isSelected'),
-  
-  /**
-    Default observer for the isEnabled state.
-    
-    The default will simply add or remove a "disabled" class name to the root 
-    element of your view based on the state.  You can override this with your
-    own behavior if you prefer.
-  */
-  isEnabledObserver: function() {
-    var disabled = !this.get('isEnabled') ;
-    this.setClassName('disabled', disabled);
-
-    // set disabled attr as well if relevant
-    if (this.rootElement && (this.rootElement.disabled !== undefined) && (this.rootElement.disabled != disabled)) {
-      this.rootElement.disabled = disabled ;
-    }
-  }.observes('isEnabled'),
-
-  /**
-    Default observer for the isFirstResponder state.
-    
-    The default will add or remove a "focus" class name ot the root element
-    of your view based on the state.  You can override this with your own
-    behavior if you prefer.
-  */
-  isFocusedObserver: function() {
-    this.setClassName('focus', !!this.get('isFirstResponder')) ;
-  }.observes('isFirstResponder'),
-  
-  // This should be null so that if content is also null, the
-  // _contentObserver won't do anything on init.
-  _content: null,
-  
-  /** @private
-    Observes when a content object has changed and handles notifying 
-    changes to the value of the content object.
-  */
-  _contentObserver: function() {
-    var content = this.get('content') ;
-    if (this._content == content) return; // nothing changed
-    
-    // create bound observer function
-    if (!this._boundContentPropertyDidChangeObserver) {
-      this._boundContentPropertyDidChangeObserver = this.contentPropertyDidChange.bind(this) ;
-    }
-    var f = this._boundContentPropertyDidChangeObserver ;
-
-    // remove an observer from the old content if necessary
-    if (this._content && this._content.removeObserver) {
-      this._content.removeObserver('*', f) ;
-    }
-
-    // cache for future use
-    var del = this.displayDelegate ;
-    this._contentValueKey = this.getDelegateProperty(del, 'contentValueKey');
-
-    
-    // add observer to new content if necessary.
-    this._content = content ;
-    if (this._content && this._content.addObserver) {
-      this._content.addObserver('*', f) ;
-    }
-    
-    // notify that value did change.
-    this.contentPropertyDidChange(this._content, '*') ;
-    
-  }.observes('content')
-      
-};

data/frameworks/sproutcore/mixins/delegate_support.js

@@ -1,66 +0,0 @@
-// ========================================================================
-// SproutCore
-// copyright 2006-2008 Sprout Systems, Inc.
-// ========================================================================
-
-/**
-  @namespace
-  
-  Support methods for the Delegate design pattern.
-  
-  The Delegate design pattern makes it easy to delegate a portion of your 
-  application logic to another object.  This is most often used in views to 
-  delegate various application-logic decisions to controllers in order to 
-  avoid having to bake application-logic directly into the view itself.
-  
-  The methods provided by this mixin make it easier to implement this pattern
-  but they are not required to support delegates.
-  
-  h2. The Pattern
-  
-  The delegate design pattern typically means that you provide a property,
-  usually ending in "delegate", that can be set to another object in the 
-  system.  
-  
-  When events occur or logic decisions need to be made that you would prefer
-  to delegate, you can call methods on the delegate if it is set.  If the 
-  delegate is not set, you should provide some default functionality instead.
-  
-  Note that typically delegates are not observable, hence it is not necessary
-  to use get() to retrieve the value of the delegate.
-  
-*/
-SC.DelegateSupport = {  
-  
-  /**
-    Invokes the named method on the delegate that you pass.  If no delegate
-    is defined or if the delegate does not implement the method, then a 
-    method of the same name on the receiver will be called instead.  
-    
-    You can pass any arguments you want to pass onto the delegate after the
-    delegate and methodName.
-    
-    @param {Object} delegate a delegate object.  May be null.
-    @param {String} methodName a method name
-    @param {*} args (OPTIONAL) any additional arguments
-    
-    @returns value returned by delegate
-  */
-  invokeDelegateMethod: function(delegate, methodName, args) {
-    args = SC.$A(arguments); args = args.slice(2, args.length) ;
-    if (!delegate || !delegate[methodName]) delegate = this ;
-    return delegate[methodName].apply(delegate, args) ;
-  },
-  
-  /**
-    Gets the named property from the delegate if the delegate exists and it
-    defines the property.  Otherwise, gets the property from the receiver.
-    
-    @param {Object} delegate the delegate or null
-    @param {String} key the property to get.
-  */
-  getDelegateProperty: function(delegate, key) {
-    return (delegate && (delegate[key] != null)) ? delegate.get(key) : this.get(key) ;
-  }
-  
-};

data/frameworks/sproutcore/mixins/editable.js

@@ -1,144 +0,0 @@
-// ========================================================================
-// SproutCore
-// copyright 2006-2008 Sprout Systems, Inc.
-// ========================================================================
-
-/**
-  @namespace
-
-  The Editable mixin is a standard protocol used to activate keyboard editing 
-  on views that are editable such as text fields, label views and item views.
-  
-  You should apply this mixin, or implement the methods, if you are
-  designing an item view for a collection and you want to automatically
-  trigger editing.
-  
-  h2. Using Editable Views
-  
-  To use a view that includes the Editable mixin, you simply call three
-  methods on the view:
-  
-  - To begin editing, call beginEditing().  This will make the view first responder and allow the user to make changes to it.  If the view cannot begin editing for some reason, it will return NO.
-  
-  - If you want to cancel editing, you should try calling discardEditing().  This will cause the editor to discard its changed value and resign first responder.  Some editors do not support cancelling editing and will return NO.  If this is the case, you may optionally try calling commitEditing() instead to force the view to resign first responder, even though this will commit the changes.
-  
-  - If you want to end editing, while saving any changes that were made, try calling commitEditing().  This will cause the editor to validate and apply its changed value and resign first responder.  If the editor cannot validate its contents for some reason, it will return NO.  In this case you may optionally try calling discardEditing() instead to force the view to resign first responder, even though this will discard the changes.
-  
-  
-  h2. Implementing an Editable View
-  
-  To implement a new view that is editable, you should implement the three
-  methods defined below: beginEditing(), discardEditing(), and
-  commitEditing().  If you already allow editing when your view becomes first
-  responder and commit your changes when the view loses first responder status
-  then you can simply apply this mixin and not override any methods.
-  
-  
-  @since SproutCore 1.0
-  
-*/
-SC.Editable = {  
-
-  /**
-    Indicates whether a view is editable or not.  You can optionally 
-    implement the methods in this mixin to disallow editing is isEditable is
-    NO.
-  */
-  isEditable: NO,
-  
-  /**
-    Indicates whether editing is currently in progress.  The methods you
-    implement should generally up this property as appropriate when you 
-    begin and end editing.
-  */
-  isEditing: NO,
-  
-  /**
-    Begins editing on the view.
-    
-    This method is called by other views when they want you to begin editing.
-    You should write this method to become first responder, perform any 
-    additional setup needed to begin editing and then return YES.
-    
-    If for some reason you do not want to allow editing right now, you can
-    also return NO.  If your view is already editing, then you should not
-    restart editing again but just return YES.
-
-    The default implementation checks to see if editing is allowed, then
-    becomes first responder and updates the isEditing property if appropriate.
-    Generally you will want to replace this method with your own 
-    implementation and not call the default.
-    
-    @returns {Boolean} YES if editing began or is in progress, NO otherwise
-  */
-  beginEditing: function() {
-    if (!this.get('isEditable')) return NO ;
-    if (this.get('isEditing')) return YES ;
-    
-    // begin editing
-    this.set('isEditing', YES) ;
-    this.becomeFirstResponder() ;
-    return YES ;
-  },
-  
-  /**
-    Ends editing on the view, discarding any changes that were made to the
-    view value in the meantime.
-    
-    This method is called by other views when they want to cancel editing
-    that began earlier.  When this method is called you should resign first
-    responder, restore the original value of the view and return YES.
-    
-    If your view cannot revert back to its original state before editing began
-    then you can implement this method to simply return NO.  A properly
-    implemented client may try to call commitEditing() instead to force your
-    view to end editing anyway.
-    
-    If this method is called on a view that is not currently editing, you
-    should always just return YES.
-    
-    The default implementation does not support discarding changes and always
-    returns NO.
-    
-    @returns {Boolean} YES if changes were discarded and editing ended.
-  */
-  discardEditing: function() {
-    // if we are not editing, return YES, otherwise NO.
-    return !this.get('isEditing') ;
-  },
-  
-  /**
-    Ends editing on the view, committing any changes that were made to the 
-    view value in the meantime.
-    
-    This method is called by other views when they want to end editing, 
-    saving any changes that were made to the view in the meantime.  When this
-    method is called you should resign first responder, save the latest
-    value of the view and return YES.
-    
-    If your view cannot save the current state of the view for some reason 
-    (for example if validation fails), then you should return NO.  Properly
-    implemented clients may then try to call discardEditing() to force your
-    view to resign first responder anyway.
-    
-    Some views apply changes to their value immediately during an edit instead
-    of waiting for the view to end editing.  If this is the case, you should
-    still implement commitEditing but you simply may not save any value 
-    changes.
-  
-    If this method is called on a view that is not currently editing, you
-    should always just reutrn YES.
-    
-    The default implementation sets isEditing to NO, resigns first responder
-    and returns YES.
-    
-    @returns {Boolean} YES if changes were discarded and editing ended.
-  */
-  commitEditing: function() {
-    if (!this.get('isEditing')) return YES;
-    this.set('isEditing', NO) ;
-    this.resignFirstResponder() ;
-    return YES ;
-  }
-
-} ;