Modules
	Area Patterns
	Support for MicroStation's Area Patterning capabilities.

Functions
int	mdlPattern_area (MSElementDescrH patternEdPP, MSElementDescrP shape, MSElementDescrP holes, MSElementDescrP cell, WChar *cellName, double scale, double angle, double rowSpacing, double columnSpacing, int view, bool searchForHoles, DPoint3dP originPoint)
	Creates an element descriptor representing a pattern of the area enclosed by an an element. More...

int	mdlPattern_hatch (MSElementDescrH hatchEdPP, MSElementDescrP shape, MSElementDescrP holes, MSElementP templateP, double angle, double spacing, int view, bool searchForHoles, DPoint3dP originPoint)
	Creates an element descriptor that contains the elements that hatch the area enclosed by an element. More...

int	mdlPattern_crossHatch (MSElementDescrH hatchEdPP, MSElementDescrP shape, MSElementDescrP holes, MSElementP templateP, double angle1, double angle2, double spacing1, double spacing2, int view, bool searchForHoles, DPoint3dP originPoint)
	Creates an element descriptor that contains the elements that crosshatch the area enclosed by an element. More...

int	mdlPattern_linear (MSElementDescrH patternEdPP, MSElementDescrP edP, UInt32 filePos, MSElementDescrP cell, const WChar *cellName, double scale, int patternType)
	Creates an element descriptor representing a linear pattern of an element. More...

int	mdlPattern_addAssociative (MSElementDescrH edPP, int line1, int line2, PatternParamsP pParams, DPoint3dP pPoint, RotMatrixP pRot, int option, DgnModelRefP modelRef)
	Adds the associative pattern linkage defined by pParams to the pattern boundary element(s). More...

int	mdlPattern_addAssociative2 (MSElementDescrH edPP, int line1, int line2, PatternParamsP pParams, DwgHatchDefLineP pHatchLines, DPoint3dP pPoint, RotMatrixP pRot, int option, DgnModelRefP modelRef)
	Adds the associative pattern linkage defined by pParams to the pattern boundary element(s). More...

int	mdlPattern_deleteAssociative (MSElementDescrH edPP, int index)
	Removes an associative pattern linkage from the element(s) contained in edPP. More...

int	mdlPattern_extractAssociative (PatternParamsP pParams, DPoint3dP pOrigin, MSElementCP elemP, DgnModelRefP modelRef, int index)
	Extracts associative pattern information from the element pointed to by elemP. More...

int	mdlPattern_extractAssociative2 (PatternParamsP pParams, DwgHatchDefLineP pHatchLines, int maxHatchLines, DPoint3dP pOrigin, MSElementCP elemP, DgnModelRefP modelRef, int index)
	Extracts associative pattern information from the element pointed to by elemP. More...

int	mdlPattern_getElementDescr (MSElementDescrH patternEdPP, MSElementDescrP inDscrP, DgnModelRefP modelRef, int patIndex, int option)
	Creates an element descriptor containing the pattern elements from an associative patterned element. More...

Detailed Description

Function Documentation

int mdlPattern_addAssociative	(	MSElementDescrH	edPP,
		int	line1,
		int	line2,
		PatternParamsP	pParams,
		DPoint3dP	pPoint,
		RotMatrixP	pRot,
		int	option,
		DgnModelRefP	modelRef
	)

Adds the associative pattern linkage defined by pParams to the pattern boundary element(s).

The element(s) in edPP can be either a closed primitive element (multi-line, ellipse or shape) or a complex element defining the pattern boundary. If edPP contains a complex element, the associative pattern linkage is appended to the complex header.

Parameters

