Méthode IXpsOMGeometryFigure ::SetSegments (xpsobjectmodel.h)

Définit les informations de segment et les points de données pour les segments de la figure.

Syntaxe

HRESULT SetSegments(
  [in] UINT32                 segmentCount,
  [in] UINT32                 segmentDataCount,
  [in] const XPS_SEGMENT_TYPE *segmentTypes,
  [in] const FLOAT            *segmentData,
  [in] const BOOL             *segmentStrokes
);

Paramètres

[in] segmentCount

Nombre de segments.

Cette valeur est également le nombre d’éléments dans les tableaux référencés par segmentTypes et segmentStrokes.

[in] segmentDataCount

Nombre de points de données de segment.

Cette valeur est également le nombre d’éléments dans le tableau référencé par segmentData.

[in] segmentTypes

Tableau de variables XPS_SEGMENT_TYPE . La valeur de segmentCount spécifie le nombre d’éléments dans ce tableau.

[in] segmentData

Tableau de valeurs de données de segment. La valeur de segmentDataCount spécifie le nombre d’éléments dans ce tableau.

[in] segmentStrokes

Tableau de valeurs de trait de segment. La valeur de segmentCount spécifie le nombre d’éléments dans ce tableau.

Valeur retournée

Cette méthode retourne un code HRESULT. Les valeurs possibles incluent, sans s’y limiter, celles de la table qui suit. Pour plus d’informations sur les valeurs de retour de l’API de document XPS qui ne sont pas répertoriées dans ce tableau, consultez Erreurs de document XPS.

Remarques

Un segment geometry est décrit par le point de départ, le type de segment et des paramètres supplémentaires dont les valeurs sont déterminées par le type de segment. Les coordonnées du point de départ du premier segment sont une propriété de la figure géométrique et sont définies en appelant SetStartPoint. Le point de départ de chaque segment suivant est le point de fin du segment précédent.

Le nombre de valeurs de données qui définissent un segment de ligne dépend du type de segment. Le tableau qui suit décrit l’ensemble spécifique de valeurs de données requises qui doivent être utilisées pour chaque type de segment. Les valeurs du tableau de données de segment passées dans le paramètre segmentData doivent correspondre aux valeurs XPS_SEGMENT_TYPE du tableau transmises dans le paramètre segmentTypes . Par exemple, si le segment de première ligne a une valeur de type de segment de XPS_SEGMENT_TYPE_LINE, les deux premières valeurs de données dans le tableau segmentData seront les coordonnées x et y du point de fin de ce segment ; si le segment suivant a une valeur de type de segment de XPS_SEGMENT_TYPE_BEZIER, les six valeurs suivantes du tableau segmentData décrivent les caractéristiques de ce segment ; et ainsi de suite pour chaque segment de ligne dans la figure géométrique.

Type de segment	Valeurs de données requises
XPS_SEGMENT_TYPE_LINE	Deux valeurs de données : coordonnée x du point de terminaison de la ligne de segment. coordonnée y du point de terminaison de la ligne de segment.
XPS_SEGMENT_TYPE_ARC_LARGE_CLOCKWISE	Cinq valeurs de données : coordonnée x du point de terminaison de l’arc. coordonnée y du point de terminaison de l’arc. Longueur du rayon de l’ellipse le long de l’axe X. Longueur du rayon de l’ellipse le long de l’axe y. Angle de rotation.
XPS_SEGMENT_TYPE_ARC_SMALL_CLOCKWISE	Cinq valeurs de données : coordonnée x du point de terminaison de l’arc. coordonnée y du point de terminaison de l’arc. Longueur du rayon de l’ellipse le long de l’axe X. Longueur du rayon de l’ellipse le long de l’axe y. Angle de rotation.
XPS_SEGMENT_TYPE_ARC_LARGE_COUNTERCLOCKWISE	Cinq valeurs de données : coordonnée x du point de terminaison de l’arc. coordonnée y du point de terminaison de l’arc. Longueur du rayon de l’ellipse le long de l’axe X. Longueur du rayon de l’ellipse le long de l’axe y. Angle de rotation.
XPS_SEGMENT_TYPE_ARC_SMALL_COUNTERCLOCKWISE	Cinq valeurs de données : coordonnée x du point de terminaison de l’arc. coordonnée y du point de terminaison de l’arc. Longueur du rayon de l’ellipse le long de l’axe X. Longueur du rayon de l’ellipse le long de l’axe y. Angle de rotation.
XPS_SEGMENT_TYPE_BEZIER	Six valeurs de données : coordonnée x du premier point de contrôle de la courbe de Béziers. coordonnée y du premier point de contrôle de la courbe de Béziers. coordonnée x du deuxième point de contrôle de la courbe de Béziers. coordonnée y du deuxième point de contrôle de la courbe de Béziers. coordonnée x du point de terminaison de la courbe de Béziers. coordonnée y du point de terminaison de la courbe de Béziers.
XPS_SEGMENT_TYPE_QUADRATIC_BEZIER	Quatre valeurs de données : coordonnée x du point de contrôle de la courbe de Béziers quad. coordonnée y du point de contrôle de la courbe de Béziers quad. coordonnée x du point de terminaison de la courbe de Béziers quad. coordonnée y du point de terminaison de la courbe de Béziers quad.

