Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[TIDOC-414] [TIDOC-120] [TIDOC-245] [TIDOC-188] APIDoc: UI.ScrollView rewrite #1515

Merged
merged 6 commits into from Mar 7, 2012
Merged

[TIDOC-414] [TIDOC-120] [TIDOC-245] [TIDOC-188] APIDoc: UI.ScrollView rewrite #1515

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0e9b173
[TIDOC-414] [TIDOC-120] [TIDOC-245] [TIDOC-188] APIDoc: UI.ScrollView…
hal-gh Feb 25, 2012
9a4eecd
Merge branch 'master' of git://github.com/appcelerator/titanium_mobil…
hal-gh Mar 2, 2012
4152d83
[TIDOC-414] [TIDOC-120] [TIDOC-245] [TIDOC-188] APIDoc: UI.ScrollView…
hal-gh Mar 2, 2012
c9c5196
Merge branch 'master' of git://github.com/appcelerator/titanium_mobil…
hal-gh Mar 6, 2012
625b0d7
[TIDOC-414] [TIDOC-120] [TIDOC-245] [TIDOC-188] APIDoc: UI.ScrollView…
hal-gh Mar 6, 2012
061b99b
[TIDOC-414] [TIDOC-120] [TIDOC-245] [TIDOC-188] APIDoc: UI.ScrollView…
hal-gh Mar 6, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
273 changes: 184 additions & 89 deletions apidoc/Titanium/UI/ScrollView.yml
View file
Open in desktop
@@ -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 <Titanium.UI.createScrollView>.

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 <Titanium.UI.ScrollView.scrollType>
property to set the scroll direction explicitly.

Use the <Titanium.UI.createScrollView> 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 <Titanium.UI.ScrollView.scrollType> 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Android does not have setContentOffset. However, there is a scrollToBottom() method.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in next update.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

x & y should not be removed. This still exists in android.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ignore this comment, didn't see it below.

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 <Titanium.UI.ScrollView.setContentOffset> 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