sproutcore 1.5.0 → 1.6.0.beta.1

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/navigation_builder.js

@@ -9,7 +9,7 @@
 /**
   @namespace
   NavigationBuilder is an implementation of the Builder protocol. It implements
-  buildIn/Out (though these only relay to buildIn/OutNavigation, so feel free to
+  `buildIn`/`Out` (though these only relay to `buildIn`/`OutNavigation, so feel free to
   override if needed; the navigation builders will still be accessible).
   
   Building in and out animates the view in and out to and from the left and right.
@@ -101,16 +101,16 @@ SC.NavigationBuilder = {
   },
   
   /**
-    You may override this. If you do, call buildInNavigation to call the original functionality.
-    You may need to override navigationBuildDidFinish as well if you call buildInNavigation.
+    You may override this. If you do, call `buildInNavigation` to call the original functionality.
+    You may need to override `navigationBuildDidFinish` as well if you call `buildInNavigation`.
   */
   buildIn: function() {
     this.buildInNavigation();
   },
   
   /**
-    You may override this. If you do, call buildOutNavigation to call the original functionality.
-    You may need to override navigationBuildDidFinish as well if you call buildOutNavigation.
+    You may override this. If you do, call `buildOutNavigation` to call the original functionality.
+    You may need to override `navigationBuildDidFinish`as well if you call `buildOutNavigation`.
   */
   buildOut: function() {
     this.buildOutNavigation();

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/scrollable.js

@@ -14,8 +14,8 @@
   provide basic support for scrolling actions.  You can also override any 
   of these methods as needed for your own specific behaviors.
   
-  Often times instead of adding SC.Scrollable to your view, you should
-  place your view inside of an SC.ScrollView.  See that class for more 
+  Often times instead of adding `SC.Scrollable` to your view, you should
+  place your view inside of an `SC.ScrollView`.  See that class for more
   info.
   
   Note that isScrollable must always be true.
@@ -30,7 +30,7 @@ SC.Scrollable = {
 
   /** Informs the view system that the receiver is scrollable.
 
-    Must always be true.
+    Must always be `true.
 
     @property {Boolean}
     @default YES
@@ -41,7 +41,7 @@ SC.Scrollable = {
   /** 
     Amount to scroll one vertical line.
   
-    Used by the default implementation of scrollDownLine() and scrollUpLine().
+    Used by the default implementation of `scrollDownLine()` and `scrollUpLine()`.
     
     @property {Number}
     @default 20
@@ -51,7 +51,7 @@ SC.Scrollable = {
   /**
     Amount to scroll one horizontal line.
   
-    Used by the default implementation of scrollLeftLine() and scrollRightLine().
+    Used by the default implementation of `scrollLeftLine()` and `scrollRightLine()`.
     
     @property {Number}
     @default 20
@@ -61,8 +61,8 @@ SC.Scrollable = {
   /**
     Amount to scroll one vertical page.
     
-    Used by the default implementation of scrollUpPage() and scrollDownPage(). Defaults to
-    current innerFrame height.
+    Used by the default implementation of `scrollUpPage()` and `scrollDownPage()`. Defaults to
+    current `innerFrame` height.
   */
   verticalPageScroll: function() {
     return this.get('innerFrame').height;
@@ -71,8 +71,8 @@ SC.Scrollable = {
   /**
     Amount to scroll one horizontal page.
     
-    Used by the default implementation of scrollLeftPage() and scrollRightPage().  Defaults
-    to current innerFrame width.
+    Used by the default implementation of `scrollLeftPage()` and `scrollRightPage()`.  Defaults
+    to current `innerFrame` width.
   */
   horizontalPageScroll: function() {
     return this.get('innerFrame').width ;
@@ -142,7 +142,7 @@ SC.Scrollable = {
   /**
     Scroll the view to make the passed frame visible.
     
-    Frame must be relative to the receiver's offsetParent.
+    Frame must be relative to the receiver's `offsetParent`.
     
     @param {SC.View} view the view you want to make visible
   */

data/lib/frameworks/sproutcore/frameworks/desktop/panes/alert.js

@@ -43,33 +43,33 @@ SC.BUTTON3_STATUS = 'button3';
   useful for showing important error messages and confirmation dialogs. They
   provide a better user experience than using the OS-level alert dialogs.
   
-  # Displaying an Alert Pane
+  ## Displaying an Alert Pane
   
   The easiest way to display an alert pane is to use one of the various
-  class methods defined on SC.AlertPane, passing the message and an optional
+  class methods defined on `SC.AlertPane`, passing the message and an optional
   detailed description and caption.
   
   There are four variations of this method can you can invoke:
   
-    - *warn()* - displays an alert pane with a warning icon to the left.
-    - *error()* - displays an alert with an error icon to the left
-    - *info()* - displays an alert with an info icon to the left
-    - *plain()* - displays an alert w/o any icon
-    - *show()* - displays an alert with a customizable icon to the left
+   - `warn()` -- displays an alert pane with a warning icon to the left.
+   - `error()` -- displays an alert with an error icon to the left
+   - `info()` -- displays an alert with an info icon to the left
+   - `plain()` -- displays an alert w/o any icon
+   - `show()` -- displays an alert with a customizable icon to the left
   
   In addition to passing a message, description and caption, you can also customize
   the title of the button 1 (OK) and add an optional button 2 and 3 (Cancel or Extra).
   
-    - button1 - 1st button from the right. default:OK
-    - button2 - 2nd button from the right. Optional. Could be Cancel or 2nd action.
-    - button3 - 1st button from the left. Optional. Could be Cancel or alternative option.
+   - button1 -- 1st button from the right. default:OK
+   - button2 -- 2nd button from the right. Optional. Could be Cancel or 2nd action.
+   - button3 -- 1st button from the left. Optional. Could be Cancel or alternative option.
   
   Additionally, you can define a delegate object.  This delegate's 
-  'alertPaneDidDismiss()' method will be called when the pane
+  `alertPaneDidDismiss()` method will be called when the pane
   is dismissed, passing the pane instance and a key indicating which 
   button was pressed.
   
-  # Examples
+  ## Examples
   
   Show a simple AlertPane with an OK button:
   
@@ -178,7 +178,7 @@ SC.AlertPane = SC.PanelPane.extend(
     
         alertPaneDidDismiss: function(pane, status) {}
     
-    The status will be one of SC.BUTTON1_STATUS, SC.BUTTON2_STATUS or SC.BUTTON3_STATUS
+    The status will be one of `SC.BUTTON1_STATUS`, `SC.BUTTON2_STATUS` or `SC.BUTTON3_STATUS`
     depending on which button was clicked.
     
     @type Object
@@ -373,11 +373,12 @@ SC.AlertPane = SC.PanelPane.extend(
     alertpane itself.
     
     This will trigger the following chain of events:
-    1. If a delegate was given, and it has alertPaneDidDismiss it will be called
-    2. Otherwise it will look for the action of the button and call:
-       a) The action function reference if one was given
-       b) The action method on the target if one was given
-       c) If both a and b are missing, call the action on the rootResponder
+
+     1. If a delegate was given, and it has alertPaneDidDismiss it will be called
+     2. Otherwise it will look for the action of the button and call:
+      a) The action function reference if one was given
+      b) The action method on the target if one was given
+      c) If both a and b are missing, call the action on the rootResponder
     
     @param {SC.View} sender - the button view that was clicked
   */
@@ -431,7 +432,7 @@ SC.AlertPane.mixin(
         });
     
     See more examples for how to configure buttons and individual actions in the 
-    documentation for the SC.AlertPane class.
+    documentation for the `SC.AlertPane` class.
     
     @param {Hash} args
     @return {SC.AlertPane} the pane shown
@@ -474,7 +475,7 @@ SC.AlertPane.mixin(
   },
   
   /**
-    Same as show() just that it uses sc-icon-alert-48 CSS classname
+    Same as `show()` just that it uses sc-icon-alert-48 CSS classname
     as the dialog icon
     
     @param {Hash} args
@@ -489,7 +490,7 @@ SC.AlertPane.mixin(
   },
   
   /**
-    Same as show() just that it uses sc-icon-info-48 CSS classname
+    Same as `show()` just that it uses sc-icon-info-48 CSS classname
     as the dialog icon
     
     @param {Hash} args
@@ -504,7 +505,7 @@ SC.AlertPane.mixin(
   },
   
   /**
-    Same as show() just that it uses sc-icon-error-48 CSS classname
+    Same as `show()` just that it uses sc-icon-error-48 CSS classname
     as the dialog icon
     
     @param {Hash} args
@@ -519,7 +520,7 @@ SC.AlertPane.mixin(
   },
   
   /**
-    Same as show() just that it uses blank CSS classname
+    Same as `show()` just that it uses blank CSS classname
     as the dialog icon
     
     @param {Hash} args

data/lib/frameworks/sproutcore/frameworks/desktop/panes/menu.js

@@ -11,17 +11,17 @@ sc_require('views/menu_item');
 /**
   @class
 
-  SC.MenuPane allows you to display a standard menu. Menus appear over other
+  `SC.MenuPane` allows you to display a standard menu. Menus appear over other
   panes, and block input to other views until a selection is made or the pane
   is dismissed by clicking outside of its bounds.
 
   You can create a menu pane and manage it yourself, or you can use the
-  SC.SelectButtonView and SC.PopupButtonView controls to manage the menu for
+  `SC.SelectButtonView` and `SC.PopupButtonView` controls to manage the menu for
   you.
 
-  h2. Specifying Menu Items
+  ## Specifying Menu Items
 
-  The menu pane examines the @items@ property to determine what menu items
+  The menu pane examines the `items` property to determine what menu items
   should be presented to the user.
 
   In its most simple form, you can provide an array of strings. Every item
@@ -33,29 +33,27 @@ sc_require('views/menu_item');
 
   Out of the box, the menu pane has some default keys it uses to get
   information from the objects. For example, to find out the title of the menu
-  item, the menu pane will ask your object for its @title@ property. If you
-  need to change this key, you can set the @itemTitleKey@ property on the pane
+  item, the menu pane will ask your object for its `title` property. If you
+  need to change this key, you can set the `itemTitleKey` property on the pane
   itself.
 
-  {{{
-    var menuItems = [
-      { title: 'Menu Item', keyEquivalent: 'ctrl_shift_n' },
-      { title: 'Checked Menu Item', isChecked: YES, keyEquivalent: 'ctrl_a' },
-      { title: 'Selected Menu Item', keyEquivalent: ['backspace', 'delete'] },
-      { isSeparator: YES },
-      { title: 'Menu Item with Icon', icon: 'inbox', keyEquivalent: 'ctrl_m' },
-      { title: 'Menu Item with Icon', icon: 'folder', keyEquivalent: 'ctrl_p' }
-    ];
-
-    var menu = SC.MenuPane.create({
-      items: menuItems
-    });
-  }}}
+      var menuItems = [
+        { title: 'Menu Item', keyEquivalent: 'ctrl_shift_n' },
+        { title: 'Checked Menu Item', isChecked: YES, keyEquivalent: 'ctrl_a' },
+        { title: 'Selected Menu Item', keyEquivalent: ['backspace', 'delete'] },
+        { isSeparator: YES },
+        { title: 'Menu Item with Icon', icon: 'inbox', keyEquivalent: 'ctrl_m' },
+        { title: 'Menu Item with Icon', icon: 'folder', keyEquivalent: 'ctrl_p' }
+      ];
+
+      var menu = SC.MenuPane.create({
+        items: menuItems
+      });
 
-  h2. Observing User Selections
+  ## Observing User Selections
 
   To determine when a user clicks on a menu item, you can observe the
-  @selectedItem@ property for changes.
+  `selectedItem` property for changes.
 
   @extends SC.PickerPane
   @since SproutCore 1.0
@@ -98,14 +96,13 @@ SC.MenuPane = SC.PickerPane.extend(
   /**
     The size of the menu. This will set a CSS style on the menu that can be
     used by the current theme to style the appearance of the control. This
-    value will also determine the default itemHeight, itemSeparatorHeight,
-    menuHeightPadding, and submenuOffsetX if you don't explicitly set these
+    value will also determine the default `itemHeight`, `itemSeparatorHeight`,
+    `menuHeightPadding`, and `submenuOffsetX` if you don't explicitly set these
     properties.
 
     Your theme can override the default values for each control size by specifying
     them in the `menuRenderDelegate`. For example:
 
-    {{{
         MyTheme.menuRenderDelegate = SC.BaseTheme.menuRenderDelegate.create({
           'sc-tiny-size': {
             itemHeight: 20,
@@ -114,7 +111,6 @@ SC.MenuPane = SC.PickerPane.extend(
             submenuOffsetX: 2
           }
         });
-    }}}
 
     Changing the controlSize once the menu is instantiated has no effect.
 
@@ -127,10 +123,10 @@ SC.MenuPane = SC.PickerPane.extend(
     The height of each menu item, in pixels.
 
     You can override this on a per-item basis by setting the (by default)
-    @height@ property on your object.
+    `height` property on your object.
 
     If you don't specify a value, the item height will be inferred from
-    controlSize.
+    `controlSize`.
 
     @property {Number}
     @default itemHeight from theme if present, or 20.
@@ -141,10 +137,10 @@ SC.MenuPane = SC.PickerPane.extend(
     The height of separator menu items.
 
     You can override this on a per-item basis by setting the (by default)
-    @height@ property on your object.
+    `height` property on your object.
 
     If you don't specify a value, the height of the separator menu items will
-    be inferred from controlSize.
+    be inferred from `controlSize`.
 
     @property {Number}
     @default itemSeparatorHeight from theme, or 9.
@@ -203,7 +199,7 @@ SC.MenuPane = SC.PickerPane.extend(
     The view class to use when creating new menu item views.
 
     The menu pane will automatically create an instance of the view class you
-    set here for each item in the @items@ array. You may provide your own
+    set here for each item in the `items` array. You may provide your own
     subclass for this property to display the customized content.
 
     @property {SC.View}
@@ -216,7 +212,7 @@ SC.MenuPane = SC.PickerPane.extend(
 
     When the menu pane is shown, it will remain anchored to the view you
     specify, even if the window is resized. You should specify the anchor as a
-    parameter when calling @popup()@, rather than setting it directly.
+    parameter when calling `popup()`, rather than setting it directly.
 
     @type SC.View
     @isReadOnly
@@ -224,7 +220,7 @@ SC.MenuPane = SC.PickerPane.extend(
   anchor: null,
 
   /**
-    YES if this menu pane was generated by a parent SC.MenuPane.
+    `YES` if this menu pane was generated by a parent `SC.MenuPane`.
 
     @type Boolean
     @default NO
@@ -243,7 +239,7 @@ SC.MenuPane = SC.PickerPane.extend(
   /**
     Whether or not this menu pane should accept the “current menu pane”
     designation when visible, which is the highest-priority pane when routing
-    events.  Generally you want this set to YES so that your menu pane can
+    events.  Generally you want this set to `YES` so that your menu pane can
     intercept keyboard events.
 
     @type Boolean
@@ -436,7 +432,7 @@ SC.MenuPane = SC.PickerPane.extend(
     item.
 
     The action of the menu item will be fired, and the menu pane's
-    @selectedItem@ property set to the menu item, if the user presses this
+    `selectedItem` property set to the menu item, if the user presses this
     key combination on the keyboard.
 
     @type String
@@ -461,7 +457,7 @@ SC.MenuPane = SC.PickerPane.extend(
   itemDisableMenuFlashKey: 'disableMenuFlash',
 
   /**
-    The array of keys used by SC.MenuItemView when inspecting your menu items
+    The array of keys used by `SC.MenuItemView` when inspecting your menu items
     for display properties.
 
     @private
@@ -487,9 +483,9 @@ SC.MenuPane = SC.PickerPane.extend(
   isModal: YES,
 
   /**
-    The view that contains the MenuItemViews that are visible on screen.
+    The view that contains the `MenuItemView`s that are visible on screen.
 
-    This is created and set in createChildViews.
+    This is created and set in `createChildViews`.
 
     @property SC.View
     @private
@@ -501,8 +497,8 @@ SC.MenuPane = SC.PickerPane.extend(
   //
 
   /**
-    If an itemHeight, itemSeparatorHeight, or menuHeightPadding have not been
-    explicitly set, we set them here based on the controlSize.
+    If an `itemHeight`, `itemSeparatorHeight`, or `menuHeightPadding` have not been
+    explicitly set, we set them here based on the `controlSize`.
 
     @returns {SC.MenuPane} the newly instantiated menu pane
     @private
@@ -515,8 +511,8 @@ SC.MenuPane = SC.PickerPane.extend(
   renderDelegateName: 'menuRenderDelegate',
 
   /**
-    Creates the child scroll view, and sets its contentView to a new
-    view.  This new view is saved and managed by the SC.MenuPane,
+    Creates the child scroll view, and sets its `contentView` to a new
+    view.  This new view is saved and managed by the `SC.MenuPane`,
     and contains the visible menu items.
 
     @private
@@ -543,9 +539,9 @@ SC.MenuPane = SC.PickerPane.extend(
 
   /**
     When the pane is attached to a DOM element in the window, set up the
-    view to be visible in the window and register with the RootResponder.
+    view to be visible in the window and register with the `RootResponder`.
 
-    We don't call sc_super() here because PanelPane sets the current pane to
+    We don't call `sc_super()` here because `PanelPane` sets the current pane to
     be the key pane when attached.
 
     @returns {SC.MenuPane} receiver
@@ -584,7 +580,7 @@ SC.MenuPane = SC.PickerPane.extend(
 
   /**
     Remove the menu pane status from the pane.  This will simply set the 
-    menuPane on the rootResponder to null.
+    `menuPane` on the `rootResponder` to `null.
 
     @returns {SC.Pane} receiver
   */
@@ -596,7 +592,8 @@ SC.MenuPane = SC.PickerPane.extend(
   /**
     The array of child menu item views that compose the menu.
 
-    This computed property parses @displayItems@ and constructs an SC.MenuItemView (or whatever class you have set as the @exampleView@) for every item.
+    This computed property parses `displayItems` and constructs an
+    `SC.MenuItemView` (or whatever class you have set as the `exampleView`) for every item.
 
     @property
     @type Array
@@ -708,21 +705,21 @@ SC.MenuPane = SC.PickerPane.extend(
     or an object with key-value pairs, or an exotic mish-mash of both, we need
     to normalize it for our display logic.
 
-    If an @items@ member is an object, we can assume it is formatted properly
+    If an `items` member is an object, we can assume it is formatted properly
     and leave it as-is.
 
-    If an @items@ member is a string, we create a hash with the title value
+    If an `items` member is a string, we create a hash with the title value
     set to that string, and some sensible defaults for the other properties.
 
-    As a last resort, if an @items@ member is an array, we have a legacy
+    As a last resort, if an `items` member is an array, we have a legacy
     handler that converts the array into a hash. This behavior is deprecated
     and is not guaranteed to be supported in the future.
 
     A side effect of running this computed property is that the menuHeight
     property is updated.
 
-    @displayItems@ should never be set directly; instead, set @items@ and
-    @displayItems@ will update automatically.
+    `displayItems` should never be set directly; instead, set `items` and
+    `displayItems` will update automatically.
 
     @property
     @type Array
@@ -847,7 +844,7 @@ SC.MenuPane = SC.PickerPane.extend(
 
     // Scroll to the selected menu item if it's not visible on screen.
     // This is useful for keyboard navigation and programmaticaly selecting
-    // the selected menu item, as in SelectButtonView.
+    // the selected menu item, as in `SelectButtonView`.
     if (currentMenuItem && currentMenuItem.get('isEnabled')) {
       currentMenuItem.scrollToVisible();
     }
@@ -990,7 +987,7 @@ SC.MenuPane = SC.PickerPane.extend(
     However, when the menu is part of another control, such as an
     SC.PopupButtonView, the menu should still respond if it is hidden but its
     parent control is visible. In those cases, the parameter
-    fromVisibleControl will be set to YES.
+    fromVisibleControl will be set to `YES`.
 
     @param keyEquivalent {String} the shortcut key sequence that was pressed
     @param fromVisibleControl {Boolean} if the shortcut key press was proxied
@@ -1046,7 +1043,7 @@ SC.MenuPane = SC.PickerPane.extend(
     Clear the key buffer if the user does not enter any text after a certain
     amount of time.
 
-    This is called by the timer created in the insertText method.
+    This is called by the timer created in the `insertText` method.
 
     @private
   */

data/lib/frameworks/sproutcore/frameworks/desktop/panes/modal.js

@@ -14,8 +14,8 @@
   panes.
   
   A modal pane is automatically appended when a pane with isModal set to
-  YES is made visible and removed when the same pane is hidden.  The only
-  purpose of the ModalPane is to absorb mouse events so that they cannot
+  `YES` is made visible and removed when the same pane is hidden.  The only
+  purpose of the `ModalPane` is to absorb mouse events so that they cannot
   filter through to the underlying content.
   
   @extends SC.Pane
@@ -50,7 +50,7 @@ SC.ModalPane = SC.Pane.extend(
   /** @private
     Called by a pane just after it removes itself.  The modal pane can remove
     itself if needed.   Modal panes only remove themselves when an equal 
-    number of paneWillAppend() and paneDidRemove() calls are received.
+    number of `paneWillAppend()` and `paneDidRemove()` calls are received.
   
     @param {SC.Pane} pane the pane
     @returns {SC.ModalPane} receiver

data/lib/frameworks/sproutcore/frameworks/desktop/panes/panel.js

@@ -124,7 +124,7 @@ SC.PanelPane = SC.Pane.extend(
   //
 
   /**
-    The name of the theme's SC.PanelPane render delegate.
+    The name of the theme's `SC.PanelPane` render delegate.
 
     @type String
     @default 'panelRenderDelegate'