[in,out]	edPP	element to modify
[in]	line1	1st boundary line (multiLines only)
[in]	line2	2nd boundary line (multiLines only)
[in]	pParams	pattern parameters or NULL for active parameters.
[in]	pPoint	origin or intersection point of the pattern or hatch. If pPoint is NULL MicroStation will define the pattern origin based on the origin of the element(s) in edPP.
[in]	pRot	orientation of the coordinate system from which the pattern angle(s) in pParams are measured. Usually this is the view rotation matrix from the view in which the pattern is being placed. The view rotation matrix can be determined using the mdlRMatrix_fromView function. If pRot is NULL the identity matrix is used which indicates the orientation of the design plane.
[in]	option	type of pattern to create. If the value of option is set to PATTERN_HATCH, a simple hatch is created. In this case pParams must contain a value for hatch spacing in primary spacing. A hatch angle (in radians) may also be specified in primary angle.
[in]	modelRef	source modelRef for the element in edPP

Remarks: The line1 and line2 parameters are used only if dscrPP contains a MicroStation multi-line element (type=MULTILINE_ELM). In this case, line1 and line2 indicate the multi-line profile index of each of the two lines in the multi-line element that define the pattern boundary. Pass -1 for both line1 and line2 to use the outermost lines of any multi-line element.; The parameters that define the pattern are specified in the Bentley::DgnPlatform::PatternParams structure paramsP which is defined in the header file AreaPattern.h. If paramsP is NULL the active pattern parameters are used.; A DgnPlatform::PatternParams structure for creation of a simple 45 degree hatch pattern can be defined as follows:
..

PatternParamsPtr params = PatternParams::Create ();

params->SetPrimarySpacing (100.0);

params->SetPrimaryAngle (Angle::DegreesToRadians (45.0));

mdlPattern_addAssociative (edPP, -1, -1, params.get (), NULL, NULL, PATTERN_HATCH, modelRef);

...; If the value of option is PATTERN_CROSSHATCH then a cross hatch pattern is created. In addition to the information specified for PATTERN_HATCH, pParams must also contain a value for the secondary hatch spacing. A secondary hatch angle can also be specified.; If the value of option is PATTERN_AREA an area pattern is created using the pattern cell name specified, the row spacing specified in primary spacing and the column spacing specified in secondary spacing. A pattern angle may also be specified in primary angle.; For each of the pattern options, values for pattern scale, and pattern element color, style and weight can also be specified in the DgnPlatform::PatternParams structure pointed to by pParams.; All element types except multi-lines can contain only one associative pattern. If the element in edPP is not a multi-line and already contains an associative pattern linkage the existing pattern linkage is replaced. If the element in edPP is a multi-line element the pattern linkage is appended without affecting any previous pattern linkages. To replace an associative pattern on a multi-line element, it is necessary to first call mdlPattern_deleteAssociative to remove previously applied patterns.

Returns: sUCCESS if the requested operation was successful. Otherwise an error status is returned.

See also: mdlPattern_deleteAssociative mdlPattern_extractAssociative

int mdlPattern_addAssociative2	(	MSElementDescrH	edPP,
		int	line1,
		int	line2,
		PatternParamsP	pParams,
		DwgHatchDefLineP	pHatchLines,
		DPoint3dP	pPoint,
		RotMatrixP	pRot,
		int	option,
		DgnModelRefP	modelRef
	)

Adds the associative pattern linkage defined by pParams to the pattern boundary element(s).

The element(s) in edPP can be either a closed primitive element (multi-line, ellipse or shape) or a complex element defining the pattern boundary. If edPP contains a complex element, the associative pattern linkage is appended to the complex header. Differs from mdlPattern_addAssociative only in that it contains a seperate argument for the DWG hatch lines.

Parameters

[in,out]	edPP	element to modify
[in]	line1	1st boundary line (multiLines only)
[in]	line2	2nd boundary line (multiLines only)
[in]	pParams	pattern parameters or NULL for active parameters.
[in]	pHatchLines	DWG hatch lines. Count specified in DwgHatchDef.
[in]	pPoint	origin or intersection point of the pattern or hatch. If pPoint is NULL MicroStation will define the pattern origin based on the origin of the element(s) in edPP.
[in]	pRot	orientation of the coordinate system from which the pattern angle(s) in pParams are measured. Usually this is the view rotation matrix from the view in which the pattern is being placed. The view rotation matrix can be determined using the mdlRMatrix_fromView function. If pRot is NULL the identity matrix is used which indicates the orientation of the design plane.
[in]	option	type of pattern to create. If the value of option is set to PATTERN_HATCH, a simple hatch is created. In this case pParams must contain a value for hatch spacing in primary spacing. A hatch angle (in radians) may also be specified in primary angle.
[in]	modelRef	source modelRef for the element in edPP

