sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

data/frameworks/sproutcore/frameworks/desktop/mixins/collection_group.js

@@ -0,0 +1,22 @@
+// ==========================================================================
+// 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
+
+  TODO: Add full description of SC.CollectionGroup
+  
+  Any view you want to use as a group view in a collection must include this
+  mixin.
+  
+  @since SproutCore 1.0
+*/
+SC.CollectionGroup = {
+  
+  classNames: ['sc-collection-group']
+  
+};

data/frameworks/sproutcore/frameworks/desktop/mixins/collection_row_delegate.js

@@ -0,0 +1,61 @@
+// ==========================================================================
+// 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
+  
+  CollectionRowDelegates are consulted by SC.ListView and SC.TableView to 
+  control the height of rows, including specifying custom heights for 
+  specific rows.  
+  
+  You can implement a custom row height in one of two ways.  
+  
+*/
+SC.CollectionRowDelegate = {
+
+  /** walk like a duck */
+  isCollectionRowDelegate: YES,
+  
+  /**
+    Default row height.  Unless you implement some custom row height 
+    support, this row height will be used for all items.
+    
+    @property
+    @type Number
+  */
+  rowHeight: 18,
+
+  /**
+    Index set of rows that should have a custom row height.  If you need 
+    certains rows to have a custom row height, then set this property to a 
+    non-null value.  Otherwise leave it blank to disable custom row heights.
+    
+    @property
+    @type SC.IndexSet
+  */
+  customRowHeightIndexes: null,
+  
+  /**
+    Called for each index in the customRowHeightIndexes set to get the 
+    actual row height for the index.  This method should return the default
+    rowHeight if you don't want the row to have a custom height.
+    
+    The default implementation just returns the default rowHeight.
+    
+    @param {SC.CollectionView} view the calling view
+    @param {Object} content the content array
+    @param {Number} contentIndex the index 
+    @returns {Number} row height
+  */
+  contentIndexRowHeight: function(view, content, contentIndex) {
+    return this.get('rowHeight');    
+  }
+  
+  
+};

data/frameworks/sproutcore/frameworks/desktop/mixins/collection_view_delegate.js

