sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/foundation/mixins/control.js

@@ -0,0 +1,352 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/** Indicates a value has a mixed state of both on and off. */
+SC.MIXED_STATE = '__MIXED__' ;
+
+/** Option for HUGE control size. */
+SC.HUGE_CONTROL_SIZE = 'sc-huge-size' ;
+
+/** Option for large control size. */
+SC.LARGE_CONTROL_SIZE = 'sc-large-size' ;
+
+/** Option for standard control size. */
+SC.REGULAR_CONTROL_SIZE = 'sc-regular-size' ;
+
+/** Option for small control size. */
+SC.SMALL_CONTROL_SIZE = 'sc-small-size' ;
+
+/** Option for tiny control size */
+SC.TINY_CONTROL_SIZE = 'sc-tiny-size' ;
+
+/**
+  @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.
+  
+  @since SproutCore 1.0
+*/
+SC.Control = {
+  
+  initMixin: function() {
+    this._control_contentDidChange() ; // setup content observing if needed.
+  },
+  
+  /** 
+    The selected state of this control.  Possible options are YES, NO or 
+    SC.MIXED_STATE.
+    
+    @type Boolean or SC.MIXED_STATE
+  */
+  isSelected: NO,
+  
+  /** @private */
+  isSelectedBindingDefault: SC.Binding.oneWay().bool(),
+  
+  /**
+    Set to YES when the item is currently active.  Usually this means the 
+    mouse is current pressed and hovering over the control, however the 
+    specific implementation my vary depending on the control.
+    
+    Changing this property value by default will cause the Control mixin to
+    add/remove an 'active' class name to the root element.
+    
+    @type Boolean
+  */
+  isActive: NO,
+  
+  /** @private */
+  isActiveBindingDefault: SC.Binding.oneWay().bool(),
+  
+  /**
+    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.
+    
+    @type SC.Object
+  */
+  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.
+    
+    @type String
+  */
+  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
+    @test in content
+  */
+  contentPropertyDidChange: function(target, key) {
+    return this.updatePropertyFromContent('value', key, 'contentValueKey');
+  },
+  
+  /**
+    Helper method you can use from your own implementation of 
+    contentPropertyDidChange().  This method will look up the content key to
+    extract a property and then update the property if needed.  If you do
+    not pass the content key or the content object, they will be computed 
+    for you.  It is more efficient, however, for you to compute these values
+    yourself if you expect this method to be called frequently.
+    
+    @param {String} prop local property to update
+    @param {String} key the contentproperty that changed
+    @param {String} contentKey the local property that contains the key
+    @param {Object} content
+    @returns {SC.Control} receiver
+  */
+  updatePropertyFromContent: function(prop, key, contentKey, content) {
+    var all = key === '*';
+    if (contentKey === undefined) {
+      contentKey = "content%@Key".fmt(prop.capitalize());
+    }
+    if (content === undefined) content = this.get('content');
+    
+    // get actual content key
+    contentKey = this[contentKey] ?
+      this.get(contentKey) :
+      this.getDelegateProperty(this.displayDelegate, contentKey) ;
+    
+    if (contentKey && (all || key === contentKey)) {
+      var v = (content) ?
+        (content.get ? content.get(contentKey) : content[contentKey]) :
+        null ;
+      this.set(prop, v) ;
+    }
+    return this ;
+  },
+  
+  /**
+    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() {
+    var key = this.contentValueKey ?
+      this.get('contentValueKey') :
+      this.getDelegateProperty(this.displayDelegate, 'contentValueKey') ;
+    
+    var content = this.get('content') ;
+    if (!key || !content) return ; // do nothing if disabled
+    
+    // get value -- set on content if changed
+    var value = this.get('value');
+    if (typeof content.setIfChanged === SC.T_FUNCTION) {
+      content.setIfChanged(key, value);
+    } else {
+      // avoid re-writing inherited props
+      if (content[key] !== value) content[key] = value ;
+    }
+  }.observes('value'),
+  
+  /**
+    The name of the property this control should display if it is part of an
+    SC.FormView.
+    
+    If you add a control as part of an SC.FormView, then the form view will 
+    automatically bind the value to the property key you name here on the 
+    content object.
+    
+    @type String
+  */
+  fieldKey: null,
+  
+  /**
+    The human readable label you want shown for errors.  May be a loc string.
+    
+    If your field fails validation, then this is the name that will be shown
+    in the error explanation.  If you do not set this property, then the 
+    fieldKey or the class name will be used to generate a human readable name.
+    
+    @type String
+  */
+  fieldLabel: null,
+  
+  /**
+    The human readable label for this control for use in error strings.  This
+    property is computed dynamically using the following rules:
+    
+    # If the fieldLabel is defined, that property is localized and returned.
+    # Otherwise, if the keyField is defined, try to localize using the string 
+    # "ErrorLabel.{fieldKeyName}".  If a localized name cannot be found, use a
+    # humanized form of the fieldKey.
+    # Try to localize using the string "ErrorLabel.{ClassName}"
+    # Return a humanized form of the class name.
+    
+    @type String
+  */
+  errorLabel: function() {
+    var ret, fk, def ;
+    if (ret = this.get('fieldLabel')) return ret ;
+    
+    // if field label is not provided, compute something...
+    fk = this.get('fieldKey') || this.constructor.toString() ;
+    def = (fk || '').humanize().capitalize() ;
+    return "ErrorLabel.%@".fmt(fk)
+      .locWithDefault("FieldKey.%@".fmt(fk).locWithDefault(def)) ;
+      
+  }.property('fieldLabel','fieldKey').cacheable(),
+
+  /**
+    The control size.  This will set a CSS style on the element that can be 
+    used by the current theme to vary the appearance of the control.
+  */
+  controlSize: SC.REGULAR_CONTROL_SIZE,
+  
+  displayProperties: 'isEnabled isSelected isFirstResponder isActive'.w(),
+  
+  /** @private */
+  _CONTROL_TMP_CLASSNAMES: {},
+  
+  /**
+    Invoke this method in your updateDisplay() method to update any basic 
+    control CSS classes.
+  */
+  renderMixin: function(context, firstTime) {
+    var sel = this.get('isSelected'), disabled = !this.get('isEnabled');
+    
+    // update the CSS classes for the control.  note we reuse the same hash
+    // to avoid consuming more memory
+    var names = this._CONTROL_TMP_CLASSNAMES ; // temporary object
+    names.mixed = sel === SC.MIXED_STATE;
+    names.sel = sel && (sel !== SC.MIXED_STATE) ;
+    names.disabled = disabled ;
+    names.focus = this.get('isFirstResponder') ;
+    names.active = this.get('isActive') ;
+    context.setClass(names).addClass(this.get('controlSize'));
+    
+    // if the control implements the $input() helper, then fixup the input
+    // tags
+    if (!firstTime && this.$input) {
+      this.$input().attr('disabled', disabled);
+    }
+  },
+  
+  /** @private
+    This should be null so that if content is also null, the
+    _contentDidChange won't do anything on init.
+  */
+  _control_content: null,
+  
+  /** @private
+    Observes when a content object has changed and handles notifying 
+    changes to the value of the content object.
+  */
+  _control_contentDidChange: function() {
+    var content = this.get('content') ;
+    if (this._control_content === content) return; // nothing changed
+    
+    var f = this.contentPropertyDidChange ;
+    
+    // remove an observer from the old content if necessary
+    var old = this._control_content ;
+    if (old && old.removeObserver) old.removeObserver('*', this, f) ;
+    
+    // add observer to new content if necessary.
+    this._control_content = content ;
+    if (content && content.addObserver) content.addObserver('*', this, f) ;
+    
+    // notify that value did change.
+    this.contentPropertyDidChange(content, '*') ;
+    
+  }.observes('content')
+  
+};