Remarks: The line1 and line2 parameters are used only if dscrPP contains a MicroStation multi-line element (type=MULTILINE_ELM). In this case, line1 and line2 indicate the multi-line profile index of each of the two lines in the multi-line element that define the pattern boundary. Pass -1 for both line1 and line2 to use the outermost lines of any multi-line element.; The parameters that define the pattern are specified in the Bentley::DgnPlatform::PatternParams structure paramsP which is defined in the header file AreaPattern.h. If paramsP is NULL the active pattern parameters are used.; A DgnPlatform::PatternParams structure for creation of a simple 45 degree hatch pattern can be defined as follows:
..

PatternParamsPtr params = PatternParams::Create ();

params->SetPrimarySpacing (100.0);

params->SetPrimaryAngle (Angle::DegreesToRadians (45.0));

mdlPattern_addAssociative (edPP, -1, -1, params.get (), NULL, NULL, PATTERN_HATCH, modelRef);

...; If the value of option is PATTERN_CROSSHATCH then a cross hatch pattern is created. In addition to the information specified for PATTERN_HATCH, pParams must also contain a value for the secondary hatch spacing. A secondary hatch angle can also be specified.; If the value of option is PATTERN_AREA an area pattern is created using the pattern cell name specified, the row spacing specified in primary spacing and the column spacing specified in secondary spacing. A pattern angle may also be specified in primary angle.; For each of the pattern options, values for pattern scale, and pattern element color, style and weight can also be specified in the DgnPlatform::PatternParams structure pointed to by pParams.; All element types except multi-lines can contain only one associative pattern. If the element in edPP is not a multi-line and already contains an associative pattern linkage the existing pattern linkage is replaced. If the element in edPP is a multi-line element the pattern linkage is appended without affecting any previous pattern linkages. To replace an associative pattern on a multi-line element, it is necessary to first call mdlPattern_deleteAssociative to remove previously applied patterns.

Returns: sUCCESS if the requested operation was successful. Otherwise an error status is returned.

See also: mdlPattern_deleteAssociative mdlPattern_extractAssociative

int mdlPattern_area	(	MSElementDescrH	patternEdPP,
		MSElementDescrP	shape,
		MSElementDescrP	holes,
		MSElementDescrP	cell,
		WChar *	cellName,
		double	scale,
		double	angle,
		double	rowSpacing,
		double	columnSpacing,
		int	view,
		bool	searchForHoles,
		DPoint3dP	originPoint
	)

Creates an element descriptor representing a pattern of the area enclosed by an an element.

Parameters

[out]	patternEdPP	result elements
[in]	shape	the closed element to be patterned, Valid closed elements include shapes, ellipses, complex shapes and closed B-spline curves.
[in]	holes	an element descriptor containing one or more closed hole elements. The holes designate areas within the shape that will not be patterned. Pass NULL if hole elements are required.
[in]	cell	the pattern cell (or NULL)
[in]	cellName	pattern cell name (or NULL)
[in]	scale	scale factor to be applied to pattern cell
[in]	angle	angle and view determine the pattern orientation. angle specifies the angle in radians between the view's X-axis and the pattern rows. If view is less than zero, the angle is measured from the design file's X-axis.
[in]	rowSpacing	rowSpacing and columnSpacing represent the distance between the pattern rows and columns in the current coordinate system. In most cases, these values are zero.
[in]	columnSpacing	column spacing
[in]	view	view number (pass -1 for unrotated)
[in]	searchForHoles	true to search for holes in the active model on the same level as the shape.
[in]	originPoint	origin for the pattern position. The pattern rows and columns begin at this point and are repeated in either direction to fill the shape. If NULL is passed, the current coordinate system origin is used.

Returns

SUCCESS if the pattern is successfully created. The following values are returned if an error occurs:


