IXRShape::GetStretch (Compact 2013)
3/28/2014
This method retrieves a value that describes how this shape fills its allocated space.
Syntax
virtual HRESULT STDMETHODCALLTYPE GetStretch(
XRStretch* pStretch
) = 0;
Parameters
- pStretch
[out] Pointer to an XRStretch member that describes how this shape fills its allocated space.
Return Value
Returns an HRESULT that indicates success or failure.
Remarks
Generally, you do not set the XRStretch value for a shape object nor change it from the shape-specified default value. This is because this value is adjusted for each kind of shape object in such a way that each shape type's sizing and positioning properties are interpreted intuitively.
The concept of a applying an XRStretch value to a shape element is related to its natural size, and also how the shape is positioned in layout. Ultimately for the layout system, all objects that render to the screen are rectangles that have a width and a height. This is reflected in the existence of the Width and Height properties of the inherited class IXRUIElement. These are properties that you can access by using the IXRFrameworkElement::GetWidth and IXRFrameworkElement::GetHeight methods.
Some kinds of shapes, such as IXREllipse and IXRRectangle, have natural sizes that are represented by their Width and Height properties, and therefore these are the only properties that you use to provide the size (although the shape that renders within that natural size is still influenced by other properties such as RadiusX on the IXRRectangle object).
However, other kinds of shape objects such as IXRLine or IXRPath have other specific properties that define their shape. In this case the appropriate behavior is to have Width and Height be deterministic properties, calculated based on values that you provide for the specific sizing properties, such as X1, Y1, X2, and Y2 of IXRLine. Even for a shape object such as IXRLine, Width and Height are still settable by using the inherited methods IXRFrameworkElement::SetWidth and IXRFrameworkElement::SetHeight. The XRStretch value associated with a shape object influences what should occur if Width and Height are deliberately set.
For IXREllipse or IXRRectangle, the default XRStretch setting is XRStretch_Fill, because their complete sizing logic is based on Width and Height. When you set XRStretch to XRStretch_None for IXREllipse or IXRRectangle, the ellipse object or rectangle object does not render.
For the other shape objects, the default setting is XRStretch_None. When you set this value to a value other than XRStretch_None, it introduces a transform effect, which could probably be controlled more efficiently with a true transform if that was a desired effect. For more information, see IXRTransform.
.NET Framework Equivalent
System.Windows.Shapes.Shape.Stretch
Requirements
Header |
XamlRuntime.h |
sysgen |
SYSGEN_XAML_RUNTIME |