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-557] Fixed description of horizontal layout. #2110

Merged
merged 6 commits into from May 10, 2012
Merged

[TIDOC-557] Fixed description of horizontal layout. #2110

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b8b8a10
[TIDOC-557] Fixed description of horizontal layout, and updated sever…
May 1, 2012
dd03086
Merge branch 'master' of git://github.com/appcelerator/titanium_mobil…
May 3, 2012
4040371
[TIDOC-557] Updated to address review comments.
May 4, 2012
90da0a3
[TIDOC-557] Updated to address review comments.
May 4, 2012
13819f7
[TIDOC-557] Rewrote layout stuff based on Bryan's comments.
May 4, 2012
d3d26f7
[TIDOC-557] Fixed typos.
May 10, 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
133 changes: 76 additions & 57 deletions apidoc/Titanium/UI/View.yml
View file
Open in desktop
Expand Up @@ -150,16 +150,11 @@ methods:
so on are not changed--these reflect the original values set by the user, not
the actual position of the view.

In this release, the view's actual position is not available to the application.
This feature will be added to a future release.
The [rect](Titanium.UI.View.rect) property can be used to determine the actual
position of the view. Note that on Mobile Web, the `rect` property is not updated
after animation. This is a known issue
[TIMOB-8930](https://jira.appcelerator.org/browse/TIMOB-8930).

If you need one or more of the layout properties to be updated after animation,
you can update them in the callback after animation is complete. For example:

var newTop = view1.top - 100;
view1.animate({ top: newTop, duration: 500 }, function () {
view.top = newTop;
});
parameters:
- name: obj
summary: |
Expand Down Expand Up @@ -764,7 +759,7 @@ properties:
description: |
This position is relative to the view's parent. Exact interpretation depends on the
parent view's [layout](Titanium.UI.View.layout) property. Can be either a float value or
a dimension string (for example, '50%' or 'auto').
a dimension string (for example, '50%' or '10px').

This is an input property for specifying where the view should be positioned, and does not
represent the view's calculated position.
Expand All @@ -791,18 +786,26 @@ properties:
- name: height
summary: View height, in platform-specific units.
description: |
Can be either a float value or a dimension string (for example, '50%' or 'auto').
Can be either a float value or a dimension string (for example, '50%' or '40dp').
Can also be one of the following special values:

* <Titanium.UI.SIZE>. The view should size itself to fit its contents.
* <Titanium.UI.FILL>. The view should size itself to fill its parent.
* 'auto'. Represents the default sizing behavior for a given type of
Copy link
Contributor

Choose a reason for hiding this comment

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

This isn't exactly true in mobile web. For us, "auto" == Ti.UI.SIZE, meaning auto will always fit to its contents

view. The use of 'auto' is deprecated, and should be replaced with the `SIZE` or
`FILL` constants if it is necessary to set the view's behavior explicitly.

This is an input property for specifying the view's height dimension. To determine the view's
size once rendered, see the [size](Titanium.UI.View.size) property.
size once rendered, use the [rect](Titanium.UI.View.rect) or
[size](Titanium.UI.View.size) properties.
Copy link
Contributor

Choose a reason for hiding this comment

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

Too many descriptors for rect property in the doc. For rect we have frame, size and position at various places.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Well, it's the bounding box, which is size + position. But I don't know what 'frame' means, so I'll remove that.

type: [Number,String]

- name: left
summary: View's left position, in platform-specific units.
description: |
This position is relative to the view's parent. Exact interpretation depends on the
parent view's [layout](Titanium.UI.View.layout) property. Can be either a float value or
a dimension string (for example, '50%' or 'auto').
a dimension string (for example, '50%' or '10px').

This is an input property for specifying where the view should be positioned, and does not
represent the view's calculated position.
Expand All @@ -812,43 +815,61 @@ properties:
type: String
summary: |
Specifies how the view positions its children.
One of: 'absolute', 'vertical', or 'horizontal'.
One of: 'composite', 'vertical', or 'horizontal'.
description: |
There are three layout options:

* `absolute`. Default layout. A child view's `top`, `bottom`, `left`, and `right`
properties are interpreted as absolute values in the parent's coordinate space.
* `composite` (or `absolute`). Default layout. A child view is positioned based
on its positioning properties or "pins" (`top`, `bottom`, `left`, `right`
and `center`). If no positioning properties are specified, the child is
centered.

If the child includes a `top` value and **not** a `bottom` value, the child is
positioned `top` units from the top of the parent's bounding box, and its height
is set based on its `height` property.
For vertical positioning, the positioning properties are used as follows:

If the child includes a `bottom` value and **not** a `top` value, the child is
positioned `bottom` units from the bottom of the parent's bounding box. Its height
is set based on its `height` property.
If the child includes a `top` value, the child is positioned `top` units from
the top of the parent's bounding box.

If the child includes both `top` and `bottom` values, the behavior is
platform-specific.

Similar calculations are used for `left` and `right`.
If the child includes a `center.y` value but not a `top` value, the child is
Copy link
Contributor

Choose a reason for hiding this comment

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

Not necessarily true...if height is not specified, then the height is calculated from these two values (as mentioned below), but the center does end up at center.y

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmm... Yes, I can see how all of the precedence stuff makes this rather confusing. Let me think about this one.

Copy link
Contributor

Choose a reason for hiding this comment

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

Actually, a child can be declared this way:

top = 10
center.y = 20

This will cause the top to be at 10, the center to be at 20, and the height to be 20 (i.e. height is inferred from these two pins). Of course this assumes that height is not defined, otherwise center is ignored.

Here are the combinations used for calculating height and top, in precedence order:

height+top
height+center
height+bottom
top+center (height inferred)
top+bottom (height inferred)
top+default height
center+bottom (height inferred)
center+default height
bottom+default height
default top+default height

default height is the classic "auto" height (mobile web supports default height properly, just not the "auto" value to set the default height)
default top is center in composite layouts

Width/left is calculated the same way in composite layouts

If anything else is defined in a pair, it is ignored. Each pair assumes that the previous pair isn't valid (i.e. one of the two is undefined).

positioned so that its vertical center is at `center.y` in the parent's
coordinate space.

You can also position a child by setting its `center` property to a <Point>.
If the child includes a `bottom` value but not a `top` or `center.y` value,
the child is positioned `bottom` units from the bottom of the parent's
bounding box.

If none of the vertical positioning properties are set, the child is centered
vertically within the parent's bounding box.

Horizontal positioning works like vertical positioning, except that the
precedence is `left`, `center.x`, `right`.

If no position is set explicitly, children are centered. For example, if a
child specifies a `top` of 20 and does not specify any other position properties,
the child is positioned 20 units from the parent's top, and centered horizontally.

If the `height` and `width` properties are set, the set values are used. If
Copy link
Contributor

Choose a reason for hiding this comment

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

I feel like this should maybe go up higher. My previous comment was based on not seeing this information. Width/Height always take precedence over positions, so I think that should be made clear before talking about positions.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The problem is that this is in a discussion of layouts, and for the most part, the layout types don't affect the sizing logic, only the positioning. (Except in horizontal layout on Mobile Web, I guess).

Copy link
Contributor

Choose a reason for hiding this comment

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

Hmmm...this may be a parity issue because that is not my understanding of layouts. Here is my understanding and how mobile web is implemented:

Composite layouts: all 5 positions can infer size
Vertical layouts: left, center.x, and right can infer width, but top and bottom only affect padding (center.y is unsupported) and so can not infer height
Horizontal layouts: no positions can infer size.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmm... OK, I'm going to take another crack at this based on your list and see if that's easier to follow.

the child's height or width is not specified explicitly, it may be calculated
implicitly from the positioning properties. For example, if both `left` and
`center.x` are specified, they can be used to calculate the width of the child
control.

For complete details on composite layout rules, see
[Transitioning to the New UI Layout System](http://docs.appcelerator.com/titanium/2.0/index.html#!/guide/Transitioning_to_the_New_UI_Layout_System)
in the Titanium Mobile Guides.

* `vertical`. Children are laid out vertically from top to bottom. The first child
is laid out `top` units from its parent's bounding box. Each subsequent child is
laid out below the previous child. The space between children is equal to the
upper child's `bottom` value plus the lower child's `top` value.

Each child is positioned horizontally as for the absolute layout mode.
Each child is positioned horizontally as in the composite layout mode.

* `horizontal`. Like vertical layout, except children are laid out horizontally
from left to right, using the `left` and `right` values to determine spacing.
* `horizontal`. Somewhat like the vertical layout, except children are laid out horizontally
from left to right, _in rows_. If a child requires more horizontal space than
exists in the current row, it is wrapped to a new row. The height of each row
is equal to the maximum height of the children in that row.

Each child is positioned vertically as in the absolute layout mode.
Each child is positioned vertically _within its row_ as in the absolute layout mode.
Copy link
Contributor

Choose a reason for hiding this comment

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

It might be worth mentioning that rows act as if they are SIZE height.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Isn't that the same as what the previous line says (that is, that the height of the row corresponds to the maximum height of the children)?

Copy link
Contributor

Choose a reason for hiding this comment

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

OK I'm embarrassed now :). yes you are correct.

Copy link
Contributor

Choose a reason for hiding this comment

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

This section specifically describes the IOS behavior. I am not sure Android follows the same behavior.
On IOS when the layout parameter is specified as horizontal children are placed starting from the top left corner irrespective of whether a top parameter is specified. Android on the other hand will start placing them at the center if no top is specified. Also am not sure if Android actually wraps the views as the documentation states. Will verify and update the PR with findings.

Copy link
Contributor

Choose a reason for hiding this comment

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

On Mobile Web, the current implementation does not wrap children, and if the children take up more space than the parent, then the children are clipped. This is about to change, however. PR #2067 includes a new horizontal layout algorithm that matches (in theory) iOS.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Android does wrap the views, but as you said, it starts placing them in the center. In addition, it doesn't treat 'top' and 'bottom' the way iOS does--iOS treats 'top' and 'bottom' relative to the row, while Android uses absolute 'top' and 'bottom' values. So if you specify top or bottom on Android and the views are wrapped, the 'top' or 'bottom' values move the views out of their rows and you have complete pandemonium.

If Mobile Web is moving to follow iOS, seems like Android should follow suit, so filed this as: https://jira.appcelerator.org/browse/TIMOB-8980.

default: absolute layout

- name: opacity
Expand All @@ -861,7 +882,7 @@ properties:
description: |
This position is relative to the view's parent. Exact interpretation depends on the
parent view's [layout](Titanium.UI.View.layout) property. Can be either a float value or
a dimension string (for example, '50%' or 'auto').
a dimension string (for example, '50%' or '10px').

This is an input property for specifying where the view should be positioned, and does not
represent the view's calculated position.
Expand All @@ -880,8 +901,11 @@ properties:

- name: size
summary: |
The bounds of the view in system units. x and y properties are always 0.
The size of the view in system units. x and y properties are always 0.
description: |
To find the position of the view, use the [rect](Titanium.UI.View.rect) property
instead.

The correct values will only be available when layout is complete.
To determine when layout is complete, add a listener for the
[postlayout](Titanium.UI.View.postlayout) event.
Expand All @@ -902,7 +926,7 @@ properties:
description: |
This position is relative to the view's parent. Exact interpretation depends on the
parent view's [layout](Titanium.UI.View.layout) property. Can be either a float value or
a dimension string (for example, '50%' or 'auto').
a dimension string (for example, '50%' or '10px').

This is an input property for specifying where the view should be positioned, and does not
represent the view's calculated position.
Expand All @@ -927,11 +951,19 @@ properties:
- name: width
summary: View's width, in platform-specific units.
description: |
Can be either a float value or a dimension string (for example, '50%' or 'auto').
Can be either a float value or a dimension string (for example, '50%' or '40dp').
Can also be one of the following special values:

* <Titanium.UI.SIZE>. The view should size itself to fit its contents.
* <Titanium.UI.FILL>. The view should size itself to fill its parent.
* 'auto'. Represents the default sizing behavior for a given type of
view. The use of 'auto' is deprecated, and should be replaced with the `SIZE` or
`FILL` constants if it is necessary to set the view's behavior explicitly.

This is an input property for specifying the view's width dimension. To determine the view's
size once rendered, use the [rect](Titanium.UI.View.rect) or
[size](Titanium.UI.View.size) properties.

This is an input property for specifying the view's width dimension. To
determine the view's size once rendered, see the
[size](Titanium.UI.View.size) property.
type: [Number,String]

- name: zIndex
Expand Down Expand Up @@ -1026,30 +1058,17 @@ properties:
- name: offset
summary: Offset of this color in the gradient, from 0 (start) to 1 (end).
type: Number
---
name: Rect
summary: A simple object consisting of measurements defined relative to the view's parent.
since: "2.0.0"
properties:
- name: top
summary: Top boundary of this Rect relative to parent's height.
type: Number
- name: left
summary: Right boundary of this Rect relative to parent's' width measured from the right boundary of parent.
type: Number
- name: right
summary: Color value at this point in the gradient.
type: Number
- name: bottom
summary: Bottom boundary of this Rect relative to parents height measured from the bottom boundary of parent.
type: Number

---
name: Dimension
summary: A simple object consisting of the position and size measurements.
since: "2.0.0"
description: |
The value of x and y positions will both be 0 when returned by the size property. When a dimension is
returned by the rect property, x will return the left position, and y will return the top position.
When a dimension is
returned by the [rect](Titanium.UI.View.rect) property, `x` represents the view's left position,
and `y` represents the view's top position.
The [size](Titanium.UI.View.size) property returns a dimension object with `x` and `y`
both set to 0.
properties:
- name: x
summary: The x-axis coordinate of the position.
Expand Down