Return value	Meaning
MDLERR_CELLNOTFOUND	Pattern cell cannot be found.
MDLERR_NONCLOSEDPATELM	Shape element is not closed.
MDLERR_NONSOLIDPATELM	Shape element has a hole bit set.
MDLERR_NOPATTERNS	No pattern components are within shape.
MDLERR_INVALIDPATSPACE	Both pattern spacing and cell size equal zero

Remarks: The element descriptor created can be displayed using mdlElmdscr_display, and/or added to the design file using mdlElmdscr_add. The element descriptor should then be freed using mdlElmdscr_freeAll.; If both cell and cellName are NULL, the active pattern cell is used. If the cell is passed as an element descriptor, the cell name should still be passed in cellName, because the cell name is stored in the invisible pattern control text element and is used by the SHOW PATTERN or MATCH PATTERN tool.

int mdlPattern_crossHatch	(	MSElementDescrH	hatchEdPP,
		MSElementDescrP	shape,
		MSElementDescrP	holes,
		MSElementP	templateP,
		double	angle1,
		double	angle2,
		double	spacing1,
		double	spacing2,
		int	view,
		bool	searchForHoles,
		DPoint3dP	originPoint
	)

Creates an element descriptor that contains the elements that crosshatch the area enclosed by an element.

Parameters

[out]	hatchEdPP	pointer to a an element descriptor pointer that is populated with the hatch components.
[in]	shape	an element descriptor containing the closed element to be hatched. Valid closed elements include shapes, ellipses, complex shapes and closed B-spline curves.
[in]	holes	an element descriptor containing one or more closed hole elements. The holes designate areas within the shape that will not be hatched. A NULL value can be passed for holes if no hole elements are required.
[in]	templateP	template for hatch lines
[in]	angle1	angle and view determine the first hatch orientation. angle1 specifies the angle in radians between the view's X-axis and the first hatch lines. If view is less than zero, the angle is measured from the design file's X-axis.
[in]	angle2	angle2 and view determine the second hatch orientation. angle2 specifies the angle in radians between the view's X-axis and the second hatch lines. If view is less than zero, the angle is measured from the design file's X-axis.
[in]	spacing1	the distance between the first hatch lines in the current coordinate system. Must be greater than zero.
[in]	spacing2	the distance between the second hatch lines in the current coordinate system. Must be greater than zero.
[in]	view	view number (optional)
[in]	searchForHoles	true to search for holes in the active model for all hole elements on the same level as the shape.
[in]	originPoint	origin for the hatch position. If NULL is passed, the current coordinate system origin is used.

Returns

SUCCESS if the hatch is successfully created. The following values are returned if an error occurs:


Return value	Meaning
MDLERR_NONCLOSEDPATELM	Shape element is not closed.
MDLERR_NONSOLIDPATELM	Shape element has a hole bit set.
MDLERR_NOPATTERNS	No hatch components are within shape.
MDLERR_INVALIDPATSPACE	spacing1 or spacing2 is not greater than zero

Remarks: You should either specify a pointer to an element descriptor for holes or pass true to the searchForHoles argument. If you do both, the results will be unpredictable.; The element descriptor created can be displayed using mdlElmdscr_display, and/or added the design file using mdlElmdscr_add. The element descriptor should then be freed using mdlElmdscr_freeAll.

int mdlPattern_deleteAssociative	(	MSElementDescrH	edPP,
		int	index
	)

Removes an associative pattern linkage from the element(s) contained in edPP.

Parameters

[in,out]	edPP	element to modify
[in]	index	pattern index (multi-lines only) (-1 to delete all)

Remarks: If edPP contains a multi-line element then there may be more than one associative pattern linkage on the element. In this case an application can use the mdlPattern_extractAssociative function to search for the desired pattern linkage and then specify the pattern to be removed using the index parameter when calling mdlPattern_deleteAssociative.; To delete all patterns from a multi-line element call mdlPattern_deleteAssociative with -1 for the index:

Returns: The number of linkage patterns deleted.

See also: mdlPattern_addAssociative mdlPattern_extractAssociative

