diff --git a/apidoc/Titanium/UI/ScrollView.yml b/apidoc/Titanium/UI/ScrollView.yml index 8dc85748599..0aa9d3c4847 100644 --- a/apidoc/Titanium/UI/ScrollView.yml +++ b/apidoc/Titanium/UI/ScrollView.yml @@ -1,178 +1,273 @@ --- name: Titanium.UI.ScrollView summary: | - A Scroll View is used to create a scrollable region of content. + A view that contains a horizontally and/or vertically-scrollable region of content. description: | - Views added to the Scroll View will be scrolled based on the content size of the - Scroll View. The Scroll View is created by the method . - - If your scrollable region fits within the size of the content area the scroll view will not scroll. - - #### Android Implementation Notes - In Android, Scroll Views can only scroll in one direction, either vertical - or horizontal, but not both at the same time. Use the - property to set the scroll direction explicitly. - + Use the method to create a scroll view. + + Views added to the scroll view will be scrolled based on the size of the scrollable region of + content. If a scrollable region fits within the size of its scroll view, the view will not + scroll. + + #### Android - If the `scrollType` property is *not* set, the scroll view - attempts to deduce the scroll direction based on some of the other - properties that have been set. Specifically, if `contentWidth` and `width` - are both set and are equal to each other, or if they are both set *and* - `showVerticalScrollIndicator` is set to `true`, then the scroll direction - is set to "vertical". If `contentHeight` and `height` are both set and are - equal, or if they are both set and `showHorizontalScrollIndicator` is set - to `true`, then the scroll direction is set to "horizontal". If - `scrollType` is set, it overrides the deduced setting. + On Android, a scroll view can only scroll in one direction, either vertical or horizontal, + and not both at the same time. Hence, the property may be + used to set the scroll direction explicitly. + + If the `scrollType` property is not defined, the scroll view attempts to deduce the scroll + direction based on some of the other properties that have been set. Specifically, if + `contentWidth` and `width` are both set and are equal to each other, or if they are both set + *and* `showVerticalScrollIndicator` is set to `true`, then the scroll direction is set to + "vertical". If `contentHeight` and `height` are both set and are equal, or if they are both + set and `showHorizontalScrollIndicator` is set to `true`, then the scroll direction is set + to "horizontal". If `scrollType` is set, it overrides the deduced setting. extends: Titanium.UI.View since: "0.9" + methods: - name: scrollTo - summary: scrollTo a particular point + summary: Moves the specified coordinate of the scrollable region into the viewable area. parameters: - name: x - summary: the x point within the view + summary: X coordinate from the scrollable region's coordinate system. type: Number + - name: y - summary: the y point within the view + summary: Y coordinate from the scrollable region's coordinate system. type: Number + - name: setContentOffset - summary: Sets the value of [contentOffset](Titanium.UI.ScrollView.contentOffset) property. - description: | - In iOS, there is an additional parameter `animated` that can be used to enable or - disable the animation while scrolling the contents offset. For example: - - setContentOffset({x:50,y:100},{animated:true}) + summary: Sets the value of the [contentOffset](Titanium.UI.ScrollView.contentOffset) property. + platforms: [iphone, ipad, mobileweb] parameters: - name: contentOffset - summary: New value for the property - type: Object + summary: | + X and Y coordinates to which to reposition the top-left point of the scrollable region. + type: Dictionary + - name: animated - summary: Whether this content area change should be animated. - optional: true + summary: Determines whether the scrollable region reposition should be animated type: contentOffsetOption + optional: true + + - name: scrollToBottom + summary: Moves the bottom of the scrollable region into the viewable area. + platforms: [android] + events: - name: scale - summary: fired when the zoom scale factor changes - platforms: [android, iphone, ipad] + summary: Fired when the zoom scale factor changes. + platforms: [iphone, ipad] properties: - - name: scale - summary: the new scale as a float - - name: y - summary: Y coordinate of the event from the `source` view's coordinate system. - - name: x - summary: X coordinate of the event from the `source` view's coordinate system. - name: globalPoint - summary: a dictionary with properties x and y describing the point of the event in screen coordinates + summary: X and Y coordinates of the event from the display's coordinate system. + type: Dictionary platforms: [iphone, ipad] deprecated: since: "1.8.0" + + - name: scale + summary: New scaling factor as a float. + type: Number + - name: scroll - summary: fired when the view is scrolled + summary: Fired when the scrollable region is scrolled. properties: - - name: y - summary: Y coordinate of the event from the `source` view's coordinate system. - - name: x - summary: X coordinate of the event from the `source` view's coordinate system. + - name: decelerating + summary: Indicates whether the scroll is decelerating. + type: Boolean + platforms: [iphone, ipad] + - name: dragging - summary: boolean to indicate if the scroll is based on a dragging gesture + summary: | + Indicates whether the event was fired during a dragging gesture, where the touch + remained in contact with the display to physically drag the view, as opposed to it being + the result of scrolling momentum. + type: Boolean platforms: [iphone, ipad, mobileweb] + - name: globalPoint - summary: a dictionary with properties x and y describing the point of the event in screen coordinates + summary: X and Y coordinates of the event from the display's coordinate system. + type: Dictionary platforms: [iphone, ipad] deprecated: since: "1.8.0" - - name: decelerating - summary: boolean to indicate if the scroll is decelerating - platforms: [iphone, ipad] + + - name: x + summary: X coordinate of the event from the `source` view's coordinate system. + type: Number + + - name: y + summary: Y coordinate of the event from the `source` view's coordinate system. + type: Number + - name: dragStart - summary: fired when the scroll view is about to start scrolling the content. + summary: Fired when the scrollable region starts being dragged. + description: | + A dragging gesture is when a touch remains in contact with the display to physically drag + the view, as opposed to it being the result of scrolling momentum. platforms: [iphone, ipad, mobileweb] + - name: dragEnd - summary: fired when when dragging ended in the scroll view. + summary: Fired when the scrollable region stops being dragged. + description: | + A dragging gesture is when a touch remains in contact with the display to physically drag + the view, as opposed to it being the result of scrolling momentum. platforms: [iphone, ipad, mobileweb] properties: - name: decelerate - summary: boolean. YES if the scrolling movement will continue, but decelerate, after a touch-up gesture during a dragging operation. If the value is NO, scrolling stops immediately upon touch-up. + summary: | + Indicates whether scrolling will continue but decelerate, now that the drag gesture has + been released by the touch. If `false`, scrolling will stop immediately. + type: Boolean properties: - - name: canCancelEvents - summary: boolean to indicate if the scroll view can cancel subview touches in order to scroll instead. Default of true - type: Boolean - platforms: [iphone, ipad] - name: contentHeight - summary: the height of the scrollable area - type: Number + summary: Height of the scrollable region. + description: | + While `auto` and absolute dimensions are supported, relative values, such as those provided + in percentages, are not. + type: [Number, String] + - name: contentOffset - summary: an object (with x and y properties) to indicate the offset of the content area - type: Object + summary: | + X and Y coordinates to which to reposition the top-left point of the scrollable region. + type: Dictionary + description: | + On iOS, a new value causes the scroll view to perform an animated scroll to the new offset. + The method can be used to prevent this animation. + - name: contentWidth - summary: the width of the scrollable area - type: Number + summary: Width of the scrollable region. + description: | + While `auto` and absolute dimensions are supported, relative values, such as those provided + in percentages, are not. + type: [Number, String] + - name: disableBounce - summary: disable view bouncing. + summary: Determines whether scroll bounce of the scrollable region is enabled. + description: | + Set to `true` to disable horizontal and vertical bounce. + + This property takes precedence over the `horizontalBounce` and `verticalBounce` properties. type: Boolean + default: false platforms: [iphone, ipad] + - name: horizontalBounce - summary: boolean to control the horizontal bounce during scrolling + summary: Determines whether horizontal scroll bounce of the scrollable region is enabled. + description: | + With the default value of `true`, dragging in the horizontal direction is always allowed and + also bounces. + + Set to `false` to disable horizontal scroll bounce if the horizontal content is smaller than + the scroll view bounds. However, larger content will still bounce when scrolled. + + Note that the `disableBounce` property takes precedence over the `horizontalBounce` and + `verticalBounce` properties. type: Boolean + default: true platforms: [iphone, ipad] + - name: maxZoomScale - summary: the maximum scale of the content + summary: Maximum scaling factor of the scrollable region and its content. type: Number platforms: [iphone, ipad] + - name: minZoomScale - summary: the minimum scale of the content + summary: Minimum scaling factor of the scrollable region and its content. type: Number platforms: [iphone, ipad] + - name: scrollType summary: | - For explicitly setting the direction -- "vertical" or "horizontal" -- in which the ScrollView will scroll. - See also the documentation notes for more information concerning how Android deduces the scroll - direction when this property is *not* set. + Limits the direction of the scrollable region, overriding the deduced setting. Set to + `horizontal` or `vertical`. + description: | + See the [scrollView](Titanium.UI.ScrollView) description for more details about how the + scroll direction is deduced when this property is not defined. type: String + availability: creation platforms: [android] + - name: showHorizontalScrollIndicator - summary: boolean to indicate whether the horizontal scroll indicator is visible + summary: Determines whether the horizontal scroll indicator is visible. + description: Set to `true` to show the horizontal scroll indicator. type: Boolean + default: false + - name: showVerticalScrollIndicator - summary: boolean to indicate whether the vertical scroll indicator is visible + summary: Determines whether the vertical scroll indicator is visible. + description: Set to `true` to show the vertical scroll indicator. type: Boolean + default: false + - name: verticalBounce - summary: boolean to control the vertical bounce during scrolling + summary: Determines whether vertical scroll bounce of the scrollable region is enabled. + description: | + With the default value of `true`, dragging in the vertical direction is always allowed and + also bounces. + + Set to `false` to disable vertical scroll bounce if the vertical content is smaller than + the scroll view bounds. However, larger content will still bounce when scrolled. + + Note that the `disableBounce` property takes precedence over the `horizontalBounce` and + `verticalBounce` properties. type: Boolean + default: true platforms: [iphone, ipad] + - name: zoomScale - summary: set the zoom scale for the current content area + summary: Scaling factor of the scrollable region and its content. type: Number + default: 1 platforms: [iphone, ipad] examples: - title: Simple Scroll View example: | Create a scroll view with content. - var scrollView = Titanium.UI.createScrollView({ - contentWidth:'auto', - contentHeight:'auto', - top:0, - showVerticalScrollIndicator:true, - showHorizontalScrollIndicator:true + var win = Ti.UI.createWindow({ + backgroundColor: 'white', + exitOnClose: true, + fullscreen: false, + title: 'ScrollView Demo' + }); + + var scrollView = Ti.UI.createScrollView({ + contentWidth: 'auto', + contentHeight: 'auto', + showVerticalScrollIndicator: true, + showHorizontalScrollIndicator: true, + height: '80%', + width: '80%' }); var view = Ti.UI.createView({ - backgroundColor:'#336699', - borderRadius:10, - width:300, - height:2000, - top:10 + backgroundColor:'#336699', + borderRadius: 10, + top: 10, + height: 2000, + width: 1000 }); scrollView.add(view); - Titanium.UI.currentWindow.add(scrollView); + win.add(scrollView); + win.open(); --- name: contentOffsetOption summary: Optional parameter for [setContentOffset](Titanium.UI.ScrollView.setContentOffset) method. +description: | + On iOS, the optional parameter `animated` to enable the animation while the scrollable region + scrolls. For example + + setContentOffset({x:50,y:100}, {animated:true}) +optional: true since: 1.8.1 platforms: [iphone, ipad] + properties: - name: animated - summary: Boolean to indicate whether the scrollview's content area change is animated. + summary: Determines whether the scroll view's content area change is animated. type: Boolean +