Pour obtenir les types de segments dans la figure, appelez GetSegmentTypes.

Les exemples de code suivants illustrent une façon de créer et de remplir les mémoires tampons requises par SetSegments.

Dans le premier exemple de code, la méthode AddSegmentDataToArrays prend les points de données qui décrivent un segment unique et les stocke dans les trois mémoires tampons de données différentes requises par la méthode SetSegments . Les mémoires tampons de données transmises en tant qu’arguments à AddSegmentDataToArrays sont gérées par la méthode appelante, comme indiqué dans l’exemple de code qui suit AddSegmentDataToArrays.

HRESULT
AddSegmentDataToArrays(
    XPS_SEGMENT_TYPE        segmentType,
    BOOL                    segmentStroke,
    FLOAT                   *segmentPoints,
    UINT32                  *segmentsAvailable,
    UINT32                  *segmentPointsAvailable,
    XPS_SEGMENT_TYPE        **segmentTypeBuffer,
    BOOL                    **segmentStrokeBuffer,
    FLOAT                   **segmentPointBuffer
)
/*
Description:

Populates the buffers required by IXpsOMGeometryFigure::SetSegmentData
using data and buffers provided by the calling method.

Parameters:

segmentType
    IN: XPS_SEGMENT_TYPE value that specifies the segment type for
        the current segment.

segmentStroke
    IN: BOOL value that specifies whether the current segment 
        is stroked.

*segmentPoints
    IN: pointer to an array of FLOAT values that specify the 
        segment's data points. The number of values in the array
        depend on the value of the segmentType parameter.

*segmentsAvailable
    IN: the number of values that remain unused in the
        segmentTypeBuffer and the segmentStrokeBuffer.
        This value must be >= 1 when calling the method.
    OUT:  the number of values that remain unused in the
        segmentTypeBuffer and the segmentStrokeBuffer after
        segmentType and segmentStroke have been added. If the 
        method was successful, the returned value is one less 
        than the value passed in to the method.

*segmentPointsAvailable
    IN: the number of values that remain unused in the
        segmentPointBuffer.    This value must be greater-than or equal
        to the number of points required by the segmentType value.
    OUT:  the number of values that remain unused in the
        segmentPointBuffer after the segmentPoints have been added.
        The returned value depends on the segmentType value.

**segmentTypeBuffer
    IN: the first free element in the buffer that receives the segment
        type values.
    OUT: the first free element in the buffer that receives the segment
        type values. If the method is successful, this will be the element
        after the element pointed to by this value before the method 
        was called.

**segmentStrokeBuffer
    IN: the first free element in the buffer that receives the segment
        stroke values.
    OUT: the first free element in the buffer that receives the segment
        stroke values. If the method is successful, this will be the element
        after the element pointed to by this value before the method 
        was called.

**segmentPointBuffer
    IN: the first free element in the buffer that receives the segment
        point values.
    OUT: the first free element in the buffer that receives the segment
        point values. If the method is successful, the element referenced
        by this value will depend on the segment type.

Remarks.
1) the buffers and values passed into this method are managed by
    the calling method.

2) if the value returned in segmentsAvailable is 0, segmentTypeBuffer
    and segmentStrokeBuffer point to invalid memory.

3) if the value returned in segmentPointsAvailable is 0, segmentPointBuffer
    point to invalid memory.

*/
{
    HRESULT hr = S_OK;

    // test to see if there is sufficient space in the 
    // segmentTypeBuffer and the segmentStrokeBuffer before
    // proceeding
    if (*segmentsAvailable == 0)
    {
        hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
    }

    if (SUCCEEDED(hr))
    {
        // process the data based on the segment type
        switch (segmentType) 
        {
            case    XPS_SEGMENT_TYPE_ARC_LARGE_CLOCKWISE:
            case    XPS_SEGMENT_TYPE_ARC_LARGE_COUNTERCLOCKWISE:
            case    XPS_SEGMENT_TYPE_ARC_SMALL_CLOCKWISE:
            case    XPS_SEGMENT_TYPE_ARC_SMALL_COUNTERCLOCKWISE:
                if (*segmentPointsAvailable >= 5) 
                {
                    // 5 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc end point (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc radius (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc radius (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<arc angle
                    *segmentPointsAvailable -= 5;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            case    XPS_SEGMENT_TYPE_BEZIER:
                if (*segmentPointsAvailable >= 6) 
                {
                    // 6 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 1 (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 1 (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (y)
                    *segmentPointsAvailable -= 6;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            case    XPS_SEGMENT_TYPE_LINE:
                if (*segmentPointsAvailable >= 2) 
                {
                    // 2 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (y)
                    *segmentPointsAvailable -= 2;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            case    XPS_SEGMENT_TYPE_QUADRATIC_BEZIER:
                if (*segmentPointsAvailable >= 4) 
                {
                    // 4 data points
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<control point 2 (y)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (x)
                    *(*segmentPointBuffer)++ = *segmentPoints++; //<end point (y)
                    *segmentPointsAvailable -= 4;
                }
                else
                {
                    hr = HRESULT_FROM_WIN32(ERROR_MORE_DATA);
                }
                break;
            default:
                // unrecognized segment type
                hr = E_UNEXPECTED;
                break;
        }

    }

    if (SUCCEEDED(hr))
    {
        // Copy segment type and segment stroke values
        // to array and decrement number of array values
        // that remain unused.
        //
        // The space available for these operations was
        // tested at the beginning of the method.
        *(*segmentTypeBuffer)++ = segmentType;
        *(*segmentStrokeBuffer)++ = segmentStroke;
        *segmentsAvailable--;
    } 

    return hr;
}

Dans cet exemple de code, UpdateSegmentData crée les mémoires tampons de données requises par la méthode SetSegments et appelle la méthode AddSegmentDataToArrays de l’exemple de code précédent pour les remplir avec les données de segment. Une fois les tampons renseignés, SetSegments est appelé pour ajouter ces données à la figure geometry.

HRESULT
UpdateSegmentData (
    IXpsOMGeometryFigure    *geometryFigure,
    UINT32                  segmentCount,
    UINT32                  segmentDataCount
)
/*
    Note that this method is not complete and only includes
    the code necessary to show how the SetSegments call is used.

    In this sample, the geometryFigure, segmentCount, and
    segmentDataCount values are assumed to have been initialized
    outside of this example.
*/
{
    HRESULT             hr = S_OK;
    XPS_SEGMENT_TYPE    segmentType = (XPS_SEGMENT_TYPE)0;
    BOOL                segmentStroke = FALSE;
    FLOAT               segmentPoints = 0;
    UINT32              segmentsAvailable = 0;
    UINT32              segmentPointsAvailable = 0;
    // these buffers are sized and allocated based on 
    //    the segment data to store.
    XPS_SEGMENT_TYPE    *segmentTypeBuffer = NULL;
    BOOL                *segmentStrokeBuffer = NULL;
    FLOAT               *segmentPointBuffer = NULL;

    XPS_SEGMENT_TYPE    *nextSegmentTypeValue = NULL;
    BOOL                *nextSegmentStrokeValue = NULL;
    FLOAT               *nextSegmentPointValue = NULL;

    // segment data is created outside of this example

    // allocate buffers as required using information 
    // from segment data. This can be dynamic or static
    // depending on how the segment information is managed.
    // This example assumes that the segment information 
    // does not change during this method.

    // initialize "next" pointers to point to the first
    // element in each array.
    nextSegmentTypeValue = segmentTypeBuffer;
    nextSegmentStrokeValue = segmentStrokeBuffer;
    nextSegmentPointValue = segmentPointBuffer;

    // for each segment in the figure, add the 
    // segment data to the buffers

        hr = AddSegmentDataToArrays(
                segmentType,
                segmentStroke,
                &segmentPoints,
                &segmentsAvailable,
                &segmentPointsAvailable,
                &nextSegmentTypeValue,
                &nextSegmentStrokeValue,
                &nextSegmentPointValue);
        
    if (SUCCEEDED(hr))
    {
        // set segment data
        hr = geometryFigure->SetSegments (
            segmentCount,
            segmentDataCount,
            segmentTypeBuffer,
            segmentPointBuffer,
            segmentStrokeBuffer);
    }
    // clean up buffers

    return hr;
}

Configuration requise

Voir aussi

GetSegmentTypes

IXpsOMGeometryFigure

XML Paper Specification

Erreurs de document XPS

XPS_SEGMENT_TYPE