sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/foundation/views/field.js

@@ -0,0 +1,276 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+sc_require('views/view') ;
+sc_require('mixins/control') ;
+sc_require('mixins/validatable') ;
+
+/** @class
+
+  Base view for managing a view backed by an input element.  Since the web
+  browser provides native support for editing input elements, this view
+  provides basic support for listening to changes on these input elements and
+  responding to them.
+  
+  Generally you will not work with a FieldView directly.  Instead, you should
+  use one of the subclasses implemented by your target platform such as 
+  SC.CheckboxView, SC.RadioView, SC.TextFieldView, and so on.
+  
+  @extends SC.View
+  @extends SC.Control
+  @extends SC.Validatable
+  @since SproutCore 1.0
+*/
+SC.FieldView = SC.View.extend(SC.Control, SC.Validatable,
+/** @scope SC.FieldView.prototype */ {
+
+  /**
+    The raw value of the field itself.  This is computed from the 'value'
+    propery by passing it through any validator you might have set.  This is 
+    the value that will be set on the field itself when the view is updated.
+    
+    @property {String}
+  */  
+  fieldValue: function() {
+    var value = this.get('value');
+    if (SC.typeOf(value) === SC.T_ERROR) value = value.get('value');
+    return this.fieldValueForObject(value);
+  }.property('value', 'validator').cacheable(),
+
+  // ..........................................................
+  // PRIMITIVES
+  // 
+  
+  /**
+    Override to return an CoreQuery object that selects the input elements
+    for the view.  If this method is defined, the field view will 
+    automatically edit the attrbutes of the input element to reflect the 
+    current isEnabled state among other things.
+  */
+  $input: function() { 
+    return this.$('input').andSelf().filter('input'); 
+  },
+  
+  /**
+    Override to set the actual value of the field.
+
+    The default implementation will simple copy the newValue to the value
+    attribute of any input tags in the receiver view.  You can override this
+    method to provide specific functionality needed by your view.
+    
+    @param {Object} newValue the value to display.
+    @returns {SC.FieldView} receiver
+  */
+  setFieldValue: function(newValue) {
+    if (SC.none(newValue)) newValue = '' ;
+    this.$input().val(newValue);
+    return this ;
+  },
+
+  /**
+    Override to retrieve the actual value of the field.
+    
+    The default implementation will simply retrieve the value attribute from
+    the first input tag in the receiver view.
+    
+    @returns {String} value
+  */
+  getFieldValue: function() {
+    return this.$input().val();
+  },
+  
+  _field_fieldValueDidChange: function(evt) {
+    SC.RunLoop.begin();
+    this.fieldValueDidChange(NO);
+    SC.RunLoop.end();  
+  },
+  
+  /**
+    Your class should call this method anytime you think the value of the 
+    input element may have changed.  This will retrieve the value and update
+    the value property of the view accordingly.
+    
+    If this is a partial change (i.e. the user is still editing the field and
+    you expect the value to change further), then be sure to pass YES for the
+    partialChange parameter.  This will change the kind of validation done on
+    the value.  Otherwise, the validator may mark the field as having an error
+    when the user is still in mid-edit.
+  
+    @param partialChange (optional) YES if this is a partial change.
+    @returns {Boolean|SC.Error} result of validation.
+  */
+  fieldValueDidChange: function(partialChange) {
+
+    // collect the field value and convert it back to a value
+    var fieldValue = this.getFieldValue();
+    var value = this.objectForFieldValue(fieldValue, partialChange);
+    this.setIfChanged('value', value);
+    
+    // validate value if needed...
+    
+    // this.notifyPropertyChange('fieldValue');
+    // 
+    // // get the field value and set it.
+    // // if ret is an error, use that instead of the field value.
+    // var ret = this.performValidate ? this.performValidate(partialChange) : YES;
+    // if (ret === SC.VALIDATE_NO_CHANGE) return ret ;
+    // 
+    // this.propertyWillChange('fieldValue');
+    // 
+    // // if the validator says everything is OK, then in addition to posting
+    // // out the value, go ahead and pass the value back through itself.
+    // // This way if you have a formatter applied, it will reformat.
+    // //
+    // // Do this BEFORE we set the value so that the valueObserver will not
+    // // overreact.
+    // //
+    // var ok = SC.$ok(ret);
+    // var value = ok ? this._field_getFieldValue() : ret ;
+    // if (!partialChange && ok) this._field_setFieldValue(value) ;
+    // this.set('value',value) ;
+    // 
+    // this.propertyDidChange('fieldValue');
+    // 
+    // return ret ;
+  },
+  
+  // ..........................................................
+  // INTERNAL SUPPORT
+  // 
+  
+  /** @private
+    invoked when the value property changes.  Sets the field value...
+  */
+  _field_valueDidChange: function() {
+    this.setFieldValue(this.get('fieldValue'));
+  }.observes('value'),
+
+  /** @private
+    after the layer is created, set the field value and observe events
+  */
+  didCreateLayer: function() {
+    this.setFieldValue(this.get('fieldValue'));
+    SC.Event.add(this.$input(), 'change', this, this._field_fieldValueDidChange) ;
+  },
+  
+  willDestroyLayer: function() {
+    SC.Event.remove(this.$input(), 'change', this, this._field_fieldValueDidChange); 
+  },
+
+  /** @private
+    when the layer is updated, go ahead and call render like normal.  this 
+    will allow normal CSS class + style updates.  by then also update field
+    value manually.
+    
+    Most subclasses should not regenerate their contents unless necessary.
+  */
+  updateLayer: function() {
+    sc_super();
+    
+    // only change field value if it has changed from the last time we 
+    // set it.  This allows the browser-native field value to change without
+    // this method interfering with it.
+    var fieldValue = this.get('fieldValue');
+    this.setFieldValue(fieldValue);
+  },
+  
+  // ACTIONS
+  // You generally do not need to override these but they may be used.
+
+  /**
+    Called to perform validation on the field just before the form 
+    is submitted.  If you have a validator attached, this will get the
+    validators.
+  */  
+  // validateSubmit: function() {
+  //   var ret = this.performValidateSubmit ? this.performValidateSubmit() : YES;
+  //   // save the value if needed
+  //   var value = SC.$ok(ret) ? this._field_getFieldValue() : ret ;
+  //   if (value != this.get('value')) this.set('value', value) ;
+  //   return ret ;
+  // },
+  
+  // OVERRIDE IN YOUR SUBCLASS
+  // Override these primitives in your subclass as required.
+
+  /**
+    Allow the browser to do its normal event handling for the mouse down
+    event.  But first, set isActive to YES.
+  */
+  mouseDown: function(evt) { 
+    if (this.get('isEnabled')) {
+      this.set('isActive', YES); 
+      this._field_isMouseDown = YES;
+    }
+    evt.allowDefault(); 
+    return YES; 
+  },
+
+  /** @private
+    Remove the active class on mouseOut if mouse is down.
+  */  
+  mouseOut: function(evt) {
+    if (this._field_isMouseDown) this.set('isActive', NO);
+    evt.allowDefault();
+    return YES;
+  },
+
+  /** @private
+    If mouse was down and we renter the button area, set the active state again.
+  */  
+  mouseOver: function(evt) {
+    this.set('isActive', this._field_isMouseDown);
+    evt.allowDefault();
+    return YES;
+  },
+
+  _field_isMouseDown: NO,
+  
+  /** @private
+    on mouse up, remove the isActive class and then allow the browser to do
+    its normal thing.
+  */  
+  mouseUp: function(evt) {
+    // track independently in case isEnabled has changed
+    if (this._field_isMouseDown) this.set('isActive', NO); 
+    this._field_isMouseDown = false;
+    evt.allowDefault();
+    return YES ;
+  },
+  
+  // called whenever the value is set on the object.  Will set the value
+  // on the field if the value is changed.
+  // valueDidChange: function() {
+  //   var value = this.get('value') ;
+  //   var isError = SC.typeOf(value) === SC.T_ERROR ;
+  //   if (!isError && (value !== this._field_getFieldValue())) {
+  //     this._field_setFieldValue(value) ;
+  //   } 
+  // }.observes('value'),
+  
+  // these methods use the validator to convert the raw field value returned
+  // by your subclass into an object and visa versa.
+  _field_setFieldValue: function(newValue) {
+    
+    this.propertyWillChange('fieldValue');
+    if (this.fieldValueForObject) {
+      newValue = this.fieldValueForObject(newValue) ;
+    }
+    var ret = this.setFieldValue(newValue) ;
+    this.propertyDidChange('fieldValue');
+    return ret ;
+  },
+  
+  _field_getFieldValue: function() {
+    var ret = this.getFieldValue() ;
+    if (this.objectForFieldValue) ret=this.objectForFieldValue(ret);
+    return ret ;
+  }
+  
+}) ;
+
+

