TIDOC-597 APIDoc: Make ScrollableView docs more consistent #2278

Merged
merged 6 commits into from Jun 1, 2012

Projects

None yet

5 participants

@hal-gh

Would someone clarify what is the purpose of this property? I can't make sense of it from this summary or description.

Collaborator

So, this is a little long and windy, so hang on and it'll all make sense.

We currently support a property, "clipViews", which lets you show the edges of the child views which appear outside of the scrollableview proper. So, to support proper swipe actions for changing pages, you would want to set the actual size of the scrollableview to less than the full width of the window (so the other views can be seen), set clipViews to false, and set hitRect to the full width of the window, so swipe actions work as expected.

@arthurevans arthurevans and 1 other commented on an outdated diff May 25, 2012
apidoc/Titanium/UI/ScrollableView.yml
horizontal swipe gestures.
description: |
Use the <Titanium.UI.createScrollableView> method to create a scrollable view.
-
- ScrollableView supports a visual paging control that may be enabled to indicate on-screen that
- a view is visible.
+
+ ScrollableView supports an on-screen visual paging control that appears on the left and right
+ of the view to indicate whether a previous or next child view exists.
@arthurevans
arthurevans May 25, 2012 Contributor

Maybe:

ScrollableView supports an on-screen paging control to indicate whether a previous or next child view exists. On iOS, the paging control appears as small dots on the bottom of the screen. Android displays arrows on the left and right sides of the screen when the paging control is enabled.

@hal-gh
hal-gh May 29, 2012 Contributor

Much better - thanks. Updated.

@hal-gh
Contributor
hal-gh commented May 29, 2012

Updated. Please review.
Arthur, can you check hitRect to see if I have understood it correctly? Thanks

@dizzymonkey dizzymonkey and 2 others commented on an outdated diff May 29, 2012
apidoc/Titanium/UI/ScrollableView.yml
@@ -1,30 +1,32 @@
---
name: Titanium.UI.ScrollableView
summary: |
- A view that encapsulates a horizontally-scrolling set of sub-views, navigable using its built-in
- horizontal swipe gestures.
+ A view that encapsulates a horizontally-scrolling set of child views, navigable using its
@dizzymonkey
dizzymonkey May 29, 2012 Contributor

It might be better to call out that the child views represent "pages" as further API points below use the term "page". I would argue that we should maintain consistent naming and stick with "page" throughout the documentation once the definition of what a "page" is defined.

@hal-gh
hal-gh May 29, 2012 Contributor

Are you certain that the term, "page", sounds correct? Web pages come to mind, when I think of a page. I am happy to change it but to me it sounds quite out of place, and does not seem relevant to mobile apps.

As it stands, all the references to "page" have been replaced with "child view", except for argument names.

@arthurevans
arthurevans May 29, 2012 Contributor

I think it's OK here. The control displays discrete pages of content, as opposed to a scroll view, which you can move pixel-by-pixel or line-by-line. And it's got a paging control, which we can't really rename because it's in a bunch of properties. So as Opie says, maybe just describe in the intro how the control arranges a series of child views as discrete pages.

@hal-gh
hal-gh May 30, 2012 Contributor

Fixed in next update.

@dizzymonkey dizzymonkey and 1 other commented on an outdated diff May 29, 2012
apidoc/Titanium/UI/ScrollableView.yml
values (i.e. cacheSize=4 renders 3 views into the cache.) Keep in mind that improved
performance (larger cache) will lead to faster performance, but greater memory usage.
type: Number
platforms: [iphone,ipad]
- name: currentPage
- summary: Index of the active page.
+ summary: Index of the active child view.
@dizzymonkey
dizzymonkey May 29, 2012 Contributor

example of disconnect between "page" terminology versus "child view"

@hal-gh
hal-gh May 30, 2012 Contributor

Fixed in next update.

@dizzymonkey
Contributor

Reviewed and feedback left.

@nebrius nebrius and 1 other commented on an outdated diff May 29, 2012
apidoc/Titanium/UI/ScrollableView.yml
description: |
Use the <Titanium.UI.createScrollableView> method to create a scrollable view.
-
- ScrollableView supports a visual paging control that may be enabled to indicate on-screen that
- a view is visible.
+
+ ScrollableView supports an on-screen paging control to indicate whether a previous or next child
@nebrius
nebrius May 29, 2012 Contributor

Mobile Web's paging control looks like iOS's paging control.

@hal-gh
hal-gh May 30, 2012 Contributor

Fixed in next update

@nebrius nebrius and 1 other commented on an outdated diff May 29, 2012
apidoc/Titanium/UI/ScrollableView.yml
description: |
- On Android, does nothing if the view does not exist in <Titanium.UI.ScrollableView.views>.
+ On Android, does nothing if the view does not exist in <Titanium.UI.ScrollableView.views>.
@nebrius
nebrius May 29, 2012 Contributor

Mobile Web does nothing.

@hal-gh
hal-gh May 30, 2012 Contributor

Fixed in next update

@vishalduggal vishalduggal and 1 other commented on an outdated diff May 29, 2012
apidoc/Titanium/UI/ScrollableView.yml
description: |
Use the <Titanium.UI.createScrollableView> method to create a scrollable view.
-
- ScrollableView supports a visual paging control that may be enabled to indicate on-screen that
- a view is visible.
+
+ ScrollableView supports an on-screen paging control to indicate whether a previous or next child
+ view exists. When the paging control is enabled on iOS, it appears as small dots on the bottom
+ of the screen, whereas Android displays arrows on the left and right-hand sides.
@vishalduggal
vishalduggal May 29, 2012 Contributor

Not strictly true. IOS allows for customization on the placement of paging control. See pagingControlOnTop, pagingControlAlpha and overlayEnabled on how to customize the paging control on IOS

@hal-gh
hal-gh May 30, 2012 Contributor

Fixed in next update

@hal-gh
Contributor
hal-gh commented May 30, 2012

Updated. Please review.

@dizzymonkey
Contributor

Code reviewed, validate and docgen passed. Accepted

@vishalduggal

Typo When the paging control is enabled **or** iOS on Mobile Web,

Owner

Thanks - fixed in next update.

@vishalduggal
Contributor

Small typo otherwise looks good.

@vishalduggal vishalduggal commented on an outdated diff May 30, 2012
apidoc/Titanium/UI/ScrollableView.yml
- Only the `scroll` event exists on Android. To support those that are missing, event listeners
- may be added to its child views.
+ The `ScrollableView` supports an on-screen paging control to indicate whether a previous or next
+ page exists. When the paging control is enabled on iOS on Mobile Web, it appears by default as
@vishalduggal
vishalduggal May 30, 2012 Contributor

Typo When the paging control is enabled on iOS or Mobile Web,

@hal-gh
Contributor
hal-gh commented May 31, 2012

Updated. Please review.

@vishalduggal
Contributor

Don't see a commit for the update

@hal-gh
Contributor
hal-gh commented May 31, 2012

Neither do I, but I have definitely pushed and git says that the branch is up to date.
Someone in the #git channel said that there may be something wrong with github's web UI today. I will check this again tomorrow.

@arthurevans
Contributor

Commit seems to be showing up now.

@hal-gh
Contributor
hal-gh commented May 31, 2012

So strange. I see it now.
OK, please review ;)

@vishalduggal
Contributor

Reviewed for IOS. ACCEPTED

@nebrius
Contributor
nebrius commented Jun 1, 2012

Docs reviewed for Mobile Web. Request accepted.

@dizzymonkey
Contributor

Update reviewed and Accepted

@dizzymonkey dizzymonkey merged commit ac0b176 into appcelerator:master Jun 1, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment