sproutcore 1.6.0.1-java → 1.7.1.beta-java

data/lib/frameworks/sproutcore/frameworks/experimental/frameworks/scroll_view/views/core_scroller.js

@@ -0,0 +1,332 @@
+// ==========================================================================
+// 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
+
+  Displays a horizontal or vertical scroller.
+
+  You will not usually need to work with scroller views directly,
+  but you may override this class to implement your own custom scrollers.
+
+  Because the scroller uses the dimensions of its constituent elements to
+  calculate layout, you may need to override the default display metrics.
+
+  You can either create a subclass of ScrollerView with the new values, or
+  provide your own in your theme:
+
+      SC.mixin(SC.ScrollerView.prototype, {
+        scrollbarThickness: 14,
+        capLength: 18,
+        capOverlap: 14,
+        buttonOverlap: 11,
+        buttonLength: 41
+      });
+
+  You can change whether scroll buttons are displayed by setting the
+  hasButtons property.
+
+  @extends SC.View
+  @since SproutCore 1.6
+ */
+SC.CoreScrollerView = SC.View.extend(
+  /** @scope SC.CoreScrollerView.prototype */{
+
+  /**
+    @type Array
+    @default ['sc-scroller-view']
+    @see SC.View#classNames
+   */
+  classNames: ['sc-scroller-view'],
+
+  /**
+    @type Array
+    @default ['thumbPosition', 'thumbLength', 'isEnabled', 'controlsHidden', 'capLength'
+              'layoutDirection', 'hasButtons', 'value', 'controlsId', 'maximum', 'minimum']
+    @see SC.View#displayProperties
+   */
+  displayProperties: ['thumbPosition', 'thumbLength', 'isEnabled', 'controlsHidden',
+                      'layoutDirection', 'hasButtons', 'capLength',
+                      'value', 'controlsId', 'maximum', 'minimum'], // WAI-ARIA attrs
+
+  /**
+    The WAI-ARIA role for scroller view.
+
+    @type String
+    @default 'scrollbar'
+    @readOnly
+   */
+  ariaRole: 'scrollbar',
+
+  // ..........................................................
+  // PROPERTIES
+  //
+
+  /**
+    If YES, a click on the track will cause the scrollbar to scroll to that position.
+    Otherwise, a click on the track will cause a page down.
+
+    In either case, alt-clicks will perform the opposite behavior.
+
+    @type Boolean
+    @default NO
+   */
+  shouldScrollToClick: NO,
+
+  /**
+    WAI-ARIA ID to the control that this scroller is controlling.
+
+    @field
+    @type String
+   */
+  controlsIdBinding: SC.Binding.oneWay('.parentView*contentView.layerId'),
+
+  /**
+    @type Number
+    @observes value
+    @observes touchValue
+   */
+  displayValue: function () {
+    return this.get('value');
+  }.property("value").cacheable(),
+
+  /**
+    The value of the scroller.
+    The value represents the position of the scroller's thumb.
+
+    @field
+    @type Number
+    @observes maximum
+    @observes minimum
+   */
+  value: function (key, value) {
+    var minimum = this.get('minimum');
+    if (typeof value !== "undefined") {
+      this._scs_value = value;
+    }
+
+    value = this._scs_value || minimum; // default value is at top / left
+    return Math.max(Math.min(value, this.get('maximum')), minimum);
+  }.property('maximum', 'minimum').cacheable(),
+
+  /**
+    The portion of the track that the thumb should fill. Usually the
+    proportion will be the ratio of the size of the scroll view's content view
+    to the size of the scroll view.
+
+    Should be specified as a value between 0.0 (minimal size) and 1.0 (fills
+    the slot). Note that if the proportion is 1.0 then the control will be
+    disabled.
+
+    @type Number
+    @default 0.0
+   */
+  proportion: 0,
+
+  /**
+    The maximum offset value for the scroller.  This will be used to calculate
+    the internal height/width of the scroller itself.
+
+    When set less than the height of the scroller, the scroller is disabled.
+
+    @type Number
+    @default 100
+   */
+  maximum: 100,
+
+  /**
+    The minimum offset value for the scroller.  This will be used to calculate
+    the internal height/width of the scroller itself.
+
+    @type Number
+    @default 0
+   */
+  minimum: 0,
+
+  /**
+    YES to enable scrollbar, NO to disable it. Scrollbars will automatically
+    disable if the maximum scroll width does not exceed their capacity.
+
+    @field
+    @type Boolean
+    @default YES
+    @observes proportion
+   */
+  isEnabled: function (key, value) {
+    var enabled;
+    if (typeof value !== "undefined") {
+      this._scsv_isEnabled = value;
+    }
+    enabled = this._scsv_isEnabled;
+
+    return !SC.none(enabled) ? enabled : this.get('proportion') < 1;
+  }.property('proportion').cacheable(),
+
+  /** @private */
+  _scsv_isEnabled: undefined,
+
+  /**
+    Determine the layout direction.  Determines whether the scrollbar should
+    appear horizontal or vertical.  This must be set when the view is created.
+    Changing this once the view has been created will have no effect. Possible
+    values:
+
+      - SC.LAYOUT_VERTICAL
+      - SC.LAYOUT_HORIZONTAL
+
+    @type String
+    @default SC.LAYOUT_VERTICAL
+   */
+  layoutDirection: SC.LAYOUT_VERTICAL,
+
+  /**
+    Whether or not the scroller should display scroll buttons
+
+    @type Boolean
+    @default YES
+   */
+  hasButtons: YES,
+
+
+  // ..........................................................
+  // DISPLAY METRICS
+  //
+
+  /**
+    The width (if vertical scroller) or height (if horizontal scroller) of the
+    scrollbar.
+
+    @type Number
+    @default 14
+   */
+  scrollbarThickness: 14,
+
+  /**
+    Whether or not the scrollbar is translucent.
+    This effectively means you would like the scroller to be overlaid.
+
+    @type Boolean
+    @default NO
+   */
+  isTranslucent: NO,
+
+  /**
+    The width or height of the cap that encloses the track.
+
+    @type Number
+    @default 18
+   */
+  capLength: 18,
+
+  /**
+    The amount by which the thumb overlaps the cap.
+
+    @type Number
+    @default 14
+   */
+  capOverlap: 14,
+
+  /**
+    The width or height of the up/down or left/right arrow buttons. If the
+    scroller is not displaying arrows, this is the width or height of the end
+    cap.
+
+    @type Number
+    @defaut 41
+   */
+  buttonLength: 41,
+
+  /**
+    The amount by which the thumb overlaps the arrow buttons. If the scroller
+    is not displaying arrows, this is the amount by which the thumb overlaps
+    the end cap.
+
+    @type Number
+    @default 11
+   */
+  buttonOverlap: 11,
+
+  /**
+    The minimium length that the thumb will be, regardless of how much content
+    is in the scroll view.
+
+    @type Number
+    @default 20
+   */
+  minimumThumbLength: 20,
+
+  // ..........................................................
+  // SCROLLER DIMENSION COMPUTED PROPERTIES
+  //
+
+  /** @private
+    Returns the total length of the track in which the thumb sits.
+
+    The length of the track is the height or width of the scroller, less the
+    cap length and the button length. This property is used to calculate the
+    position of the thumb relative to the view.
+
+    @property
+   */
+  trackLength: function () {
+    return this.get('scrollerLength') -
+      (this.get('capLength') - this.get('capOverlap')) -      // Subtract the size of the top/left cap
+      (this.get('buttonLength') - this.get('buttonOverlap')); // Subtract the size of the scroll buttons,
+                                                              // or the end cap if they are not shown.
+  }.property('scrollerLength', 'capLength', 'capOverlap', 'buttonLength', 'buttonOverlap').cacheable(),
+
+  /** @private
+    Returns the height of the view if this is a vertical scroller or the width
+    of the view if this is a horizontal scroller. This is used when scrolling
+    up and down by page, as well as in various layout calculations.
+
+    @type Number
+   */
+  scrollerLength: function () {
+    var frame = this.get('frame'),
+        layoutDirection = this.get('layoutDirection');
+
+    return layoutDirection === SC.LAYOUT_VERTICAL ? frame.height :
+           layoutDirection === SC.LAYOUT_HORIZONTAL ? frame.width : 0;
+  }.property('frame').cacheable(),
+
+  /** @private
+    The total length of the thumb. The size of the thumb is the
+    length of the track times the content proportion.
+
+    @property
+   */
+  thumbLength: function () {
+    var length = Math.floor(this.get('trackLength') * this.get('proportion'));
+
+    return Math.max(isNaN(length) ? 0 : length, this.get('minimumThumbLength'));
+  }.property('trackLength', 'proportion', 'minimumThumbLength').cacheable(),
+
+  /** @private
+    The position of the thumb in the track.
+
+    @type Number
+    @isReadOnly
+   */
+  thumbPosition: function () {
+    var position = (this.get('displayValue') / this.get('maximum')) *
+                    (this.get('trackLength') - this.get('thumbLength')) +
+                    this.get('capLength') - this.get('capOverlap'); // account for the top / left cap
+    return Math.floor(isNaN(position) ? 0 : position);
+  }.property('displayValue', 'maximum', 'trackLength', 'thumbLength', 'capLength', 'capOverlap').cacheable(),
+
+  /** @private
+    YES if the maximum value exceeds the frame size of the scroller.  This
+    will hide the thumb and buttons.
+
+    @type Boolean
+    @isReadOnly
+   */
+  controlsHidden: function () {
+    return this.get('proportion') >= 1;
+  }.property('proportion').cacheable()
+
+});