data/frameworks/sproutcore/frameworks/foundation/views/image.js

@@ -0,0 +1,158 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+sc_require('views/view') ;
+sc_require('mixins/control') ;
+
+SC.IMAGE_STATE_NONE = 'none';
+SC.IMAGE_STATE_LOADING = 'loading';
+SC.IMAGE_STATE_LOADED = 'loaded';
+SC.IMAGE_STATE_FAILED = 'failed';
+SC.IMAGE_STATE_SPRITE = 'sprite';
+
+/**
+  URL to a transparent GIF.  Used for spriting.
+*/
+SC.BLANK_IMAGE_URL = sc_static('blank.gif');
+
+/**
+  @class
+
+  Displays an image in the browser.  
+  
+  The ImageView can be used to efficiently display images in the browser.
+  It includes a built in support for a number of features that can improve
+  your page load time if you use a lot of images including a image loading
+  queue and automatic support for CSS spriting.
+
+  Note that there are actually many controls that will natively include 
+  images using an icon property name.
+  
+  @extends SC.View
+  @extends SC.Control
+  @since SproutCore 1.0
+*/
+SC.ImageView = SC.View.extend(SC.Control, 
+/** @scope SC.ImageView.prototype */ {
+  
+  /** Image views contain an img tag. */
+  classNames: 'sc-image-view',
+  tagName: 'img',
+  
+  /**
+    Current load status of the image.
+    
+    This status changes as an image is loaded from the server.  If spriting
+    is used, this will always be loaded.  Must be one of the following
+    constants: SC.IMAGE_STATE_NONE, SC.IMAGE_STATE_LOADING, 
+    SC.IMAGE_STATE_LOADED, SC.IMAGE_STATE_FAILED, SC.IMAGE_STATE_SPRITE
+    
+    @property {String}
+  */
+  status: SC.IMAGE_STATE_NONE,
+  
+  /**
+    A url or CSS class name.
+    
+    This is the image you want the view to display.  It should be either a
+    url or css class name.  You can also set the content and 
+    contentValueKey properties to have this value extracted 
+    automatically.
+    
+    If you want to use CSS spriting, set this value to a CSS class name.  If
+    you need to use multiple class names to set your icon, separate them by
+    spaces.
+    
+    Note that if you provide a URL, it must contain at least one '/' as this
+    is how we autodetect URLs.
+    
+    @property {String}
+  */
+  value: null,
+
+  /**
+    If YES, image view will use the imageCache to control loading.  This 
+    setting is generally preferred.
+    
+    @property {String}
+  */
+  useImageCache: YES,
+  
+  /**
+    If YES, this image can load in the background.  Otherwise, it is treated
+    as a foreground image.  If the image is not visible on screen, it will
+    always be treated as a background image.
+  */
+  canLoadInBackground: NO,
+  
+  displayProperties: 'status'.w(),
+  
+  render: function(context, firstTime) {
+    // the image source is the value if the status is LOADED or blank
+    var status = this.get('status'), value = this.get('value');
+    
+    if (status === SC.IMAGE_STATE_NONE && value) this._image_valueDidChange() ; // setup initial state
+    
+    var src = (status === SC.IMAGE_STATE_LOADED) ? value : SC.BLANK_IMAGE_URL;
+    if (status === SC.IMAGE_STATE_SPRITE) context.addClass(value);
+    context.attr('src', src);
+  },
+  
+  /** @private - 
+    Whenever the value changes, update the image state and possibly schedule
+    an image to load.
+  */
+  _image_valueDidChange: function() {
+    var value = this.get('value'), isUrl = SC.ImageView.valueIsUrl(value);
+    
+    // if the old image is still loading, cancel it
+    // if (this._loadingUrl) SC.imageCache.abortImage(this._loadingUrl);
+    
+    // now update local state as needed....
+    if (isUrl && this.get('useImageCache')) {
+      var isBackground = this.get('isVisibleInWindow') || this.get('canLoadInBackground');
+      
+      this._loadingUrl = value ; // note that we're loading...
+      SC.imageCache.loadImage(value, this, this.imageDidLoad, isBackground);
+      
+      // only mark us as loading if we are still loading...
+      if (this._loadingUrl) this.set('status', SC.IMAGE_STATE_LOADING);
+      
+    // otherwise, just set state immediately
+    } else {
+      this._loadingUrl = null ; // not loading...
+      this.set('status', (isUrl) ? SC.IMAGE_STATE_LOADED : SC.IMAGE_STATE_SPRITE);
+      this.displayDidChange(); // call manually in case status did not change
+      // (e.g value changes from one sprite to another)
+    }
+  }.observes('value'),
+  
+  /** 
+    Called when the imageCache indicates that the image has loaded. 
+    Changing the image state will update the display.
+  */
+  imageDidLoad: function(url, imageOrError) {
+    if (url === this._loadingUrl) this._loadingUrl = null;
+
+    // do nothing if we get this notification by the value of the image has 
+    // since changed.
+    if (this.get('value') === url) {
+      this.set('status', SC.$ok(imageOrError) ? SC.IMAGE_STATE_LOADED : SC.IMAGE_STATE_FAILED);
+      this.displayDidChange();
+    }
+  }
+  
+}) ;
+
+/**
+  Returns YES if the passed value looks like an URL and not a CSS class
+  name.
+*/
+SC.ImageView.valueIsUrl = function(value) {
+  return value ? value.indexOf('/') >= 0 : NO ;
+} ;
+