@@ -0,0 +1,283 @@
+// ==========================================================================
+// 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
+
+  A Collection View Delegate is consulted by a SC.CollectionView's to make
+  policy decisions about certain behaviors such as selection control and
+  drag and drop.  If you need to control other aspects of your data, you may
+  also want to add the SC.CollectionContent mixin.
+  
+  To act as a Collection Delegate, just apply this mixin to your class.  You
+  must then set the "delegate" property on the CollectionView to your object.
+  
+  Alternatively, if no delegate is set on a CollectionView, but the content 
+  implements this mixin, the content object will be used as the delegate 
+  instead.
+  
+  If you set an ArrayController or its arrangedObjects property as the content
+  of a CollectionView, the ArrayController will automatically act as the 
+  delegate for the view.
+  
+  @since SproutCore 1.0
+*/
+SC.CollectionViewDelegate = {
+
+  /**
+    Used to detect the mixin by SC.CollectionView
+  */
+  isCollectionViewDelegate: YES,
+  
+  // ..........................................................
+  // SELECTION
+  // 
+  
+  /**
+    This method will be called anytime the collection view is about to
+    change the selection in response to user mouse clicks or keyboard events.
+    
+    You can use this method to adjust the proposed selection, eliminating any
+    selected objects that cannot be selected.  The default implementation of
+    this method simply returns the proposed selection.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.IndexSet} sel Proposed array of selected objects.
+    @returns {SC.IndexSet} Actual allow selection index set
+  */
+  collectionViewSelectionForProposedSelection: function(view, sel) {
+    return sel ;
+  },
+
+  /**
+    Called by the collection when attempting to select an item.  Return the 
+    actual indexes you want to allow to be selected.  Return null to disallow
+    the change.  The default allows all selection.
+    
+    @param {SC.CollectionView} view the view collection view
+    @param {SC.IndexSet} indexes the indexes to be selected
+    @param {Boolean} extend YES if the indexes will extend existing sel
+    @returns {SC.IndexSet} allowed index set
+  */
+  collectionViewShouldSelectIndexes: function (view, indexes, extend) { 
+    return indexes; 
+  },
+  
+  /**
+    Called by the collection when attempting to deselect an item.  Return the 
+    actual indexes you want to allow to be deselected.  Return null to 
+    disallow the change.  The default allows all selection.
+    
+    Note that you should not modify the passed in IndexSet.  clone it instead.
+    
+    @param {SC.CollectionView} view the view collection view
+    @param {SC.IndexSet} indexes the indexes to be selected
+    @returns {SC.IndexSet} allowed index set
+  */
+  collectionViewShouldDeselectIndexes: function (view, indexes) { 
+    return indexes; 
+  },
+
+  // ..........................................................
+  // EDIT OPERATIONS
+  // 
+  
+  /**
+    Called by the collection view whenever the deleteSelection() method is
+    called.  You can implement this method to get fine-grained control over
+    which items can be deleted.  To prevent deletion, return null.
+    
+    This method is only called if canDeleteContent is YES on the collection
+    view.
+    
+    @param {SC.CollectionView} view the collection view
+    @param {SC.IndexSet} indexes proposed index set of items to delete.
+    @returns {SC.IndexSet} index set allowed to delete or null.
+  */
+  collectionViewShouldDeleteIndexes: function(view, indexes) { 
+    return indexes; 
+  },
+  
+  /**
+    Called by the collection view to actually delete the selected items.
+    
+    The default behavior will use standard array operators to delete the 
+    indexes from the array.  You can implement this method to provide your own 
+    deletion method.
+    
+    If you simply want to control the items to be deleted, you should instead
+    implement collectionViewShouldDeleteItems().  This method will only be 
+    called if canDeleteContent is YES and collectionViewShouldDeleteIndexes()
+    returns a non-empty index set
+    
+    @param {SC.CollectionView} view collection view
+    @param {SC.IndexSet} indexes the items to delete
+    @returns {Boolean} YES if the deletion was a success.
+  */
+  collectionViewDeleteContent: function(view, content, indexes) {
+    if (!content) return NO ;
+    
+    if (SC.typeOf(content.destroyAt) === SC.T_FUNCTION) {
+      content.destroyAt(indexes);
+      return YES ;
+      
+    } else if (SC.typeOf(content.removeAt) === SC.T_FUNCTION) {
+      content.removeAt(indexes);
+      return YES;
+      
+    } else return NO ;
+  },
+  
+  // ..........................................................
+  // DRAGGING
+  // 
+  
+  /**
+    Called by the collection view just before it starts a drag to give you
+    an opportunity to decide if the drag should be allowed. 
+    
+    You can use this method to implement fine-grained control over when a 
+    drag will be allowed and when it will not be allowed.  For example, you
+    may enable content reordering but then implement this method to prevent
+    reordering of certain items in the view.
+    
+    The default implementation always returns YES.
+    
+    @param view {SC.CollectionView} the collection view
+    @returns {Boolean} YES to alow, NO to prevent it
+  */
+  collectionViewShouldBeginDrag: function(view) { return YES; },
+  
+  /**
+    Called by the collection view just before it starts a drag so that 
+    you can provide the data types you would like to support in the data.
+    
+    You can implement this method to return an array of the data types you
+    will provide for the drag data.
+    
+    If you return null or an empty array, can you have set canReorderContent
+    to YES on the CollectionView, then the drag will go ahead but only 
+    reordering will be allowed.  If canReorderContent is NO, then the drag
+    will not be allowed to start.
+    
+    If you simply want to control whether a drag is allowed or not, you
+    should instead implement collectionViewShouldBeginDrag().
+    
+    The default returns an empty array.
+    
+    @param view {SC.CollectionView} the collection view to begin dragging.
+    @returns {Array} array of supported data types.
+  */
+  collectionViewDragDataTypes: function(view) { return []; },
+  
+  /**
+    Called by a collection view when a drag concludes to give you the option
+    to provide the drag data for the drop.
+    
+    This method should be implemented essentially as you would implement the
+    dragDataForType() if you were a drag data source.  You will never be asked
+    to provide drag data for a reorder event, only for other types of data.
+    
+    The default implementation returns null.
+    
+    @param view {SC.CollectionView} 
+      the collection view that initiated the drag
+
+    @param dataType {String} the data type to provide
+    @param drag {SC.Drag} the drag object
+    @returns {Object} the data object or null if the data could not be provided.
+  */
+  collectionViewDragDataForType: function(view, drag, dataType) {  
+    return null ;
+  },
+  
+  /**
+    Called once during a drag the first time view is entered. Return all 
+    possible drag operations OR'd together.
+    
+    @param {SC.CollectionView} view
+      the collection view that initiated the drag
+
+    @param {SC.Drag} drag
+      the drag object
+    
+    @param {Number} proposedDragOperations
+      proposed logical OR of allowed drag operations.
+
+    @returns {Number} the allowed drag operations. Defaults to op
+  */
+  collectionViewComputeDragOperations: function(view, drag, proposedDragOperations) {
+    return proposedDragOperations ;
+  },
+  
+  /**
+    Called by the collection view during a drag to let you determine the
+    kind and location of a drop you might want to accept.
+    
+    You can override this method to implement fine-grained control over how
+    and when a dragged item is allowed to be dropped into a collection view.
+
+    This method will be called by the collection view both to determine in 
+    general which operations you might support and specifically the operations
+    you would support if the user dropped an item over a specific location.
+    
+    If the proposedDropOperaration parameter is SC.DROP_ON or SC.DROP_BEFORE, 
+    then the proposedInsertionPoint will be a non-negative value and you 
+    should determine the specific operations you will support if the user 
+    dropped the drag item at that point.
+    
+    If you do not like the proposed drop operation or insertion point, you 
+    can override these properties as well by setting the proposedDropOperation
+    and proposedInsertionIndex properties on the collection view during this
+    method.  These properties are ignored all other times.
+    
+    @param view {SC.CollectionView} the collection view
+    @param drag {SC.Drag} the current drag object
+    @param op {Number} proposed logical OR of allowed drag operations.
+    @param proposedInsertionIndex {Number} an index into the content array 
+      representing the proposed insertion point.
+    @param proposedDropOperation {String} the proposed drop operation.  Will be one of SC.DROP_ON, SC.DROP_BEFORE, or SC.DROP_ANY.
+    @returns the allowed drag operation.  Defaults to op
+  */
+  collectionViewValidateDragOperation: function(view, drag, op, proposedInsertionIndex, proposedDropOperaration) {
+    return (op & SC.DROP_ON) ? SC.DRAG_NONE : op ;
+  },
+  
+  /**
+    Called by the collection view to actually accept a drop.  This method will
+    only be invoked AFTER your validateDrop method has been called to
+    determine if you want to even allow the drag operation to go through.
+    
+    You should actually make changes to the data model if needed here and
+    then return the actual drag operation that was performed.  If you return
+    SC.DRAG_NONE and the dragOperation was SC.DRAG_REORDER, then the default
+    reorder behavior will be provided by the collection view.
+    
+    @param view {SC.CollectionView}
+    @param drag {SC.Drag} the current drag object
+    @param op {Number} proposed logical OR of allowed drag operations.
+    @param proposedInsertionIndex {Number} an index into the content array representing the proposed insertion point.
+    @param proposedDropOperation {String} the proposed drop operation.  Will be one of SC.DROP_ON, SC.DROP_BEFORE, or SC.DROP_ANY.
+    @returns the allowed drag operation.  Defaults to proposedDragOperation
+  */
+  collectionViewPerformDragOperation: function(view, drag, op, proposedInsertionIndex, proposedDropOperaration) {
+    return SC.DRAG_NONE ;
+  },
+  
+  /**
+    Renders a drag view for the passed content indexes. If you return null
+    from this, then a default drag view will be generated for you.
+    
+    @param {SC.CollectionView} view
+    @param {SC.IndexSet} dragContent
+    @returns {SC.View} view or null
+  */
+  collectionViewDragViewFor: function(view, dragContent) {
+    return null;
+  }
+
+};