int mdlPattern_extractAssociative	(	PatternParamsP	pParams,
		DPoint3dP	pOrigin,
		MSElementCP	elemP,
		DgnModelRefP	modelRef,
		int	index
	)

Extracts associative pattern information from the element pointed to by elemP.

Parameters

[out]	pParams	The members of the Bentley::DgnPlatform::PatternParams structure are filled in with the pattern parameters extracted from elemP. Returns ERROR if NULL. See mdlPattern_addAssociative for additional information about the DgnPlatform::PatternParams structure.
[out]	pOrigin	pattern origin. can be NULL if the origin is not needed.
[in]	elemP	the element for which the associative pattern is extracted.
[in]	modelRef	source modelRef of elemP. Currently modelRef is only used if elemP is a multi-line element that contains associative points.
[in]	index	requested pattern index

Returns: SUCCESS if the requested operation was successful. Otherwise an error status is returned.

Remarks: If elemP is a multi-line element it can contain more than one associative pattern. In this case pass the index (zero based) of the desired pattern in the index parameter. If elemP is not a multi-line element pass a value of zero for index.; Use PatternParams::Create () to create an instance of a PatternParams.
..

PatternParamsPtr params = PatternParams::Create ();

mdlPattern_extractAssociative (params.get (), NULL, elemP, modelRef, 0);

...

See also: mdlPattern_addAssociative mdlPattern_deleteAssociative

int mdlPattern_extractAssociative2	(	PatternParamsP	pParams,
		DwgHatchDefLineP	pHatchLines,
		int	maxHatchLines,
		DPoint3dP	pOrigin,
		MSElementCP	elemP,
		DgnModelRefP	modelRef,
		int	index
	)

Extracts associative pattern information from the element pointed to by elemP.

Differs from mdlPattern_extractAssociative only in the addition of a seperate argument to receive DWG hatch lines.

Parameters

[out]	pParams	The members of the Bentley::DgnPlatform::PatternParams structure are filled in with the pattern parameters extracted from elemP. Returns ERROR if NULL.
[out]	pHatchLines	If nonNull and the associative pattern contains DWG hatch pattern, the hatch lines are returned here.
[in]	maxHatchLines	Maximum size of pHatchLines buffer. See mdlPattern_addAssociative for additional information about the DgnPlatform::PatternParams structure.
[out]	pOrigin	pattern origin. can be NULL if the origin is not needed.
[in]	elemP	the element for which the associative pattern is extracted.
[in]	modelRef	source modelRef of elemP. Currently modelRef is only used if elemP is a multi-line element that contains associative points.
[in]	index	requested pattern index

Returns: SUCCESS if the requested operation was successful. Otherwise an error status is returned.

Remarks: If elemP is a multi-line element it can contain more than one associative pattern. In this case pass the index (zero based) of the desired pattern in the index parameter. If elemP is not a multi-line element pass a value of zero for index.; Use PatternParams::Create () to create an instance of a PatternParams.
..

PatternParamsPtr params = PatternParams::Create ();

mdlPattern_extractAssociative (params.get (), NULL, elemP, modelRef, 0);

...

See also: mdlPattern_addAssociative mdlPattern_deleteAssociative

int mdlPattern_getElementDescr	(	MSElementDescrH	patternEdPP,
		MSElementDescrP	inDscrP,
		DgnModelRefP	modelRef,
		int	patIndex,
		int	option
	)

Creates an element descriptor containing the pattern elements from an associative patterned element.

Parameters

[out]	patternEdPP	pointer to a an element descriptor pointer that is populated with the pattern components.
[in]	inDscrP	an element descriptor containing an associative patterned element. If inDscrP does not contain an associative pattern, an error status is returned and patternEdPP is unchanged.
[in]	modelRef	source modelRef for inDscrP. Currently modelRef is only used if inDscrP is a multi-line element that contains associative points.
[in]	patIndex	pattern index (multi-lines only)
[in]	option	If option is true all output elements have their graphic group number set to the next available graphic group number and the next available graphic group number is incremented. If option is false, output elements have their graphic group number set to zero.