data/frameworks/sproutcore/frameworks/foundation/views/label.js

@@ -0,0 +1,261 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+sc_require('views/view') ;
+sc_require('mixins/control') ;
+
+SC.ALIGN_LEFT = 'left';
+SC.ALIGN_RIGHT = 'right';
+SC.ALIGN_CENTER = 'center';
+
+SC.REGULAR_WEIGHT = 'normal';
+SC.BOLD_WEIGHT = 'bold';
+
+/**
+  @class
+  
+  Displays a static string of text.
+  
+  You use a label view anytime you need to display a static string of text 
+  or to display text that may need to be edited using only an inline control.
+  
+  @extends SC.View
+  @extends SC.Control
+  @extends SC.InlineEditorDelegate
+  @since SproutCore 1.0
+*/
+SC.LabelView = SC.View.extend(SC.Control,
+/** @scope SC.LabelView.prototype */ {
+
+  classNames: ['sc-label-view'],
+
+  /**
+    Specify the font weight for this.  You may pass SC.REGULAR_WEIGHT, or SC.BOLD_WEIGHT.
+  */
+  fontWeight: SC.REGULAR_WEIGHT,
+  
+  /**
+    If true, value will be escaped to avoid scripting attacks.
+    
+    This is a default value that can be overridden by the
+    settings on the owner view.
+  */
+  escapeHTML: true,
+  escapeHTMLBindingDefault: SC.Binding.oneWay().bool(),
+
+  /**
+    If true, then the value will be localized.
+    
+    This is a default default that can be overidden by the
+    settings in the owner view.
+  */
+  localize: false,
+  localizeBindingDefault: SC.Binding.oneWay().bool(),
+  
+  /**
+    Set this to a validator or to a function and the value
+    will be passed through it before being set.
+    
+    This is a default default that can be overidden by the
+    settings in the owner view.
+  */
+  formatter: null,
+
+  /** 
+    The value of the label.
+    
+    You may also set the value using a content object and a contentValueKey.
+    
+    @field {String}
+  */
+  value: '',
+  
+  /**
+    An optional icon to display to the left of the label.  Set this value
+    to either a CSS class name (for spriting) or an image URL.
+  */
+  icon: null,
+  
+  /**
+    Set the alignment of the label view.
+  */
+  textAlign: SC.ALIGN_LEFT,
+  
+  /**
+    [RO] The value that will actually be displayed.
+    
+    This property is dynamically computed by applying localization, 
+    string conversion and other normalization utilities.
+    
+    @field
+  */
+  displayValue: function() {
+    var value = this.get('value') ;
+    
+    // 1. apply the formatter
+    var formatter = this.getDelegateProperty(this.displayDelegate, 'formatter') ;
+    if (formatter) {
+      var formattedValue = (SC.typeOf(formatter) === SC.T_FUNCTION) ? formatter(value, this) : formatter.fieldValueForObject(value, this) ;
+      if (!SC.none(formattedValue)) value = formattedValue ;
+    }
+    
+    // 2. If the returned value is an array, convert items to strings and 
+    // join with commas.
+    if (SC.typeOf(value) === SC.T_ARRAY) {
+      var ary = [];
+      for(var idx=0;idx<value.get('length');idx++) {
+        var x = value.objectAt(idx) ;
+        if (!SC.none(x) && x.toString) x = x.toString() ;
+        ary.push(x) ;
+      }
+      value = ary.join(',') ;
+    }
+    
+    // 3. If value is not a string, convert to string. (handles 0)
+    if (!SC.none(value) && value.toString) value = value.toString() ;
+    
+    // 4. Localize
+    if (value && this.getDelegateProperty(this.displayDelegate, 'localize')) value = value.loc() ;
+
+    // 5. escapeHTML if needed
+    if (this.get('escapeHTML')) value = SC.RenderContext.escapeHTML(value);
+    
+    return value ;
+  }.property('value', 'localize', 'formatter', 'escapeHTML').cacheable(),
+  
+  /**
+    Enables editing using the inline editor.
+  */
+  isEditable: NO,
+  isEditableBindingDefault: SC.Binding.bool(),
+
+  /**
+    YES if currently editing label view.
+  */
+  isEditing: NO,
+  
+  /**
+    Validator to use during inline editing.
+    
+    If you have set isEditing to YES, then any validator you set on this
+    property will be used when the label view is put into edit mode.
+    
+    @type {SC.Validator}
+  */
+  validator: null,
+
+  /**
+    Event dispatcher callback.
+    If isEditable is set to true, opens the inline text editor view.
+
+    @param {DOMMouseEvent} evt DOM event
+    
+  */
+  doubleClick: function( evt ) { return this.beginEditing(); },
+  
+  
+  /**
+    Opens the inline text editor (closing it if it was already open for 
+    another view).
+    
+    @return {Boolean} YES if did begin editing
+  */
+  beginEditing: function() {
+    if (this.get('isEditing')) return YES ;
+    if (!this.get('isEditable')) return NO ;
+    
+    var value = this.get('value') || '' ;
+    var f = this.convertFrameToView(this.get('frame'), null) ;
+    var el = this.rootElement;
+    SC.InlineTextFieldView.beginEditing({
+      frame: f,
+      delegate: this,
+      exampleElement: el,
+      value: value, 
+      multiline: NO, 
+      validator: this.get('validator')
+    });
+  },
+  
+  /**
+    Cancels the current inline editor and then exits editor. 
+    
+    @return {Boolean} NO if the editor could not exit.
+  */
+  discardEditing: function() {
+    if (!this.get('isEditing')) return YES ;
+    return SC.InlineTextFieldView.discardEditing() ;
+  },
+  
+  /**
+    Commits current inline editor and then exits editor.
+    
+    @return {Boolean} NO if the editor could not exit
+  */
+  commitEditing: function() {
+    if (!this.get('isEditing')) return YES ;
+    return SC.InlineTextFieldView.commitEditing() ;
+  },
+
+  /** @private
+    Set editing to true so edits will no longer be allowed.
+  */
+  inlineEditorWillBeginEditing: function(inlineEditor) {
+    this.set('isEditing', YES);
+  },
+
+  /** @private 
+    Hide the label view while the inline editor covers it.
+  */
+  inlineEditorDidBeginEditing: function(inlineEditor) {
+    this._oldOpacity = this.$().css('opacity') ;
+    this.$().css('opacity', 0.0);
+  },
+
+  /** @private
+    Could check with a validator someday...
+  */
+  inlineEditorShouldEndEditing: function(inlineEditor, finalValue) {
+    return YES ;
+  },
+
+  /** @private
+    Update the field value and make it visible again.
+  */
+  inlineEditorDidEndEditing: function(inlineEditor, finalValue) {
+    this.setIfChanged('value', finalValue) ;
+    this.$().css('opacity', this._oldOpacity);
+    this._oldOpacity = null ;
+    this.set('isEditing', NO) ;
+  },
+
+  displayProperties: ['displayValue', 'textAlign', 'fontWeight', 'icon'],
+  
+  render: function(context, firstTime) {
+    var value = this.get('displayValue');
+    var icon = this.get('icon') ;
+    
+    // add icon if needed
+    if (icon) {
+      var url = (icon.indexOf('/')>=0) ? icon : static_url('blank');
+      var className = (url === icon) ? '' : icon ;
+      icon = '<img src="%@" alt="" class="icon %@" />'.fmt(url, className) ;
+      context.push(icon);
+    }
+    
+    // add display value
+    context.push(value);
+    
+    // and setup alignment and font-weight on styles
+    context.addStyle('text-align',  this.get('textAlign'))
+           .addStyle('font-weight', this.get('fontWeight'));
+           
+    // if we are editing, set the opacity to 0
+    if (this.get('isEditing')) context.addStyle('opacity', 0.0);
+  }
+  
+});