sproutcore 1.5.0.rc.1 → 1.5.0.rc.2

data/lib/frameworks/sproutcore/frameworks/desktop/views/workspace.js

@@ -5,6 +5,8 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
+require("views/toolbar");
+
 /** @class
   WorkspaceView manages a content view and two optional toolbars (top and bottom).
   You want to use WorkspaceView in one of two situations: iPhone apps where the toolbars
@@ -12,58 +14,82 @@
   handy!) and iPad apps where you would like the masterIsHidden property to pass through.
   
   @since SproutCore 1.2
+  @extends SC.View
+  @author Alex Iskander
 */
+SC.WorkspaceView = SC.View.extend(
+/** @scope SC.WorkspaceView.prototype */ {
 
-require("views/toolbar");
-
-SC.VERTICAL_ORIENTATION = "vertical";
-SC.HORIZONTAL_ORIENTATION = "horizontal";
-
-SC.WorkspaceView = SC.View.extend({
+  /**
+    @type Array
+    @default ['sc-workspace-view']
+    @see SC.View#classNames
+  */
   classNames: ["sc-workspace-view"],
+  
   /**
-    The top toolbar. This defaults to an empty toolbar.
+    @type Array
+    @default "hasTopToolbar hasBottomToolbar".w()
+    @see SC.View#displayProperties
+  */
+  displayProperties: "hasTopToolbar hasBottomToolbar".w(),
+  
+  /**
+    @type String
+    @default 'workspaceRenderDelegate'
+  */
+  renderDelegateName: 'workspaceRenderDelegate',
+
+  /**
+    @type SC.View
+    @default SC.ToolbarView
   */
   topToolbar: SC.ToolbarView.extend(),
   
   /**
-    The bottom toolbar. Defaults to null (no toolbar).
+    @type SC.View
+    @default null
   */
   bottomToolbar: null,
   
   /**
-    The content. Must NOT be null. Defaults to an empty view.
+    The content. Must NOT be null.
+    
+    @type SC.View
+    @default SC.View
   */
   contentView: SC.View.extend(),
   
   /**
-    Whether to automatically resize toolbars.
-    
-    By default, this property is NO. If you want to automatically resize like iPhone
+    If you want to automatically resize the toolbars like iPhone
     apps should, set to YES.
+    
+    @type Boolean
+    @default NO
   */
   autoResizeToolbars: NO,
   
   /**
-    The default toolbar size. The default is 44, as that looks
-    great on higher-resolution devices.
-    
-    TODO: move into a renderer or something.
+    @type Number
+    @default 44
   */
   defaultToolbarSize: 44,
   
   /**
-    The large toolbar size.
+    @type Number
+    @default 44
   */
   largeToolbarSize: 44,
   
   /**
-    The small toolbar size.
+    @type Number
+    @default 30
   */
   smallToolbarSize: 30,
   
   /**
-    A property (computed) that says what size the toolbars are.
+    @field
+    @type Number
   */
   toolbarSize: function() {
     if (!this.get("autoResizeToolbars")) return this.get("defaultToolbarSize");
@@ -72,7 +98,14 @@ SC.WorkspaceView = SC.View.extend({
   }.property("autoHideMaster", "orientation"),
   
   /**
-    Tracks the orientation of the view. Is a computed property. Property, people, not a method.
+    Tracks the orientation of the view. Possible values:
+    
+      - SC.HORIZONTAL_ORIENTATION
+      - SC.PORTRAIT_ORIENTATION
+    
+    @field
+    @type String
+    @default SC.HORIZONTAL_ORIENTATION
   */
   orientation: function() {
     var f = this.get("frame");
@@ -81,11 +114,12 @@ SC.WorkspaceView = SC.View.extend({
   }.property("frame").cacheable(),
   
   /**
-    Thees property es passed throo too make eet zeemple for zee toolbar buttonz
-    to hide and show theemselves.
+    @type Boolean
+    @default NO
   */
   masterIsHidden: NO,
   
+  /** @private */
   masterIsHiddenDidChange: function() {
     var t, mih = this.get("masterIsHidden");
     if (t = this.get("topToolbar")) t.set("masterIsHidden", mih);
@@ -104,7 +138,7 @@ SC.WorkspaceView = SC.View.extend({
     this.invokeOnce("_scws_tile");
   }.observes("toolbarSize"),
   
-  /**
+  /** @private
     Creates the child views. Specifically, instantiates master and detail views.
   */
   createChildViews: function() {
@@ -162,7 +196,7 @@ SC.WorkspaceView = SC.View.extend({
     });
   },
   
-  /**
+  /** @private
     Returns YES if a top toolbar is present.
   */
   hasTopToolbar: function() {
@@ -170,7 +204,7 @@ SC.WorkspaceView = SC.View.extend({
     return NO;    
   }.property("topToolbar").cacheable(),
   
-  /**
+  /** @private
     Returns YES if a bottom toolbar is present.
   */
   hasBottomToolbar: function() {
@@ -178,29 +212,29 @@ SC.WorkspaceView = SC.View.extend({
     return NO;
   }.property("bottomToolbar").cacheable(),
   
-  /**
+  /** @private
     Called by the individual toolbar/contentView observers at runloop end when the toolbars change.
   */
   childDidChange: function() {
     this._scws_tile();
   },
   
-  /**
+  /** @private
     For subclassing, this is the currently displaying top toolbar.
   */
   activeTopToolbar: null,
   
-  /**
+  /** @private
     For subclassing, this is the currently displaying bottom toolbar.
   */
   activeBottomToolbar: null,
   
-  /**
+  /** @private
     For subclassing, this is the currently displaying content view.
   */
   activeContentView: null,
   
-  /**
+  /** @private
     Called when the top toolbar changes. It appends it, removes any old ones, and calls toolbarsDidChange. 
     
     You may want to override this if, for instance, you want to add transitions of some sort (should be trivial).
@@ -218,6 +252,9 @@ SC.WorkspaceView = SC.View.extend({
     this.invokeLast("childDidChange");
   }.observes("topToolbar"),
   
+  /**
+    @private
+  */
   bottomToolbarDidChange: function() {
     var active = this.activeBottomToolbar, replacement = this.get("bottomToolbar");
     if (active) {
@@ -231,6 +268,7 @@ SC.WorkspaceView = SC.View.extend({
     this.invokeLast("childDidChange");
   }.observes("bottomToolbar"),
   
+  /** @private */
   contentViewDidChange: function() {
     var active = this.activeContentView, replacement = this.get("contentView");
     if (active) {
@@ -242,10 +280,6 @@ SC.WorkspaceView = SC.View.extend({
     
     this.activeContentView = replacement;
     this.invokeLast("childDidChange");
-  }.observes("contentView"),
-  
-  
-  displayProperties: "hasTopToolbar hasBottomToolbar".w(),
-  
-  renderDelegateName: 'workspaceRenderDelegate'
+  }.observes("contentView")
+
 });

data/lib/frameworks/sproutcore/frameworks/foundation/controllers/tree.js

@@ -7,6 +7,10 @@
 
 sc_require('private/tree_item_observer');
 
+/*
+  TODO Document more
+*/
+
 /**
   @class
 
@@ -16,8 +20,6 @@ sc_require('private/tree_item_observer');
   that the TreeController will also provide an arrangedObjects property that
   can be used as the content of a CollectionView.
 
-  TODO: Document More
-
   @extends SC.ObjectController
   @extends SC.SelectionSupport
   @since SproutCore 1.0
@@ -33,7 +35,8 @@ SC.TreeController = SC.ObjectController.extend(SC.SelectionSupport,
     Set to YES if you want the top-level items in the tree to be displayed as
     group items in the collection view.
 
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   treeItemIsGrouped: NO,
 
@@ -43,7 +46,8 @@ SC.TreeController = SC.ObjectController.extend(SC.SelectionSupport,
     determine the expansion state of the item.  The default is
     "treeItemIsExpanded"
 
-    @property {String}
+    @type String
+    @default "treeItemIsExpanded"
   */
   treeItemIsExpandedKey: "treeItemIsExpanded",
 
@@ -51,7 +55,8 @@ SC.TreeController = SC.ObjectController.extend(SC.SelectionSupport,
     Set to the name of the property on your content object that holds the
     children array for each tree node.  The default is "treeItemChildren".
 
-    @property {String}
+    @type String
+    @default "treeItemChildren"
   */
   treeItemChildrenKey: "treeItemChildren",
 

data/lib/frameworks/sproutcore/frameworks/foundation/debug/control_test_pane.js

@@ -4,7 +4,7 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
-/*global test */
+/*global test Q$ */
 
 // TODO: IMPROVE CODE QUALITY.  This code was put together quickly in order to
 // test the SproutCore framework.  It does not match up to the project's 
@@ -16,22 +16,20 @@
   You can use this class in test mode to easily create a palette with views
   configured in different ways.
   
-  h1. Example
+  # Example
   
-  {{{
-    var pane = SC.ControlTestPane.design()
-      .add('basic', SC.CheckboxView.design({ title: "Hello World" }))
-      .add('disabled', SC.CheckboxView.design({
-        title: "Hello World", isEnabled: NO
-      }));
+      var pane = SC.ControlTestPane.design()
+        .add('basic', SC.CheckboxView.design({ title: "Hello World" }))
+        .add('disabled', SC.CheckboxView.design({
+          title: "Hello World", isEnabled: NO
+        }));
       
-    module("CheckboxView UI", pane);
+      module("CheckboxView UI", pane);
     
-    test("basic", function() {
-      var view = pane.view('basic');
-      ok(view.get('isEnabled'), 'should be enabled');
-    });
-  }}}
+      test("basic", function() {
+        var view = pane.view('basic');
+        ok(view.get('isEnabled'), 'should be enabled');
+      });
   
   @extends SC.Pane
   @since SproutCore 1.0
@@ -45,19 +43,28 @@ SC.ControlTestPane = SC.Pane.extend(
   /**
     The starting top location for the first row.  This will increment as 
     views are added to the pane.
+    
+    @type Number
+    @default 0
   */
-  top:       0,
+  top: 0,
   
   /**
     The default height of each row.  This will be used for a view unless you
     manually specify a height in the view's layout.
+    
+    @type Number
+    @default 20
   */
-  height:    20,
+  height: 20,
   
   /**
     The default padding added to the edges and between each row.
+    
+    @type Number
+    @default 4
   */
-  padding:   4,
+  padding: 4,
 
   /**
     Retrieves the test sample view that was added with the passed key name.
@@ -71,6 +78,7 @@ SC.ControlTestPane = SC.Pane.extend(
     return this.childViews[idx].childViews[0]; 
   },
   
+  /** @private */
   init: function() {
     sc_super();
     if (!this._views) this._views = {};
@@ -168,6 +176,9 @@ SC.ControlTestPane.standardSetup = function() {
 /**
   Convenience method.  Returns the view with the given name on the current
   pane instance if there is one.
+  
+  @param {String} keyName the key used to register the view.
+  @returns {SC.View} view instance
 */
 SC.ControlTestPane.view = function(viewKey) {
   var pane = this._pane || this._showPane ;

data/lib/frameworks/sproutcore/frameworks/foundation/delegates/inline_text_field.js

@@ -3,47 +3,47 @@
 // Copyright: ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
-/*
-* @delegate
-*
-* This is the default InlineEditorDelegate for SC.LabelView. The default editor
-* is an SC.InlineTextFieldView.
-*
-* Only one editor is allowed to be active at a time. If another view requests an
-* editor while an editor is already active, the delegate will first attempt to
-* commit the existing editor, then discard it if commit fails, and fail to
-* acquire if the active editor could not be discarded.
-*
-* Each time an editor is required, it instantiates it and appends it to the same
-* pane as the view being edited. The editor is responsible for positioning
-* itself correctly in its beginEditing method.
-*
-* @implements SC.InlineEditorDelegate
+
+/**
+  @namespace
+  
+  This is the default InlineEditorDelegate for SC.LabelView. The default editor
+  is an SC.InlineTextFieldView.
+
+  Only one editor is allowed to be active at a time. If another view requests an
+  editor while an editor is already active, the delegate will first attempt to
+  commit the existing editor, then discard it if commit fails, and fail to
+  acquire if the active editor could not be discarded.
+
+  Each time an editor is required, it instantiates it and appends it to the same
+  pane as the view being edited. The editor is responsible for positioning
+  itself correctly in its beginEditing method.
+
+  @since SproutCore 1.0
 */
-SC.InlineTextFieldDelegate = {
+SC.InlineTextFieldDelegate = /** @scope SC.InlineTextFieldDelegate */{
+
   /**
     The current shared inline editor.
 
-    @property {SC.InlineTextFieldView}
+    @type SC.InlineTextFieldView
   */
   editor: null,
 
-  /*
-  * @method
-  *
-  * If an editor is currently active, dismisses it by first attempting to commit
-  * and if that fails attempting to dismiss. If that fails, the acquire fails
-  * and returns null.
-  *
-  * Otherwise, it creates the editor as a child of the client view's pane and
-  * returns it.
-  *
-  * The default editor is an SC.InlineTextFieldView. The client view may
-  * customize this by setting a different inlineEditor as its exampleEditor
-  * property.
-  *
-  * @param {SC.InlineEditable} the label that is requesting an editor
-  * @returns {SC.InlineEditor} the editor the label should use to edit
+  /**
+    If an editor is currently active, dismisses it by first attempting to commit
+    and if that fails attempting to dismiss. If that fails, the acquire fails
+    and returns null.
+
+    Otherwise, it creates the editor as a child of the client view's pane and
+    returns it.
+
+    The default editor is an SC.InlineTextFieldView. The client view may
+    customize this by setting a different inlineEditor as its exampleEditor
+    property.
+
+    @param {SC.InlineEditable} label the label that is requesting an editor
+    @returns {SC.InlineEditor} the editor the label should use to edit
   */
   acquireEditor: function(label) {
     var editor = this.editor;
@@ -71,15 +71,13 @@ SC.InlineTextFieldDelegate = {
     return editor;
   },
 
-  /*
-  * @method
-  *
-  * Cleans up the given editor by simply removing it from the view hierarchy. The
-  * client view should null any references to the editor so it may be garbage
-  * collected.
-  *
-  * @params {SC.InlineEditor} the editor that should be cleaned up
-  * @returns {Boolean} whether the cleanup succeeded
+  /**
+    Cleans up the given editor by simply removing it from the view hierarchy. The
+    client view should null any references to the editor so it may be garbage
+    collected.
+
+    @params {SC.InlineEditor} editor the editor that should be cleaned up
+    @returns {Boolean} whether the cleanup succeeded
   */
   releaseEditor: function(editor) {
     editor.removeFromParent();

data/lib/frameworks/sproutcore/frameworks/foundation/gestures/pinch.js

@@ -4,18 +4,47 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 sc_require("system/gesture");
 
-SC.PinchGesture = SC.Gesture.extend({
+/*
+  TODO Document this class
+*/
+
+/**
+  @class
+  @extends SC.Gesture
+*/
+SC.PinchGesture = SC.Gesture.extend(
+/** @scope SC.PinchGesture.prototype */{
+
+  /**
+    @type String
+    @default "pinch"
+    @readOnly
+  */
   name: "pinch",
+
+  /**
+    @type Boolean
+    @default YES
+    @readOnly
+  */
   acceptsMultitouch: YES,
 
+  /**
+    @type Number
+    @default 1
+  */
   scale: 1,
 
   /**
     The default for this method is to loop through each touch one by one to see if it qualifies.
     Here, however, we want to take the touches when there are 2, and only 2 of them. As a result
     we can do the work here, with no need to pass them on.
+    
+    @param {Event} evt The touch event
+    @param {Array} touches All touches
   */
   unassignedTouchesDidChange: function(evt, touches) {
     if (touches.length == 2) {
@@ -28,10 +57,13 @@ SC.PinchGesture = SC.Gesture.extend({
     We could probably just return YES here, since unassignedTouchesDidChange shouldn't let more
     than 2 touches through, however, we're double checking here to make sure that we haven't
     already captured 2 touches.
+    
+    @param {Touch} touch
+    @returns {Boolean} YES if there were none or one touches prior to this, NO otherwise
   */
   touchStart: function(touch) {
     var touches = touch.touchesForResponder(this);
-    if (!touches || touches.length == 0) {
+    if (!touches || touches.length === 0) {
       return YES;
     } else if (touches.length == 1) {
       this.start([touches[0], touch]);
@@ -45,6 +77,9 @@ SC.PinchGesture = SC.Gesture.extend({
     Here we're getting the distance between the 2 touches and comparing it to their starting
     distance. It's possible we'll want to implement a more complex algorithm to make things
     a bit smoother. Once we have the relative change, we trigger the pinch action in the view.
+    
+    @param {Event} evt
+    @param {Array} touches
   */
   touchesDragged: function(evt, touches) {
     var touch = touches.firstObject(),
@@ -63,13 +98,15 @@ SC.PinchGesture = SC.Gesture.extend({
 
   /**
     Once one touch has ended we don't need to watch the other so we release all touches.
+    
+    @param {SC.Touch} touch
   */
   touchEnd: function(touch) {
     this._startDistance = null;
 
     var touches = touch.touchesForResponder(this);
 
-    this.trigger(touches, this.scale)
+    this.trigger(touches, this.scale);
     this.end(touches, this.scale);
 
     if (touches) {
@@ -78,4 +115,5 @@ SC.PinchGesture = SC.Gesture.extend({
       }, this);
     }
   }
-});
+
+});