sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

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

@@ -0,0 +1,159 @@
+// ==========================================================================
+// 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 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. */
+  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
+    @type {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 
+    @type {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
+    @type {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
+    @param {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/frameworks/sproutcore/frameworks/foundation/mixins/validatable.js

@@ -0,0 +1,176 @@
+// ==========================================================================
+// 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
+
+  Views that include the Validatable mixin can be used with validators to 
+  ensure their values are valid.  
+  
+*/
+SC.Validatable = {
+  
+  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.
+  */
+  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.
+  */
+  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.
+    
+    @field
+  */
+  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.
+  */
+  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 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
+  */
+  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} the object
+  */
+  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.
+  */
+  validateSubmit: function() { return this.performValidateSubmit(); },
+  
+  /**
+    Convert the field value string into an object.
+    
+    This method will call the validators objectForFieldValue if it exists.
+    
+    @param fieldValue the raw value from the field.
+    @returns converted 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 the objec to convert
+    @returns converted field value
+  */
+  fieldValueForObject: function(object) {
+    return this._validator ? this._validator.fieldValueForObject(object, this.get('ownerForm'), this) : object ;
+  },
+  
+  _validatable_displayObserver: function() {
+    this.displayDidChange();
+  }.observes('isValid'),
+  
+  updateLayerMixin: 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/frameworks/sproutcore/frameworks/foundation/panes/main.js

@@ -0,0 +1,47 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+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({
+
+  layout: { left:0, right:0, top:0, bottom:0 },
+  
+  /** @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 ;
+  },
+  
+  acceptsKeyPane: YES,
+  
+  classNames: ['sc-main']
+});

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

@@ -0,0 +1,584 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+require('views/view');
+
+/** @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({
+
+  /** 
+    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. */
+  currentWindowSize: null,
+  
+  /** The parent dimensions are always the last known window size. */
+  computeParentDimensions: function(frame) {
+    var pframe = this.get('currentWindowSize');
+    return {
+      width: (pframe) ? pframe.width : 1000,
+      height: (pframe) ? pframe.height : 1000
+    } ;
+  },
+  
+  /** @private Disable caching due to an known bug in SC. */
+  frame: function() {
+    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.
+  */
+  windowSizeDidChange: function(oldSize, newSize) {
+    this.set('currentWindowSize', newSize) ;
+    this.parentViewDidResize(); // start notifications.
+  },
+  
+  /**
+    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 firstResponder 
+    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 if (target.isResponderContext) {
+        target = target.sendAction(action, this, evt);
+      } else target = target.tryToPerform(action, evt) ? target : null ;
+    }
+        
+    return evt.mouseHandler || target ;
+  },
+
+  // .......................................................
+  // HANDLE FIRST RESPONDER AND KEY RESPONDER STATUS
+  //
+
+  /** @property
+    The default responder.  Set this to point to a responder object that can 
+    respond to events when no other view in the hierarchy handles them.
+  */
+  defaultResponder: null,
+  
+  /** @property
+    Pane's never have a next responder
+  */
+  nextResponder: function() {
+    return null;
+  }.property().cacheable(),
+  
+  /** @property
+    The first responder.  This is the first view that should receive action 
+    events.  Whenever you click on a view, it will usually become firstResponder. 
+  */
+  firstResponder: null,
+  
+  /** @property
+    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.
+  */
+  acceptsKeyPane: YES,
+  
+  /** @property
+    This is set to YES when your pane is currently the target of key events. 
+  */
+  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
+    @returns {SC.Pane} receiver
+  */
+  makeFirstResponder: function(view) {
+    var current=this.get('firstResponder'), isKeyPane=this.get('isKeyPane');
+    if (current === view) return this ; // nothing to do
+    
+    // notify current of firstResponder change
+    if (current) current.willLoseFirstResponder(current);
+    
+    // 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 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
+  //
+  
+  isMainPane: NO,
+  
+  /**
+    Invoked when the pane is about to become the focused pane.
+    
+    @param {SC.Pane} pane the pane that currently have focus
+  */
+  focusFrom: function(pane) {},
+  
+  /**
+    Invoked when the the pane is about to lose its focused pane status.
+    
+    @param {SC.Pane} pane the pane that will receive focus next
+  */
+  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.
+  */
+  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.
+  */
+  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.
+  */
+  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.parentNode) dom.parentNode.removeChild(dom) ;
+    dom = null ;
+    
+    // remove from the RootResponder also
+    var responder = this.rootResponder ;
+    if (this.get('isKeyPane')) responder.makeKeyPane(null) ; // orders matter, remove keyPane first
+    if (this.get('isMainPane')) responder.makeMainPane(null) ;
+    responder.panes.remove(this) ;
+    this.rootResponder = responder = 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'); 
+    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) {
+    var layer = this.get('layer');
+    if (!layer) layer =this.createLayer().get('layer'); 
+    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) {
+    var layer = this.get('layer');
+    if (!layer) layer =this.createLayer().get('layer');
+    
+    var parent = elem.parentNode ; 
+    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 ;
+    elem.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().
+  */
+  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() ;
+    return this ;
+  },
+  
+  /** @property
+    YES when the pane is currently attached to a document DOM.  Read only.
+  */
+  isPaneAttached: NO,
+
+  /**
+    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.
+    
+    @param {Boolean} parentViewIsVisible (ignored)
+    @returns {SC.Pane} receiver
+  */
+  recomputeIsVisibleInWindow: function(parentViewIsVisible) {
+    var last = this.get('isVisibleInWindow') ;
+    var cur = this.get('isPaneAttached') && this.get('isVisible') ;
+
+    // if the state has changed, update it and notify children
+    if (last !== cur) {
+      this.set('isVisibleInWindow', cur) ;
+      
+      // if we just became visible, update layer + layout if needed...
+      if (cur && this.get('layerNeedsUpdate')) this.updateLayerIfNeeded();
+      if (cur && this.get('childViewsNeedLayout')) this.layoutChildViewsIfNeeded();
+      
+      var childViews = this.get('childViews'), len = childViews.length, idx;
+      for(idx=0;idx<len;idx++) {
+        childViews[idx].recomputeIsVisibleInWindow(cur);
+      }
+      
+      // if we were firstResponder, resign firstResponder also if no longer
+      // visible.
+      if (!cur && this.get('isFirstResponder')) this.resignFirstResponder();
+    }
+    
+    return this ;
+  },
+  
+  updateLayerLocation: function() {
+    // note: the normal code here to update node location is removed 
+    // because we don't need it for panes.
+    return this ; 
+  },
+
+  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();
+  },
+
+  classNames: 'sc-pane'.w()
+  
+}) ;
+