sproutcore 1.4.0-java

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/tree_item_content.js

@@ -0,0 +1,160 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @namespace
+
+  A tree item is a model object that acts as a node in a tree-like data 
+  structure such as a hierarchy of folders or outline of items.  This mixin 
+  can be applied to tree item model objects to customize the way the tree
+  information is extracted from the object.
+
+  h2. Basic Implementation
+  
+  If you add this mixin, you must implement the treeItemChildren property so
+  that it returns the current array of child tree items for the receiver.  If
+  you do not implement this property the tree item will not function.
+  
+  h2. Optimizing Branches
+  
+  The most common use of this mixin is to override the treeItemBranchIndexes
+  property to return an index set of child items that are themselves branches
+  in the tree.  Normally the TreeController will need to walk every item in
+  your list to determine these branch items.  However by implementing this 
+  method yourself, you can provide a result faster.
+  
+  If none of your child items are branches, override this property to return
+  null or an empty index set.
+  
+  @since SproutCore 1.0
+*/
+SC.TreeItemContent = {
+
+  /** 
+    Walk like a duck. 
+    
+    @property {Boolean}
+  */
+  isTreeItemContent: YES,
+  
+  /**
+    Property returns the children for this tree item.  The default simply 
+    returns null.  If you implement this mixin, you MUST implement this 
+    property to return the actual tree item children for the item.
+   
+    @property {SC.Array}
+  */
+  treeItemChildren: null,
+
+  /**
+    The default property used to determine if the tree item is expanded.  You
+    can implement you model object to update this property or you can override
+    treeItemDisclosureState() to compute the disclosure state however you 
+    want.
+    
+    @property {Boolean}
+  */
+  treeItemIsExpanded: YES,
+  
+  /**
+    Indicates whether the tree item should be rendered as a group or not. 
+    This property is only useful on the root item in your tree.  Setting it to
+    YES on any other item will be ignored.
+    
+    @property {Boolean}
+  */
+  treeItemIsGrouped: NO,
+  
+  /**
+    Returns the disclosure state for the tree item, which appears at the 
+    index of the parent's treeItemChildren array.  The response must be one of 
+    SC.BRANCH_OPEN, SC.BRANCH_CLOSED or SC.LEAF_NODE.
+     
+    If the parent parameter is null, then this item is part of the root 
+    children array.
+    
+    This method will only be called for tree items that have children.  Tree
+    items with no children are assumed to be leaf nodes.
+
+    The default implementation uses the treeItemIsExpanded property to 
+    determine if the item should be open or closed.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} idx the index of the item in the parent
+    @returns {Number} branch state
+  */
+  treeItemDisclosureState: function(parent, idx) {
+    return this.get('treeItemIsExpanded') ? SC.BRANCH_OPEN : SC.BRANCH_CLOSED;
+  },
+  
+  /**
+    Collapse the tree item.  The default implementation will change the 
+    treeItemIsExpanded property, but you can override this method to handle
+    collapsing anyway you like.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} idx the index of the item in the parent
+    @returns {void}
+  */
+  treeItemCollapse: function(parent, idx) {
+    this.setIfChanged('treeItemIsExpanded', NO);    
+  },
+
+  /**
+    Expand the tree item.  The default implementation will change the 
+    treeItemIsExpanded property, but you can override this method to handle
+    collapsing anyway you like.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} idx the index of the item in the parent
+    @returns {void}
+  */
+  treeItemExpand: function(parent, idx) {
+    this.setIfChanged('treeItemIsExpanded', YES);    
+  },
+  
+  /**
+    Returns an index set containing the child indexes of the item that are 
+    themselves branches.  This will only be called on tree items with a branch
+    disclosure state.
+
+    If the passed parent and index are both null, then the receiver is the 
+    root node in the tree.
+    
+    The default implementation iterates over the item's children to get the
+    disclosure state of each one.  Child items with a branch disclosure state
+    will have their index added to the return index set.  
+    
+    You may want to override this method to provide a more efficient 
+    implementation if you are working with large data sets and can infer which
+    children are branches without iterating over each one.
+
+    If you know for sure that all of the child items for this item are leaf
+    nodes and not branches, simply override this method to return null.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} index the index of the item in the parent
+    @returns {SC.IndexSet} branch indexes
+  */
+  treeItemBranchIndexes: function(parent, index) {
+    var children = this.get('treeItemChildren'),
+        ret, lim, idx, item;
+        
+    if (!children) return null ; // nothing to do
+    
+    ret = SC.IndexSet.create();
+    lim = children.get('length');
+    for(idx=0;idx<lim;idx++) {
+      if (!(item = children.objectAt(idx))) continue;
+      if (!item.get('treeItemChildren')) continue;
+      if (item.treeItemDisclosureState(this,idx)!==SC.LEAF_NODE) ret.add(idx);
+    }
+
+    return ret.get('length')>0 ? ret : null;
+  }
+  
+};

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/validatable.js

