sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/foundation/render_delegates/render_delegate.js

@@ -0,0 +1,386 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @class
+  Base class for all render delegates.
+
+  You should use SC.RenderDelegate or a subclass of it as the base for all 
+  of your render delegates. SC.RenderDelegate offers many helper methods 
+  and can be simpler to subclass between themes than `SC.Object`.
+
+  Creating & Subclassing
+  ============================
+  You create render delegates just like you create SC.Objects:
+
+      MyTheme.someRenderDelegate = SC.RenderDelegate.create({ ... });
+
+  You can subclass a render delegate and use that:
+
+      MyTheme.RenderDelegate = SC.RenderDelegate.extend({ ... });
+      MyTheme.someRenderDelegate = MyTheme.RenderDelegate.create({});
+
+  And you can even subclass instances or SC.RenderDelegate:
+
+      MyTheme.someRenderDelegate = SC.RenderDelegate.create({ ... });
+      MyTheme.otherRenderDelegate = MyTheme.someRenderDelegate.create({ ... });
+
+      // this allows you to subclass another theme's render delegate:
+      MyTheme.buttonRenderDelegate = SC.BaseTheme.buttonRenderDelegate.create({ ... });
+
+  For render delegates, subclassing and instantiating are the same.
+
+  NOTE: Even though `.extend` and `.create` technically do the same thing, 
+  convention dictates that you use `.extend` for RenderDelegates that 
+  will be used primarily as base classes, and `create` for RenderDelegates
+  that you expect to be instances.
+
+  Rendering and Updating
+  =========================
+  Render delegates are most commonly used for two things: rendering and updating
+  DOM representations of controls.
+
+  Render delegates use their `render` and `update` methods to do this:
+
+      render: function(dataSource, context) {
+        // rendering tasks here
+        // example:
+        context.begin('div').addClass('title')
+          .text(dataSource.get('title')
+        .end();
+      },
+
+      update: function(dataSource, jquery) {
+        // updating tasks here
+        // example:
+        jquery.find('.title').text(dataSource.get('title'));
+      }
+
+  Variables
+  ==========================
+  The data source provides your render delegate with all of the information
+  needed to render. However, the render delegate's consumer--usually a view--
+  may need to get information back.
+
+  For example, `SC.AutoResize` resizes controls to fit their text. You can use
+  it to size a button to fit its title. But it can't just make the button
+  have the same width as its title: it needs to be a little larger to make room
+  for the padding to the left and right sides of the title.
+
+  This padding will vary from theme to theme.
+  
+  You can specify properties on the render delegate like any other property:
+
+      MyRenderDelegate = SC.RenderDelegate.create({
+        autoSizePadding: 10
+        ...
+      });
+
+  But there are multiple sizes of buttons; shouldn't the padding change as
+  well? You can add hashes for the various control sizes and override properties:
+
+      SC.RenderDelegate.create({
+        autoSizePadding: 10,
+
+        'sc-jumbo-size': {
+          autoResizePadding: 20
+        }
+
+  For details, see the discussion on size helpers below.
+
+  You can also calculate values for the data source. In this example, we calculate
+  the autoSizePadding to equal half the data source's height:
+
+      SC.RenderDelegate.create({
+        autoSizePaddingFor: function(dataSource) {
+          if (dataSource.get('frame')) {
+            return dataSource.get('frame').height / 2;
+          }
+        }
+
+
+  When SC.ButtonView tries to get `autoSizePadding`, the render delegate will look for
+  `autoSizePaddingFor`. It will be called if it exists. Otherwise, the property will
+  be looked up like normal.
+
+  Note: To support multiple sizes, you must also render the class name; see size
+  helper discussion below.
+
+  Helpers
+  =====================
+  SC.RenderDelegate have "helper methods" to assist the rendering process.
+  There are a few built-in helpers, and you can add your own.
+
+  Slices
+  ----------------------
+  Chance provides the `includeSlices` method to easily slice images for
+  use in the SproutCore theme system.
+
+      includeSlices(dataSource, context, slices);
+
+  You can call this to add DOM that matches Chance's `@include slices()`
+  directive. For example:
+
+      MyTheme.buttonRenderDelegate = SC.RenderDelegate.create({
+        name: 'button',
+        render: function(dataSource, context) {
+          this.includeSlices(dataSource, context, SC.THREE_SLICE);
+        }
+      });
+
+  DOM elements will be added as necessary for the slices. From your CSS, you
+  can match it like this:
+
+      $theme.button {
+        @include slices('button.png', $left: 3, $right: 3);
+      }
+
+  See the Chance documentation at http://guides.sproutcore.com/chance.html
+  for more about Chance's `@include slices` directive.
+
+  Sizing Helpers
+  -------------------------
+  As discussed previously, you can create hashes of properties for each size. 
+  However, to support sizing, you must render the size's class name.
+
+  Use the `addSizeClassName` and `updateSizeClassName` methods:
+
+      SC.RenderDelegate.create({
+        render: function(dataSource, context) {
+          // if you want to include a class name for the control size
+          // so you can style it via CSS, include this line:
+          this.addSizeClassName(dataSource, context);
+
+          ...
+        },
+
+        update: function(dataSource, jquery) {
+          // and don't forget to use its companion in update as well:
+          this.updateSizeClassName(dataSource, jquery);
+
+          ...
+        }
+      });
+
+  Controls that allow multiple sizes should also be able to automatically choose
+  the correct size based on the `layout` property supplied by the user. To support
+  this, you can add properties to your size hashes:
+
+      'sc-regular-size': {
+        // to match _only_ 24px-high buttons
+        height: 24,
+
+        // or, alternatively, to match ones from 22-26:
+        minHeight: 20, maxHeight: 26,
+
+        // you can do the same for width if you wanted
+        width: 100
+      }
+
+  The correct size will be calculated automatically when `addSlizeClassName` is
+  called. If the view explicitly supplies a control size, that size will be used;
+  otherwise, it will be calculated automatically based on the properties in your
+  size hash.
+
+  Adding Custom Helpers
+  ---------------------
+  You can mix your own helpers into this base class by calling 
+  SC.RenderDelegate.mixin; they will be available to all render delegates:
+
+      SC.RenderDelegate.mixin({
+        myHelperMethod: function(dataSource) { ... }
+      });
+
+
+  You can then use the helpers from your render delegates:
+
+      MyTheme.someRenderDelegate = SC.RenderDelegate.create({
+        name: 'some-thingy',
+        render: function(dataSource, context) {
+          this.myHelperMethod(dataSource);
+        }
+      });
+
+
+  By convention, all render delegate methods should take a `dataSource` as 
+  their first argument. If they do any rendering or updating, their second
+  argument should be the `SC.RenderContext` or `jQuery` object to use.
+
+  In addition, helpers like these are only meant for methods that should
+  be made available to _all_ render delegates. If your method is specific
+  to just one, add it directly; if it is specific to just a few in your
+  own theme, consider just using mixins or subclassing SC.RenderDelegate:
+
+      // If you use it in a couple of render delegates, perhaps a mixin
+      // would be best:
+      MyTheme.MyRenderHelper = {
+        helper: function(dataSource) {
+          ...
+        }
+      };
+
+      MyTheme.myRenderDelegate = SC.RenderDelegate.create(MyTheme.MyRenderHelper, {
+        render: function(dataSource, context) { ... }
+      });
+
+
+      // If you use it in all render delegates in your theme, perhaps it
+      // would be better to create an entire subclass of
+      // SC.RenderDelegate:
+      MyTheme.RenderDelegate = SC.RenderDelegate.extend({
+        helper: function(dataSource) {
+          ...
+        }
+      });
+
+      MyTheme.myRenderDelegate = MyTheme.RenderDelegate.create({
+        render: function(dataSource, context) { ... }
+      });
+
+  Data Sources
+  ====================
+  Render delegates get the content to be rendered from their data sources.
+
+  A data source can be any object, so long as the object implements
+  the following methods:
+
+  - `get(propertyName)`: Returns a value for a given property.
+  - `didChangeFor(context, propertyName)`: Returns YES if any properties
+    listed have changed since the last time `didChangeFor` was called with
+    the same context.
+
+  And the following properties (to be accessed through `.get`):
+
+  - `theme`: The theme being used to render.
+  - `renderState`: An empty hash for the render delegate to save state in.
+    While render delegates are _usually_ completely stateless, there are
+    cases where they may need to save some sort of state.
+*/
+SC.RenderDelegate = {
+  // docs will look more natural if these are all considered instance
+  // methods/properties.
+  /*@scope SC.RenderDelegate.prototype*/
+
+  /**
+    Creates a new render delegate based on this one. When you want to
+    create a render delegate, you call this:
+   
+        MyTheme.myRenderDelegate = SC.RenderDelegate.create({
+          name: 'my-render-delegate',
+          render: function(dataSource, context) {
+            // your code here...
+          }
+        })
+  */
+  create: function() {
+    var ret = SC.beget(this);
+
+    var idx, len = arguments.length;
+    for (idx = 0; idx < len; idx++) {
+      ret.mixin(arguments[idx]);
+    }
+
+    return ret;
+  },
+
+  /**
+    Adds extra capabilities to this render delegate.
+   
+    You can use this to add helpers to all render delegates:
+   
+        SC.RenderDelegate.reopen({
+          myHelperMethod: function(dataSource) { ... }
+        });
+   
+  */
+  reopen: function(mixin) {
+    var i, v;
+    for (i in mixin) {
+      v = mixin[i];
+      if (!mixin.hasOwnProperty(i)) {
+        continue;
+      }
+
+      if (typeof v === 'function' && v !== this[i]) {
+        v.base = this[i] || SC.K;
+      }
+
+      if (v && v.isEnhancement && v !== this[i]) {
+        v = SC._enhance(this[i] || K, v);
+      }
+
+      this[i] = v;
+    }
+  },
+
+  /**
+    Returns the specified property from this render delegate.
+    Implemented to match SC.Object's API.
+  */
+  get: function(propertyName) { return this[propertyName]; },
+
+  /**
+    Gets or generates the named property for the specified
+    dataSource. If a method `propertyName + 'For'` is found,
+    it will be used to compute the value, `dataSource`
+    being passed as an argument. Otherwise, it will simply
+    be looked up on the render delegate.
+    
+    NOTE: this implementation is a reference implementation. It
+    is overriden in the sizing code (helpers/sizing.js) to be
+    size-sensitive.
+  */
+  getPropertyFor: function(dataSource, propertyName) {
+    if (this[propertyName + 'For']) {
+      return this[propertyName + 'For'](dataSource, propertyName);
+    }
+
+    return this[propertyName];
+  },
+
+  /**
+    All render delegates should have a name. Any time a render delegate is
+    used, this name should be added as a class name (`SC.View`s do this
+    automatically).
+  */
+  name: undefined,
+
+  /**
+    Writes the DOM representation of this render delegate to the
+    supplied `SC.RenderContext`, using the supplied `dataSource`
+    for any data needed.
+    
+    @method
+    @param {DataSource} dataSource An object from which to get
+    data. See documentation on data sources above.
+    @param {SC.RenderContext} context A context to render DOM into.
+  */
+  render: function(dataSource, context) {
+
+  },
+
+  /**
+    Updates the DOM representation of this render delegate using
+    the supplied `jQuery` instance and `dataSource`.
+    
+    @method
+    @param {DataSource} dataSource An object from which to get
+    data. See documentation on data sources above.
+    @param {jQuery} jquery A jQuery instance containing the DOM
+    element to update. This will be the DOM generated by `render()`.
+  */
+  update: function(dataSource, jQuery) {
+
+  }
+};
+
+// create and extend are technically identical.
+SC.RenderDelegate.extend = SC.RenderDelegate.create;
+
+// and likewise, as this is both a class and an instance, mixin makes
+// sense instead of reopen...
+SC.RenderDelegate.mixin = SC.RenderDelegate.reopen;

data/lib/frameworks/sproutcore/frameworks/foundation/system/benchmark.js

@@ -1,106 +1,156 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
-/*globals $A*/
+/*globals $A */
 
 sc_require('core') ;
- 
+
 /** @namespace
 
   This bit of meta-programming magic can install a benchmark handler on any
   object method.  When a benchmark is installed, the time required to execute
-  the method will be printed to the console log everytime the method is 
+  the method will be printed to the console log everytime the method is
   called.
 
   This class can be used to implement benchmarking.  To use this object, just
-  call start() with a key name and end() with a keyname.  The benchmark will 
-  be logged.  If you set verbose = true, then benchmark will log everytime it 
+  call start() with a key name and end() with a keyname.  The benchmark will
+  be logged.  If you set verbose = true, then benchmark will log everytime it
   saves a bench.  Otherwise, it just keeps stats.  You can get the stats by
   calling report().
 
   Benchmark does not require anything other than the date.js class.  It also
   does not rely on SC.Object so that you can benchmark code in that area as
   well.
-  
+
   The benchmark has three types of reports.
-  
-  report(): Returns an abbreviated list with just the durations of the bench. 
-            Also, it averages multiple runs. Everything is reported on the top
-            level only.
-            
-  timelineReport(): Returns an list of benchmarks and sub-benchmarks. If the
-                    the globalStartTime is set, then it will show relative
-                    time from that time.
-  
-  timelineChart(): Displays a chart of all the benchmarks (not sub-benchmarks)
-                   relative to the first time capture or to the globalStartTime.
-                   Hide this by calling hideChart()
+
+    - report(): Returns an abbreviated list with just the durations of the bench.
+              Also, it averages multiple runs. Everything is reported on the top
+              level only.
+    - timelineReport(): Returns an list of benchmarks and sub-benchmarks. If the
+                      the globalStartTime is set, then it will show relative
+                      time from that time.
+    - timelineChart(): Displays a chart of all the benchmarks (not sub-benchmarks)
+                     relative to the first time capture or to the globalStartTime.
+                     Hide this by calling hideChart()
+
+  @since SproutCore 1.0
 */
 SC.Benchmark = {
 
   /**
-    If true, then benchmarks will be logged to the console as they are 
+    If true, then benchmarks will be logged to the console as they are
     recorded.
-  
-    @property {Boolean}
+
+    @type Boolean
+    @default NO
   */
   verbose: NO,
-  
+
   /**
     If false, benchmarking will be disabled.  You might want to disable this
     during production to maximize performance.
-  
-    @property {Boolean}
+
+    @type Boolean
+    @default YES
   */
   enabled: YES,
-  
-  /** 
-     This hash stores collected stats.  It contains key value pairs.  The value
-     will be a hash with the following properties:
-   
-    * * *runs*: the number of times this stat has run
-    * * *amt*: the total time consumed by this (divide by runs to get avg)
-    * * *name*: an optional longer name you assigned to the stat key.  Set this  using name().
-    * * *_starts*: this array is used internally.
-    * * *_times*: this array is used internally.
-    
-    @property {Object}
+
+  /**
+    Events are a way of assigning specific, individual times to names, rather than
+    durations of time. A benchmark event can only occur once—if it occurs again, it
+    will overwrite the old event.
+
+    The purpose of events is different than the purpose for normal benchmarks. Normal
+    benchmarks may be used to benchmark a specific process, and may do so repeatedly;
+    events, conversely, are usually used to benchmark things like startup time, and
+    occur only once. For instance, an 'event' is registered when the document is ready.
+
+    Events are kept as a hash of names to timestamps. To add an event, just set it:
+
+        SC.Benchmark.events['myEventName'] = new Date().getTime();
+
+        // Or, more conveniently:
+        SC.Benchmark.addEvent('myEventName', [optional time]);
+
+    On a timeline chart, events are usually represented as lines rather than bars. However,
+    if you add eventNameStart and eventNameEnd, they will be automatically added as standard
+    benchmarks.
+
+    This is useful when adding preload events to SC.benchmarkPreloadEvents; as SC.Benchmark
+    does not yet exist, you cannot call .start() and .end(), but adding the items to
+    SC.benchmarkPreloadEvents will ensure they are included.
+
+    @type Hash
+    @default {}
+  */
+  events: {},
+
+  /**
+    This hash stores collected stats.  It contains key value pairs.  The value
+    will be a hash with the following properties:
+
+      - *runs*: the number of times this stat has run
+      - *amt*: the total time consumed by this (divide by runs to get avg)
+      - *name*: an optional longer name you assigned to the stat key.  Set this  using name().
+
+    @type Hash
+    @default {}
   */
   stats: {},
 
   /**
     If set, one can tell when the benchmark is started relatively to the global start time.
-  
-    @property {Number}
+
+    This property is set to a default automatically (from HTML5 NavigationTiming if possible,
+    otherwise the SC bootstrap).
+
+    @type Number
+    @default null
   */
   globalStartTime: null,
 
-   /**
+  /**
+    Adds an 'event' to the events hash.
+
+    Unlike normal benchmarks, recorded with start/end and that represent a block of time,
+    events represent a single instance in time. Further, unlike normal benchmarks, which
+    may be run more than once for the same benchmark name, only one instance in time
+    will be recorded for any event name.
+
+    @param {String} name
+      A name that identifies the event. If addEvent is called again with the same name,
+      the previous call's timestamp will be overwritten.
+    @param {Timestamp} time
+      Optional. The timestamp to record for the event.
+  */
+  addEvent: function(name, time) {
+    if (!time) time = new Date().getTime();
+    this.events[name] = time;
+  },
+
+  /**
     Call this method at the start of whatever you want to collect.
-    If a parentKey is passed, then you will attach the stat to the parent, 
-    otherwise it will be on the top level. If topLevelOnly is passed, then 
-    recursive calls to the start will be ignored and only the top level call 
+    If a parentKey is passed, then you will attach the stat to the parent,
+    otherwise it will be on the top level. If topLevelOnly is passed, then
+    recursive calls to the start will be ignored and only the top level call
     will be benchmarked.
-    
-    @param {String} key 
-      A unique key that identifies this benchmark.  All calls to start/end 
+
+    @param {String} key
+      A unique key that identifies this benchmark.  All calls to start/end
       with the same key will be groups together.
-    
     @param {String} parentKey
-      A unique key that identifies the parent benchmark.  All calls to 
+      A unique key that identifies the parent benchmark.  All calls to
       start/end with the same key will be groups together.
-    
     @param {Boolean} topLevelOnly
-      If true then recursive calls to this method with the same key will be 
-      ignored.  
-    
+      If true then recursive calls to this method with the same key will be
+      ignored.
     @param {Number} time
-      Only pass if you want to explicitly set the start time.  Otherwise the 
+      Only pass if you want to explicitly set the start time.  Otherwise the
       start time is now.
-      
     @returns {String} the passed key
   */
   start: function(key, parentKey, time, topLevelOnly) {
@@ -110,7 +160,7 @@ SC.Benchmark = {
 
     if (parentKey) stat = this._subStatFor(key, parentKey) ;
     else stat = this._statFor(key) ;
-    
+
     if (topLevelOnly && stat._starts.length > 0) stat._starts.push('ignore');
     else stat._starts.push(start) ;
 
@@ -121,15 +171,13 @@ SC.Benchmark = {
   /**
     Call this method at the end of whatever you want to collect.  This will
     save the collected benchmark.
-    
+
     @param {String} key
       The benchmark key you used when you called start()
-    
     @param {String} parentKey
       The benchmark parent key you used when you called start()
-    
     @param {Number} time
-      Only pass if you want to explicitly set the end time.  Otherwise start 
+      Only pass if you want to explicitly set the end time.  Otherwise start
       time is now.
   */
   end: function(key, parentKey, time) {
@@ -145,13 +193,13 @@ SC.Benchmark = {
     }
     var start = stat._starts.pop() ;
     if (!start) {
-      console.log('SC.Benchmark "%@" ended without a matching start.  No information was saved.'.fmt(key));
+      SC.Logger.log('SC.Benchmark "%@" ended without a matching start.  No information was saved.'.fmt(key));
       return ;
     }
 
     // top level only.
-    if (start == 'ignore') return ; 
-    
+    if (start == 'ignore') return ;
+
     var end = (time || Date.now()) ;
     var dur = end - start;
 
@@ -160,11 +208,11 @@ SC.Benchmark = {
 
     stat.amt += dur ;
     stat.runs++ ;
-    
+
     if (this.verbose) this.log(key) ;
   },
-  
-  /* 
+
+  /*
     Set the inital global start time.
   */
   setGlobalStartTime: function(time)
@@ -173,34 +221,33 @@ SC.Benchmark = {
   },
 
   /**
-    This is a simple way to benchmark a function.  The function will be 
+    This is a simple way to benchmark a function.  The function will be
     run with the name you provide the number of times you indicate.  Only the
     function is a required param.
-  */  
+  */
   bench: function(func, key, reps) {
     if (!key) key = "bench%@".fmt(this._benchCount++) ;
     if (!reps) reps = 1 ;
     var ret ;
-    
+
     while(--reps >= 0) {
       var timeKey = SC.Benchmark.start(key) ;
       ret = func();
-      SC.Benchmark.end(timeKey) ; 
+      SC.Benchmark.end(timeKey) ;
     }
-    
+
     return ret ;
   },
-  
-  /**  
+
+  /**
     This bit of metaprogramming magic install a wrapper around a method and
     benchmark it whenever it is run.
-  */  
+  */
   install: function(object,method, topLevelOnly) {
-    
     // vae the original method.
     object['b__' + method] = object[method] ;
     var __func = object['b__' + method];
-    
+
     // replace with this helper.
     object[method] = function() {
       var key = '%@(%@)'.fmt(method, $A(arguments).join(', ')) ;
@@ -210,18 +257,17 @@ SC.Benchmark = {
       return ret ;
     } ;
   },
-  
+
   /**
     Restore the original method, deactivating the benchmark.
-  
-    @param {object} object the object to change
-    @param {string} method the method name as a string.
-  
-  */  
+
+    @param {Object} object the object to change
+    @param {String} method the method name as a string.
+  */
   restore: function(object,method) {
     object[method] = object['b__' + method] ;
   },
-  
+
   /**
     This method will return a string containing a report of the stats
     collected so far.  If you pass a key, only the stats for that key will
@@ -240,10 +286,9 @@ SC.Benchmark = {
   /**
     Generate a human readable benchmark report. Pass in appName if you desire.
 
-    @param {string} application name.
+    @param {String} application name.
   */
-  timelineReport: function(appName) 
-  {
+  timelineReport: function(appName) {
     appName = (appName) ? 'SproutCore Application' : appName;
     var ret = [appName, 'User-Agent: %@'.fmt(navigator.userAgent), 'Report Generated: %@ (%@)'.fmt(new Date().toString(), Date.now()), ''] ;
 
@@ -263,135 +308,294 @@ SC.Benchmark = {
   },
 
   /**
-    Generate a human readable benchmark chart. Pass in appName if you desire.
+    Returns a hash containing the HTML representing the timeline chart, and
+    various metrics and information about the chart:
 
+        - html
+        - totalWidth
+        - totalHeight
+        - totalCapturedTime
+        - pointsCaptured
+
+    @returns {Hash}
   */
-  timelineChart: function(appName) {
-    var i=0;
-    // Hide the chart if there is an existing one.
-    this.hideChart();
-    
+  getTimelineChartContent: function() {
     // Compile the data.
     var chart = this._compileChartData(false);
     var chartLen = chart.length;
-    
+
     // Return if there is nothing to draw.
     if(chartLen === 0) return;
-    
+
     // Get the global start of the graph.
     var gStart = this.globalStartTime ? this.globalStartTime : chart[0][1];
     var maxDur = chart[chartLen-1][2]-gStart;
-    var maxHeight = 50+chartLen*30;
+    var maxHeight = 25+chartLen*30;
     var incr = Math.ceil(maxDur/200)+1;
     var maxWidth = incr*50;
-    
-    // Create the basic graph element.
-    var graph = document.createElement('div');
-    graph.className = 'sc-benchmark-graph';
-    document.body.appendChild(graph);
-
-    // Set the title.
-    var title = document.createElement('div');
-    title.innerHTML = ((appName) ? appName : 'SproutCore Application') + (' - Total Captured Time: ' + maxDur +' ms - Points Captured: ' + chartLen) + ' [<a href="javascript:SC.Benchmark.hideChart();">Hide Chart</a>]';
-    title.className = 'sc-benchmark-title'; 
-    graph.appendChild(title);
-
-
-    var topBox = document.createElement('div');
-    topBox.className = 'sc-benchmark-top'; 
-    topBox.style.width = maxWidth + 'px';
-    graph.appendChild(topBox);
-
-    // Draw the tick marks.
-    for(i=0;i<incr; i++)
-    {
-      var tick = document.createElement('div');
-      tick.className = 'sc-benchmark-tick';
-      tick.style.left = (i*50)+'px';
-      tick.style.height = maxHeight+'px';
-      var tickLabel = document.createElement('div');
-      tickLabel.className = 'sc-benchmark-tick-label';
-      tickLabel.style.left = (i*50)+'px';
-      tickLabel.innerHTML = i*200+" ms";
-      graph.appendChild(tick);
-      graph.appendChild(tickLabel);
+    var leftPadding = 10, rightPadding = 300;
+
+
+    var str = "<div class = 'sc-benchmark-timeline-chart' style = 'position:relative;'>";
+    str += "<div class = 'sc-benchmark-top'></div>";
+
+    // add tick marks
+    for (var i = 0; i < incr; i++) {
+      str += "<div class = 'sc-benchmark-tick' style = '";
+      str += "left: " + (leftPadding + i * 50) + "px; ";
+      str += "height: " + maxHeight + "px;";
+      str += "'></div>";
+
+      str += "<div class = 'sc-benchmark-tick-label' style = '";
+      str += "left: " + (leftPadding + i * 50) + "px; ";
+      str += "'>" + (i * 200) + "ms</div>";
     }
-    
-    // For each item in the chart, print it out on the screen.
-    for(i=0;i<chartLen; i++)
-    {
-    	var row = document.createElement('div');
-    	row.style.top = (75+(i*30))+'px';
-    	row.style.width = maxWidth+'px';
-    	row.className = (i%2===0) ? 'sc-benchmark-row even' : 'sc-benchmark-row';
-    	graph.appendChild(row);
+
+    // print each chart item
+    for (i = 0; i < chartLen; i++) {
+      str += "<div class = 'sc-benchmark-row ";
+      str += (i % 2 === 0) ? 'even' : 'odd';
+      str += "' style = '";
+      str += "top: " + (50 + (i * 30)) + "px; ";
+      str += "'></div>";
 
       var div = document.createElement('div');
       var start = chart[i][1];
       var end = chart[i][2];
       var duration = chart[i][3];
-      
-      div.innerHTML = '&nbsp;' + (chart[i][0] + " <span class='sc-benchmark-emphasis'>" + duration + 'ms</span>');
-      
-      div.className = 'sc-benchmark-bar';
-      div.style.cssText = 'left:'+ (((start-gStart)/4))+'px; width: '+((duration/4))+
-                          'px; top: '+(53+(i*30))+'px;';
-      div.title = "start: " + (start-gStart) + " ms, end: " + (end-gStart) + ' ms, duration: ' + duration + ' ms';
-      graph.appendChild(div);
+
+
+      str += "<div class = 'sc-benchmark-bar' style = '";
+      str += 'left:'+ (leftPadding + ((start-gStart)/4))+'px; width: '+((duration/4)) + 'px;';
+      str += 'top: '+(28+(i*30))+'px;';
+
+      str += "' title = 'start: " + (start-gStart) + " ms, end: " + (end-gStart) + ' ms, duration: ' + duration + " ms'";
+      str += ">";
+      str += '&nbsp;' + chart[i][0] + " <span class='sc-benchmark-emphasis'>";
+      str += duration + "ms (start: " + (start - gStart) + "ms)";
+      str += "</span>";
+
+      str += "</div>";
+    }
+
+    // add the events
+    var events = this.events, idx = 0;
+    for (i in events) {
+      var t = events[i] - gStart;
+      str += "<div class = 'sc-benchmark-event idx" + (idx % 10) + "' style = '";
+      str += "left: " + (leftPadding + t / 4) + "px; height: " + maxHeight + "px; top: 20px;";
+      str += "' title = '" + i + ": " + t + "'></div>";
+      idx++;
     }
 
-    // Save the graph.
-    this._graph = graph;
+    str += "</div>";
+
+    return {
+      html: str,
+      totalCapturedTime: maxDur,
+      pointsCaptured: chartLen,
+      width: maxWidth + leftPadding + rightPadding,
+      height: maxHeight
+    };
+  },
+
+  /**
+    Returns a view with the timeline chart. The view has a 'reload' method to
+    refresh its data.
+
+    @returns {SC.View}
+  */
+  getTimelineChartView: function() {
+    var view = SC.ScrollView.create({
+      contentView: SC.StaticContentView.extend({
+
+      }),
+
+      reload: function() {
+        var content = SC.Benchmark.getTimelineChartContent();
+        this.contentView.set('content', content.html);
+        this.contentView.adjust({
+          width: content.width,
+          height: content.height
+        });
+
+        this.chartContent = content;
+
+        SC.RunLoop.invokeLater(SC.Benchmark, function() {
+          this.contentView.notifyPropertyChange('frame');
+        });
+      }
+    });
+
+    view.reload();
+
+    return view;
+  },
+
+  /**
+    Generate a human readable benchmark chart. Pass in appName if you desire.
+  */
+  timelineChart: function(appName) {
+    SC.RunLoop.begin();
+
+    var i=0;
+    // Hide the chart if there is an existing one.
+    this.hideChart();
+
+    // Compile the data.
+    var chartView = this.getTimelineChartView();
+    var chartLen = chartView.chartContent.pointsCaptured,
+        chartCapturedTime = chartView.chartContent.totalCapturedTime;
+
+    // Get the global start of the graph.
+
+    this._benchmarkChart = SC.Pane.create({
+      classNames: ["sc-benchmark-pane"],
+      layout: { left: 20, right: 20, bottom: 20, top: 20 },
+      childViews: ["title", "exit"],
+      exit: SC.ButtonView.extend({
+        layout: { right: 20, top: 20, width: 100, height: 30 },
+        title: "Hide Chart",
+        target: this,
+        action: "hideChart"
+      }),
+
+      title: SC.LabelView.extend({
+        classNames: ['sc-benchmark-title'],
+        layout: { left: 20, top: 23, right: 200, height: 30 },
+        value: ((appName) ? appName : 'SproutCore Application') + (' - Total Captured Time: ' + chartCapturedTime +' ms - Points Captured: ' + chartLen),
+        fontWeight: 'bold'
+      })
+
+    }).append();
+
+    chartView.set('layout', { left: 20, top: 60, bottom: 20, right: 20 });
+    this._benchmarkChart.appendChild(chartView);
+
+    SC.RunLoop.end();
   },
-  
+
   /*
     Hide chart.
-    
   */
-  hideChart: function()
-  {
-    if(this._graph) {
-      try{ 
-        document.body.removeChild(this._graph);
-      }catch(e){}
+  hideChart: function() {
+    if (this._benchmarkChart) {
+      this._benchmarkChart.remove();
+      this._benchmarkChart = null;
     }
+
+    return YES;
+  },
+
+  /** @private
+    Because we show a pane to display the chart...
+  */
+  tryToPerform: function(action, sender) {
+    if (this[action]) return this[action](sender);
+    return NO;
   },
-  
 
   /**
     This method is just like report() except that it will log the results to
     the console.
-  */  
+  */
   log: function(key) {
     // log each line to make this easier to read on an iPad
     var lines = this.report(key).split('\n'),
         len   = lines.length, idx;
-    for(idx=0;idx<len;idx++) console.log(lines[idx]);
+    for(idx=0;idx<len;idx++) SC.Logger.log(lines[idx]);
   },
-  
+
   /**
     This will activate profiling if you have Firebug installed.  Otherwise
     does nothing.
   */
   startProfile: function(key) {
     if (!this.enabled) return ;
-    if (console && console.profile) console.profile(key) ;
+    SC.Logger.profile(key) ;
   },
-  
+
   endProfile: function(key) {
     if (!this.enabled) return ;
-    if (console && console.profileEnd) console.profileEnd(key) ;
+    SC.Logger.profileEnd(key) ;
   },
-  
-  // PRIVATE METHODS
 
-  // @private
-  
-  // Generates, sorts, and returns the array of all the data that has been captured.
-  _compileChartData: function(showSub)
-  {
+
+  // ..........................................................
+  // Internal Support
+  // 
+
+  /** @private
+    Loads data from both the browser's own event hash and SC's pre-load event hash.
+  */
+  loadPreloadEvents: function() {
+    var preloadEvents = SC.benchmarkPreloadEvents, events = [], idx, len, evt;
+
+    // the browsers may have their own event hash. Ours uses the same format, so
+    // all that we need to do is mixin the browser's to our own.
+    if (typeof webkitPerformnce !== 'undefined') SC.mixin(preloadEvents, webkitPerformane.timing);
+
+    // we will attempt to find when the loading started and use that as our
+    // global start time, but only do so if the global start time is not already set.
+    if (!this.globalStartTime) {
+      // the potential events representing start time can be either from the browser
+      // or our own recordings. We prefer the browser.
+      var globalStartEvents = ['navigation', 'navigationStart', 'headStart'];
+      len = globalStartEvents.length;
+
+      for (idx = 0; idx < len; idx++) {
+        if (preloadEvents[globalStartEvents[idx]]) {
+          this.globalStartTime = preloadEvents[globalStartEvents[idx]];
+          break;
+        }
+      }
+    }
+
+    // the JavaScript start time will be one recorded by us
+    // we record headStart in bootstrap.
+    this.javascriptStartTime = preloadEvents['headStart'];
+
+    // finally, mix in the events to our own events hash
+    SC.mixin(this.events, preloadEvents);
+
+    this._hasLoadedPreloadEvents = true;
+  },
+
+  /** @private
+    Some events represent a beginning and end. While this is not common for events
+    that take place after the app loads (as they can just use SC.Benchmark.start/end),
+    SC.Benchmark.start/end is not available before load—as such, code will add
+    *Start and *End events to the event hash.
+
+    This method iterates over the event hash and removes those items that represent
+    starts and ends, calling .start/.end for them.
+  */
+  _loadBenchmarksFromEvents: function() {
+    if (!this._hasLoadedPreloadEvents) this.loadPreloadEvents();
+
+    var events = this.events;
+    for (var i in events) {
+      if (i.substr(-3) !== 'End') continue;
+
+      var stem = i.substr(0, i.length - 3);
+      if (!events[stem + 'Start']) continue;
+
+      SC.Benchmark.start(stem, undefined, events[stem + 'Start']);
+      SC.Benchmark.end(stem, undefined, events[stem + 'End']);
+
+      delete events[stem + 'Start'];
+      delete events[stem + 'End'];
+    }
+  },
+
+  /** @private
+    Generates, sorts, and returns the array of all the data that has been captured.
+  */
+  _compileChartData: function(showSub) {
+    this._loadBenchmarksFromEvents();
+
     var chart = [], dispKey;
-    for(var key in this.stats) 
+    for(var key in this.stats)
     {
       var stat = this.stats[key];
       for(var i=0; i<stat._times.length; i++)
@@ -402,25 +606,25 @@ SC.Benchmark = {
         if(showSub)
         {
           var subStats = st._subStats;
-          for(var k in subStats) 
+          for(var k in subStats)
           {
-           
+
             var subStat = subStats[k];
             for(var j=0; j<subStat._times.length; j++)
             {
               var s = subStat._times[j];
               dispKey = (subStat._times.length > 1) ? (j+1)+' - '+k : k;
               chart.push([dispKey, s.start, s.end, s.dur, true]);
-         
+
             }
           }
         }
       }
     }
-    
+
     chart.sort(function(a,b)
     {
-      if(a[1] < b[1]) 
+      if(a[1] < b[1])
       {
         return -1;
       }
@@ -435,43 +639,48 @@ SC.Benchmark = {
 
     return chart;
   },
-  
+
   // Generate the traditional report show multiple runs averaged.
+  /** @private */
   _genReport: function(key) {
     var stat = this._statFor(key) ;
     var avg = (stat.runs > 0) ? (Math.floor(stat.amt * 1000 / stat.runs) / 1000) : 0 ;
-     
-    return 'BENCH %@ msec: %@ (%@x)'.fmt(avg, (stat.name || key), stat.runs) ;  
+    var last = stat._times[stat._times.length - 1];
+
+    return 'BENCH %@ msec: %@ (%@x); latest: %@'.fmt(avg, (stat.name || key), stat.runs, last.end - last.start);
   },
 
   // Generate the report in the form of at time line. This returns the parent.
-  _timelineGenReport: function(val) 
+  /** @private */
+  _timelineGenReport: function(val)
   {
     if(this.globalStartTime)
     {
-      return 'BENCH start: %@ msec, duration: %@ msec,  %@'.fmt((val[1]-this.globalStartTime), val[3], val[0]) ;  
-    } 
+      return 'BENCH start: %@ msec, duration: %@ msec,  %@'.fmt((val[1]-this.globalStartTime), val[3], val[0]) ;
+    }
     else
     {
-      return 'BENCH duration: %@ msec, %@'.fmt( val[3],  val[0]) ;  
+      return 'BENCH duration: %@ msec, %@'.fmt( val[3],  val[0]) ;
     }
   },
-  
+
   // Generate the report in the form of at time line. This returns the children.
-  _timelineGenSubReport: function(val) 
+  /** @private */
+  _timelineGenSubReport: function(val)
   {
     if(this.globalStartTime)
     {
-      return '   CHECKPOINT BENCH start: %@ msec, duration: %@ msec,  %@'.fmt((val[1]-this.globalStartTime), val[3], val[0]) ;  
-    } 
+      return '   CHECKPOINT BENCH start: %@ msec, duration: %@ msec,  %@'.fmt((val[1]-this.globalStartTime), val[3], val[0]) ;
+    }
     else
     {
-      return '   CHECKPOINT BENCH duration: %@ msec, %@'.fmt( val[3], val[0]) ;  
+      return '   CHECKPOINT BENCH duration: %@ msec, %@'.fmt( val[3], val[0]) ;
     }
   },
-  
+
   // returns a stats hash for the named key and parent key.  If the hash does not exist yet,
   // creates it.
+  /** @private */
   _subStatFor: function(key, parentKey) {
     var parentTimeLen = this.stats[parentKey]._times.length;
     if(parentTimeLen === 0) return;
@@ -479,7 +688,7 @@ SC.Benchmark = {
     var ret = parentSubStats[key] ;
     if (!ret) {
       parentSubStats[key] = {
-        runs: 0, amt: 0, name: key, _starts: [], _times: []      
+        runs: 0, amt: 0, name: key, _starts: [], _times: []
       };
       ret = parentSubStats[key];
     }
@@ -488,27 +697,31 @@ SC.Benchmark = {
 
   // returns a stats hash for the named key.  If the hash does not exist yet,
   // creates it.
+  /** @private */
   _statFor: function(key) {
     var ret = this.stats[key] ;
     if (!ret) {
       ret = this.stats[key] = {
-        runs: 0, amt: 0, name: key, _starts: [], _times: []      
+        runs: 0, amt: 0, name: key, _starts: [], _times: []
       };
       ret = this.stats[key];
     }
     return ret ;
   },
-  
+
+  /** @private */
   reset: function() { this.stats = {} ; },
-  
+
   // This is private, but it is used in some places, so we are keeping this for
   // compatibility.
+  /** @private */
   _bench: function(func, name) {
     SC.Benchmark.bench(func, name, 1) ;
   },
-  
+
+  /** @private */
   _benchCount: 1
-  
+
 } ;
 
 SC.Benchmark = SC.Benchmark;