Remarks: If inDscrP is a multi-line element it can contain more than one associative pattern. In this case index indicates the desired pattern. If inDscrP is not a multi-line element pass zero for index.

Returns: SUCCESS if the requested operation was successful, otherwise an error status.

See also: mdlPattern_addAssociative mdlPattern_deleteAssociative mdlPattern_extractAssociative

int mdlPattern_hatch	(	MSElementDescrH	hatchEdPP,
		MSElementDescrP	shape,
		MSElementDescrP	holes,
		MSElementP	templateP,
		double	angle,
		double	spacing,
		int	view,
		bool	searchForHoles,
		DPoint3dP	originPoint
	)

Creates an element descriptor that contains the elements that hatch the area enclosed by an element.

Parameters

[out]	hatchEdPP	pointer to a an element descriptor pointer that is populated with the hatch components.
[in]	shape	an element descriptor containing the closed element to be hatched. Valid closed elements include shapes, ellipses, complex shapes and closed B-spline curves.
[in]	holes	an element descriptor containing one or more closed hole elements. The holes designate areas within the shape that will not be hatched. A NULL value can be passed for holes if no hole elements are required.
[in]	templateP	template for hatch lines
[in]	angle	angle and view determine the hatch orientation. angle specifies the angle in radians between the view's X-axis and the hatch lines. If view is less than zero, the angle is measured from the design file's X-axis.
[in]	spacing	the distance between the hatch lines in the current coordinate system. Must be greater than zero.
[in]	view	view number (optional)
[in]	searchForHoles	true to search for holes in the active model for all hole elements on the same level as the shape.
[in]	originPoint	origin for the hatch position. If NULL is passed, the current coordinate system origin is used.
[in]	spacing	spacing represents the distance between the hatch lines

Returns

SUCCESS if the hatch is successfully created. The following values are returned if an error occurs:


Return value	Meaning
MDLERR_NONCLOSEDPATELM	Shape element is not closed.
MDLERR_NONSOLIDPATELM	Shape element has a hole bit set.
MDLERR_NOPATTERNS	No hatch components are within shape.
MDLERR_INVALIDPATSPACE	spacing is not greater than zero

Remarks: You should either specify a pointer to an element descriptor for holes or pass true to the searchForHoles argument. If you do both, the results will be unpredictable.; The element descriptor created can be displayed using mdlElmdscr_display, and/or added the design file using mdlElmdscr_add. The element descriptor should then be freed using mdlElmdscr_freeAll.

int mdlPattern_linear	(	MSElementDescrH	patternEdPP,
		MSElementDescrP	edP,
		UInt32	filePos,
		MSElementDescrP	cell,
		const WChar *	cellName,
		double	scale,
		int	patternType
	)

Creates an element descriptor representing a linear pattern of an element.

Parameters

[out] patternEdPP result elements

[in] edP element to be patterned, Valid Elements include lines, line strings, shapes, curves, B-spline curves, complex chains, and complex shapes.

[in] filePos file position of element to be patterned (optional)

[in] cell the pattern cell (or NULL)

[in] cellName pattern cell name (or NULL)

[in] scale scale factor to be applied to pattern cell

[in]

patternType

pattern type. Can be one of the following values:


patternType	Description
0	Truncated cycle (unscaled)
1	Untruncated cycle (scaled)
2	Single cycle
3	Multiple cycle

Returns: SUCESS if the pattern is successfully created, or MDLERR_CELLNOTFOUND if the pattern cell cannot be located.

Remarks: Normally, when an element is linear patterned, its class is changed to 5 to indicate that it has an associated linear pattern. When patterns are enabled for a view, the pattern components display and the original elements are inhibited. When patterns are not enabled, the original elements display and the patterns do not. If it is desired to update the class of the element being patterned, the filePos argument must be supplied.; If both cell and cellName are NULL, the active pattern cell is used. If the cell is passed as an element descriptor, the cell name should still be passed in cellName, because the cell name is stored in the invisible pattern control text element and is used by the SHOW PATTERN or MATCH PATTERN tool.

Modules

Functions

Detailed Description

Function Documentation