data/lib/frameworks/sproutcore/frameworks/experimental/frameworks/scroll_view/views/desktop/scroll.js

@@ -0,0 +1,236 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+sc_require('views/core_scroll');
+sc_require('views/desktop/scroller');
+
+/** @class
+  Implements a desktop scroll view using mouse events.
+
+  This class uses native scroll events, inverting the control
+  of `horizontalScrollOffset` and `verticalScrollOffset` to
+  properly proxy the scroll offset values to and from SC.
+
+  When you set these, SC gets notified _after_ the scroll
+  offset gets set in the DOM.
+
+  Important Events:
+
+    - contentView frame size changes (to autoshow/hide scrollbar- adjust scrollbar size)
+    - horizontalScrollOffset change
+    - verticalScrollOffsetChanges
+
+  @extends SC.View
+  @since SproutCore 1.6
+*/
+SC.DesktopScrollView = SC.CoreScrollView.extend(
+  /** @scope SC.DesktopScrollView.prototype */{
+
+  /** @private
+    Adjust scrollers immediately.
+   */
+  init: function () {
+    SC.platform.propertyDidChange('scrollbarSize'); // invalidate the cache.
+    this.set('nativeScrollbarThickness', SC.platform.get('scrollbarSize'));
+    return sc_super();
+  },
+
+  /**
+    @type SC.CoreScrollerView
+    @default SC.DesktopScrollerView
+   */
+  horizontalScrollerView: SC.DesktopScrollerView,
+
+  /**
+    @type SC.CoreScrollerView
+    @default SC.DesktopScrollerView
+   */
+  verticalScrollerView: SC.DesktopScrollerView,
+
+  /**
+    Dynamically compute the renderDelegate name off of
+    the property `wantsNativeScrollbars`, which will flip
+    the render delegate between custom scrollbars and
+    native ones.
+    @field
+    @type String
+    @default scrollRenderDelegate
+   */
+  renderDelegateName: function () {
+    return this.get('wantsNativeScrollbars') ? 'nativeScrollRenderDelegate' : 'scrollRenderDelegate';
+  }.property('wantsNativeScrollbars').cacheable(),
+
+  /**
+    @type Array
+    @default ['canScrollVertical', 'canScrollHorizontal', 'nativeScrollbarThickness']
+   */
+  displayProperties: ['canScrollVertical', 'canScrollHorizontal', 'nativeScrollbarThickness'],
+
+  /**
+    The current horizontal scroll offset.
+    Changing this value will update both the `contentView`
+    and the horizontal scroller, if there is one.
+
+    @field
+    @type Number
+    @default 0
+   */
+  horizontalScrollOffset: function (key, value) {
+    if (arguments.length === 2) {
+      var minOffset = this.minimumHorizontalScrollOffset(),
+          maxOffset = this.get('maximumHorizontalScrollOffset'),
+          layer = this.getPath('containerView.layer'),
+          offset = Math.max(minOffset, Math.min(maxOffset, value));
+
+      this._scroll_horizontalScrollOffset = offset;
+      if (layer && layer.scrollLeft !== offset) {
+        layer.scrollLeft = offset;
+      }
+    }
+
+    return this._scroll_horizontalScrollOffset || 0;
+  }.property().cacheable(),
+
+  /**
+    The current vertical scroll offset.
+    Changing this value will update both the `contentView`
+    and the vertical scroller, if there is one.
+
+    @field
+    @type Number
+    @default 0
+   */
+  verticalScrollOffset: function (key, value) {
+    if (arguments.length === 2) {
+      var minOffset = this.get('minimumVerticalScrollOffset'),
+          maxOffset = this.get('maximumVerticalScrollOffset'),
+          layer = this.getPath('containerView.layer'),
+          offset = Math.max(minOffset, Math.min(maxOffset, value));
+
+      this._scroll_verticalScrollOffset = offset;
+      if (layer && layer.scrollTop !== offset) {
+        layer.scrollTop = offset;
+      }
+    }
+
+    return this._scroll_verticalScrollOffset || 0;
+  }.property().cacheable(),
+
+   /**
+    The minimum interval between scroll event before
+    it signals that scrolling is "done".
+
+    @type Number
+    @default 100
+    */
+  debounceInterval: 100,
+
+  // ..........................................................
+  // SCROLL WHEEL SUPPORT
+  //
+
+  containerView: SC.ContainerView.extend({
+
+    classNames: ['sc-scroll-container-view'],
+
+    wheelEvent: function () {
+      // Firefox emits different mousewheel events than other browsers
+      return SC.browser.mozilla ? 'DOMMouseScroll' : 'mousewheel';
+    }.property().cacheable(),
+
+    /** @private
+      Remove the "scroll" event handler for the layer.
+     */
+    willDestroyLayer: function () {
+      SC.Event.remove(this.get('layer'), 'scroll', this, this.scroll);
+      SC.Event.remove(this.get('layer'), this.get('wheelEvent'), this, this._scdsv_scrollDebounce);
+    },
+
+    /** @private
+      Attach the "scroll" event handler for the layer.
+     */
+    didCreateLayer: function () {
+      SC.Event.add(this.get('layer'), 'scroll', this, this.scroll);
+      SC.Event.add(this.get('layer'), this.get('wheelEvent'), this, this._scdsv_scrollDebounce);
+      this.get('parentView').displayDidChange();
+    },
+
+    _scdsv_scrollDebounce: function (evt) {
+      var self = this;
+      
+      if (this._debounce != null) {
+        this._debounce.invalidate();
+        this._debounce = null;
+      } else {
+        var layer = this.get('layer'),
+            scrollTop = layer.scrollTop,
+            scrollLeft = layer.scrollLeft;
+        this.get('parentView').willScroll(this.get('parentView'));
+      }
+
+      this._debounce = this.invokeLater(function() {
+        self._scdsv_scrollDidFinish();
+      }, this.getPath('parentView.debounceInterval'));
+    },
+
+    _scdsv_scrollDidFinish: function () {
+      var layer = this.get('layer'),
+          scrollTop = layer.scrollTop,
+          scrollLeft = layer.scrollLeft;
+      this.get('parentView').didScroll(this.get('parentView'));
+      this._debounce = null;
+    },
+
+    /** @private
+      Notify the container that the scroll offsets have changed.
+     */
+    scroll: function (evt) {
+      var layer = this.get('layer'),
+          scrollTop = layer.scrollTop,
+          scrollLeft = layer.scrollLeft,
+          parentView = this.get('parentView');
+
+      // I'm using `verticalScrollOffset` and `horizontalScrollOffset`
+      // as proxies for the the actual scroll offsets.
+
+      // Since we know what the offsets are (we got the event), this
+      // needs to set the cached value, and let properties know that
+      // the offset changed.
+      if (parentView._scroll_verticalScrollOffset !== scrollTop) {
+        parentView.propertyWillChange('verticalScrollOffset');
+        parentView._scroll_verticalScrollOffset = scrollTop;
+        parentView.propertyDidChange('verticalScrollOffset');
+      }
+
+      if (parentView._scroll_horizontalScrollOffset !== scrollLeft) {
+        parentView.propertyWillChange('horizontalScrollOffset');
+        parentView._scroll_horizontalScrollOffset = scrollLeft;
+        parentView.propertyDidChange('horizontalScrollOffset');
+      }
+
+      return parentView.get('canScrollHorizontal') || parentView.get('canScrollVertical');
+    }
+  }),
+
+  /**
+    The native scrollbar thickness.
+    @type Number
+    @default 15
+   */
+  nativeScrollbarThickness: 15,
+
+  /** @private
+    Check to see if the native scrollbarSize changed due to scaling on the part
+    of the browser.
+   */
+  viewDidResize: function () {
+    SC.platform.propertyDidChange('scrollbarSize'); // invalidate the cache.
+    this.set('nativeScrollbarThickness', SC.platform.get('scrollbarSize'));
+    return sc_super();
+  }
+
+});