sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/desktop/views/scroller.js

@@ -0,0 +1,203 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+/** Vary based on current platform. */
+SC.NATURAL_SCROLLER_THICKNESS = 16;
+
+/** @class
+
+  Displays a horizontal or vertical scroller.  You will not usually need to
+  work with scroller views directly, but you may override this class to 
+  implement your own custom scrollers. 
+  
+  @extends SC.View
+  @since SproutCore 1.0
+*/
+SC.ScrollerView = SC.View.extend({
+  
+  // emptyElement: '<%@1><div class="sc-inner"></div></%@1>',
+  emptyElement: '<%@1></%@1>',
+  classNames: ['sc-scroller-view'],
+  
+  // ..........................................................
+  // PROPERTIES
+  // 
+
+  /** 
+   Used by the SC.ScrollView to properly layout the scrollers.
+  */
+  scrollerThickness: SC.NATURAL_SCROLLER_THICKNESS,
+  
+  /** 
+    The scroller offset value.  This value will adjust between the minimum
+    and maximum values that you set.
+    
+    @property
+  */
+  value: 0,
+  
+  /**
+    The minimum offset value for the scroller.  When the scroller is at the 
+    top/left, it will have this value.
+    
+    @property
+  */
+  minimum: 0,
+  
+  /**
+    The maximum offset value for the scroller.  This will be used to calculate
+    the internal height/width of the scroller itself.
+    
+    @property
+  */
+  maximum: 0,
+  
+  /**
+    YES if enable scrollbar, NO to disable it.  Scrollbars will automatically 
+    disable if the maximum scroll width does not exceed their capacity.
+    
+    @property
+  */
+  isEnabled: YES,
+  
+  /**
+    Determine the layout direction.  Determines whether the scrollbar should 
+    appear horizontal or vertical.  This must be set when the view is created.
+    Changing this once the view has been created will have no effect.
+    
+    @property
+  */
+  layoutDirection: SC.LAYOUT_VERTICAL,
+  
+  /**
+    Returns the owner view property the scroller should modify.  If this 
+    property is non-null and the owner view defines this property, then the 
+    scroller will automatically update this property whenever its own value 
+    changes.
+    
+    The default value of this property is computed based on the 
+    layoutDirection.  You can override this property to provide your own 
+    calculation if necessary or to return null if you want to disable this 
+    behavior.
+    
+    @property {String}
+  */
+  ownerScrollValueKey: function() {
+    var key = null;
+    switch(this.get('layoutDirection')) {
+      case SC.LAYOUT_VERTICAL:
+        key = 'verticalScrollOffset';
+        break;
+      case SC.LAYOUT_HORIZONTAL:
+        key = 'horizontalScrollOffset' ;
+        break;
+      default:
+        key = null ;
+    }
+    return key ;  
+  }.property('layoutDirection').cacheable(),
+  
+  // ..........................................................
+  // INTERNAL SUPPORT
+  // 
+  
+  displayProperties: 'value minimum maximum isEnabled'.w(),
+
+  /** @private
+    Update the scroll location or inner height/width if needed.
+  */
+  render: function(context, firstTime) {
+    // console.log('%@.render called'.fmt(this));
+    sc_super();
+    
+    var dir = this.get('layoutDirection');
+    var min = this.get('minimum'), max = this.get('maximum');
+    var enabled = this.get('isEnabled'), value = this.get('value');
+    
+    // console.log(dir) ;
+    
+    if (firstTime) {
+      if (dir===SC.LAYOUT_HORIZONTAL) context.addClass('sc-horizontal') ;
+      else context.addClass('sc-vertical') ;
+    }
+    
+    // calculate required size...
+    var size = (enabled) ? max-min-2 : 0 ;
+    switch (dir) {
+      case SC.LAYOUT_VERTICAL:
+        context.push('<div class="sc-inner" style="height: %@px"></div>'.fmt(size));
+        context.addStyle('scrollTop', value-min) ;
+        break;
+        
+      case SC.LAYOUT_HORIZONTAL:
+        context.push('<div class="sc-inner" style="width: %@px"></div>'.fmt(size));
+        context.addStyle('scrollLeft', value-min) ;
+        break;
+      
+      default:
+        break;
+    }
+  },
+  
+  didCreateLayer: function() {
+    // console.log('%@.didCreateLayer called'.fmt(this));
+    SC.Event.add(this.$(), 'scroll', this, this.scrollDidChange) ;
+  },
+  
+  didDestroyLayer: function() {
+    // console.log('%@.didDestroyLayer called'.fmt(this));
+    SC.Event.remove(this.$(), 'scroll', this, this.scrollDidChange) ;
+  },
+
+  /** 
+    Whenever the scroll location changes, simply set a timer to fire to 
+    update the scroll location and then exit.  It's important to minimize the
+    actual work done during an onscroll change since it will block the UI
+    from updating.
+  */
+  scrollDidChange: function() {
+    // schedule scrollDidChange to execute later if not already scheduled...
+    if (!this._scrollTimer) {
+      SC.RunLoop.begin();
+      this._scrollTimer = this.invokeLater(this._scroll_scrollDidChange, 1);
+      SC.RunLoop.end();
+    }
+  },
+  
+  _scroll_scrollDidChange: function() {
+    // console.log('%@._scroll_scrollDidChange called'.fmt(this));
+    this._scrollTimer = null; // clear so we can fire again
+    
+    if (!this.get('isEnabled')) return ; // nothing to do.
+    var dir = this.get('layoutDirection');
+    var loc = 0;
+    switch(dir) {
+      case SC.LAYOUT_VERTICAL:
+        loc = this.$().get(0).scrollTop;
+        break;
+        
+      case SC.LAYOUT_HORIZONTAL:
+        loc = this.$().get(0).scrollLeft;
+        break;
+      
+      default:
+        break;
+    }
+    
+    this.set('value', loc + this.get('minimum'));
+  },
+
+  /** @private Notify owner if it has a *ScrollOffset value */
+  _scroll_scrollDidChange2: function() {
+    // console.log('%@._scroll_scrollDidChange2 called'.fmt(this));
+    var key = this.get('ownerScrollValueKey');
+    if (key && this.owner && (this.owner[key] !== undefined)) {
+      this.owner.setIfChanged(key, this.get('value'));
+    }
+  }.observes('value')
+  
+}) ;