data/frameworks/sproutcore/frameworks/foundation/mixins/editable.js

@@ -0,0 +1,146 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @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 ;
+  }
+
+} ;

data/frameworks/sproutcore/frameworks/foundation/mixins/responder.js

@@ -0,0 +1,156 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/** @static
+
+  The Responder mixin provides common methods needed to respond to user-interface events in SproutCore.
+  
+  @namespace
+  @since SproutCore 1.0
+*/
+SC.Responder = {
+
+  /** @property
+    The pane this responder belongs to.  This is used to determine where you 
+    belong to in the responder chain.
+  */
+  pane: null,
+  
+  /** @property
+    This is the nextResponder in the responder chain.  If the receiver does 
+    not implement a particular event handler, it will bubble to the next 
+    responder.
+  */
+  nextResponder: null,
+  
+  /** @property 
+    YES if the view is currently first responder.  This property is always 
+    edited by the pane during its makeFirstResponder() method.
+  */
+  isFirstResponder: NO,
+  
+  /** @property
+    YES if the view is currently first responder and the pane the view belongs 
+    to is also key pane.  While this property is set, you should expect to 
+    receive keyboard events.
+  */
+  isKeyResponder: NO,
+  
+  /** @property
+    Set to YES if your view is willing to accept first responder status.  This is used when calculcating key responder loop.
+  */
+  acceptsFirstResponder: NO,
+  
+  /** 
+    Call this method on your view or responder to make it become first responder.
+    
+    @returns {SC.Responder} receiver
+  */
+  becomeFirstResponder: function() {  
+    var pane = this.get('pane');
+    if (pane && this.get('acceptsFirstResponder')) {
+      if (pane.get('firstResponder') !== this) pane.makeFirstResponder(this);
+    } 
+    return this ;
+  },
+  
+  /**
+    Call this method on your view or responder to resign your first responder status. Normally this is not necessary since you will lose first responder status automatically when another view becomes first responder.
+    
+    @returns {SC.Responder} receiver
+  */
+  resignFirstResponder: function() {
+    var pane = this.get('pane');
+    if (pane && (pane.get('firstResponder') === this)) {
+      pane.makeFirstResponder(null);
+    }
+    return YES;  
+  },
+
+  /**
+    This method will be called just before you lose first responder status.
+  */
+  willLoseFirstResponder: function() {},
+  
+  /**
+    This method is invoked just before you lost the key responder status.  The passed view is the view that is about to gain keyResponder status.  This gives you a chance to do any early setup.
+    
+    Remember that you can gain/lose key responder status either because another view in the same pane is becoming first responder or because another pane is about to become key.
+    
+    @param {SC.Responder} responder
+  */
+  willLoseKeyResponderTo: function(responder) {},
+  
+  /**
+    This method is invoked just before you become the key responder.  The passed view is the view that is about to lose keyResponder status.  You can use this to do any setup before the view changes.
+    
+    Remember that you can gain/lose key responder status either because another view in the same pane is becoming first responder or because another pane is about to become key.
+    
+    @param {SC.Responder} responder
+  */
+  willBecomeKeyResponderFrom: function(responder) {},
+  
+  /**
+    Invokved just after the responder loses key responder status.
+  */
+  didLoseKeyResponderTo: function(responder) {},
+  
+  /**
+    Invoked just after the responder gains key responder status.
+  */
+  didBecomeKeyResponderFrom: function(responder) {},
+  
+  /**
+    This method will be called just before you become the first responder
+    so you can make changes.
+  */
+  didBecomeFirstResponder: function() {},
+  
+  /**
+    This method will process a key input event, attempting to convert it to an appropriate action method and sending it up the responder chain.  The event is converted using the SC.KEY_BINDINGS hash, which maps key events into method names.  If no key binding is found, then the key event will be passed along using an insertText() method.
+    
+    @param {SC.Event} event
+    @returns {Object} object that handled event, if any
+  */
+  interpretKeyEvents: function(event) {
+    var codes = event.commandCodes(), cmd = codes[0], chr = codes[1];
+
+    if (!cmd && !chr) return null ;  //nothing to do.
+
+    // if this is a command key, try to do something about it.
+    if (cmd) {
+      var methodName = SC.MODIFIED_KEY_BINDINGS[cmd] || SC.BASE_KEY_BINDINGS[cmd.match(/[^_]+$/)[0]];
+      if (methodName) {
+        var target = this, pane = this.get('pane'), handler = null;
+        while(target && !(handler = target.tryToPerform(methodName, event))){
+          target = (target===pane)? null: target.get('nextResponder') ;
+        }
+        return handler ;
+      }
+    } 
+
+    if (chr && this.respondsTo('insertText')) {
+      // if we haven't returned yet and there is plain text, then do an insert 
+      // of the text.  Since this is not an action, do not send it up the 
+      // responder chain.
+     return this.insertText(chr);
+    }
+
+    return null ; //nothing to do.
+  },
+  
+  /**
+    This method is invoked by interpretKeyEvents() when you receive a key event matching some plain text.  You can use this to actually insert the text into your application, if needed.
+    
+    @param {SC.Event} event
+    @returns {Object} receiver or object that handled event
+  */
+  insertText: function(chr) {
+    return this ;
+  }
+
+};