spade 0.0.1

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

@@ -0,0 +1,426 @@
+sc_require("views/view");
+
+SC.View.reopen({
+  /**
+    This code exists to make it possible to pool SC.Views. We are not going to pool SC.Views in Amber
+    */
+  _lastLayerId: null,
+
+  /**
+    Handles changes in the layer id.
+  */
+  layerIdDidChange: function() {
+    var layer  = this.get('layer'),
+        lid    = this.get('layerId'),
+        lastId = this._lastLayerId;
+
+    if (lid !== lastId) {
+      // if we had an earlier one, remove from view hash.
+      if (lastId && SC.View.views[lastId] === this) {
+        delete SC.View.views[lastId];
+      }
+
+      // set the current one as the new old one
+      this._lastLayerId = lid;
+
+      // and add the new one
+      SC.View.views[lid] = this;
+
+      // and finally, set the actual layer id.
+      if (layer) { layer.id = lid; }
+    }
+  }.observes("layerId"),
+
+  /**
+    This method is called whenever the receiver's parentView has changed.
+    The default implementation of this method marks the view's display
+    location as dirty so that it will update at the end of the run loop.
+
+    You will not usually need to override or call this method yourself, though
+    if you manually patch the parentView hierarchy for some reason, you should
+    call this method to notify the view that it's parentView has changed.
+
+    @returns {SC.View} receiver
+  */
+  parentViewDidChange: function() {
+    this.recomputeIsVisibleInWindow() ;
+
+    this.resetBuildState();
+    this.set('layerLocationNeedsUpdate', YES) ;
+    this.invokeOnce(this.updateLayerLocationIfNeeded) ;
+
+    // We also need to iterate down through the view hierarchy and invalidate
+    // all our child view's caches for 'pane', since it could have changed.
+    //
+    // Note:  In theory we could try to avoid this invalidation if we
+    //        do this only in cases where we "know" the 'pane' value might
+    //        have changed, but those cases are few and far between.
+
+    this._invalidatePaneCacheForSelfAndAllChildViews();
+
+    return this ;
+  },
+
+  /** @private
+    We want to cache the 'pane' property, but it's impossible for us to
+    declare a dependence on all properties that can affect the value.  (For
+    example, if our grandparent gets attached to a new pane, our pane will
+    have changed.)  So when there's the potential for the pane changing, we
+    need to invalidate the caches for all our child views, and their child
+    views, and so on.
+  */
+  _invalidatePaneCacheForSelfAndAllChildViews: function () {
+    var childView, childViews = this.get('childViews'),
+        len = childViews.length, idx ;
+
+    this.notifyPropertyChange('pane');
+
+    for (idx=0; idx<len; ++idx) {
+      childView = childViews[idx];
+      if (childView._invalidatePaneCacheForSelfAndAllChildViews) {
+        childView._invalidatePaneCacheForSelfAndAllChildViews();
+      }
+    }
+  },
+
+  // ..........................................................
+  // LAYER LOCATION
+  //
+
+  /**
+    Set to YES when the view's layer location is dirty.  You can call
+    updateLayerLocationIfNeeded() to clear this flag if it is set.
+
+    @property {Boolean}
+  */
+  layerLocationNeedsUpdate: NO,
+
+  /**
+    Calls updateLayerLocation(), but only if the view's layer location
+    currently needs to be updated.  This method is called automatically at
+    the end of a run loop if you have called parentViewDidChange() at some
+    point.
+
+    @property {Boolean} force This property is ignored.
+    @returns {SC.View} receiver
+    @test in updateLayerLocation
+  */
+  updateLayerLocationIfNeeded: function(force) {
+    if (this.get('layerLocationNeedsUpdate')) {
+      this.updateLayerLocation() ;
+    }
+    return this ;
+  },
+
+  /**
+    Insert the view into the the receiver's childNodes array.
+
+    The view will be added to the childNodes array before the beforeView.  If
+    beforeView is null, then the view will be added to the end of the array.
+    This will also add the view's rootElement DOM node to the receivers
+    containerElement DOM node as a child.
+
+    If the specified view already belongs to another parent, it will be
+    removed from that view first.
+
+    @param {SC.View} view
+    @param {SC.View} beforeView
+    @returns {SC.View} the receiver
+  */
+  insertBefore: function(view, beforeView) {
+    view.beginPropertyChanges(); // limit notifications
+
+    // remove view from old parent if needed.  Also notify views.
+    if (view.get('parentView')) { view.removeFromParent() ; }
+    if (this.willAddChild) { this.willAddChild(view, beforeView) ; }
+    if (view.willAddToParent) { view.willAddToParent(this, beforeView) ; }
+
+    // set parentView of child
+    view.set('parentView', this);
+
+    // add to childView's array.
+    var idx, childViews = this.get('childViews') ;
+    if (childViews.needsClone) { this.set(childViews = []); }
+    idx = (beforeView) ? childViews.indexOf(beforeView) : childViews.length;
+    if (idx<0) { idx = childViews.length ; }
+    childViews.insertAt(idx, view) ;
+
+    // The DOM will need some fixing up, note this on the view.
+    if(view.parentViewDidChange) view.parentViewDidChange();
+    if(view.layoutDidChange) view.layoutDidChange();
+
+    var pane = view.get('pane');
+    if(pane && pane.get('isPaneAttached')) {
+      view._notifyDidAppendToDocument();
+    }
+
+    // notify views
+    if (this.didAddChild) { this.didAddChild(view, beforeView) ; }
+    if (view.didAddToParent) { view.didAddToParent(this, beforeView) ; }
+
+    view.endPropertyChanges();
+
+    return this ;
+  },
+
+  removeChild: function(original, view) {
+    if (!view) { return this; } // nothing to do
+    if (view.parentView !== this) {
+      throw "%@.removeChild(%@) must belong to parent".fmt(this,view);
+    }
+    // notify views
+    if (view.willRemoveFromParent) { view.willRemoveFromParent() ; }
+    if (this.willRemoveChild) { this.willRemoveChild(view) ; }
+
+    original(view);
+
+    // The DOM will need some fixing up, note this on the view.
+    if(view.parentViewDidChange) view.parentViewDidChange() ;
+
+    // notify views
+    if (this.didRemoveChild) { this.didRemoveChild(view); }
+    if (view.didRemoveFromParent) { view.didRemoveFromParent(this) ; }
+
+    return this;
+  }.enhance(),
+
+  /**
+    Replace the oldView with the specified view in the receivers childNodes
+    array. This will also replace the DOM node of the oldView with the DOM
+    node of the new view in the receivers DOM.
+
+    If the specified view already belongs to another parent, it will be
+    removed from that view first.
+
+    @param view {SC.View} the view to insert in the DOM
+    @param view {SC.View} the view to remove from the DOM.
+    @returns {SC.View} the receiver
+  */
+  replaceChild: function(view, oldView) {
+    // suspend notifications
+    view.beginPropertyChanges();
+    oldView.beginPropertyChanges();
+    this.beginPropertyChanges();
+
+    this.insertBefore(view,oldView).removeChild(oldView) ;
+
+    // resume notifications
+    this.endPropertyChanges();
+    oldView.endPropertyChanges();
+    view.endPropertyChanges();
+
+    return this;
+  },
+
+  /**
+    Replaces the current array of child views with the new array of child
+    views.
+
+    @param {Array} views views you want to add
+    @returns {SC.View} receiver
+  */
+  replaceAllChildren: function(views) {
+    var len = views.get('length'), idx;
+
+    this.beginPropertyChanges();
+    this.destroyLayer().removeAllChildren();
+    for(idx=0;idx<len;idx++) { this.appendChild(views.objectAt(idx)); }
+    this.replaceLayer();
+    this.endPropertyChanges();
+
+    return this ;
+  },
+
+  /**
+    Appends the specified view to the end of the receivers childViews array.
+    This is equivalent to calling insertBefore(view, null);
+
+    @param view {SC.View} the view to insert
+    @returns {SC.View} the receiver
+  */
+  appendChild: function(view) {
+    return this.insertBefore(view, null);
+  },
+
+  ///
+  /// BUILDING IN/OUT
+  ///
+
+  /**
+    Call this to append a child while building it in. If the child is not
+    buildable, this is the same as calling appendChild.
+  */
+  buildInChild: function(view) {
+    view.willBuildInToView(this);
+    this.appendChild(view);
+    view.buildInToView(this);
+  },
+
+  /**
+    Call to remove a child after building it out. If the child is not buildable,
+    this will simply call removeChild.
+  */
+  buildOutChild: function(view) {
+    view.buildOutFromView(this);
+  },
+
+  /**
+    Called by child view when build in finishes. By default, does nothing.
+
+  */
+  buildInDidFinishFor: function(child) {
+  },
+
+  /**
+    @private
+    Called by child view when build out finishes. By default removes the child view.
+  */
+  buildOutDidFinishFor: function(child) {
+    this.removeChild(child);
+  },
+
+  /**
+    Whether the view is currently building in.
+  */
+  isBuildingIn: NO,
+
+  /**
+    Whether the view is currently building out.
+  */
+  isBuildingOut: NO,
+
+  /**
+    Implement this, and call didFinishBuildIn when you are done.
+  */
+  buildIn: function() {
+    this.buildInDidFinish();
+  },
+
+  /**
+    Implement this, and call didFinsihBuildOut when you are done.
+  */
+  buildOut: function() {
+    this.buildOutDidFinish();
+  },
+
+  /**
+    This should reset (without animation) any internal states; sometimes called before.
+
+    It is usually called before a build in, by the parent view.
+  */
+  resetBuild: function() {
+
+  },
+
+  /**
+    Implement this if you need to do anything special when cancelling build out;
+    note that buildIn will subsequently be called, so you usually won't need to do
+    anything.
+
+    This is basically called whenever build in happens.
+  */
+  buildOutDidCancel: function() {
+
+  },
+
+  /**
+    Implement this if you need to do anything special when cancelling build in.
+    You probably won't be able to do anything. I mean, what are you gonna do?
+
+    If build in was cancelled, it means build out is probably happening.
+    So, any timers or anything you had going, you can cancel.
+    Then buildOut will happen.
+  */
+  buildInDidCancel: function() {
+
+  },
+
+  /**
+    Call this when you have built in.
+  */
+  buildInDidFinish: function() {
+    this.isBuildingIn = NO;
+    this._buildingInTo.buildInDidFinishFor(this);
+    this._buildingInTo = null;
+  },
+
+  /**
+    Call this when you have finished building out.
+  */
+  buildOutDidFinish: function() {
+    this.isBuildingOut = NO;
+    this._buildingOutFrom.buildOutDidFinishFor(this);
+    this._buildingOutFrom = null;
+  },
+
+  /**
+    Usually called by parentViewDidChange, this resets the build state (calling resetBuild in the process).
+  */
+  resetBuildState: function() {
+    if (this.isBuildingIn) {
+      this.buildInDidCancel();
+      this.isBuildingIn = NO;
+    }
+    if (this.isBuildingOut) {
+      this.buildOutDidCancel();
+      this.isBuildingOut = NO;
+    }
+
+    // finish cleaning up
+    this.buildingInTo = null;
+    this.buildingOutFrom = null;
+
+    this.resetBuild();
+  },
+
+  /**
+    @private (semi)
+    Called by building parent view's buildInChild method. This prepares
+    to build in, but unlike buildInToView, this is called _before_ the child
+    is appended.
+
+    Mostly, this cancels any build out _before_ the view is removed through parent change.
+  */
+  willBuildInToView: function(view) {
+    // stop any current build outs (and if we need to, we also need to build in again)
+    if (this.isBuildingOut) {
+      this.buildOutDidCancel();
+    }
+  },
+
+  /**
+    @private (semi)
+    Called by building parent view's buildInChild method.
+  */
+  buildInToView: function(view) {
+    // if we are already building in, do nothing.
+    if (this.isBuildingIn) { return; }
+
+    this._buildingInTo = view;
+    this.isBuildingOut = NO;
+    this.isBuildingIn = YES;
+    this.buildIn();
+  },
+
+  /**
+    @private (semi)
+    Called by building parent view's buildOutChild method.
+
+    The supplied view should always be the parent view.
+  */
+  buildOutFromView: function(view) {
+    // if we are already building out, do nothing.
+    if (this.isBuildingOut) { return; }
+
+    // cancel any build ins
+    if (this.isBuildingIn) {
+      this.buildInDidCancel();
+    }
+
+    // in any case, we need to build out
+    this.isBuildingOut = YES;
+    this.isBuildingIn = NO;
+    this._buildingOutFrom = view;
+    this.buildOut();
+  }
+});

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

