Skip to main content
  1. Index

Sizing GraphObjects

The size of a GraphObject is determined by the values of the GraphObject.desiredSize, GraphObject.minSize, GraphObject.maxSize and GraphObject.stretch properties. The actual size of an object after its containing panel measures and arranges it is given by several read-only properties: GraphObject.naturalBounds, GraphObject.measuredBounds, and GraphObject.actualBounds.

Setting GraphObject.width and GraphObject.height is exactly the same as setting GraphObject.desiredSize; the GraphObject height and width properties correspond to the Size.width and Size.height components of the GraphObject.desiredSize. The default value of GraphObject.desiredSize is (NaN, NaN) -- meaning that the size must be computed. One can set the width to a real number and leave the height to be NaN, or vice-versa.

Users can also change the size of an object within a Part via the ResizingTool: ResizingTool learn page.

desiredSize, minSize, and maxSize

When the GraphObject.desiredSize property is not set to NaN, the value of the desiredSize property becomes the GraphObject's natural size. When the desiredSize property is not set but there is a GraphObject.stretch value, it will get the size of the available space. When desiredSize is not set and there is no stretch, an object prefers being its natural size, based on the type of object that it is and the other properties that it has.

But the effective width and effective height, whether given by desiredSize or computed, are each constrained by the GraphObject.maxSize and by the GraphObject.minSize. The minimum size takes precedence over the maximum size in case of conflict. For example, if the min width is 100 and max is 50, the effective width will be 100.

The size for a GraphObject in a Table Panel may also be constrained by the width of the column and the height of the row that the object is in.

By resizing the boxes and changing the GraphObject.stretch property in the sample below, you can get a feel for how sizing is computed with GraphObjects. The light purple box is the actual size of the object after applying these properties. There will be more about stretching in the Stretching of GraphObjects section of this page, but note that the stretch property only has an effect when there is no desiredSize.

Stretching of GraphObjects

When you specify a GraphObject.stretch value other than Stretch.None, the object will stretch or contract to fill the available space. However, the GraphObject.maxSize and GraphObject.minSize properties still limit the size.

But setting the GraphObject.desiredSize (or equivalently, the GraphObject.width and/or GraphObject.height) will cause any stretch value to be ignored.

In the following examples the left column is constrained to have a width of 200.

To summarize, the order of precedence is:

  • GraphObject.minSize: No matter what, the GraphObject's size cannot be smaller than minSize. If minSize is greater than maxSize, minSize takes precedence. If minSize is greater than desiredSize, minSize takes precedence.
  • GraphObject.maxSize: Unless minSize is greater than maxSize, the GraphObject's size cannot be greater than maxSize. If maxSize is smaller than desiredSize, the size will be constrained to maxSize. If there is a stretch value but maxSize is smaller than the container to stretch to, the size will be constrained to maxSize.
  • GraphObject.desiredSize: desiredSize will be the object's size unless it conflicts with minSize or maxSize. If desiredSize is set to a real number (not NaN), any GraphObject.stretch is ignored. The desiredSize takes precedence over any stretch values.
  • GraphObject.stretch: The size will stretch to the container, provided that minSize is not greater than the container's size and maxSize is not smaller than the container's size. Stretch values are entirely ignored when desiredSize/width/height is set to a real number.
The width values are constrained independently of the height values. For example, if desiredSize is set to (50, NaN) and stretch is set to Stretch.Fill, the size will be constrained to 50 in width, but will stretch to fit the height of the container.

Stretch and alignment

The size of a GraphObject in a Panel is determined by many factors. The GraphObject.stretch property specifies whether the width and/or height should take up all of the space given to it by the Panel. When the width and/or height is not stretched to fill the given space, the GraphObject.alignment property controls where the object is placed if it is smaller than available space. One may also stretch the width while aligning vertically, just as one may also stretch vertically while aligning along the X axis.

The alignment value for a GraphObject, if not given by the value of GraphObject.alignment, may be inherited. If the object is in a Table Panel, the value may inherit from the RowColumnDefinitions of the row and of the column that the object is in. Finally the value may be inherited from the Panel.defaultAlignment property.

If you specify a fill stretch (horizontal or vertical or both) and an alignment, the alignment will be ignored. Basically if an object is exactly the size that is available to it, there is only one position for it, so all alignments are the same.

Alignment of Shapes

When the element is larger than the available space, the GraphObject.alignment property still controls where the element is positioned. However, the element will be clipped to fit.

To make things clearer, we have made the shape stroke thicker in the following example.

Measured and actual sizes

Every GraphObject also has a GraphObject.measuredBounds, which describes how big the object seems to be, and a GraphObject.actualBounds, which describes the position and size of an object. These read-only properties take into account any non-zero GraphObject.angle or non-unitary GraphObject.scale. These measurements are in the containing Panel's coordinate system.

Note that the size of the regular, not scaled, shape is 52x52. The additional size is due to the thickness of the pen (Shape.strokeWidth) used to outline the shape. Rotating or increasing the scale causes the 50x50 shape to actually take up significantly more space.

To summarize: the GraphObject.desiredSize (a.k.a. GraphObject.width and GraphObject.height) and the GraphObject.naturalBounds are in the object's local coordinate system. The GraphObject.minSize, GraphObject.maxSize, GraphObject.margin, GraphObject.measuredBounds, and GraphObject.actualBounds are all in the containing Panel's coordinate system, or in document coordinates if there is no such panel because it is a Part.

  • GraphObject.naturalBounds: Size is determined only by minSize, maxSize, desiredSize and stretch. Position is always (0, 0).
  • GraphObject.measuredBounds: Size is determined by naturalBounds and taking into account angle and scale. Position takes into account angle and strokeWidth. It will be (0, 0) if the object's angle is 0 or a multiple of 90, and the strokeWidth is 0.
  • GraphObject.actualBounds: Size is the same as GraphObject.measuredBounds. Position is the object's position in its surrounding panel. If there is another item above it in a panel, then the y value for measuredBounds will be greater than for actualBounds. Stroke width is also a factor.