@@ -0,0 +1,189 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @namespace
+
+  Views that include the Validatable mixin can be used with validators to 
+  ensure their values are valid.  
+  
+*/
+SC.Validatable = {
+  
+  /** @private */
+  initMixin: function() {
+    this._validatable_validatorDidChange() ;
+  },
+  
+  /**
+    The validator for this field.  
+  
+    Set to a validator class or instance.  If this points to a class, it will 
+    be instantiated when the validator is first used.
+    
+    @property {SC.Validator}
+  */
+  validator: null,
+
+  /**
+    This property must return the human readable name you want used when 
+    describing an error condition.  For example, if set this property to
+    "Your Email", then the returned error string might be something like
+    "Your Email is not valid".
+    
+    You can return a loc string here if you like.  It will be localized when
+    it is placed into the error string.
+    
+    @property {String}
+  */
+  errorLabel: null,
+
+  /**
+    YES if the receiver is currently valid.
+    
+    This property watches the value property by default.  You can override
+    this property if you want to use some other method to calculate the
+    current valid state.
+    
+    @property {Boolean}
+  */
+  isValid: function() { 
+    return SC.typeOf(this.get('value')) !== SC.T_ERROR; 
+  }.property('value'),
+  
+  /**
+    The form that the view belongs to.  May be null if the view does not 
+    belong to a form.  This property is usually set automatically by an 
+    owner form view.
+    
+    @property {SC.View}
+  */
+  ownerForm: null,
+  
+  /**
+    Attempts to validate the receiver. 
+    
+    Runs the validator and returns SC.VALIDATE_OK, SC.VALIDATE_NO_CHANGE,
+    or an error object.  If no validator is installed, this method will
+    always return SC.VALIDATE_OK.
+
+    @param {Boolean} partialChange YES if this is a partial edit.
+    @returns {String} SC.VALIDATE_OK, error, or SC.VALIDATE_NO_CHANGE
+  */
+  performValidate: function(partialChange) {
+    var ret = SC.VALIDATE_OK ;
+
+    if (this._validator) {
+      var form = this.get('ownerForm') ;
+      if (partialChange) {
+        ret = this._validator.validatePartial(form,this) ;
+
+        // if the partial returned NO_CHANGE, then check to see if the 
+        // field is valid anyway.  If it is not valid, then don't update the
+        // value.  This way the user can have partially constructed values 
+        // without the validator trying to convert it to an object.
+        if ((ret == SC.VALIDATE_NO_CHANGE) && (this._validator.validateChange(form, this) == SC.VALIDATE_OK)) {
+          ret = SC.VALIDATE_OK; 
+        }
+      } else ret = this._validator.validateChange(form, this) ;
+    }
+    return ret ;
+  },
+
+  /**
+    Runs validateSubmit.  You should use this in your implementation of 
+    validateSubmit.  If no validator is installed, this always returns
+    SC.VALIDATE_OK
+    
+    @returns {String}
+  */
+  performValidateSubmit: function() {
+    return this._validator ? this._validator.validateSubmit(this.get('ownerForm'), this) : SC.VALIDATE_OK;
+  },
+  
+  /**
+    Runs a keypress validation.  Returns YES if the keypress should be 
+    allowed, NO otherwise.  If no validator is defined, always returns YES.
+    
+    @param {String} charStr the key string
+    @returns {Boolean}
+  */
+  performValidateKeyDown: function(evt) {
+    // ignore anything with ctrl or meta key press
+    var charStr = evt.getCharString();
+    if (!charStr) return YES ;
+    return this._validator ? this._validator.validateKeyDown(this.get('ownerForm'), this, charStr) : YES;
+  },
+  
+  /**
+    Returns the validator object, if one has been created.
+    
+    @property {SC.Validator}
+  */
+  validatorObject: function() {
+    return this._validator;
+  }.property(),
+  
+  /**
+    Invoked by the owner form just before submission.  Override with your 
+    own method to commit any final changes after you perform validation. 
+    
+    The default implementation simply calls performValidateSubmit() and 
+    returns that value.
+    
+    @property {Boolean}
+  */
+  validateSubmit: function() { return this.performValidateSubmit(); },
+  
+  /**
+    Convert the field value string into an object.
+    
+    This method will call the validators objectForFieldValue if it exists.
+    
+    @param {Object} fieldValue the raw value from the field.
+    @param {Boolean} partialChange
+    @returns {Object}
+  */
+  objectForFieldValue: function(fieldValue, partialChange) {
+    return this._validator ? this._validator.objectForFieldValue(fieldValue, this.get('ownerForm'), this) : fieldValue ;
+  },
+  
+  /**
+    Convert the object into a field value.
+    
+    This method will call the validator's fieldValueForObject if it exists.
+    
+    @param object {Object} the objec to convert
+    @returns {Object}
+  */
+  fieldValueForObject: function(object) {
+    return this._validator ? this._validator.fieldValueForObject(object, this.get('ownerForm'), this) : object ;
+  },
+  
+  _validatable_displayObserver: function() {
+    this.displayDidChange();
+  }.observes('isValid'),
+
+  /** @private */
+  renderMixin: function(context) {
+    context.setClass('invalid', !this.get('isValid'));
+  },
+
+  // invoked whenever the attached validator changes.
+  _validatable_validatorDidChange: function() {
+    var form = this.get('ownerForm') ;
+    var val = SC.Validator.findFor(form, this, this.get('validator')) ;
+    if (val != this._validator) {
+      this.propertyWillChange('validatorObject');
+      if (this._validator) this._validator.detachFrom(form, this) ;
+      this._validator = val;
+      if (this._validator) this._validator.attachTo(form, this) ;
+      this.propertyDidChange('validatorObject');
+    }  
+  }.observes('validator', 'ownerForm')
+      
+};

