Package com.smartgwt.client.docs

# Interface PercentSizing

public interface PercentSizing

### Canvas Percentage sizing

Canvas `width` and `height` may be set to a percentage value or `"*"` rather than an explicit pixel value. This indicates to the framework that these widgets should be sized dynamically.

Percentage sizes are resolved to pixel values as follows:

- If a canvas has a specified `percentSource`, sizing will be a percentage of the size of that widget (see also `Canvas.percentBox`).
- Otherwise, if a canvas has a `master canvas`, and `snapTo` is set for the widget, sizing will be a percentage of the size of that widget (see also `Canvas.percentBox`).
- Otherwise if this is a child of some other canvas, percentages will be based on the inner size of the `parent canvas`'s viewport. This is the available space inside the parent, taking border, scrollbars etc into account.
  If the parent has overflow set to "visible", percentage sizes are based on the inner specified size of the parent rather than the overflowed size.
- Otherwise, for top level widgets, sizing is calculated as a percentage of page size.

`Layouts` may specially interpret percentage sizes on their children, and also allow "*" as a size. See the Layout class documentation for more information.

Minimums and maximums for dynamic sizing:
Note that if a `Canvas.maxWidth` or `Canvas.minWidth` are specified (or `Canvas.maxHeight` / `Canvas.minHeight` for heights), these properties act as explicit pixel limits on the canvas' size. For example, a canvas with `Canvas.maxWidth` set to `500`, and width specified as "100%" will not render larger than 500 pixels in width even if there is more space available in the parent canvas or percentSource.

Percent sizing within overflow:"visible" parents:
If a canvas is a `child` of another canvas with `Canvas.overflow` set to "visible", percentage sizes are based on the specified size of the parent, not the drawn size. In other words - if the parent's content, or the size and position of some other child cause it to render larger than its specified size, a "100%"-sized child will not expand to fill the larger, rendered size of the parent.

The framework avoids sizing percent sized children to fit the overflowed size of their parents, as the child itself contributes to the overflowed size of the parent. If a child both drives and is driven by its parent's overflowed size unintended behaviors become very likely.
It becomes much more likely to see runaway sizing and infinite loops with this kind of pattern and, while a parent holding a child sized to its overflowed inner height or width could grow (for example, expanding its overflow to accommodate another, taller child), it would never dynamically reduce its overflow, as the percent sized child would always completely fill the drawn area.

Note that a developer could explicitly set the `Canvas.percentSource` attribute of some canvas to its parent, but this isn't recommended for the reasons described above. If you are trying to make a canvas fit to the (overflowed) viewport of its parent, it is probably appropriate to instead match the size of the sibling causing it to overflow. This could be achieved by setting `percentSource` to that sibling and setting an appropriate percentBox value. You could also consider whether a `master/peer relationship` is appropriate.

Also note that the `Layout` class supports expanding all members to match the drawn size of some `minimum breadth member`.

Developers wishing to implement some other dynamic sizing paradigm for a component based on the drawn size of other component(s) can also add custom handling to the `resized notification`.