sproutcore 1.5.0.pre.3 → 1.5.0.pre.4

data/lib/frameworks/sproutcore/frameworks/core_foundation/views/view.js

@@ -0,0 +1,1280 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('system/browser');
+sc_require('system/event');
+sc_require('system/cursor');
+sc_require('system/responder') ;
+sc_require('system/theme');
+
+sc_require('mixins/string') ;
+sc_require('views/view/base') ;
+
+/**
+  Default property to disable or enable by default the contextMenu
+*/
+SC.CONTEXT_MENU_ENABLED = YES;
+
+/**
+  Default property to disable or enable if the focus can jump to the address
+  bar or not.
+*/
+SC.TABBING_ONLY_INSIDE_DOCUMENT = YES;
+
+/**
+  Tells the property (when fetched with themed()) to get its value from the renderer (if any).
+*/
+SC.FROM_THEME = "__FROM_THEME__"; // doesn't really matter what it is, so long as it is unique. Readability is a plus.
+
+/** @private - custom array used for child views */
+SC.EMPTY_CHILD_VIEWS_ARRAY = [];
+SC.EMPTY_CHILD_VIEWS_ARRAY.needsClone = YES;
+
+/**
+  @class
+
+  Base class for managing a view.  Views provide two functions:
+
+  1. They translate state and events into drawing instructions for the
+     web browser and
+
+  2. They act as first responders for incoming keyboard, mouse, and
+     touch events.
+
+  h2. View Initialization
+
+  When a view is setup, there are several methods you can override that
+  will be called at different times depending on how your view is created.
+  Here is a guide to which method you want to override and when:
+
+  - *init:* override this method for any general object setup (such as
+    observers, starting timers and animations, etc) that you need to happen
+    everytime the view is created, regardless of whether or not its layer
+    exists yet.
+
+  - *render:* override this method to generate or update your HTML to reflect
+    the current state of your view.  This method is called both when your view
+    is first created and later anytime it needs to be updated.
+
+  - *didCreateLayer:* the render() method is used to generate new HTML.
+    Override this method to perform any additional setup on the DOM you might
+    need to do after creating the view.  For example, if you need to listen
+    for events.
+
+  - *willDestroyLayer:* if you implement didCreateLayer() to setup event
+    listeners, you should implement this method as well to remove the same
+    just before the DOM for your view is destroyed.
+
+  - *updateLayer:* Normally, when a view needs to update its content, it will
+    re-render the view using the render() method.  If you would like to
+    override this behavior with your own custom updating code, you can
+    replace updateLayer() with your own implementation instead.
+
+  - *didAppendToDocument:* in theory all DOM setup could be done
+    in didCreateLayer() as you already have a DOM element instantiated.
+    However there is cases where the element has to be first appended to the
+    Document because there is either a bug on the browser or you are using
+    plugins which objects are not instantiated until you actually append the
+    element to the DOM. This will allow you to do things like registering
+    DOM events on flash or quicktime objects.
+
+  @extends SC.Responder
+  @extends SC.DelegateSupport
+  @since SproutCore 1.0
+*/
+SC.CoreView.reopen(
+/** @scope SC.View.prototype */ {
+
+  concatenatedProperties: 'outlets displayProperties classNames renderMixin didCreateLayerMixin willDestroyLayerMixin'.w(),
+
+  /**
+    The current pane.
+    @property {SC.Pane}
+  */
+  pane: function() {
+    var view = this ;
+    while (view && !view.isPane) { view = view.get('parentView') ; }
+    return view ;
+  }.property('parentView').cacheable(),
+
+  /**
+    The page this view was instantiated from.  This is set by the page object
+    during instantiation.
+
+    @property {SC.Page}
+  */
+  page: null,
+
+  /**
+    If the view is currently inserted into the DOM of a parent view, this
+    property will point to the parent of the view.
+  */
+  parentView: null,
+
+  /**
+    The isVisible property determines if the view is shown in the view
+    hierarchy it is a part of. A view can have isVisible == YES and still have
+    isVisibleInWindow == NO. This occurs, for instance, when a parent view has
+    isVisible == NO. Default is YES.
+
+    The isVisible property is considered part of the layout and so changing it
+    will trigger a layout update.
+
+    @property {Boolean}
+  */
+  isVisible: YES,
+  isVisibleBindingDefault: SC.Binding.bool(),
+
+  // ..........................................................
+  // CHILD VIEW SUPPORT
+  //
+
+  /**
+    Array of child views.  You should never edit this array directly unless
+    you are implementing createChildViews().  Most of the time, you should
+    use the accessor methods such as appendChild(), insertBefore() and
+    removeChild().
+
+    @property {Array}
+  */
+  childViews: SC.EMPTY_CHILD_VIEWS_ARRAY,
+
+  // ..........................................................
+  // LAYER SUPPORT
+  //
+
+  /**
+    Returns the current layer for the view.  The layer for a view is only
+    generated when the view first becomes visible in the window and even
+    then it will not be computed until you request this layer property.
+
+    If the layer is not actually set on the view itself, then the layer will
+    be found by calling this.findLayerInParentLayer().
+
+    You can also set the layer by calling set on this property.
+
+    @property {DOMElement} the layer
+  */
+  layer: function(key, value) {
+    if (value !== undefined) {
+      this._view_layer = value ;
+
+    // no layer...attempt to discover it...
+    } else {
+      value = this._view_layer;
+      if (!value) {
+        var parent = this.get('parentView');
+        if (parent) { parent = parent.get('layer'); }
+        if (parent) { this._view_layer = value = this.findLayerInParentLayer(parent); }
+      }
+    }
+    return value ;
+  }.property('isVisibleInWindow').cacheable(),
+
+  /**
+    Get a CoreQuery object for this view's layer, or pass in a selector string
+    to get a CoreQuery object for a DOM node nested within this layer.
+
+    @param {String} sel a CoreQuery-compatible selector string
+    @returns {SC.CoreQuery} the CoreQuery object for the DOM node
+  */
+  $: function(sel) {
+    var layer = this.get('layer') ;
+
+    if(!layer) { return SC.$(); }
+    else if(sel === undefined) { return SC.$(layer); }
+    else { return SC.$(sel, layer); }
+  },
+
+  /**
+    Returns the DOM element that should be used to hold child views when they
+    are added/remove via DOM manipulation.  The default implementation simply
+    returns the layer itself.  You can override this to return a DOM element
+    within the layer.
+
+    @property {DOMElement} the container layer
+  */
+  containerLayer: function() {
+    return this.get('layer') ;
+  }.property('layer').cacheable(),
+
+  /**
+    The ID to use when trying to locate the layer in the DOM.  If you do not
+    set the layerId explicitly, then the view's GUID will be used instead.
+    This ID must be set at the time the view is created.
+
+    @property {String}
+    @readOnly
+  */
+  layerId: function(key, value) {
+    if (value) { this._layerId = value; }
+    if (this._layerId) { return this._layerId; }
+    return SC.guidFor(this) ;
+  }.property().cacheable(),
+
+  /**
+    Attempts to discover the layer in the parent layer.  The default
+    implementation looks for an element with an ID of layerId (or the view's
+    guid if layerId is null).  You can override this method to provide your
+    own form of lookup.  For example, if you want to discover your layer using
+    a CSS class name instead of an ID.
+
+    @param {DOMElement} parentLayer the parent's DOM layer
+    @returns {DOMElement} the discovered layer
+  */
+  findLayerInParentLayer: function(parentLayer) {
+    var id = "#" + this.get('layerId');
+    return jQuery(id)[0] || jQuery(id, parentLayer)[0] ;
+  },
+
+  /**
+    Returns YES if the receiver is a subview of a given view or if it's
+    identical to that view. Otherwise, it returns NO.
+
+    @property {SC.View} view
+  */
+  isDescendantOf: function(view) {
+    var parentView = this.get('parentView');
+
+    if(this === view) { return YES; }
+    else if(parentView) { return parentView.isDescendantOf(view); }
+    else { return NO; }
+  },
+
+  /**
+    This method is invoked whenever a display property changes.  It will set
+    the layerNeedsUpdate method to YES.  If you need to perform additional
+    setup whenever the display changes, you can override this method as well.
+
+    @returns {SC.View} receiver
+  */
+  displayDidChange: function() {
+    this.set('layerNeedsUpdate', YES) ;
+    return this;
+  },
+
+  /**
+    Setting this property to YES will cause the updateLayerIfNeeded method to
+    be invoked at the end of the runloop.  You can also force a view to update
+    sooner by calling updateLayerIfNeeded() directly.  The method will update
+    the layer only if this property is YES.
+
+    @property {Boolean}
+    @test in updateLayer
+  */
+  layerNeedsUpdate: NO,
+
+  /** @private
+    Schedules the updateLayerIfNeeded method to run at the end of the runloop
+    if layerNeedsUpdate is set to YES.
+  */
+  _view_layerNeedsUpdateDidChange: function() {
+    if (this.get('layerNeedsUpdate')) {
+      this.invokeOnce(this.updateLayerIfNeeded) ;
+    }
+  }.observes('layerNeedsUpdate'),
+
+  /**
+    Updates the layer only if the view is visible onscreen and if
+    layerNeedsUpdate is set to YES.  Normally you will not invoke this method
+    directly.  Instead you set the layerNeedsUpdate property to YES and this
+    method will be called once at the end of the runloop.
+
+    If you need to update view's layer sooner than the end of the runloop, you
+    can call this method directly.  If your view is not visible in the window
+    but you want it to update anyway, then call this method, passing YES for
+    the 'skipIsVisibleInWindowCheck' parameter.
+
+    You should not override this method.  Instead override updateLayer() or
+    render().
+
+    @returns {SC.View} receiver
+    @test in updateLayer
+  */
+  updateLayerIfNeeded: function(skipIsVisibleInWindowCheck) {
+    var needsUpdate  = this.get('layerNeedsUpdate'),
+        shouldUpdate = needsUpdate  &&  (skipIsVisibleInWindowCheck || this.get('isVisibleInWindow'));
+    if (shouldUpdate) {
+      // only update a layer if it already exists
+      if (this.get('layer')) {
+        this.beginPropertyChanges() ;
+        this.set('layerNeedsUpdate', NO) ;
+        this.updateLayer() ;
+        this.endPropertyChanges() ;
+      }
+    }
+
+    return this ;
+  },
+
+  /**
+    This is the core method invoked to update a view layer whenever it has
+    changed.  This method simply creates a render context focused on the
+    layer element and then calls your render() method.
+
+    You will not usually call or override this method directly.  Instead you
+    should set the layerNeedsUpdate property to YES to cause this method to
+    run at the end of the run loop, or you can call updateLayerIfNeeded()
+    to force the layer to update immediately.
+
+    Instead of overriding this method, consider overidding the render() method
+    instead, which is called both when creating and updating a layer.  If you
+    do not want your render() method called when updating a layer, then you
+    should override this method instead.
+
+    @param optionalContext provided only for backwards-compatibility.
+
+    @returns {SC.View} receiver
+  */
+  updateLayer: function(optionalContext) {
+    var mixins, idx, len, hasLegacyRenderMethod;
+
+    var context = optionalContext || this.renderContext(this.get('layer')) ;
+    this._renderLayerSettings(context, NO);
+
+    // If the render method takes two parameters, we assume that it is a
+    // legacy implementation that takes context and firstTime. If it has only
+    // one parameter, we assume it is the render delegates style that requires
+    // only context. Note that, for backwards compatibility, the default
+    // SC.View implementation of render uses the old style.
+    hasLegacyRenderMethod = !this.update;
+    // Call render with firstTime set to NO to indicate an update, rather than
+    // full re-render, should be performed.
+    if (hasLegacyRenderMethod) {
+      this.render(context, NO);
+    }
+    else {
+      this.update(context.$());
+    }
+    if (mixins = this.renderMixin) {
+      len = mixins.length;
+      for(idx=0; idx<len; ++idx) { mixins[idx].call(this, context, NO) ; }
+    }
+
+    context.update() ;
+    if (context._innerHTMLReplaced) {
+      var pane = this.get('pane');
+      if(pane && pane.get('isPaneAttached')) {
+        this._notifyDidAppendToDocument();
+      }
+    }
+
+    // If this view uses static layout, then notify that the frame (likely)
+    // changed.
+    if (this.useStaticLayout) { this.viewDidResize(); }
+
+    if (this.didUpdateLayer) { this.didUpdateLayer(); } // call to update DOM
+    if(this.designer && this.designer.viewDidUpdateLayer) {
+      this.designer.viewDidUpdateLayer(); //let the designer know
+    }
+    return this ;
+  },
+
+  parentViewDidResize: function() {
+    this.viewDidResize();
+  },
+
+  /**
+    Override this in a child class to define behavior that should be invoked
+    when a parent's view was resized.
+   */
+  viewDidResize: function() {},
+
+  /**
+    Creates a new renderContext with the passed tagName or element.  You
+    can override this method to provide further customization to the context
+    if needed.  Normally you will not need to call or override this method.
+
+    @returns {SC.RenderContext}
+  */
+  renderContext: function(tagNameOrElement) {
+    return SC.RenderContext(tagNameOrElement) ;
+  },
+
+  /**
+    Creates the layer by creating a renderContext and invoking the view's
+    render() method.  This will only create the layer if the layer does not
+    already exist.
+
+    When you create a layer, it is expected that your render() method will
+    also render the HTML for all child views as well.  This method will
+    notify the view along with any of its childViews that its layer has been
+    created.
+
+    @returns {SC.View} receiver
+  */
+  createLayer: function() {
+    if (this.get('layer')) { return this ; } // nothing to do
+
+    var context = this.renderContext(this.get('tagName')) ;
+
+    // now prepare the content like normal.
+    this.renderToContext(context) ;
+    this.set('layer', context.element()) ;
+
+    // now notify the view and its child views..
+    this._notifyDidCreateLayer() ;
+
+    return this ;
+  },
+
+  /** @private -
+    Invokes the receivers didCreateLayer() method if it exists and then
+    invokes the same on all child views.
+  */
+  _notifyDidCreateLayer: function() {
+    this.notifyPropertyChange("layer");
+    if (this.didCreateLayer) { this.didCreateLayer() ; }
+
+    // and notify others
+    var mixins = this.didCreateLayerMixin, len, idx,
+        childViews = this.get('childViews'),
+        childView;
+    if (mixins) {
+      len = mixins.length ;
+      for (idx=0; idx<len; ++idx) { mixins[idx].call(this) ; }
+    }
+
+    len = childViews.length ;
+    for (idx=0; idx<len; ++idx) {
+      childView = childViews[idx];
+      if (!childView) { continue; }
+
+      // A parent view creating a layer might result in the creation of a
+      // child view's DOM node being created via a render context without
+      // createLayer() being invoked on the child.  In such cases, if anyone
+      // had requested 'layer' and it was cached as null, we need to
+      // invalidate it.
+      childView.notifyPropertyChange('layer');
+
+      childView._notifyDidCreateLayer() ;
+    }
+  },
+
+  /**
+    Destroys any existing layer along with the layer for any child views as
+    well.  If the view does not currently have a layer, then this method will
+    do nothing.
+
+    If you implement willDestroyLayer() on your view or if any mixins
+    implement willDestroLayerMixin(), then this method will be invoked on your
+    view before your layer is destroyed to give you a chance to clean up any
+    event handlers, etc.
+
+    If you write a willDestroyLayer() handler, you can assume that your
+    didCreateLayer() handler was called earlier for the same layer.
+
+    Normally you will not call or override this method yourself, but you may
+    want to implement the above callbacks when it is run.
+
+    @returns {SC.View} receiver
+  */
+  destroyLayer: function() {
+    var layer = this.get('layer') ;
+    if (layer) {
+
+      // Now notify the view and its child views.  It will also set the
+      // layer property to null.
+      this._notifyWillDestroyLayer() ;
+
+      // do final cleanup
+      if (layer.parentNode) { layer.parentNode.removeChild(layer) ; }
+      layer = null ;
+    }
+    return this ;
+  },
+
+  /**
+    Destroys and recreates the current layer.  This can be more efficient than
+    modifying individual child views.
+
+    @returns {SC.View} receiver
+  */
+  replaceLayer: function() {
+    this.destroyLayer();
+    //this.set('layerLocationNeedsUpdate', YES) ;
+    this.invokeOnce(this.updateLayerLocation) ;
+  },
+
+  /** @private -
+    Invokes willDestroyLayer() on view and child views.  Then sets layer to
+    null for receiver.
+  */
+  _notifyWillDestroyLayer: function() {
+    if (this.willDestroyLayer) { this.willDestroyLayer() ; }
+    var mixins = this.willDestroyLayerMixin, len, idx,
+        childViews = this.get('childViews') ;
+    if (mixins) {
+      len = mixins.length ;
+      for (idx=0; idx<len; ++idx) { mixins[idx].call(this) ; }
+    }
+
+    len = childViews.length ;
+    for (idx=0; idx<len; ++idx) { childViews[idx]._notifyWillDestroyLayer() ; }
+
+    this.set('layer', null) ;
+  },
+
+
+
+  /**
+    @private
+
+    Renders to a context.
+    Rendering only happens for the initial rendering. Further updates happen in updateLayer,
+    and are not done to contexts, but to layers.
+    Note: You should not generally override nor directly call this method. This method is only
+    called by createLayer to set up the layer initially, and by renderChildViews, to write to
+    a context.
+
+    @param {SC.RenderContext} context the render context.
+    @param {Boolean} firstTime Provided for compatibility when rendering legacy views only.
+  */
+  renderToContext: function(context, firstTime) {
+    var hasLegacyRenderMethod, mixins, idx, len;
+
+    this.beginPropertyChanges() ;
+    this.set('layerNeedsUpdate', NO) ;
+
+    if (SC.none(firstTime)) { firstTime = YES; }
+
+    this._renderLayerSettings(context, firstTime);
+
+    // If the render method takes two parameters, we assume that it is a
+    // legacy implementation that takes context and firstTime. If it has only
+    // one parameter, we assume it is the render delegates style that requires
+    // only context. Note that, for backwards compatibility, the default
+    // SC.View implementation of render uses the old style.
+    hasLegacyRenderMethod = !this.update;
+
+    // Let the render method handle rendering. If we have a render delegate
+    // object set, it will be used there.
+    if (hasLegacyRenderMethod) {
+      this.render(context, firstTime);
+    }
+    // This view implements the render delegate protocol.
+    else {
+      if (firstTime) {
+        this.render(context);
+      } else {
+        this.update(context.$());
+      }
+    }
+
+    if (firstTime && !this._didRenderChildViews) { this.renderChildViews(context, firstTime); }
+
+    if (mixins = this.renderMixin) {
+      len = mixins.length;
+      for(idx=0; idx<len; ++idx) { mixins[idx].call(this, context, firstTime) ; }
+    }
+
+    this.endPropertyChanges() ;
+  },
+
+  _renderLayerSettings: function(context, firstTime) {
+    context.resetClassNames();
+    context.resetStyles();
+
+    this.applyAttributesToContext(context);
+  },
+
+  applyAttributesToContext: function(context) {
+    context.addClass(this.get('classNames'));
+
+    var cursor = this.get('cursor');
+    if (cursor) { context.addClass(cursor.get('className')); }
+
+    if (this.get('isTextSelectable')) { context.addClass('allow-select'); }
+    if (!this.get('isVisible')) { context.addClass('hidden'); }
+    if (this.get('isFirstResponder')) { context.addClass('focus'); }
+
+    context.id(this.get('layerId'));
+    context.attr('role', this.get('ariaRole'));
+  },
+
+  /**
+  @private
+
+    Invoked by createLayer() and updateLayer() to actually render a context.
+    This method calls the render() method on your view along with any
+    renderMixin() methods supplied by mixins you might have added.
+
+    You should not override this method directly. Nor should you call it. It is OLD.
+
+    @param {SC.RenderContext} context the render context
+    @param {Boolean} firstTime YES if this is creating a layer
+    @returns {void}
+  */
+  prepareContext: function(context, firstTime) {
+    // eventually, firstTime will be removed because it is ugly.
+    // for now, we will sense whether we are doing things the ugly way or not.
+    // if ugly, we will allow updates through.
+    if (firstTime !== false) { firstTime = YES; } // the GOOD code path :)
+
+    if (firstTime) {
+      this.renderToContext(context);
+    } else {
+      this.updateLayer(context);
+    }
+  },
+
+  /**
+    Your render method should invoke this method to render any child views,
+    especially if this is the first time the view will be rendered.  This will
+    walk down the childView chain, rendering all of the children in a nested
+    way.
+
+    @param {SC.RenderContext} context the context
+    @param {Boolean} firstName true if the layer is being created
+    @returns {SC.RenderContext} the render context
+    @test in render
+  */
+  renderChildViews: function(context, firstTime) {
+    var cv = this.get('childViews'), len = cv.length, idx, view ;
+    for (idx=0; idx<len; ++idx) {
+      view = cv[idx] ;
+      if (!view) { continue; }
+      context = context.begin(view.get('tagName')) ;
+      view.renderToContext(context, firstTime);
+      context = context.end() ;
+    }
+    return context;
+  },
+
+  /** @private -
+    override to add support for theming or in your view
+  */
+  render: function() { },
+
+  /** @private -
+    Invokes the receivers didAppendLayerToDocument() method if it exists and
+    then invokes the same on all child views.
+  */
+
+  _notifyDidAppendToDocument: function() {
+    if (this.didAppendToDocument) { this.didAppendToDocument(); }
+
+    var i=0, child, childLen, children = this.get('childViews');
+    for(i=0, childLen=children.length; i<childLen; i++) {
+      child = children[i];
+      if(child._notifyDidAppendToDocument){
+        child._notifyDidAppendToDocument();
+      }
+    }
+  },
+
+  childViewsObserver: function(){
+    var childViews = this.get('childViews'), i, iLen, child;
+    for(i=0, iLen = childViews.length; i<iLen; i++){
+      child = childViews[i];
+      if(child._notifyDidAppendToDocument){
+        child._notifyDidAppendToDocument();
+      }
+    }
+  }.observes('childViews'),
+
+  // ..........................................................
+  // STANDARD RENDER PROPERTIES
+  //
+
+  /**
+    Tag name for the view's outer element.  The tag name is only used when
+    a layer is first created.  If you change the tagName for an element, you
+    must destroy and recreate the view layer.
+
+    @property {String}
+  */
+  tagName: 'div',
+
+  /**
+    The WAI-ARIA role of the control represented by this view. For example, a
+    button may have a role of type 'button', or a pane may have a role of
+    type 'alertdialog'. This property is used by assistive software to help
+    visually challenged users navigate rich web applications.
+
+    The full list of valid WAI-ARIA roles is available at:
+    http://www.w3.org/TR/wai-aria/roles#roles_categorization
+
+    @property {String}
+  */
+  ariaRole: null,
+
+  /**
+    Standard CSS class names to apply to the view's outer element.  This
+    property automatically inherits any class names defined by the view's
+    superclasses as well.
+
+    @property {Array}
+  */
+  classNames: ['sc-view'],
+
+  /**
+    Tool tip property that will be set to the title attribute on the HTML
+    rendered element.
+
+    @property {String}
+  */
+  toolTip: null,
+
+  /**
+    The computed tooltip.  This is generated by localizing the toolTip
+    property if necessary.
+
+    @property {String}
+  */
+  displayToolTip: function() {
+    var ret = this.get('toolTip');
+    return (ret && this.get('localize')) ? ret.loc() : (ret || '');
+  }.property('toolTip','localize').cacheable(),
+
+  /**
+    Determines if the user can select text within the view.  Normally this is
+    set to NO to disable text selection.  You should set this to YES if you
+    are creating a view that includes editable text.  Otherwise, settings this
+    to YES will probably make your controls harder to use and it is not
+    recommended.
+
+    @property {Boolean}
+    @readOnly
+  */
+  isTextSelectable: NO,
+
+  /**
+    You can set this array to include any properties that should immediately
+    invalidate the display.  The display will be automatically invalidated
+    when one of these properties change.
+
+    These are the properties that will be visible to any Render Delegate.
+    When the RenderDelegate asks for a property it needs, the view checks the
+    displayProperties array. It first looks for the property name prefixed
+    by 'display'; for instance, if the render delegate needs a 'title',
+    the view will attempt to find 'displayTitle'. If there is no 'displayTitle'
+    in displayProperties, the view will then try 'title'. If 'title' is not
+    in displayProperties either, an error will be thrown.
+
+    This allows you to avoid collisions between your view's API and the Render
+    Delegate's API.
+
+    Implementation note:  'isVisible' is also effectively a display property,
+    but it is not declared as such because the same effect is implemented
+    inside _sc_isVisibleDidChange().  This avoids having two observers on
+    'isVisible', which is:
+      a.  More efficient
+      b.  More correct, because we can guarantee the order of operations
+
+    @property {Array}
+    @readOnly
+  */
+  displayProperties: ['isFirstResponder'],
+
+  // .......................................................
+  // SC.RESPONDER SUPPORT
+  //
+
+  /** @property
+    The nextResponder is usually the parentView.
+  */
+  nextResponder: function() {
+    return this.get('parentView') ;
+  }.property('parentView').cacheable(),
+
+
+  /** @property
+    Set to YES if your view is willing to accept first responder status.  This
+    is used when calculcating key responder loop.
+  */
+  acceptsFirstResponder: NO,
+
+  // .......................................................
+  // CORE DISPLAY METHODS
+  //
+
+  /** @private
+    Setup a view, but do not finish waking it up.
+    - configure childViews
+    - Determine the view's theme
+    - Fetch a render delegate from the theme, if necessary
+    - register the view with the global views hash, which is used for event
+      dispatch
+  */
+  init: function() {
+    var parentView = this.get('parentView'),
+        path, root, lp, displayProperties ;
+
+    sc_super();
+
+    // Register the view for event handling. This hash is used by
+    // SC.RootResponder to dispatch incoming events.
+    SC.View.views[this.get('layerId')] = this;
+
+    // setup child views.  be sure to clone the child views array first
+    this.childViews = this.get('childViews').slice() ;
+    this.createChildViews() ; // setup child Views
+
+    // register display property observers ..
+    // TODO: Optimize into class setup
+    displayProperties = this.get('displayProperties') ;
+    for(var i=0, l=displayProperties.length; i<l; i++) {
+      this.addObserver(displayProperties[i], this, this.displayDidChange);
+    }
+  },
+
+  /**
+    Wakes up the view. The default implementation immediately syncs any
+    bindings, which may cause the view to need its display updated. You
+    can override this method to perform any additional setup. Be sure to
+    call sc_super to setup bindings and to call awake on childViews.
+
+    It is best to awake a view before you add it to the DOM.  This way when
+    the DOM is generated, it will have the correct initial values and will
+    not require any additional setup.
+
+    @returns {void}
+  */
+  awake: function() {
+    sc_super();
+    var childViews = this.get('childViews'), len = childViews.length, idx ;
+    for (idx=0; idx<len; ++idx) {
+      if (!childViews[idx]) { continue ; }
+      childViews[idx].awake() ;
+    }
+  },
+
+  /**
+    Removes the child view from the parent view.
+
+    @param {SC.View} view
+    @returns {SC.View} receiver
+  */
+  removeChild: function(view) {
+    // update parent node
+    view.set('parentView', null) ;
+
+    // remove view from childViews array.
+    var childViews = this.get('childViews'),
+        idx = childViews.indexOf(view) ;
+    if (idx>=0) { childViews.removeAt(idx); }
+
+    return this ;
+  },
+
+  /**
+    Removes all children from the parentView.
+
+    @returns {SC.View} receiver
+  */
+  removeAllChildren: function() {
+    var childViews = this.get('childViews'), view ;
+    while (view = childViews.objectAt(childViews.get('length')-1)) {
+      this.removeChild(view) ;
+    }
+    return this ;
+  },
+
+  /**
+    Removes the view from its parentView, if one is found.  Otherwise
+    does nothing.
+
+    @returns {SC.View} receiver
+  */
+  removeFromParent: function() {
+    var parent = this.get('parentView') ;
+    if (parent) { parent.removeChild(this) ; }
+    return this ;
+  },
+
+  /**
+    You must call this method on a view to destroy the view (and all of its
+    child views). This will remove the view from any parent node, then make
+    sure that the DOM element managed by the view can be released by the
+    memory manager.
+  */
+  destroy: function() {
+    if (this.get('isDestroyed')) { return this; } // nothing to do
+
+    this._destroy(); // core destroy method
+
+    // remove from parent if found
+    if (this.get('parentView')) { this.removeFromParent(); }
+
+    //Do generic destroy. It takes care of mixins and sets isDestroyed to YES.
+    sc_super();
+    return this; // done with cleanup
+  },
+
+  _destroy: function() {
+    if (this.get('isDestroyed')) { return this ; } // nothing to do
+
+    // destroy the layer -- this will avoid each child view destroying
+    // the layer over and over again...
+    this.destroyLayer() ;
+
+    // first destroy any children.
+    var childViews = this.get('childViews'), len = childViews.length, idx ;
+    if (len) {
+      childViews = childViews.slice() ;
+      for (idx=0; idx<len; ++idx) { childViews[idx].destroy() ; }
+    }
+
+    // next remove view from global hash
+    delete SC.View.views[this.get('layerId')] ;
+    delete this._CQ ;
+    delete this.page ;
+
+    return this ;
+  },
+
+  /**
+    This method is called when your view is first created to setup any  child
+    views that are already defined on your class.  If any are found, it will
+    instantiate them for you.
+
+    The default implementation of this method simply steps through your
+    childViews array, which is expects to either be empty or to contain View
+    designs that can be instantiated
+
+    Alternatively, you can implement this method yourself in your own
+    subclasses to look for views defined on specific properties and then build
+     a childViews array yourself.
+
+    Note that when you implement this method yourself, you should never
+    instantiate views directly.  Instead, you should use
+    this.createChildView() method instead.  This method can be much faster in
+    a production environment than creating views yourself.
+
+    @returns {SC.View} receiver
+  */
+  createChildViews: function() {
+    var childViews = this.get('childViews'),
+        len        = childViews.length,
+        idx, key, views, view ;
+
+    this.beginPropertyChanges() ;
+
+    // swap the array
+    for (idx=0; idx<len; ++idx) {
+      if (key = (view = childViews[idx])) {
+
+        // is this is a key name, lookup view class
+        if (typeof key === SC.T_STRING) {
+          view = this[key];
+        } else {
+          key = null ;
+        }
+
+        if (!view) {
+          console.error ("No view with name "+key+" has been found in "+this.toString());
+          // skip this one.
+          continue;
+        }
+
+        // createChildView creates the view if necessary, but also sets
+        // important properties, such as parentView
+        view = this.createChildView(view) ;
+        if (key) { this[key] = view ; } // save on key name if passed
+      }
+      childViews[idx] = view;
+    }
+
+    this.endPropertyChanges() ;
+    return this ;
+  },
+
+  /**
+    Instantiates a view to be added to the childViews array during view
+    initialization. You generally will not call this method directly unless
+    you are overriding createChildViews(). Note that this method will
+    automatically configure the correct settings on the new view instance to
+    act as a child of the parent.
+
+    @param {Class} viewClass
+    @param {Hash} attrs optional attributes to add
+    @returns {SC.View} new instance
+    @test in createChildViews
+  */
+  createChildView: function(view, attrs) {
+    if (!view.isClass) {
+      attrs = view;
+    } else {
+      // attrs should always exist...
+      if (!attrs) { attrs = {} ; }
+      // clone the hash that was given so we dont pollute it if it's being reused
+      else { attrs = SC.clone(attrs); }
+    }
+
+    attrs.owner = attrs.parentView = this ;
+    attrs.isVisibleInWindow = this.get('isVisibleInWindow');
+    if (!attrs.page) { attrs.page = this.page ; }
+
+    // Now add this to the attributes and create.
+    if (view.isClass) { view = view.create(attrs); }
+    return view ;
+  },
+
+  /** walk like a duck */
+  isView: YES,
+
+  /**
+    Default method called when a selectstart event is triggered. This event is
+    only supported by IE. Used in sproutcore to disable text selection and
+    IE8 accelerators. The accelerators will be enabled only in
+    text selectable views. In FF and Safari we use the css style 'allow-select'.
+
+    If you want to enable text selection in certain controls is recommended
+    to override this function to always return YES , instead of setting
+    isTextSelectable to true.
+
+    For example in textfield you dont want to enable textSelection on the text
+    hint only on the actual text you are entering. You can achieve that by
+    only overriding this method.
+
+    @param evt {SC.Event} the selectstart event
+    @returns YES if selectable
+  */
+  selectStart: function(evt) {
+    return this.get('isTextSelectable');
+  },
+
+  /**
+    Used to block the contextMenu per view.
+
+    @param evt {SC.Event} the contextmenu event
+    @returns YES if the contextmenu can show up
+  */
+  contextMenu: function(evt) {
+    if(!this.get('isContextMenuEnabled')) evt.stop();
+    return true;
+  }
+
+});
+
+SC.CoreView.mixin(/** @scope SC.CoreView */ {
+
+  /** @private walk like a duck -- used by SC.Page */
+  isViewClass: YES,
+
+  /**
+    This method works just like extend() except that it will also preserve
+    the passed attributes in case you want to use a view builder later, if
+    needed.
+
+    @param {Hash} attrs Attributes to add to view
+    @returns {Class} SC.View subclass to create
+    @function
+  */
+  design: function() {
+    if (this.isDesign) { return this; } // only run design one time
+    var ret = this.extend.apply(this, arguments);
+    ret.isDesign = YES ;
+    if (SC.ViewDesigner) {
+      SC.ViewDesigner.didLoadDesign(ret, this, SC.A(arguments));
+    }
+    return ret ;
+  },
+
+  extend: function() {
+    var last = arguments[arguments.length - 1];
+
+    if (last && !SC.none(last.theme)) {
+      last.themeName = last.theme;
+      delete last.theme;
+    }
+
+    return SC.Object.extend.apply(this, arguments);
+  },
+
+  /**
+    Helper applies the layout to the prototype.
+  */
+  layout: function(layout) {
+    this.prototype.layout = layout ;
+    return this ;
+  },
+
+  /**
+    Helper applies the classNames to the prototype
+  */
+  classNames: function(sc) {
+    sc = (this.prototype.classNames || []).concat(sc);
+    this.prototype.classNames = sc;
+    return this ;
+  },
+
+  /**
+    Help applies the tagName
+  */
+  tagName: function(tg) {
+    this.prototype.tagName = tg;
+    return this ;
+  },
+
+  /**
+    Helper adds the childView
+  */
+  childView: function(cv) {
+    var childViews = this.prototype.childViews || [];
+    if (childViews === this.superclass.prototype.childViews) {
+      childViews = childViews.slice();
+    }
+    childViews.push(cv) ;
+    this.prototype.childViews = childViews;
+    return this ;
+  },
+
+  /**
+    Helper adds a binding to a design
+  */
+  bind: function(keyName, path) {
+    var p = this.prototype, s = this.superclass.prototype;
+    var bindings = p._bindings ;
+    if (!bindings || bindings === s._bindings) {
+      bindings = p._bindings = (bindings || []).slice() ;
+    }
+
+    keyName = keyName + "Binding";
+    p[keyName] = path ;
+    bindings.push(keyName);
+
+    return this ;
+  },
+
+  /**
+    Helper sets a generic property on a design.
+  */
+  prop: function(keyName, value) {
+    this.prototype[keyName] = value;
+    return this ;
+  },
+
+  /**
+    Used to construct a localization for a view.  The default implementation
+    will simply return the passed attributes.
+  */
+  localization: function(attrs, rootElement) {
+    // add rootElement
+    if (rootElement) attrs.rootElement = SC.$(rootElement)[0];
+    return attrs;
+  },
+
+  /**
+    Creates a view instance, first finding the DOM element you name and then
+    using that as the root element.  You should not use this method very
+    often, but it is sometimes useful if you want to attach to already
+    existing HTML.
+
+    @param {String|Element} element
+    @param {Hash} attrs
+    @returns {SC.View} instance
+  */
+  viewFor: function(element, attrs) {
+    var args = SC.$A(arguments); // prepare to edit
+    if (SC.none(element)) {
+      args.shift(); // remove if no element passed
+    } else args[0] = { rootElement: SC.$(element)[0] } ;
+    var ret = this.create.apply(this, arguments) ;
+    args = args[0] = null;
+    return ret ;
+  },
+
+  /**
+    Create a new view with the passed attributes hash.  If you have the
+    Designer module loaded, this will also create a peer designer if needed.
+  */
+  create: function() {
+    var last = arguments[arguments.length - 1];
+
+    if (last && last.theme) {
+      last.themeName = last.theme;
+      delete last.theme;
+    }
+
+    var C=this, ret = new C(arguments);
+    if (SC.ViewDesigner) {
+      SC.ViewDesigner.didCreateView(ret, SC.$A(arguments));
+    }
+    return ret ;
+  },
+
+  /**
+    Applies the passed localization hash to the component views.  Call this
+    method before you call create().  Returns the receiver.  Typically you
+    will do something like this:
+
+    view = SC.View.design({...}).loc(localizationHash).create();
+
+    @param {Hash} loc
+    @param rootElement {String} optional rootElement with prepped HTML
+    @returns {SC.View} receiver
+  */
+  loc: function(loc) {
+    var childLocs = loc.childViews;
+    delete loc.childViews; // clear out child views before applying to attrs
+
+    this.applyLocalizedAttributes(loc) ;
+    if (SC.ViewDesigner) {
+      SC.ViewDesigner.didLoadLocalization(this, SC.$A(arguments));
+    }
+
+    // apply localization recursively to childViews
+    var childViews = this.prototype.childViews, idx = childViews.length,
+      viewClass;
+    while(--idx>=0) {
+      viewClass = childViews[idx];
+      loc = childLocs[idx];
+      if (loc && viewClass && viewClass.loc) viewClass.loc(loc) ;
+    }
+
+    return this; // done!
+  },
+
+  /**
+    Internal method actually updates the localizated attributes on the view
+    class.  This is overloaded in design mode to also save the attributes.
+  */
+  applyLocalizedAttributes: function(loc) {
+    SC.mixin(this.prototype, loc) ;
+  },
+
+  views: {}
+
+}) ;
+
+// .......................................................
+// OUTLET BUILDER
+//
+
+/**
+  Generates a computed property that will look up the passed property path
+  the first time you try to get the value.  Use this whenever you want to
+  define an outlet that points to another view or object.  The root object
+  used for the path will be the receiver.
+*/
+SC.outlet = function(path, root) {
+  return function(key) {
+    return (this[key] = SC.objectForPropertyPath(path, (root !== undefined) ? root : this)) ;
+  }.property();
+};
+
+/** @private on unload clear cached divs. */
+SC.CoreView.unload = function() {
+  // delete view items this way to ensure the views are cleared.  The hash
+  // itself may be owned by multiple view subclasses.
+  var views = SC.View.views;
+  if (views) {
+   for(var key in views) {
+     if (!views.hasOwnProperty(key)) continue ;
+     delete views[key];
+   }
+  }
+} ;
+
+SC.View = SC.CoreView.extend({});
+
+//unload views for IE, trying to collect memory.
+if(SC.browser.msie) SC.Event.add(window, 'unload', SC.View, SC.View.unload) ;
+
+