data/lib/frameworks/sproutcore/frameworks/foundation/panes/main.js

@@ -0,0 +1,51 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+require('panes/pane');
+
+/** @class
+
+  Most SproutCore applications have a main pane, which dominates the 
+  application page.  You can extend from this view to implement your own main 
+  pane.  This class will automatically make itself main whenever you append it 
+  to a document, removing any other main pane that might be currently in 
+  place.  If you do have another already focused as the keyPane, this view 
+  will also make itself key automatically.  The default way to use the main 
+  pane is to simply add it to your page like this:
+  
+  {{{
+    SC.MainPane.create().append();
+  }}}
+  
+  This will cause your root view to display.  The default layout for a 
+  MainPane is to cover the entire document window and to resize with the 
+  window.
+
+  @extends SC.Pane
+  @since SproutCore 1.0
+*/
+SC.MainPane = SC.Pane.extend({
+
+  /** @private */
+  layout: { top: 0, left: 0, bottom: 0, right: 0, minHeight:200, minWidth:200 },
+  
+  /** @private - extends SC.Pane's method */
+  paneDidAttach: function() {
+    var ret = sc_super();
+    var responder = this.rootResponder;
+    responder.makeMainPane(this);
+    if (!responder.get('keyRootView')) responder.makeKeyPane(this);
+    return ret ;
+  },
+  
+  /** @private */
+  acceptsKeyPane: YES,
+
+  /** @private */
+  classNames: ['sc-main']
+  
+});

data/lib/frameworks/sproutcore/frameworks/foundation/panes/pane.js