data/frameworks/sproutcore/frameworks/desktop/mixins/scrollable.js

@@ -0,0 +1,247 @@
+// ========================================================================
+// SproutCore -- JavaScript Application Framework
+// Copyright ©2006-2008, Sprout Systems, Inc. and contributors.
+// Portions copyright ©2008 Apple, Inc.  All rights reserved.
+// ========================================================================
+
+/**
+  @namespace
+
+  Any views you implement that are scrollable should include this mixin to
+  provide basic support for scrolling actions.  You can also override any 
+  of these methods as needed for your own specific behaviors.
+  
+  Often times instead of adding SC.Scrollable to your view, you should
+  place your view inside of an SC.ScrollView.  See that class for more 
+  info.
+  
+  Note that isScrollable must always be true.
+
+*/
+SC.Scrollable = {
+  
+  /** Informs the view system that the receiver is scrollable.
+  
+    Must always be true.
+  */
+  isScrollable: true,
+  
+  /** 
+    Amount to scroll one vertical line.
+  
+    Used by the default implementation of scrollDownLine() and scrollUpLine().  Defaults
+    to 20px.
+  */
+  verticalLineScroll: 20,
+  
+  /**
+    Amount to scroll one horizontal line.
+  
+    Used by the default implementation of scrollLeftLine() and scrollRightLine(). Defaults
+    to 20px.
+  */
+  horizontalLineScroll: 20,
+  
+  /**
+    Amount to scroll one vertical page.
+    
+    Used by the default implementation of scrollUpPage() and scrollDownPage(). Defaults to
+    current innerFrame height.
+  */
+  verticalPageScroll: function() {
+    return this.get('innerFrame').height ;
+  }.property('innerFrame'),
+  
+  /**
+    Amount to scroll one horizontal page.
+    
+    Used by the default implementation of scrollLeftPage() and scrollRightPage().  Defaults
+    to current innerFrame width.
+  */
+  horizontalPageScroll: function() {
+    return this.get('innerFrame').width ;  
+  }.property('innerFrame'),
+  
+  /**
+    Returns true if the receiver has enough vertical content to require 
+    scrolling.
+    
+    If you do not want to allow vertical scrolling, override this to be false 
+    and set the appropriate CSS.
+    
+  */
+  hasVerticalScroller: function() {
+    return this.get('scrollFrame').height > this.get('innerFrame').height ;
+  }.property('scrollFrame'),
+  
+  /**
+    Returns true if the receiver has enough horizontal content to require 
+    scrolling.
+    
+    If you do not want to allow horizontal scrolling, override this to be 
+    false and set the appropriate CSS.
+    
+  */
+  hasHorizontalScroller: function() {
+    return this.get('scrollFrame').width > this.get('innerFrame').width ;
+  }.property('scrollFrame'),
+
+  /**
+    Scrolls the receiver in the horizontal and vertical directions by the 
+    amount specified, if allowed.
+    
+    @param {Point} amount the amount to scroll.  Must include x, y or both
+    @returns {Point} the actual amount scrolled.
+  */
+  scrollBy: function(amount) {
+    var sf = this.get('scrollFrame') ;
+    var f = this.get('innerFrame') ;
+
+    if (!this.get('hasVerticalScroller')) amount.y = 0 ;
+    if (sf.height <= f.height) amount.y = 0 ;
+    
+    if (!this.get('hasHorizontalScroller')) amount.x = 0 ; 
+    if (sf.width <= f.width) amount.x = 0 ;
+
+    // compute new sf
+    var newSf = { x: sf.x - (amount.x || 0), y: sf.y - (amount.y || 0) } ;
+    this.set('scrollFrame', newSf) ;
+    newSf = this.get('scrollFrame') ;
+    
+    return { x: newSf.x - sf.x, y: newSf.y - sf.y }; 
+  },
+
+  /**
+    Scrolls the receiver to the specified x,y coordinate
+  */
+  scrollTo: function(x,y) {
+    this.set('scrollFrame', { x: 0-x, y: 0-y }) ;  
+  },
+  
+  /**
+    Scroll the view to make the passed frame visible.
+    
+    Frame must be relative to the receiver's offsetParent.
+    
+    @param {SC.ClassicView} view the view you want to make visible
+  */
+  scrollToVisible: function(view) {
+
+    // get frames and convert them to proper offsets
+    var f = this.get('innerFrame') ;
+    var sf = this.get('scrollFrame') ;
+    
+    // frame of the view, relative to the top of the scroll frame
+    var vf = this.convertFrameFromView(view.get('frame'), view) ;
+    vf.x -= (f.x + sf.x); vf.y -= (f.y + sf.y);
+    
+    // first visible origin
+    var vo = { 
+      x: 0-sf.x, 
+      y: 0-sf.y, 
+      width: f.width, 
+      height: f.height 
+    };
+
+    // if top edge is not visible, shift origin
+    vo.y -= Math.max(0, SC.minY(vo) - SC.minY(vf)) ;
+    vo.x -= Math.max(0, SC.minX(vo) - SC.minX(vf)) ;
+
+    // if bottom edge is not visible, shift origin
+    vo.y += Math.max(0, SC.maxY(vf) - SC.maxY(vo)) ;
+    vo.x += Math.max(0, SC.maxX(vf) - SC.maxX(vo)) ;
+
+    // scroll to that origin.
+    this.scrollTo(vo.x, vo.y) ;
+  },
+  
+  /**
+    Scrolls the receiver down one line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollDownLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return this.scrollBy({ y: this.get('verticalLineScroll')*lines }).y ;
+  },
+
+  /**
+    Scrolls the receiver down up line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollUpLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return 0-this.scrollBy({ y: 0-this.get('verticalLineScroll')*lines }).y ;
+  },
+
+  /**
+    Scrolls the receiver right one line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollRightLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return this.scrollTo({ y: this.get('horizontalLineScroll')*lines }).x ;
+  },
+
+  /**
+    Scrolls the receiver left one line if allowed.
+    
+    @param {Number} lines number of lines to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollLeftLine: function(lines) {
+    if (lines === undefined) lines = 1 ;
+    return 0-this.scrollTo({ y: 0-this.get('horizontalLineScroll')*lines }).x ;
+  },
+
+  /**
+    Scrolls the receiver down one page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollDownPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return this.scrollBy({ y: this.get('verticalPageScroll')*pages }).y ;
+  },
+
+  /**
+    Scrolls the receiver down up page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollUpPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return 0-this.scrollBy({ y: 0-this.get('verticalPageScroll')*pages }).y ;
+  },
+
+  /**
+    Scrolls the receiver right one page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollRightPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return this.scrollTo({ y: this.get('horizontalPageScroll')*pages }).x ;
+  },
+
+  /**
+    Scrolls the receiver left one page if allowed.
+    
+    @param {Number} pages number of pages to scroll
+    @returns {Number} the amount actually scrolled.
+  */
+  scrollLeftPage: function(pages) {
+    if (pages === undefined) pages = 1 ;
+    return 0-this.scrollTo({ y: 0-this.get('horizontalPageScroll')*pages }).x ;
+  }
+  
+} ;
+