@@ -0,0 +1,362 @@
+sc_require("views/view");
+
+SC.View.reopen(
+  /** @scope SC.View.prototype */ {
+
+  init: function(original) {
+    original();
+    this._lastTheme = this.get('theme');
+  }.enhance(),
+
+  // ..........................................................
+  // THEME SUPPORT
+  //
+
+  /**
+    Names which theme this view should use; the theme named by this property
+    will be set to the view's 'theme' property.
+
+    Themes are identified by their name. In addition to looking for the
+    theme globally, SproutCore will look for the theme inside 'baseTheme',
+    which is almost always the parent view's theme.
+
+    If null (the default), the view will set its 'theme' property to
+    be equal to 'baseTheme'.
+
+    Example: themeName: 'ace'
+
+    @property {String}
+  */
+  themeName: null,
+
+  /**
+    Selects which theme to use as a 'base theme'. If null, the 'baseTheme'
+    property will be set to the parent's theme. If there is no parent, the theme
+    named by SC.defaultTheme is used.
+
+    This property is private for the time being.
+
+    @private
+    @property {String}
+  */
+  baseThemeName: null,
+
+  /**
+    The SC.Theme instance which this view should use to render.
+
+    Note: the actual code for this function is in _themeProperty for backwards-compatibility:
+    some older views specify a string value for 'theme', which would override this property,
+    breaking it.
+
+    @property {SC.Theme}
+  */
+  theme: function() {
+    var base = this.get('baseTheme'), themeName = this.get('themeName');
+
+    // find theme, if possible
+    if (themeName) {
+      // Note: theme instance "find" function will search every parent
+      // _except_ global (which is not a parent)
+      var theme;
+      if (base) {
+        theme = base.find(themeName);
+        if (theme) { return theme; }
+      }
+
+      theme = SC.Theme.find(themeName);
+      if (theme) { return theme; }
+
+      // Create a new invisible subtheme. This will cause the themeName to
+      // be applied as a class name.
+      return base.invisibleSubtheme(themeName);
+    }
+
+    // can't find anything, return base.
+    return base;
+  }.property('baseTheme', 'themeName').cacheable(),
+
+  /**
+    Detects when the theme changes. Replaces the layer if necessary.
+
+    Also, because
+  */
+  _sc_view_themeDidChange: function() {
+    if (this._lastTheme === this.get('theme')) { return; }
+    this._lastTheme = this.get('theme');
+
+    // invalidate child view base themes, if present
+    var childViews = this.childViews, len = childViews.length, idx;
+    for (idx = 0; idx < len; idx++) {
+      childViews[idx].notifyPropertyChange('baseTheme');
+    }
+
+    if (this.get('layer')) { this.replaceLayer(); }
+  }.observes('theme'),
+
+  /**
+    The SC.Theme instance in which the 'theme' property should look for the theme
+    named by 'themeName'.
+
+    For example, if 'baseTheme' is SC.AceTheme, and 'themeName' is 'popover',
+    it will look to see if SC.AceTheme has a child theme named 'popover',
+    and _then_, if it is not found, look globally.
+
+    @private
+    @property {SC.Theme}
+  */
+  baseTheme: function() {
+    var parent;
+    var baseThemeName = this.get('baseThemeName');
+    if (baseThemeName) {
+      return SC.Theme.find(baseThemeName);
+    } else {
+      parent = this.get('parentView');
+      var theme  = parent && parent.get('theme');
+      return   theme || SC.Theme.find(SC.defaultTheme);
+    }
+  }.property('baseThemeName', 'parentView').cacheable(),
+
+  /**
+   * Returns the named property if it is specified on the view, and
+   * otherwise returns the named constant from the view's theme.
+   *
+   * @param {String} property The property on the view.
+   * @param {String} constantName The name of the constant on the theme.
+  */
+  getThemedProperty: function(property, constantName){
+    var value = this.get(property);
+    if (value !== undefined) { return value; }
+
+    var theme = this.get('theme');
+    if (!theme) { return undefined; }
+
+    return theme[constantName];
+  },
+
+  /**
+    The object to which rendering and updating the HTML representation of this
+    view should be delegated.
+
+    By default, views are responsible for creating their own HTML
+    representation. In some cases, however, you may want to create an object
+    that is responsible for rendering all views of a certain type. For example,
+    you may want rendering of SC.ButtonView to be controlled by an object that
+    is specific to the current theme.
+
+    By setting a render delegate, the render and update methods will be called
+    on that object instead of the view itself.
+
+    For your convenience, the view will provide its displayProperties to the
+    RenderDelegate. In some cases, you may have a conflict between the RenderDelegate's
+    API and your view's. For instance, you may have a 'value' property that is
+    any number, but the render delegate expects a percentage. Make a 'displayValue'
+    property, add _it_ to displayProperties instead of 'value', and the Render Delegate
+    will automatically use that when it wants to find 'value.'
+
+    You can also set the render delegate by using the 'renderDelegateName' property.
+
+    @property {Object}
+  */
+  renderDelegate: function(key, value) {
+    if (value) { this._setRenderDelegate = value; }
+    if (this._setRenderDelegate) { return this._setRenderDelegate; }
+
+    // If this view does not have a render delegate but has
+    // renderDelegateName set, try to retrieve the render delegate from the
+    // theme.
+    var renderDelegateName = this.get('renderDelegateName'), renderDelegate;
+
+    if (renderDelegateName) {
+      renderDelegate = this.get('theme')[renderDelegateName];
+      if (!renderDelegate) {
+        throw "%@: Unable to locate render delegate \"%@\" in theme.".fmt(this, renderDelegateName);
+      }
+
+      return renderDelegate;
+    }
+
+    return null;
+  }.property('renderDelegateName', 'theme'),
+
+  /**
+    The name of the property of the current theme that contains the render
+    delegate to use for this view.
+
+    By default, views are responsible for creating their own HTML
+    representation. You can tell the view to instead delegate rendering to the
+    theme by setting this property to the name of the corresponding property
+    of the theme.
+
+    For example, to tell the view that it should render using the
+    SC.ButtonView render delegate, set this property to
+    'buttonRenderDelegate'. When the view is created, it will retrieve the
+    buttonRenderDelegate property from its theme and set the renderDelegate
+    property to that object.
+  */
+  renderDelegateName: null,
+
+  /**
+    [RO] Pass this object as the data source for render delegates. This proxy object
+    for the view relays requests for properties like 'title' to 'displayTitle'
+    as necessary.
+
+    If you ever communicate with your view's render delegate, you should pass this
+    object as the data source.
+
+    The proxy that forwards RenderDelegate requests for properties to the view,
+    handling display*, keeps track of the delegate's state, etc.
+  */
+  renderDelegateProxy: function() {
+    return SC.View._RenderDelegateProxy.createForView(this);
+  }.property('renderDelegate').cacheable(),
+
+  /**
+    Invoked whenever your view needs to create its HTML representation.
+
+    You will normally override this method in your subclassed views to
+    provide whatever drawing functionality you will need in order to
+    render your content.
+
+    This method is usually only called once per view. After that, the update
+    method will be called to allow you to update the existing HTML
+    representation.
+
+
+    The default implementation of this method calls renderChildViews().
+
+    For backwards compatibility, this method will also call the appropriate
+    method on a render delegate object, if your view has one.
+
+    @param {SC.RenderContext} context the render context
+    @returns {void}
+  */
+  render: function(context, firstTime) {
+    var renderDelegate = this.get('renderDelegate');
+
+    if (renderDelegate) {
+      if (firstTime) {
+        renderDelegate.render(this.get('renderDelegateProxy'), context);
+      } else {
+        renderDelegate.update(this.get('renderDelegateProxy'), context.$());
+      }
+    }
+  },
+
+  applyAttributesToContext: function(original, context) {
+    var theme = this.get('theme');
+    var themeClassNames = theme.classNames, idx, len = themeClassNames.length;
+
+    for (idx = 0; idx < len; idx++) {
+      context.addClass(themeClassNames[idx]);
+    }
+
+    original(context);
+
+    var renderDelegate = this.get('renderDelegate');
+    if (renderDelegate && renderDelegate.name) {
+      context.addClass(renderDelegate.name);
+    }
+  }.enhance()
+});
+
+/**
+  @class
+  @private
+  View Render Delegate Proxies are tool SC.Views use to:
+
+  a) limit properties the render delegate can access to the displayProperties
+  b) look up 'display*' ('displayTitle' instead of 'title') to help deal with
+     differences between the render delegate's API and the view's.
+
+  RenderDelegateProxies are fully valid data sources for render delegates. They
+  act as proxies to the view, interpreting the .get and .didChangeFor commands
+  based on the view's displayProperties.
+
+  This tool is not useful outside of SC.View itself, and as such, is private.
+*/
+SC.View._RenderDelegateProxy = {
+
+  // for testing:
+  isViewRenderDelegateProxy: YES,
+
+  /**
+   * Creates a View Render Delegate Proxy for the specified view.
+   *
+   * Implementation note: this creates a hash of the view's displayProperties
+   * array so that the proxy may quickly determine whether a property is a
+   * displayProperty or not. This could cause issues if the view's displayProperties
+   * array is modified after instantiation.
+   *
+   * @param {SC.View} view The view this proxy should proxy to.
+   * @returns SC.View._RenderDelegateProxy
+  */
+  createForView: function(view) {
+    var ret = SC.beget(this);
+
+    // set up displayProperty lookup for performance
+    var dp = view.get('displayProperties'), lookup = {};
+    for (var idx = 0, len = dp.length; idx < len; idx++) {
+      lookup[dp[idx]] = YES;
+    }
+
+    // also allow the few special properties through
+    lookup.theme = YES;
+
+    ret._displayPropertiesLookup = lookup;
+    ret.renderState = {};
+
+    ret.view = view;
+    return ret;
+  },
+
+
+  /**
+   * Provides the render delegate with any property it needs.
+   *
+   * This first looks up whether the property exists in the view's
+   * displayProperties, and whether it exists prefixed with 'display';
+   * for instance, if the render delegate asks for 'title', this will
+   * look for 'displayTitle' in the view's displayProperties array.
+   *
+   * @param {String} property The name of the property the render delegate needs.
+   * @returns The value.
+  */
+  get: function(property) {
+    if (this[property] !== undefined) { return this[property]; }
+
+    var displayProperty = 'display' + property.capitalize();
+
+    if (this._displayPropertiesLookup[displayProperty]) {
+      return this.view.get(displayProperty);
+    } else if (this._displayPropertiesLookup[property]) {
+      return this.view.get(property);
+    }
+
+    return undefined;
+  },
+
+  /**
+   * Checks if any of the specified properties have changed.
+   *
+   * For each property passed, this first determines whether to use the
+   * 'display' prefix. Then, it calls view.didChangeFor with context and that
+   * property name.
+   *
+  */
+  didChangeFor: function(context) {
+    var len = arguments.length, idx;
+    for (idx = 1; idx < len; idx++) {
+      var property = arguments[idx],
+          displayProperty = 'display' + property.capitalize();
+
+      if (this._displayPropertiesLookup[displayProperty]) {
+        if (this.view.didChangeFor(context, displayProperty)) { return YES; }
+      } else if (this._displayPropertiesLookup[property]) {
+        if (this.view.didChangeFor(context, property)) { return YES; }
+      }
+    }
+
+    return NO;
+  }
+};
+