IXpsOMGradientStop interface (xpsobjectmodel.h)

Represents a single color and location within a gradient.

Inheritance

The IXpsOMGradientStop interface inherits from the IUnknown interface. IXpsOMGradientStop also has these types of members:

Methods

The IXpsOMGradientStop interface has these methods.

IXpsOMGradientStop::Clone Makes a deep copy of the IXpsOMGradientStop interface.
IXpsOMGradientStop::GetColor Gets the color value and color profile of the gradient stop.
IXpsOMGradientStop::GetOffset Gets the offset value of the gradient stop.
IXpsOMGradientStop::GetOwner Gets a pointer to the IXpsOMGradientBrush interface that contains the gradient stop.
IXpsOMGradientStop::SetColor Sets the color value and color profile of the gradient stop.
IXpsOMGradientStop::SetOffset Sets the offset location of the gradient stop.

Remarks

A gradient stop is a specific color that is defined for a location within the gradient region. The color of the gradient changes between the gradient stops of the gradient. The area and absolute location of the gradient is defined by the gradient interface. The offset is a relative location within the gradient region and is measured between 0.0 and 1.0. An offset of 0.0 is the beginning of the gradient and 1.0 is the end. Gradient stops can be defined for any offset within the range, including the end points. This interface describes one and only one stop in a gradient.

The gradient path is the straight line that connects the start point and the end point of a linear gradient. The gradient region of a linear gradient consists of the area between the start point and the end point, including those points, and extends in both directions at a right angle to the gradient path. The spread area is the area outside the gradient region.

Gradient stops define the color at a specific location along the gradient path; the color is interpolated along the gradient path between the gradient stops. In the example that follows, the gradient region fills the image, so there is no spread area.

For gradient stops used in linear-gradient brushes, the offset value of 0.0 corresponds to the start point of the gradient path, and the offset value of 1.0 corresponds to the end point. To determine the location of a gradient stop between these two points, intermediate offset values are interpolated between them. The following illustration shows two intermediate gradient stops, one at an offset of 0.25 and another at 0.75.

For gradient stops used in radial-gradient brushes, the offset value of 0.0 corresponds to the gradient origin location, and the offset value of 1.0 corresponds to the circumference of the ellipse that bounds the gradient. Offsets between 0.0 and 1.0 define an ellipse that is interpolated between the gradient origin and the bounding ellipse. The illustration that follows has one intermediate gradient stop at an offset of 0.50 (Gradient stop 1). The gradient is using the XPS_SPREAD_METHOD_REFLECT spread method to fill the space outside of the gradient region.

The calculations that are used to render a gradient are described in the XML Paper Specification.

The code example that follows illustrates how to create an instance of this interface.

IXpsOMGradientStop    *newInterface;
// The following values are defined outside of 
// this example.
//  XPS_COLOR                    color;
//  IXpsOMColorProfileResource    *colorProfile;
//  FLOAT                        offset;

// Note the implicit requirement that CoInitializeEx 
//  has previously been called from this thread.

hr = CoCreateInstance(
    __uuidof(XpsOMObjectFactory),
    NULL,
    CLSCTX_INPROC_SERVER,
    _uuidof(IXpsOMObjectFactory),
    reinterpret_cast<LPVOID*>(&xpsFactory)
    );

if (SUCCEEDED(hr))
{
    hr = xpsFactory->CreateGradientStop (
        &color,
        colorProfile,
        offset,
        &newInterface);

    if (SUCCEEDED(hr))
    {
        // use newInterface

        newInterface->Release();
    }
    xpsFactory->Release();
}
else
{
    // evaluate HRESULT error returned in hr
}

Requirements

Requirement	Value
Minimum supported client	Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps | UWP apps]
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | UWP apps]
Target Platform	Windows
Header	xpsobjectmodel.h

See also

IXpsOMGradientBrush

IXpsOMObjectFactory::CreateGradientStop

Interfaces

XML Paper Specification