data/frameworks/sproutcore/frameworks/desktop/views/segmented.js

@@ -0,0 +1,509 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+/**
+  @class
+
+  SegmentedView is a special type of button that can display multiple
+  segments.  Each segment has a value assigned to it.  When the user clicks
+  on the segment, the value of that segment will become the new value of 
+  the control.
+  
+  You can also optionally configure a target/action that will fire whenever
+  the user clicks on an item.  This will give your code an opportunity to take
+  some action depending on the new value.  (of course, you can always bind to
+  the value as well, which is generally the preferred approach.)
+  
+  h1. Defining Your Segments
+  
+  You define your segments by providing a items array, much like you provide
+  to a RadioView.  Your items array can be as simple as an array of strings 
+  or as complex as full model objects.  Based on how you configure your
+  itemKey properties, the segmented view will read the properties it needs 
+  from the array and construct the button.
+  
+  You can define the following properties on objects you pass in:
+  
+  | *itemTitleKey* | the title of the button |
+  | *itemValueKey* | the value of the button |
+  | *itemWidthKey* | the preferred width. if omitted, it autodetects |
+  | *itemIconKey*  | an icon |
+  | *itemActionKey* | an optional action to fire when pressed |
+  | *itemTargetKey* | an optional target for the action |
+
+  @extends SC.View
+  @since SproutCore 1.0
+*/
+SC.SegmentedView = SC.View.extend(SC.Control,
+/** @scope SC.SegmentedView.prototype */ {
+  
+  classNames: ['sc-segmented-view'],
+  
+  /**
+    The value of the segmented view.
+    
+    The SegmentedView's value will always be the value of the currently
+    selected button.  Setting this value will change the selected button. 
+    If you set this value to something that has no matching button, then
+    no buttons will be selected.
+    
+    @field {Object}
+  */
+  value: null,
+
+  /**
+    Set to YES to enabled the segmented view, NO to disabled it.
+  */
+  isEnabled: YES, 
+
+  /**
+    If YES, clicking a selected button again will deselect it, setting the
+    segmented views value to null.  Defaults to NO.
+  */
+  allowsEmptySelection: NO,  
+  
+  /**
+    If YES, then clicking on a tab will not deselect the other segments, it
+    will simply add or remove it from the selection.
+  */
+  allowsMultipleSelection: NO,
+
+  /**
+    If YES, titles will be localized before display.
+  */
+  localize: YES,
+  
+  /**
+    Change the layout direction to make this a vertical set of tabs instead
+    of horizontal ones.
+  */
+  layoutDirection: SC.LAYOUT_HORIZONTAL,
+  
+  // ..........................................................
+  // SEGMENT DEFINITION
+  //
+   
+  /**
+    The array of items to display.  This can be a simple array of strings,
+    objects or hashes.  If you pass objects or hashes, you must also set the
+    various itemKey properties to tell the SegmentedView how to extract the
+    information it needs.
+    
+    @property {Array}
+  */
+  items: [],
+
+  /** 
+    The key that contains the title for each item.
+    
+    @property {String}
+  */
+  itemTitleKey: null,
+  
+  /** 
+    The key that contains the value for each item.
+    
+    @property {String}
+  */
+  itemValueKey: null,
+  
+  /** 
+    A key that determines if this item in particular is enabled.  Note if the
+    control in general is not enabled, no items will be enabled, even if the
+    item's enabled property returns YES.
+    
+    @property {String}
+  */
+  itemIsEnabledKey: null,
+
+  /** 
+    The key that contains the icon for each item.  If omitted, no icons will
+    be displayed.
+    
+    @property {String}
+  */
+  itemIconKey: null,
+
+  /** 
+    The key that contains the desired width for each item.  If omitted, the
+    width will autosize.
+  
+    @property {String}
+  */
+  itemWidthKey: null,
+  
+  /** 
+    The key that contains the action for this item.  If defined, then 
+    selecting this item will fire the action in addition to changing the 
+    value.  See also itemTargetKey.
+    
+    @property {String}
+  */
+  itemActionKey: null,
+
+  /** 
+    The key that contains the target for this item.  If this and itemActionKey
+    are defined, then this will be the target of the action fired. 
+    
+    @property {String}
+  */
+  itemTargetKey: null,
+
+  /** 
+    The key that contains the key equivalent for each item.  If defined then
+    pressing that key equivalent will be like selecting the tab.  Also, 
+    pressing the Alt or Option key for 3 seconds will display the key 
+    equivalent in the tab.
+  */
+  itemKeyEquivalentKey: null,
+
+  /**
+    The array of itemKeys that will be searched to build the displayItems
+    array.  This is used internally by the class.  You will not generally
+    need to access or edit this array.
+    
+    @property {Array}
+  */
+  itemKeys: 'itemTitleKey itemValueKey itemIsEnabledKey itemIconKey itemWidthKey'.w(),
+  
+  /**
+    This computed property is generated from the items array based on the 
+    itemKey properties that you set.  The return value is an array of arrays
+    that contain private information used by the SegmentedView to render. 
+    
+    You will not generally need to access or edit this property.
+    
+    @property {Array}
+  */
+  displayItems: function() {
+    var items = this.get('items'), loc = this.get('localize') ;
+    var keys=null, itemType, cur ;
+    var ret = [], max = items.get('length'), idx, item ;
+    var fetchKeys = SC._segmented_fetchKeys;
+    var fetchItem = SC._segmented_fetchItem;
+    
+    // loop through items and collect data
+    for(idx=0;idx<max;idx++) {
+      item = items.objectAt(idx) ;
+      if (SC.none(item)) continue; //skip is null or undefined
+
+      // if the item is a string, build the array using defaults...
+      itemType = SC.typeOf(item);
+      if (itemType === SC.T_STRING) {
+        cur = [item.humanize().titleize(), item, YES, null, null, idx] ;
+        
+      // if the item is not an array, try to use the itemKeys.
+      } else if (itemType !== SC.T_ARRAY) {
+        
+        // get the itemKeys the first time
+        if (keys===null) {
+          keys = this.itemKeys.map(fetchKeys,this);
+        }
+        
+        // now loop through the keys and try to get the values on the item
+        cur = keys.map(fetchItem, item);
+        cur[cur.length] = idx; // save current index
+        
+        // special case 1...if title key is null, try to make into string
+        if (!keys[0] && item.toString) cur[0] = item.toString();
+        
+        // special case 2...if value key is null, use item itself
+        if (!keys[1]) cur[1] = item;
+        
+        // special case 3...if isEnabled is null, default to yes.
+        if (!keys[2]) cur[2] = YES ; 
+      }
+      
+      // finally, be sure to loc the title if needed
+      if (loc && cur[0]) cur[0] = cur[0].loc();
+      
+      // add to return array
+      ret[ret.length] = cur;
+    }
+    
+    // all done, return!
+    return ret ;
+  }.property('items', 'itemTitleKey', 'itemValueKey', 'itemIsEnabledKey', 'localize', 'itemIconKey', 'itemWidthKey').cacheable(),
+  
+  /** If the items array itself changes, add/remove observer on item... */
+  itemsDidChange: function() { 
+    if (this._items) {
+      this._items.removeObserver('[]',this,this.itemContentDidChange) ;
+    } 
+    this._items = this.get('items') ;
+    if (this._items) {
+      this._items.addObserver('[]', this, this.itemContentDidChange) ;
+    }
+    this.itemContentDidChange();
+  }.observes('items'),
+  
+  /** 
+    Invoked whenever the item array or an item in the array is changed.  This method will reginerate the list of items.
+  */
+  itemContentDidChange: function() {
+    this.notifyPropertyChange('displayItems');
+  },
+  
+  init: function() {
+    sc_super();
+    this.itemsDidChange() ;
+  },
+
+  
+  // ..........................................................
+  // RENDERING/DISPLAY SUPPORT
+  // 
+  
+  displayProperties: ['displayItems', 'value', 'activeIndex'],
+  
+  
+  render: function(context, firstTime) { 
+    
+    // collect some data 
+    var items = this.get('displayItems');
+    
+    // regenerate the buttons only if the new display items differs from the
+    // last cached version of it needsFirstDisplay is YES.
+    var last = this._seg_displayItems;
+    if (firstTime || (items !== last)) {
+      this._seg_displayItems = items; // save for future
+      this.renderDisplayItems(context, items) ;
+      context.addStyle('text-align', 'center');
+    }else{
+    // update selection and active state
+      var activeIndex = this.get('activeIndex');
+      var value = this.get('value');
+      var isArray = SC.isArray(value);
+      if (isArray && value.get('length')===1) {
+        value = value.objectAt(0); isArray = NO ;
+      }
+      var names = {}; // reuse
+    
+      var loc = items.length, cq = this.$('a.sc-segment'), item;
+      while(--loc>=0) {
+        item = items[loc];
+        names.sel = isArray ? (value.indexOf(item[1])>=0) : (item[1]===value);
+        names.active = (activeIndex === loc);
+        SC.$(cq.get(loc)).setClass(names);
+      }
+      names = items = value = items = null; // cleanup
+    }
+  },
+  
+  /**
+    Actually generates the segment HTML for the display items.  This method 
+    is called the first time a view is constructed and any time the display
+    items change thereafter.  This will construct the HTML but will not set
+    any "transient" states such as the global isEnabled property or selection.
+  */
+  renderDisplayItems: function(context, items) {
+    var title = null, icon = null, url=null, className=null, ic=null, item=null;
+    var value = this.get('value');
+    var isArray = SC.isArray(value);
+    var activeIndex = this.get('activeIndex');
+    var len= items.length;
+    for(var i=0; i< len; i++){
+      ic = context.begin('a').attr('href', 'javascript:;');
+      item=items[i];
+      title = item[0]; 
+      icon = item[3];
+      ic.addStyle('display', 'inline-block');
+      ic.addClass('sc-segment');
+      if(!item[2]){
+        ic.addClass('disabled');
+      }
+      if(i===0){
+        ic.addClass('sc-first-segment');
+      }
+      if(i===(len-1)){
+        ic.addClass('sc-last-segment');
+      }
+      if(i!==0 && i!==(len-1)){
+        ic.addClass('sc-middle-segment');
+      }      
+      if( isArray ? (value.indexOf(item[1])>=0) : (item[1]===value)){
+        ic.addClass('sel');
+      }
+      if(activeIndex === i) {
+        ic.addClass('active') ;
+      }
+      if(item[4]){
+        width=item[4];
+        ic.addStyle('width', width+'px');
+      }
+      if (icon) {
+        url = (icon.indexOf('/')>=0) ? icon : static_url('blank');
+        className = (url === icon) ? '' : icon ;
+        icon = '<img src="'+url+'" alt="" class="icon '+className+'" />';
+      } else {
+        icon = '';
+      }
+      ic.push('<span class="sc-button-inner"><label class="sc-button-label">');
+      ic.push(icon+title);
+      ic.push('</label></span>');
+      ic.end();
+    }   
+  },  
+  // ..........................................................
+  // EVENT HANDLING
+  // 
+  
+  /** 
+    Determines the index into the displayItems array where the passed mouse
+    event occurred.
+  */
+  displayItemIndexForEvent: function(evt) {
+    var elem = SC.$(evt.target) ;
+    if (!elem || elem===document) return -1; // nothing found
+
+    // start at the target event and go upwards until we reach either the 
+    // root responder or find an anchor.sc-segment.
+    var root = this.$(), match = null ;
+    while(!match && (elem.length>0) && (elem.get(0)!==root.get(0))) {
+      if (elem.hasClass('sc-segment') && elem.attr('tagName')==='A') {
+        match = elem;
+      } else elem = elem.parent();
+    }
+    
+    elem = root = null;
+    
+    // if a match was found, return the index of the match in subtags
+    return (match) ? this.$('a.sc-segment').index(match) : -1;
+  },
+  
+  mouseDown: function(evt) {
+    if (!this.get('isEnabled')) return YES; // nothing to do
+    var idx = this.displayItemIndexForEvent(evt);
+    
+    // if mouse was pressed on a button, then start detecting pressed events
+    if (idx>=0) {
+      this._isMouseDown = YES ;
+      this.set('activeIndex', idx);
+    }
+    
+    return YES ;
+  },
+  
+  mouseUp: function(evt) {
+    var idx = this.displayItemIndexForEvent(evt);
+    
+    // if mouse was pressed on a button then detect where we where when we
+    // release and use that one.
+    if (this._isMouseDown && (idx>=0)) this.triggerItemAtIndex(idx);
+    
+    // cleanup
+    this._isMouseDown = NO ;
+    this.set('activeIndex', -1);
+    return YES ;
+  },
+  
+  mouseMoved: function(evt) {
+    var idx = this.displayItemIndexForEvent(evt);
+    if (this._isMouseDown) this.set('activeIndex', idx);
+    return YES;
+  },
+  
+  mouseOver: function(evt) {
+    // if mouse was pressed down initially, start detection again
+    var idx = this.displayItemIndexForEvent(evt);
+    if (this._isMouseDown) this.set('activeIndex', idx);
+    return YES;
+  },
+  
+  mouseOut: function(evt) {
+    // if mouse was down, hide active index
+    if (this._isMouseDown) this.set('activeIndex', -1);
+    return YES ;
+  },
+  
+  /** 
+    Simulates the user clicking on the segment at the specified index. This
+    will update the value if possible and fire the action.
+  */
+  triggerItemAtIndex: function(idx) {
+    var items = this.get('displayItems') ;
+    var item = items.objectAt(idx);
+    if (!item[2]) return this; // nothing to do!
+
+    var empty = this.get('allowsEmptySelection');
+    var mult = this.get('allowsMultipleSelection');
+    
+    // get new value... bail if not enabled
+    var sel = item[1];
+    var value = this.get('value') ;
+    if (!SC.isArray(value)) value = [value]; // force to array
+    
+    // if we do not allow multiple selection, either replace the current
+    // selection or deselect it
+    if (!mult) {
+      // if we allow empty selection and the current value is the same as
+      // the selected value, then deselect it.
+      if (empty && (value.get('length')===1) && (value.objectAt(0)===sel)){
+        value = [];
+      
+      // otherwise, simply replace the value.
+      } else value = [sel] ;
+      
+    // if we do allow multiple selection, then add or remove item to the
+    // array.
+    } else {
+      if (value.indexOf(sel) >= 0) {
+        if (value.get('length')>1 || (value.objectAt(0)!==sel) || empty) {
+          value = value.without(sel);
+        }
+      } else value = value.concat([sel]) ;
+    }
+    
+    // normalize back to non-array form
+    switch(value.get('length')) {
+      case 0:
+        value = null;
+        break;
+      case 1:
+        value = value.objectAt(0);
+        break;
+      default:
+        break;
+    }
+    
+    // set the new value
+    this.set('value', value);
+    
+    // also, trigger target if needed.
+    var actionKey = this.get('itemActionKey');
+    var targetKey = this.get('itemTargetKey');
+    var action, target = null;
+    var resp = this.getPath('pane.rootResponder');
+    if (actionKey && (item = this.get('items').objectAt(item[5]))) {
+      // get the source item from the item array.  use the index stored...
+      action = item.get ? item.get(actionKey) : item[actionKey];
+      if (targetKey) {
+        target = item.get ? item.get(targetKey) : item[targetKey];
+      }
+      
+      if (resp) resp.sendAction(action, target, this, this.get('pane'));
+    }
+    
+    // if an action/target is defined on self use that also
+    action =this.get('action');
+    if (action && resp) {
+      resp.sendAction(action, this.get('target'), this, this.get('pane'));
+    }
+  }
+    
+}) ;
+
+// Helpers defined here to avoid creating lots of closures...
+SC._segmented_fetchKeys = function(k) { return this.get(k); };
+SC._segmented_fetchItem = function(k) { 
+  if (!k) return null;
+  return this.get ? this.get(k) : this[k]; 
+};
+
+
+
+