@@ -0,0 +1,848 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('views/view');
+sc_require('mixins/responder_context');
+
+/** @class
+  A Pane is like a regular view except that it does not need to live within a 
+  parent view.  You usually use a Pane to form the root of a view hierarchy in 
+  your application, such as your main application view or for floating 
+  palettes, popups, menus, etc.
+  
+  Usually you will not work directly with the SC.Pane class, but with one of 
+  its subclasses such as SC.MainPane, SC.Panel, or SC.PopupPane.
+
+  h1. Showing a Pane
+  
+  To make a pane visible, you need to add it to your HTML document.  The 
+  simplest way to do this is to call the append() method:
+  
+  {{{
+     myPane = SC.Pane.create();
+     myPane.append(); // adds the pane to the document
+  }}}
+  
+  This will insert your pane into the end of your HTML document body, causing 
+  it to display on screen.  It will also register your pane with the 
+  SC.RootResponder for the document so you can start to receive keyboard, 
+  mouse, and touch events.
+  
+  If you need more specific control for where you pane appears in the 
+  document, you can use several other insertion methods such as appendTo(), 
+  prependTo(), before() and after().  These methods all take a an element to 
+  indicate where in your HTML document you would like you pane to be inserted.
+  
+  Once a pane is inserted into the document, it will be sized and positioned 
+  according to the layout you have specified.  It will then automatically 
+  resize with the window if needed, relaying resize notifications to children 
+  as well.
+  
+  h1. Hiding a Pane
+  
+  When you are finished with a pane, you can hide the pane by calling the 
+  remove() method.  This method will actually remove the Pane from the 
+  document body, as well as deregistering it from the RootResponder so that it 
+  no longer receives events.
+  
+  The isVisibleInWindow method will also change to NO for the Pane and all of 
+  its childViews and the views will no longer have their updateDisplay methods 
+  called.  
+  
+  You can readd a pane to the document again any time in the future by using 
+  any of the insertion methods defined in the previous section.
+  
+  h1. Receiving Events
+  
+  Your pane and its child views will automatically receive any mouse or touch 
+  events as long as it is on the screen.  To receive keyboard events, however, 
+  you must focus the keyboard on your pane by calling makeKeyPane() on the 
+  pane itself.  This will cause the RootResponder to route keyboard events to 
+  your pane.  The pane, in turn, will route those events to its current 
+  keyView, if there is any.
+  
+  Note that all SC.Views (anything that implements SC.ClassicResponder, 
+  really) will be notified when it is about or gain or lose keyboard focus.  
+  These notifications are sent both when the view is made keyView of a 
+  particular pane and when the pane is made keyPane for the entire 
+  application.
+  
+  You can prevent your Pane from becoming key by setting the acceptsKeyPane 
+  to NO on the pane.  This is useful when creating palettes and other popups 
+  that should not steal keyboard control from another view.
+
+  @extends SC.View
+  @extends SC.ResponderContext
+  @since SproutCore 1.0
+*/
+SC.Pane = SC.View.extend(SC.ResponderContext,
+/** @scope SC.Pane.prototype */ {
+
+  /** 
+    Returns YES for easy detection of when you reached the pane. 
+    @property {Boolean}
+  */
+  isPane: YES,
+  
+  /** 
+    Set to the current page when the pane is instantiated from a page object.
+    @property {SC.Page}
+  */
+  page: null,
+  
+  // .......................................................
+  // ROOT RESPONDER SUPPORT
+  //
+
+  /**
+    The rootResponder for this pane.  Whenever you add a pane to a document, 
+    this property will be set to the rootResponder that is now forwarding 
+    events to the pane.
+    
+    @property {SC.Responder}
+  */
+  rootResponder: null,  
+  
+  /** 
+    Last known window size. 
+    
+    @property {Rect}
+  */
+  currentWindowSize: null,
+  
+  /** 
+    The parent dimensions are always the last known window size. 
+    
+    @returns {Rect} current window size 
+  */
+  computeParentDimensions: function(frame) {
+    if(this.get('designer') && SC.suppressMain) return sc_super();
+    
+    var wframe = this.get('currentWindowSize'),
+        wDim = {x: 0, y: 0, width: 1000, height: 1000},
+        layout = this.get('layout');
+
+    if (wframe){
+      wDim.width = wframe.width;
+      wDim.height = wframe.height;
+    }
+    // Call the RootResponder instance...
+    else if (SC.RootResponder.responder) {
+      var wSize = SC.RootResponder.responder.get('currentWindowSize');
+      if (wSize){
+        wDim.width = wSize.width;
+        wDim.height = wSize.height;
+      }
+    }
+    // If all else fails then we need to Calculate it from the window size and DOM
+    else {
+      var size, body, docElement;
+      if(!this._bod || !this._docElement){
+        body = document.body;
+        docElement = document.documentElement;
+        this._body=body;
+        this._docElement=docElement;
+      }else{
+        body = this._body;
+        docElement = this._docElement;
+      }
+      
+      if (window.innerHeight) {
+        wDim.width = window.innerWidth;
+        wDim.height = window.innerHeight;
+      } else if (docElement && docElement.clientHeight) {
+        wDim.width = docElement.clientWidth;
+        wDim.height = docElement.clientHeight; 
+      } else if (body) {
+        wDim.width = body.clientWidth;
+        wDim.height = body.clientHeight;
+      }
+      this.windowSizeDidChange(null, wDim);
+    }
+
+
+    // If there is a minWidth or minHeight set on the pane, take that
+    // into account when calculating dimensions.
+  
+    if (layout.minHeight || layout.minWidth) {
+      if (layout.minHeight) {
+        wDim.height = Math.max(wDim.height, layout.minHeight);
+      }
+      if (layout.minWidth) {
+        wDim.width = Math.max(wDim.width, layout.minWidth);
+      }
+    }
+    return wDim;
+  },
+    
+  /** @private Disable caching due to an known bug in SC. */
+  frame: function() {
+    if(this.get('designer') && SC.suppressMain) return sc_super();    
+    return this.computeFrameWithParentFrame(null) ;
+  }.property(),
+  
+  /** 
+    Invoked by the root responder whenever the window resizes.  This should
+    simply begin the process of notifying children that the view size has
+    changed, if needed.
+    
+    @param {Rect} oldSize the old window size
+    @param {Rect} newSize the new window size
+    @returns {SC.Pane} receiver
+  */
+  windowSizeDidChange: function(oldSize, newSize) {
+    this.set('currentWindowSize', newSize) ;
+    this.parentViewDidResize(); // start notifications.
+    return this ;
+  },
+
+  /** @private */
+  paneLayoutDidChange: function() {
+    this.invokeOnce(this.updateLayout);
+  }.observes('layout'),
+  
+  /**
+    Attempts to send the event down the responder chain for this pane.  If you 
+    pass a target, this method will begin with the target and work up the 
+    responder chain.  Otherwise, it will begin with the current rr 
+    and walk up the chain looking for any responder that implements a handler 
+    for the passed method and returns YES when executed.
+
+    @param {String} action
+    @param {SC.Event} evt
+    @param {Object} target
+    @returns {Object} object that handled the event
+  */
+  sendEvent: function(action, evt, target) {
+    var handler ;
+    
+    // walk up the responder chain looking for a method to handle the event
+    if (!target) target = this.get('firstResponder') ;
+    while(target && !target.tryToPerform(action, evt)) {
+
+      // even if someone tries to fill in the nextResponder on the pane, stop
+      // searching when we hit the pane.
+      target = (target === this) ? null : target.get('nextResponder') ;
+    }
+    
+    // if no handler was found in the responder chain, try the default
+    if (!target && (target = this.get('defaultResponder'))) {
+      if (typeof target === SC.T_STRING) {
+        target = SC.objectForPropertyPath(target);
+      }
+
+      if (!target) target = null;
+      else target = target.tryToPerform(action, evt) ? target : null ;
+    }
+
+    // if we don't have a default responder or no responders in the responder
+    // chain handled the event, see if the pane itself implements the event
+    else if (!target && !(target = this.get('defaultResponder'))) {
+      target = this.tryToPerform(action, evt) ? this : null ;
+    }
+
+    return evt.mouseHandler || target ;
+  },
+
+  performKeyEquivalent: function(keystring, evt) {
+    var ret = sc_super() ; // try normal view behavior first
+    if (!ret) {
+      var defaultResponder = this.get('defaultResponder') ;
+      if (defaultResponder) {
+        // try default responder's own performKeyEquivalent method,
+        // if it has one...
+        if (defaultResponder.performKeyEquivalent) {
+          ret = defaultResponder.performKeyEquivalent(keystring, evt) ;
+        }
+        
+        // even if it does have one, if it doesn't handle the event, give
+        // methodName-style key equivalent handling a try
+        if (!ret && defaultResponder.tryToPerform) {
+          ret = defaultResponder.tryToPerform(keystring, evt) ;
+        }
+      }
+    }
+    return ret ;
+  },
+
+  // .......................................................
+  // RESPONDER CONTEXT
+  //
+
+  /**
+    Pane's never have a next responder.
+
+    @property {SC.Responder}
+    @readOnly
+  */
+  nextResponder: function() {
+    return null;
+  }.property().cacheable(),
+
+  /**
+    The first responder.  This is the first view that should receive action 
+    events.  Whenever you click on a view, it will usually become 
+    firstResponder. 
+    
+    @property {SC.Responder}
+  */
+  firstResponder: null,
+  
+  /** 
+    If YES, this pane can become the key pane.  You may want to set this to NO 
+    for certain types of panes.  For example, a palette may never want to 
+    become key.  The default value is YES.
+    
+    @property {Boolean}
+  */
+  acceptsKeyPane: YES,
+  
+  /**
+    This is set to YES when your pane is currently the target of key events. 
+    
+    @property {Boolean}
+  */
+  isKeyPane: NO,
+
+  /**
+    Make the pane receive key events.  Until you call this method, the 
+    keyView set for this pane will not receive key events. 
+  
+    @returns {SC.Pane} receiver
+  */
+  becomeKeyPane: function() {
+    if (this.get('isKeyPane')) return this ;
+    if (this.rootResponder) this.rootResponder.makeKeyPane(this) ;
+    return this ;
+  },
+  
+  /**
+    Remove the pane view status from the pane.  This will simply set the 
+    keyPane on the rootResponder to null.
+    
+    @returns {SC.Pane} receiver
+  */
+  resignKeyPane: function() {
+    if (!this.get('isKeyPane')) return this ;
+    if (this.rootResponder) this.rootResponder.makeKeyPane(null);
+    return this ;
+  },
+  
+  /**
+    Makes the passed view (or any object that implements SC.Responder) into 
+    the new firstResponder for this pane.  This will cause the current first
+    responder to lose its responder status and possibly keyResponder status as
+    well.
+    
+    @param {SC.View} view
+    @param {Event} evt that cause this to become first responder
+    @returns {SC.Pane} receiver
+  */
+  makeFirstResponder: function(view, evt) {
+    var current=this.get('firstResponder'), isKeyPane=this.get('isKeyPane');
+    if (current === view) return this ; // nothing to do
+    if (SC.platform.touch && view && view.kindOf(SC.TextFieldView) && !view.get('focused')) return this;
+    
+    // notify current of firstResponder change
+    if (current) current.willLoseFirstResponder(current, evt);
+    
+    // if we are currently key pane, then notify key views of change also
+    if (isKeyPane) {
+      if (current) current.willLoseKeyResponderTo(view) ;
+      if (view) view.willBecomeKeyResponderFrom(current) ;
+    }
+    
+    // change setting
+    if (current) {
+      current.beginPropertyChanges()
+        .set('isFirstResponder', NO).set('isKeyResponder', NO)
+      .endPropertyChanges();
+    }
+
+    this.set('firstResponder', view) ;
+    
+    if (view) {
+      view.beginPropertyChanges()
+        .set('isFirstResponder', YES).set('isKeyResponder', isKeyPane)
+      .endPropertyChanges();
+    }
+    
+    // and notify again if needed.
+    if (isKeyPane) {
+      if (view) view.didBecomeKeyResponderFrom(current) ; 
+      if (current) current.didLoseKeyResponderTo(view) ;
+    }
+    
+    if (view) view.didBecomeFirstResponder(view);
+    return this ;
+  },
+
+  /** @private
+    If the user presses the tab key and the pane does not have a first
+    responder, try to give it to the next eligible responder.
+
+    If the keyDown event reaches the pane, we can assume that no responders in
+    the responder chain, nor the default responder, handled the event.
+  */
+  keyDown: function(evt) {
+    var nextValidKeyView;
+
+    // Handle tab key presses if we don't have a first responder already
+    if (evt.which === 9 && !this.get('firstResponder')) {
+      // Cycle forwards by default, backwards if the shift key is held
+      if (evt.shiftKey) {
+        nextValidKeyView = this.get('previousValidKeyView');
+      } else {
+        nextValidKeyView = this.get('nextValidKeyView');
+      }
+
+      if (nextValidKeyView) {
+        this.makeFirstResponder(nextValidKeyView);
+        return YES;
+      }
+    }
+
+    return NO;
+  },
+
+  /** @private method forwards status changes in a generic way. */
+  _forwardKeyChange: function(shouldForward, methodName, pane, isKey) {
+    var keyView, responder, newKeyView;
+    if (shouldForward && (responder = this.get('firstResponder'))) {
+      newKeyView = (pane) ? pane.get('firstResponder') : null ;
+      keyView = this.get('firstResponder') ;
+      if (keyView) keyView[methodName](newKeyView);
+      
+      if ((isKey !== undefined) && responder) {
+        responder.set('isKeyResponder', isKey);
+      }
+    } 
+  },
+  
+  /**
+    Called just before the pane loses it's keyPane status.  This will notify 
+    the current keyView, if there is one, that it is about to lose focus, 
+    giving it one last opportunity to save its state. 
+    
+    @param {SC.Pane} pane
+    @returns {SC.Pane} reciever
+  */
+  willLoseKeyPaneTo: function(pane) {
+    this._forwardKeyChange(this.get('isKeyPane'), 'willLoseKeyResponderTo', pane, NO);
+    return this ;
+  },
+  
+  /**
+    Called just before the pane becomes keyPane.  Notifies the current keyView 
+    that it is about to gain focus.  The keyView can use this opportunity to 
+    prepare itself, possibly stealing any value it might need to steal from 
+    the current key view.
+    
+    @param {SC.Pane} pane
+    @returns {SC.Pane} receiver
+  */
+  willBecomeKeyPaneFrom: function(pane) {
+    this._forwardKeyChange(!this.get('isKeyPane'), 'willBecomeKeyResponderFrom', pane, YES);
+    return this ;
+  },
+
+
+  /**
+    Called just after the pane has lost its keyPane status.  Notifies the 
+    current keyView of the change.  The keyView can use this method to do any 
+    final cleanup and changes its own display value if needed.
+    
+    @param {SC.Pane} pane
+    @returns {SC.Pane} reciever
+  */
+  didLoseKeyPaneTo: function(pane) {
+    var isKeyPane = this.get('isKeyPane');
+    this.set('isKeyPane', NO);
+    this._forwardKeyChange(isKeyPane, 'didLoseKeyResponderTo', pane);
+    return this ;
+  },
+  
+  /**
+    Called just after the keyPane focus has changed to the receiver.  Notifies 
+    the keyView of its new status.  The keyView should use this method to 
+    update its display and actually set focus on itself at the browser level 
+    if needed.
+    
+    @param {SC.Pane} pane
+    @returns {SC.Pane} receiver
+
+  */
+  didBecomeKeyPaneFrom: function(pane) {
+    var isKeyPane = this.get('isKeyPane');
+    this.set('isKeyPane', YES);
+    this._forwardKeyChange(!isKeyPane, 'didBecomeKeyResponderFrom', pane, YES);
+    return this ;
+  },
+  
+  // .......................................................
+  // MAIN PANE SUPPORT
+  //
+  
+  /**
+    Returns YES whenever the pane has been set as the main pane for the 
+    application.
+    
+    @property {Boolean}
+  */
+  isMainPane: NO,
+  
+  /**
+    Invoked when the pane is about to become the focused pane.  Override to
+    implement your own custom handling.
+    
+    @param {SC.Pane} pane the pane that currently have focus
+    @returns {void}
+  */
+  focusFrom: function(pane) {},
+  
+  /**
+    Invoked when the the pane is about to lose its focused pane status.  
+    Override to implement your own custom handling
+    
+    @param {SC.Pane} pane the pane that will receive focus next
+    @returns {void}
+  */
+  blurTo: function(pane) {},
+  
+  /**
+    Invoked when the view is about to lose its mainPane status.  The default 
+    implementation will also remove the pane from the document since you can't 
+    have more than one mainPane in the document at a time.
+    
+    @param {SC.Pane} pane
+    @returns {void}
+  */
+  blurMainTo: function(pane) {
+    this.set('isMainPane', NO) ;
+  },
+  
+  /** 
+    Invokes when the view is about to become the new mainPane.  The default 
+    implementation simply updates the isMainPane property.  In your subclass, 
+    you should make sure your pane has been added to the document before 
+    trying to make it the mainPane.  See SC.MainPane for more information.
+    
+    @param {SC.Pane} pane
+    @returns {void}
+  */
+  focusMainFrom: function(pane) {
+    this.set('isMainPane', YES);
+  },
+  
+  // .......................................................
+  // ADDING/REMOVE PANES TO SCREEN
+  //  
+  
+  /**
+    Inserts the pane at the end of the document.  This will also add the pane 
+    to the rootResponder.
+    
+    @param {SC.RootResponder} rootResponder
+    @returns {SC.Pane} receiver
+  */
+  append: function() {   
+    return this.appendTo(document.body) ;
+  },
+  
+  /**
+    Removes the pane from the document.  This will remove the
+    DOM node and deregister you from the document window.
+    
+    @returns {SC.Pane} receiver
+  */
+  remove: function() {
+    if (!this.get('isVisibleInWindow')) return this ; // nothing to do
+    if (!this.get('isPaneAttached')) return this ; // nothing to do
+    
+    // remove layer...
+    var dom = this.get('layer') ;
+    if (dom && dom.parentNode) dom.parentNode.removeChild(dom) ;
+    dom = null ;
+    
+    // remove intercept
+    this._removeIntercept();
+    
+    // resign keyPane status, if we had it
+    this.resignKeyPane();
+    
+    // remove the pane
+    var rootResponder = this.rootResponder ;
+    if (this.get('isMainPane')) rootResponder.makeMainPane(null) ;
+    rootResponder.panes.remove(this) ;
+    this.rootResponder = null ;
+    
+    // clean up some of my own properties
+    this.set('isPaneAttached', NO) ;
+    this.parentViewDidChange();
+    return this ;
+  },
+  
+  /**
+    Inserts the pane into the DOM as the last child of the passed DOM element. 
+    You can pass in either a CoreQuery object or a selector, which will be 
+    converted to a CQ object.  You can optionally pass in the rootResponder 
+    to use for this operation.  Normally you will not need to pass this as 
+    the default responder is suitable.
+    
+    @param {DOMElement} elem the element to append to
+    @returns {SC.Pane} receiver
+  */
+  appendTo: function(elem) {
+    var layer = this.get('layer');
+    if (!layer) layer =this.createLayer().get('layer'); 
+    
+    if (this.get('isPaneAttached') && (layer.parentNode === elem)) {
+      return this; // nothing to do
+    }
+    
+    elem.insertBefore(layer, null); // add to DOM
+    elem = layer = null ;
+
+    return this.paneDidAttach(); // do the rest of the setup
+  },
+
+  /** 
+    inserts the pane's rootElement into the top of the passed DOM element.
+    
+    @param {DOMElement} elem the element to append to
+    @returns {SC.Pane} receiver
+  */
+  prependTo: function(elem) {
+    if (this.get('isPaneAttached')) return this;
+    
+    var layer = this.get('layer');
+    if (!layer) layer =this.createLayer().get('layer'); 
+    
+    if (this.get('isPaneAttached') && (layer.parentNode === elem)) {
+      return this; // nothing to do
+    }
+    
+    elem.insertBefore(layer, elem.firstChild); // add to DOM
+    elem = layer = null ;
+
+    return this.paneDidAttach(); // do the rest of the setup
+  },
+
+  /** 
+    inserts the pane's rootElement into the hierarchy before the passed 
+    element.
+    
+    @param {DOMElement} elem the element to append to
+    @returns {SC.Pane} receiver
+  */
+  before: function(elem) {
+    if (this.get('isPaneAttached')) return this;
+    
+    var layer = this.get('layer');
+    if (!layer) layer =this.createLayer().get('layer');
+    
+    var parent = elem.parentNode ; 
+
+    if (this.get('isPaneAttached') && (layer.parentNode === parent)) {
+      return this; // nothing to do
+    }
+    
+    parent.insertBefore(layer, elem); // add to DOM
+    parent = elem = layer = null ;
+
+    return this.paneDidAttach(); // do the rest of the setup
+  },
+
+  /** 
+    inserts the pane's rootElement into the hierarchy after the passed 
+    element.
+    
+    @param {DOMElement} elem the element to append to
+    @returns {SC.Pane} receiver
+  */
+  after: function(elem) {
+    
+    var layer = this.get('layer');
+    if (!layer) layer =this.createLayer().get('layer'); 
+    
+    var parent = elem.parentNode ;
+  
+    if (this.get('isPaneAttached') && (layer.parentNode === parent)) {
+      return this; // nothing to do
+    }
+    
+    parent.insertBefore(layer, elem.nextSibling); // add to DOM
+    parent = elem = layer = null ;
+
+    return this.paneDidAttach(); // do the rest of the setup
+  },
+  
+  /**
+    This method has no effect in the pane.  Instead use remove().
+    
+    @returns {void}
+  */
+  removeFromParent: function() { },
+  
+  /** @private
+    Called when the pane is attached to a DOM element in a window, this will 
+    change the view status to be visible in the window and also register 
+    with the rootResponder.
+  */
+  paneDidAttach: function() {
+
+    // hook into root responder
+    var responder = (this.rootResponder = SC.RootResponder.responder);
+    responder.panes.add(this);
+  
+    // set currentWindowSize
+    this.set('currentWindowSize', responder.computeWindowSize()) ;
+    
+    // update my own location
+    this.set('isPaneAttached', YES) ;
+    this.parentViewDidChange() ;
+    
+    //notify that the layers have been appended to the document
+    this._notifyDidAppendToDocument();
+    
+    // handle intercept if needed
+    this._addIntercept();
+    return this ;
+  },
+  
+  /**
+    YES when the pane is currently attached to a document DOM.  Read only.
+    
+    @property {Boolean}
+    @readOnly
+  */
+  isPaneAttached: NO,
+  
+  /**
+    If YES, a touch itnercept pane will be added above this pane.
+  */
+  hasTouchIntercept: NO,
+  
+  /**
+    The Z-Index of the pane. Currently, you have to match this in CSS.
+    TODO: ALLOW THIS TO AUTOMATICALLY SET THE Z-INDEX OF THE PANE (as an option).
+  */
+  zIndex: 0,
+  
+  /**
+    The amount over the pane's z-index that the touch intercept should be.
+  */
+  touchZ: 99,
+
+  _addIntercept: function() {
+    if (this.get("hasTouchIntercept") && SC.platform.touch) {
+      this.set("usingTouchIntercept", YES);
+      var div = document.createElement("div");
+      var divStyle = div.style;
+      divStyle.position = "absolute";
+      divStyle.left = "0px";
+      divStyle.top = "0px";
+      divStyle.right = "0px";
+      divStyle.bottom = "0px";
+      divStyle.webkitTransform = "translateZ(0px)";
+      divStyle.zIndex = this.get("zIndex") + this.get("touchZ");
+      div.className = "touch-intercept";
+      div.id = "touch-intercept-" + SC.guidFor(this);
+      this._touchIntercept = div;
+      document.body.appendChild(div);
+    }
+  },
+  
+  _removeIntercept: function() {
+    if (this._touchIntercept) {
+      document.body.removeChild(this._touchIntercept);
+      this._touchIntercept = null;
+    }
+  },
+  
+  hideTouchIntercept: function() {
+    if (this._touchIntercept) this._touchIntercept.style.display = "none";
+  },
+  
+  showTouchIntercept: function() {
+    if (this._touchIntercept) this._touchIntercept.style.display = "block";
+  },
+
+  /**
+    Updates the isVisibleInWindow state on the pane and its childViews if 
+    necessary.  This works much like SC.View's default implementation, but it
+    does not need a parentView to function.
+    
+    @returns {SC.Pane} receiver
+  */
+  recomputeIsVisibleInWindow: function() {
+    if (this.get('designer') && SC.suppressMain) return sc_super();
+    var previous = this.get('isVisibleInWindow'),
+        current  = this.get('isVisible') && this.get("isPaneAttached");
+
+    // If our visibility has changed, then set the new value and notify our
+    // child views to update their value.
+    if (previous !== current) {
+      this.set('isVisibleInWindow', current);
+      
+      var childViews = this.get('childViews'), len = childViews.length, idx;
+      for(idx=0;idx<len;idx++) {
+        childViews[idx].recomputeIsVisibleInWindow(current);
+      }
+
+
+      // For historical reasons, we'll also layout the child views if
+      // necessary.
+      if (current) {
+        if (this.get('childViewsNeedLayout')) this.invokeOnce(this.layoutChildViewsIfNeeded);
+      }
+      else {
+        // Also, if we were previously visible and were the key pane, resign
+        // it.  This more appropriately belongs in a 'isVisibleInWindow'
+        // observer or some such helper method because this work is not
+        // strictly related to computing the visibility, but view performance
+        // is critical, so avoiding the extra observer is worthwhile.
+        if (this.get('isKeyPane')) this.resignKeyPane();
+      }
+    }
+
+    // If we're in this function, then that means one of our ancestor views
+    // changed, or changed its 'isVisibleInWindow' value.  That means that if
+    // we are out of sync with the layer, then we need to update our state
+    // now.
+    //
+    // For example, say we're isVisible=NO, but we have not yet added the
+    // 'hidden' class to the layer because of the "don't update the layer if
+    // we're not visible in the window" check.  If any of our parent views
+    // became visible, our layer would incorrectly be shown!
+    this.updateLayerIfNeeded(YES);
+
+    return this;
+  },
+  
+  /** @private */
+  updateLayerLocation: function() {
+    if(this.get('designer') && SC.suppressMain) return sc_super();
+    // note: the normal code here to update node location is removed 
+    // because we don't need it for panes.
+    return this ; 
+  },
+
+  /** @private */
+  init: function() {
+    // if a layer was set manually then we will just attach to existing 
+    // HTML.
+    var hasLayer = !!this.get('layer') ;
+    sc_super() ;
+    if (hasLayer) this.paneDidAttach();
+  },
+
+  /** @private */
+  classNames: 'sc-pane'.w()
+  
+}) ;
+