Export (0) Print
Expand All

IXpsOMObjectFactory::CreateLinearGradientBrush method

Creates an IXpsOMLinearGradientBrush interface.

Syntax


HRESULT CreateLinearGradientBrush(
  [in]           IXpsOMGradientStop *gradStop1,
  [in]           IXpsOMGradientStop *gradStop2,
  [in]           const XPS_POINT *startPoint,
  [in]           const XPS_POINT *endPoint,
  [out, retval]  IXpsOMLinearGradientBrush **linearGradientBrush
);

Parameters

gradStop1 [in]

The IXpsOMGradientStop interface that specifies the gradient properties at the beginning of the gradient's vector. This parameter must not be NULL.

gradStop2 [in]

The IXpsOMGradientStop interface that specifies the gradient properties at the end of the gradient's vector. This parameter must not be NULL.

startPoint [in]

The XPS_POINT structure that contains the coordinates of the start point in two-dimensional space.

endPoint [in]

The XPS_POINT structure that contains the coordinates of the end point in two-dimensional space.

linearGradientBrush [out, retval]

A pointer to the new IXpsOMLinearGradientBrush interface.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the table that follows. For information about XPS document API return values that are not listed in this table, see XPS Document Errors.

Return codeDescription
S_OK

The method succeeded.

E_INVALIDARG

The point specified by either startPoint or endPoint was not valid. The members of the XPS_POINT structure must contain valid and finite floating-point values.

E_POINTER

gradStop1, gradStop2, startPoint, figure, or linearGradientBrush is NULL.

XPS_E_NO_CUSTOM_OBJECTS

gradStop1 or gradStop1 does not point to a recognized interface implementation. Custom implementation of XPS Document API interfaces is not supported.

 

Remarks

The gradient region of a linear gradient is the area between and including the start and end points and extending in both directions at a right angle to the gradient path. The spread area is the area of the geometry that lies outside the gradient region.

Gradient stops define the color at specific locations along the gradient path. In the illustration, gradient stop 0, specified by the gradStop1 parameter, is located at the start point of the gradient path, and gradient stop 1, specified by the gradStop2 parameter, is at the end point.

As shown in the illustration that follows, the start and end points of a linear gradient are also the start and end points of the gradient path, which is the straight line that connects those points.

A figure that shows the terms used in a linear gradient

The code example that follows illustrates how this method is used to create a new interface.



IXpsOMLinearGradientBrush    *newInterface;
// The following values are defined outside of 
// this example.
//  IXpsOMGradientStop       *gradStop1, *gradStop2;
//  XPS_POINT                startPoint, endPoint;

// 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->CreateLinearGradientBrush (
        gradStop1,
        gradStop2,
        &startPoint,
        &endPoint,
        &newInterface);

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

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


Requirements

Minimum supported client

Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | Windows Store apps]

Header

Xpsobjectmodel.h

IDL

XpsObjectModel.idl

See also

IXpsOMObjectFactory
IXpsOMGradientStop
IXpsOMLinearGradientBrush
XPS_POINT
XPS Document Errors
XML Paper Specification

 

 

Community Additions

ADD
Show:
© 2014 Microsoft