deprecated10_0.fdf File Reference

Macros
#define	LEVEL_ITERATE_TYPE_ROOT_LEVELS   2
#define	LEVEL_ITERATE_TYPE_CHILD_LEVELS   3
#define	LEVEL_COUNT_TYPE_ROOT   4

Functions
MSElementCP	mdlLevel_getLinkageHolder (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn)
StatusInt	mdlLevel_setLinkageHolder (DgnModelRefP modelRefIn, DgnPlatform::LevelId levelIdIn, MSElementP pLinkageHolderElementIn)
MSElementCP	mdlLevelTable_getLinkageHolder (DgnModelRefP modelRefIn)
StatusInt	mdlLevelTable_setLinkageHolder (DgnModelRefP modelRefIn, MSElementP pLinkageHolderElementIn)
void	mdlDependency_setTrackingDisabled (bool bSuppress)
	Disable or enable change-tracking. More...
int	mdlDependency_getTrackingDisabled (void)
	Query if change-tracking has been disabled. More...
void	mdlDependency_setErrorLevel (int l)
	Determine how a post-processing failure is treated: More...
int	mdlDependency_getErrorLevel (void)
	Determine how a post-processing failure is treated. More...
void	mdlDependency_setEager (bool bEager)
	Specify if MDL should invoke post-processing callbacks during the execution of commands or if post-processing should be deferred until a command ends. More...
bool	mdlDependency_getEager ()
	Query if post-processing is triggered eagerly. More...
void	mdlDependency_setAppendChanges (bool bAppendChanges)
	Specify if changes caused during post-processing should be appended to the current undo group. More...
bool	mdlDependency_getAppendChanges ()
	Query if changes caused during post-processing will be added to the current undo group. More...
RASTERLIB_EXPORT StatusInt	mdlRaster_eventGroupEnd (int eventMode)
	End a ground of operation started by mdlRaster_eventGroupStart. More...
RASTERLIB_EXPORT StatusInt	mdlRaster_eventGroupStart (int eventMode, int commandName)
	Start a group of operation. More...
StatusInt	mdlText_strokeToElementDescr (MSElementDescrH outEdPP, MSElementDescrP pTextOrNodeElmDscr, RotMatrixP viewRMatrixP, DgnModelRefP modelRef)
	Drops a text (or text node) element to geometry. More...
StatusInt	mdlText_nodeFromTextExt (DgnPlatform::Text_node_2d *nodeTemplate, DgnPlatform::Text_2d *textTemplate, int *pNodeNumber)
	Creates a text node template element from a text element. More...
StatusInt	mdlText_extractW (WCharP string, DPoint3dP origin, DPoint3dP userOrigin, RotMatrixP rotMatrix, DgnPlatform::TextSizeParam *textSize, DgnPlatform::TextParamWide *textParam, TextEDParamP edParam, MSElementDescrP ed)
	Gets formatting and text data from the provided text element. More...
StatusInt	mdlText_create (MSElementP out, MSElementCP in, WCharCP string, DPoint3dCP userOrigin, RotMatrixCP trans, DgnPlatform::TextSizeParam const *textSize, DgnPlatform::TextParamWide const *textParam, TextEDParamCP edParam, DgnModelRefP modelRef)
	Creates a text element from constituent data. More...
int	mdlTextNode_create (MSElementP pElementOut, MSElementP pTemplateElement, DPoint3dP dOrigin, RotMatrixP rotMatrix, double *lineSpacing, DgnPlatform::MSTextSize *size, DgnPlatform::TextParam *txtParams)
	Creates a blank text node element. More...
StatusInt	mdlTextNode_extract (DPoint3dP userOrigin, RotMatrixP rotMatrix, DgnPlatform::MSTextSize *tileSize, double *lineSpacing, DgnPlatform::TextParam *txtParams, int *nodeNumber, MSElementCP in, MSElementDescrCP edP)
	Gets formatting from the provided text node. More...
StatusInt	mdlTextNode_extractShape (Dpoint3d rPoints[5], DPoint3dP rOrigin, MSElementDescrP edP, int addsnaptol, int view)
	Computes fitted box points around a text node. More...
int	mdlText_addStringsToNodeDscr (MSElementDescrP in, WCharCP buffer)
	Appends the given string to a text node. More...
void	mdlText_changeElementFont (MSElementP u, TextStyleInfoP newTfs)
	Sets the font number on a text element, node, or tag. More...
int	mdlText_expandTabs (WStringR outstring, WCharCP instring, int tabInterval)
	Replaces tab characters with space characters, attempting to preserve alignment by inserting the appropriate number of spaces. More...
void	mdlText_extractFontStyle (MSElementCP u, DgnPlatform::TextStyleInfo *tfs)
	Gets formatting information from the provided text element. More...
int	mdlText_extractShape (Dpoint3d rPoints[5], DPoint3dP rOrigin, MSElementCP in, int addSnaptol, int view)
	Computes fitted box points around a text element. More...
int	mdlText_getFontInfo (DgnPlatform::TextFontInfo *tfiP, UInt32 fontNum)
	Determines if a font by that number already exists. More...
int	mdlText_nodeFromText (DgnPlatform::Text_node_2d *nodeTemplate, DgnPlatform::Text_2d *textTemplate)
	Creates a text node template from a text element. More...
int	mdlText_textFromNode (MSElementP pElementOut, MSElementCP elementIn)
	Creates a text element template from a text node. More...
int	mdlText_extract (WStringP wString, DPoint3dP origin, DPoint3dP userOrigin, RotMatrixP rotMatrix, DgnPlatform::TextSizeParam *textSize, DgnPlatform::TextParamWide *textParam, TextEDParamP edParam, MSElementCP in)
	Gets formatting information and text content from the provided text element. More...
int	mdlText_extractString (WStringR wString, MSElementCP el)
	Gets text content from the provided text element. More...
int	mdlTextNode_createWide (MSElementP out, MSElementP in, DPoint3dP userOrigin, RotMatrixP rotMatrix, DgnPlatform::TextSizeParam *size, DgnPlatform::TextParamWide *txtParams)
	Creates a blank text node element. More...
StatusInt	mdlTextNode_createWithStrings (MSElementDescrH nodeDescrPP, MSElementCP nodeTemplate, bvector< WString > const &, DPoint3dCP userOrigin, RotMatrixCP rotMatrix, DgnPlatform::TextSizeParam const *sizeParam, DgnPlatform::TextParamWide const *txtParams, TextEDParamCP textEDParam)
	Creates a text node with the provided strings, inserting a paragraph break between each one. More...
int	mdlTextNode_extractWide (DPoint3dP userOrigin, RotMatrixP rotMatrix, DgnPlatform::TextSizeParam *txtSizeParam, DgnPlatform::TextParamWide *txtParams, MSElementCP in, MSElementDescrCP edP)
	Gets formatting from the provided text node. More...
int	mdlText_extractStringsFromDscr (WStringR buffer, MSElementDescrP in)
	Gets the concatenation of all strings in a text node. More...
int	mdlText_compressString (WStringR outBuffer, WCharCP inBuffer, int conversionType)
	Scans the input string for fractions and/or character escape sequences (determined by conversionType), turning them into single characters as allowed by the active font. More...
int	mdlText_expandString (WStringR outBuffer, WCharCP inBuffer, int conversionType)
	Scans the input string for single-character fractions and/or escape sequences (determined by conversionType), turning them into font-agnostic representations that can be round-tripped with a "compress" function. More...
int	mdlText_getElementDescr (MSElementDescrH outEdPP, DgnPlatform::Text_2d *pTextElm, RotMatrixP viewRMatrixP)
	Drops a text (or text node) element to geometry. More...
int	mdlText_getElementDescrWithModelRef (MSElementDescrH outEdPP, DgnPlatform::Text_2d *pTextElm, RotMatrixP viewRMatrixP, DgnModelRefP modelRef)
	Drops a text (or text node) element to geometry. More...
void	mdlText_setTextParamWideCodePage (DgnPlatform::TextParamWide *textParamWide, LangCodePage codePage)
	Sets the code page (and associated flag) on a TextParamWide structure. More...
int	mdlTextNode_createEx (MSElementDescrH nodeDescrPP, MSElementP nodeTemplate, MSElementDescrP textEdp, DPoint3dP dOrigin, RotMatrixP rotMatrix, DgnPlatform::TextSizeParam *sizeParam, DgnPlatform::TextParamWide *txtParams)
	Creates a text node element, and appends the contents of the chain of text elements provided. More...
StatusInt	elementRef_addDependency (ElementRefP baseElem, ElementRefP dependentElm, bool allowCircular, bool allowCrossCache)
	*//* Bentley Systems More...
StatusInt	elementRef_removeDependency (ElementRefP baseElem, ElementRefP dependentElm)
	*//* Bentley Systems More...
void	elementRef_removeAllDependencies (ElementRefP fromElem)
	remove all dependencies from an element More...
bool	dgnModel_setReadOnly (DgnModelP dgnModel, bool readOnly)
	set cache read only status More...
StatusInt	dgnModel_getModelHeader (DgnModelP dgnModel, MSElementP header)
	get the model header Element More...

Macro Definition Documentation

#define LEVEL_COUNT_TYPE_ROOT   4

#define LEVEL_ITERATE_TYPE_CHILD_LEVELS   3

#define LEVEL_ITERATE_TYPE_ROOT_LEVELS   2

Function Documentation

StatusInt dgnModel_getModelHeader	(	DgnModelP	dgnModel,
		MSElementP	header
	)

get the model header Element

bool dgnModel_setReadOnly	(	DgnModelP	dgnModel,
		bool	readOnly
	)

set cache read only status

StatusInt elementRef_addDependency	(	ElementRefP	baseElem,
		ElementRefP	dependentElm,
		bool	allowCircular,
		bool	allowCrossCache
	)

*//* Bentley Systems

void elementRef_removeAllDependencies

(

ElementRefP

fromElem

)

remove all dependencies from an element

StatusInt elementRef_removeDependency	(	ElementRefP	baseElem,
		ElementRefP	dependentElm
	)

*//* Bentley Systems

bool mdlDependency_getAppendChanges

(

)

Query if changes caused during post-processing will be added to the current undo group.

Returns

true if append mode is enabled

Deprecated:

bool mdlDependency_getEager

(

)

Query if post-processing is triggered eagerly.

See also

mdlDependency_setEager

Deprecated:

Returns

true if eager post-processing is enabled

int mdlDependency_getErrorLevel

(

void

)

Determine how a post-processing failure is treated.

Call mdlDependency_setErrorLevel to set the error level.

Call mdlDependency_processAffected to trigger post-processing.

Returns

current errorlevel (0:ignore, 1:warning, 2:error)

Deprecated:

int mdlDependency_getTrackingDisabled

(

void

)

Query if change-tracking has been disabled.

Returns

Number of times disable has been called.

Deprecated:

void mdlDependency_setAppendChanges

(

bool

bAppendChanges

)

Specify if changes caused during post-processing should be appended to the current undo group.

If append mode is turned on, changes caused by post-processing callbacks will appear to be part of the current command or the command that is just finishing. Therefore, undo will rollback post-processsing changes along with the immediately preceeding command.

If append mode is turned off, changes caused by callbacks are added to a new undo group, distinct from the previous command. This allows post-processing changes to be undone separately from command-specific changes.

See mdlDependency_processAffected for more details on post-processing.

Parameters

[in]

bAppendChanges

true: append; false: separate

Deprecated:

void mdlDependency_setEager

(

bool

bEager

)

Specify if MDL should invoke post-processing callbacks during the execution of commands or if post-processing should be deferred until a command ends.

Remarks

Eager post-processing occurs whenever control returns to the ustn event queue, and after pending events are processed. This could occur during the execution of a command, e.g., in between datapoint events.

By default, post-processing occurs whenever an undo mark is set. This happens at least whenever a command ends, i.e., when mdlState_startPrimitive is called.

Parameters

[in]

bEager

true: eager; false: when undo mark is set

Deprecated:

void mdlDependency_setErrorLevel

(

int

l

)

Determine how a post-processing failure is treated:

• 0: ignore
• 1: print a warning
• 2: print an error message and rollback changes
• 3: display an error message box and rollback changes

Errorlevel 2 is the default.

Call mdlDependency_setProcessingDisabled to turn off post-processing completely.

See mdlDependency_processAffected for details on post-processing.

Parameters

[in]

l

0:ignore, 1:warning, 2:error

Deprecated:

void mdlDependency_setTrackingDisabled

(

bool

bSuppress

)

Disable or enable change-tracking.

Remarks

Call mdlDependency_setProcessingDisabled to control post-processing.

Parameters

[in]

bSuppress

if true, disable; else enable

Deprecated:

MSElementCP mdlLevel_getLinkageHolder	(	DgnModelRefP	modelRefIn,
		DgnPlatform::LevelId	levelIdIn
	)

Deprecated:

• Use XAttributes to store custom data on level table entry element

StatusInt mdlLevel_setLinkageHolder	(	DgnModelRefP	modelRefIn,
		DgnPlatform::LevelId	levelIdIn,
		MSElementP	pLinkageHolderElementIn
	)

Deprecated:

• Use XAttributes to store custom data on level table element

MSElementCP mdlLevelTable_getLinkageHolder

(

DgnModelRefP

modelRefIn

)

Deprecated:

• Use XAttributes to store custom data on level table element

StatusInt mdlLevelTable_setLinkageHolder	(	DgnModelRefP	modelRefIn,
		MSElementP	pLinkageHolderElementIn
	)

Deprecated:

• Use XAttributes to store custom data on level table element

int mdlText_addStringsToNodeDscr	(	MSElementDescrP	in,
		WCharCP	buffer
	)

Appends the given string to a text node.

Note

Despite the name, only one string is appended. If it contains special characters such as "\n", "\r", or "\t", they will be interpretted as special whitepace, and laid out accordingly.

Deprecated:

It is recommended that you create a TextBlock out of the element, and append the string via this object.

ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

// Append the text...
// While Unicode strings are best, WString (buffer).c_str () can be used to create a Unicode string from a locale-encoded string using the system's active code page.
textBlock->AppendText (...);
textBlock->AppendParagraphBreak ();
textBlock->AppendLineBreak ();
textBlock->AppendTab ();
textBlock->AppendStackedFraction (...);
textBlock->AppendEnterDataField (...);

// Create the element...
EditElementHandle eeh;
if (TextBlock::TO_ELEMENT_RESULT_Success != TextHandlerBase::CreateElement (eeh, &eh, *textBlock))
    /* ERROR */

// eeh now contains a text element (or node) that you can ReplaceInModel etc.

Remarks

Required Library: mdlbltin.lib

void mdlText_changeElementFont	(	MSElementP	u,
		TextStyleInfoP	newTfs
	)

Sets the font number on a text element, node, or tag.

Warning

This method can corrupt text elements when changing between fonts that use different locales.

Deprecated:

It is recommended that you use the edit properties interface. Aside from supporting all elements that contain fonts, it will correctly remap strings between encodings.

// Acquire the font object... some possibilities:
DgnFontCP   newFont     = DgnFontManager::FindSystemFont (L"<FontName>");                       // Optionally provide a filter to find only RSC, SHX, or TrueType fonts; must also check NULL.
DgnFontCR   newFont     = <DgnFileR>.GetDgnFontMapP ()->ResolveFont (<FontNumber>);             // Font number maps are per-file; for instance, ISessionMgr::GetActiveDgnFile (). ResolveFont will always provide a font object, even if it has to provide a fallback font.
DgnFontCP   newFont;    DgnTextStyle::GetActive ()->GetProperty (TextStyle_Font, newFont); // While this interface deals with DgnFontCP, it should never fail to provide a value for TextStyle_Font.
DgnFontCR   newFont     = DgnFontManager::GetDefaultTrueTypeFont ();                            // Gets the "active" font. The user controls this through the text style dialog.

// Create the helper class...
ElementPropertiesSetterPtr remapper = ElementPropertiesSetter::Create ();

remapper->SetFont (newFont); // Dereference newFont if required based on how you got and verified the font object.

// Change the font...
EditElementHandle eeh (...);

remapper->Apply (eeh);

// You may now AddToModel or ReplaceInModel on eeh.

Remarks

Required Library: mdlbltin.lib

int mdlText_compressString	(	WStringR	outBuffer,
		WCharCP	inBuffer,
		int	conversionType
	)

Scans the input string for fractions and/or character escape sequences (determined by conversionType), turning them into single characters as allowed by the active font.

Note

The MSWideChar parameter(s) have changed to WChar/WString (a.k.a. wchar_t). WChar is always Unicode, is a native Windows- and CRT-supported data type, and does not need to vary with the font used. Elements maybe still store locale-encoded text, but you no longer need to account for this when using the API.

Deprecated:

Acquire the appropriate font object (see DgnFontManager and DgnFontNumMap), and call CompressRscFractions and/or CompressEscapeSequences.

// Instead of using an "active" or "loaded" font, you should acquire the appropriate DgnFont object directly. For instance:
DgnFontCR   font        = <DgnFileR>.GetDgnFontMapP ()->ResolveFont (<FontNumber>);             // <DgnFileR> such as ISessionMgr::GetActiveFile ().
DgnFontCP   newFont;    DgnTextStyle::GetActive ()->GetProperty (TextStyle_Font, newFont); // While this interface deals with DgnFontCP, it should never fail to provide a value for TextStyle_Font.

WString uniString = ...;

font.CompressRscFractions (uniString.c_str (), uniString);      // Dereference font if required based on how you got and verified the font object.
font.CompressEscapeSequences (uniString.c_str (), uniString);   // Dereference font if required based on how you got and verified the font object.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlText_create	(	MSElementP	out,
		MSElementCP	in,
		WCharCP	string,
		DPoint3dCP	userOrigin,
		RotMatrixCP	trans,
		DgnPlatform::TextSizeParam const *	textSize,
		DgnPlatform::TextParamWide const *	textParam,
		TextEDParamCP	edParam,
		DgnModelRefP	modelRef
	)

Creates a text element from constituent data.

Deprecated:

Create a TextBlock object, and configure the formatting and content that way.

// If you want to start with active settings, or from any other DgnTextStyle object...
TextBlockPtr textBlock = TextBlock::Create (*DgnTextStyle::GetActive (*ISessionMgr::GetActiveDgnFile ()), *ISessionMgr::GetActiveDgnModelP ());

// -or- If you want to start from an existing template element...
ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

textBlock->Clear ();

// -or- If you want to start from scratch...
TextBlockPtr textBlock = TextBlock::Create (*ISessionMgr::GetActiveDgnModelP ());

// -or- You can manually configure the settings up front...

TextBlockPropertiesPtr  tbProps     = TextBlockProperties::Create (...);
ParagraphPropertiesPtr  paraProps   = ParagraphProperties::Create (...);
RunPropertiesPtr        runProps    = RunProperties::Create (...);

tbProps.Set... ();
paraProps.Set... ();
runProps.Set... ();

TextBlockPtr textBlock = TextBlock::Create (*tbProps, *paraProps, *runProps, *ISessionMgr::GetActiveDgnModelP ());

// Then tweak as desired (if you didn't set up properties up-front)...
// TextParamWide is split between TextBlockProperties, ParagraphProperties, and RunProperties. TextSizeParam (now simply a DPoint2d in UORs) is on RunProperties (via (Get|Set)FontSize).
TextBlockPropertiesPtr tbProps = textBlock->GetProperties ().Clone ();
tbProps->Set... ();
textBlock->SetProperties (*tbProps);

textBlock->GetParagraphPropertiesForAddR ().Set... ();
textBlock->GetRunPropertiesForAddR ().Set... ();

textBlock->SetUserOrigin (...);
textBlock->SetOrientation (...);

// Add text...
textBlock->AppendText (...);
textBlock->AppendEnterDataField (...);

// Create the element...
EditElementHandle eeh;
if (TextBlock::TO_ELEMENT_RESULT_Success != TextHandlerBase::CreateElement (eeh, NULL /* use the template if you have it */, *textBlock))
    /* ERROR */

// eeh now contains a text element (or node) that you can AddToModel etc.

Remarks

Required Library: mdlbltin.lib

int mdlText_expandString	(	WStringR	outBuffer,
		WCharCP	inBuffer,
		int	conversionType
	)

Scans the input string for single-character fractions and/or escape sequences (determined by conversionType), turning them into font-agnostic representations that can be round-tripped with a "compress" function.

Note

The MSWideChar parameter(s) have changed to WChar/WString (a.k.a. wchar_t). WChar is always Unicode, is a native Windows- and CRT-supported data type, and does not need to vary with the font used. Elements maybe still store locale-encoded text, but you no longer need to account for this when using the API.

Deprecated:

Acquire the appropriate font object (see DgnFontManager and DgnFontNumMap), and call ExpandRscFractions and/or ExpandEscapeSequences.

// Instead of using an "active" or "loaded" font, you should acquire the appropriate DgnFont object directly. For instance:
DgnFontCR   font        = <DgnFileR>.GetDgnFontMapP ()->ResolveFont (<FontNumber>);            // <DgnFileR> such as ISessionMgr::GetActiveFile ().
DgnFontCP   newFont;    DgnTextStyle::GetActive ()->GetProperty (TextStyle_Font, newFont); // While this interface deals with DgnFontCP, it should never fail to provide a value for TextStyle_Font.

WString uniString = ...;

font.ExpandEscapeSequences (uniString.c_str (), uniString); // Dereference font if required based on how you got and verified the font object.
font.ExpandRscFractions (uniString.c_str (), uniString);    // Dereference font if required based on how you got and verified the font object.

Remarks

Required Library: mdlbltin.lib

int mdlText_expandTabs	(	WStringR	outstring,
		WCharCP	instring,
		int	tabInterval
	)

Replaces tab characters with space characters, attempting to preserve alignment by inserting the appropriate number of spaces.

This is only meaningful for fixed-width fonts.

Deprecated:

This utility has been deprecated, with no direct replacement. When dealing with text elements, the TextBockAPI can handle tabs (see AppendTab; and ParagraphProperties for tab settings), and should be used instead of faking alignment with spaces.

int mdlText_extract	(	WStringP	wString,
		DPoint3dP	origin,
		DPoint3dP	userOrigin,
		RotMatrixP	rotMatrix,
		DgnPlatform::TextSizeParam *	textSize,
		DgnPlatform::TextParamWide *	textParam,
		TextEDParamP	edParam,
		MSElementCP	in
	)

Gets formatting information and text content from the provided text element.

Note

The MSWideChar parameter(s) have changed to WChar/WString (a.k.a. wchar_t). WChar is always Unicode, is a native Windows- and CRT-supported data type, and does not need to vary with the font used. Elements maybe still store locale-encoded text, but you no longer need to account for this when using the API.

Deprecated:

It is recommended that you create a TextBlock out of the element, and query the properties and content from there.

See also

mdlTextNode_extract for porting recommendations.

Remarks

Required Library: mdlbltin.lib

void mdlText_extractFontStyle	(	MSElementCP	u,
		DgnPlatform::TextStyleInfo *	tfs
	)

Gets formatting information from the provided text element.

Deprecated:

It is recommended that you create a TextBlock out of the element, and query the properties from there.

See also

mdlTextNode_extract for porting recommendations.

Remarks

Required Library: mdlbltin.lib

int mdlText_extractShape	(	Dpoint3d	rPoints[5],
		DPoint3dP	rOrigin,
		MSElementCP	in,
		int	addSnaptol,
		int	view
	)

Computes fitted box points around a text element.

Deprecated:

It is recommended that you create a TextBlock out of the element, and call GetNominalRange. You may then transform this range as you wish (e.g. GetUserOrigin and GetOrientation), and create an array of points if that was actually the desired end result.

See also

textNode_extractShape for porting recommendations.

Remarks

Required Library: mdlbltin.lib

int mdlText_extractString	(	WStringR	wString,
		MSElementCP	el
	)

Gets text content from the provided text element.

Note

The MSWideChar parameter(s) have changed to WChar/WString (a.k.a. wchar_t). WChar is always Unicode, is a native Windows- and CRT-supported data type, and does not need to vary with the font used. Elements maybe still store locale-encoded text, but you no longer need to account for this when using the API.

Deprecated:

It is recommended that you create a TextBlock out of the element, and query the content from there.

See also

mdlTextNode_extract for porting recommendations.

Remarks

Required Library: mdlbltin.lib

int mdlText_extractStringsFromDscr	(	WStringR	buffer,
		MSElementDescrP	in
	)

Gets the concatenation of all strings in a text node.

Note

The MSWideChar parameter(s) have changed to WChar/WString (a.k.a. wchar_t). WChar is always Unicode, is a native Windows- and CRT-supported data type, and does not need to vary with the font used. Elements maybe still store locale-encoded text, but you no longer need to account for this when using the API.

Deprecated:

It is recommended that you create a TextBlock out of the element, and get the string value from it. Better yet, you can use a Caret to walk the runs of a TextBlock, which allows you to get text content, stacked fractions, and special whitespace.

ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

// Returns a Unicode string representing the entire text node (or element). Special whitespace (e.g. paragraph breaks, line breaks, and tabs) is indicated as escape characters in the string.
WString textValue = textBlock->ToString ();

// This value is Unicode (differs from old function); this is the recommended string encoding, and you should update your application to use it, as opposed to down-converting this to a locale-encoded string.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlText_extractW	(	WCharP	string,
		DPoint3dP	origin,
		DPoint3dP	userOrigin,
		RotMatrixP	rotMatrix,
		DgnPlatform::TextSizeParam *	textSize,
		DgnPlatform::TextParamWide *	textParam,
		TextEDParamP	edParam,
		MSElementDescrP	ed
	)

Gets formatting and text data from the provided text element.

Deprecated:

It is recommended that you create a TextBlock out of the element, and query the properties from there. You can also use the getters on TextElemHandler for direct access.

ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

// Often, getting the parameters was only required to modify the text and re-create it. If this is your goal, instead of acquiring the properties, mutate the TextBlock in-place and re-generate the element.
// There is no direct equivalent to getting the element origin (lower-left) from a TextBlock; only user origin is supported. The user origin is the data point / snap point used to create the text, and affects how it flows and positions itself as its content changes. Element origins were always lower-left, and failure to keep this concept synchronized with the user origin resulted in poorly positioned text.

WString     string      = textBlock->ToString ();
DPoint3d    userOrigin  = textBlock->GetUserOrigin ();
RotMatrix   rotMatrix   = textBlock->GetOrientation ();

// If the TextBlock came from a text element, querying the paragraph and run formatting at the beginning is sufficient (since it will not have heterogeneous formatting).
CaretPtr caret = textBlock->CreateStartCaret ();

// TextParamWide is split between TextBlockProperties, ParagraphProperties, and RunProperties. TextSizeParam (now simply a DPoint2d in UORs) is on RunProperties (via (Get|Set)FontSize).
textBlock->GetProperties ().Get/Is... ();
caret->GetCurrentParagraphCP ()->GetProperties ().Get/Is... ();
caret->GetCurrentRunCP ()->GetProperties ().Get/Is... ();

// There is no direct equivalent to TextEDParam in TextBlock. You must iterate the runs and dynamic_cast to an EdfCharStream to get EDF information.

// To mutate the TextBlock, see methods such as TextBlock::Clear (), TextBlock::AppentText (), TextBlock::InsertText (), TextBlock::Remove (), TextBlock::SetParagraphPropertiesForAdd (), and TextBlock::SetRunPropertiesForAdd ().
// To create the updated element, see TextHandlerBase::CreateElement, then you can use standard EditElementHandle methods (such as EditElementHandle::ReplaceInModel ()).

int mdlText_getElementDescr	(	MSElementDescrH	outEdPP,
		DgnPlatform::Text_2d *	pTextElm,
		RotMatrixP	viewRMatrixP
	)

Drops a text (or text node) element to geometry.

If the text was view independent, and an orientation is provided, the resulting geometry will be transformed to that orientation.

Deprecated:

Get the element's DisplayHandler, and call Drop with the DropGeometry::OPTION_Text option.

ElementHandle   eh              (...);
DisplayHandlerP displayHandler  = eh.GetDisplayHandler ();
if (NULL == displayHandler)
    /* ERROR */

ElementAgenda agenda;
if (SUCCESS != displayHandler->Drop (eh, agenda, DropGeometry (DropGeometry::OPTION_Text)))
    /* ERROR */

// Work with the dropped elements inside the agenda. For instance, loop over the agenda, and call AddToModel to emit the dropped geometry to the file.

Remarks

Required Library: mdlbltin.lib

int mdlText_getElementDescrWithModelRef	(	MSElementDescrH	outEdPP,
		DgnPlatform::Text_2d *	pTextElm,
		RotMatrixP	viewRMatrixP,
		DgnModelRefP	modelRef
	)

Drops a text (or text node) element to geometry.

If the text was view independent, and an orientation is provided, the resulting geometry will be transformed to that orientation.

Deprecated:

Get the element's DisplayHandler, and call Drop with the DropGeometry::OPTION_Text option.

See also

mdlText_getElementDescr for porting recommendations.

Remarks

Required Library: mdlbltin.lib

int mdlText_getFontInfo	(	DgnPlatform::TextFontInfo *	tfiP,
		UInt32	fontNum
	)

Determines if a font by that number already exists.

RSC fonts will be found regardless of use in the file; SHX and TrueType fonts will only be found if they've already been used in the file.

Deprecated:

Use the DgnFontManager and DgnFontNumMap APIs for dealing with fonts.

   bool fontExists = (NULL != <DgnFileR>.GetDgnFontMapP ()->GetFontP (<FontNumber>)); // <DgnFileR> such as ISessionMgr::GetActiveFile ().
   @encode
   @remark Required Library: mdlbltin.lib
bool mdlText_fontExists (int fontNum);

   Gets metric information about a font.
   @deprecated This utility has been deprecated, with no direct replacement.
   @code
   DgnFontCR font = <DgnFileR>.GetDgnFontMapP ()->ResolveFont (<FontNumber>); // <DgnFileR> such as ISessionMgr::GetActiveFile ().
   
   // These properties can still be computed:
   TextFontInfo.lettersType.upper  = font.IsCharacterPresent (L'A');
   TextFontInfo.lettersType.lower  = font.IsCharacterPresent (L'a');
   TextFontInfo.lettersType.space  = font.IsCharacterPresent (L' ');
   TextFontInfo.lettersType.filled = font.IsOutlineFont ();
   TextFontInfo.lettersType.fract  = (font.GetMaxFractionDenominator () > 0);
   TextFontInfo.charType           = (font.IsSymbolFont () ? TXTFONT_SYMBOL : TXTFONT_NORMAL);
   
   // These properties are hard-coded to these values, and are no longer useful.
   TextFontInfo.lettersType.intl   = true;
   TextFontInfo.lettersType.fast   = false;
   TextFontInfo.vectorSize         = 2;
   TextFontInfo.graphicType        = 0;
   TextFontInfo.charSize           = 1;
   TextFontInfo.tileSize           = 1;
   TextFontInfo.dataSize           = 1;
   TextFontInfo.origin.x           = 0;
   TextFontInfo.origin.y           = 0;
   TextFontInfo.scale.x            = 1.0;
   TextFontInfo.scale.y            = 1.0;

Remarks

Required Library: mdlbltin.lib

int mdlText_nodeFromText	(	DgnPlatform::Text_node_2d *	nodeTemplate,
		DgnPlatform::Text_2d *	textTemplate
	)

Creates a text node template from a text element.

Deprecated:

The TextBlock API accepts either element type as a template, and will generate an element or node as required by content or formatting automatically. You should not have to manually deal with text element vs. node specifics.

See also

mdlTextNode_create for an example of creating a text element or node.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlText_nodeFromTextExt	(	DgnPlatform::Text_node_2d *	nodeTemplate,
		DgnPlatform::Text_2d *	textTemplate,
		int *	pNodeNumber
	)

Creates a text node template element from a text element.

Deprecated:

TextBlock knows how to promote a text element to a node when required. You can can force it to generate a text node by calling SetForceTextNodeFlag.

ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

textBlock->SetForceTextNodeFlag (true);
// Work with textBlock.

EditElementHandle eeh;
if (TextBlock::TO_ELEMENT_RESULT_Success != TextHandlerBase::CreateElement (eeh, &eh, *textBlock))
    /* ERROR */

// eeh now contains a text node, regardless of the TextBlock content.

void mdlText_setTextParamWideCodePage	(	DgnPlatform::TextParamWide *	textParamWide,
		LangCodePage	codePage
	)

Sets the code page (and associated flag) on a TextParamWide structure.

Warning

The required code page is that of the font, and should not be arbitrarily set; setting this to other values can result in corrupt elements.

Deprecated:

Use the TextBlock API to create elements; this API is an abstraction over the low-level TextParamWide, and will guarantee that the code page is set correctly.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlText_strokeToElementDescr	(	MSElementDescrH	outEdPP,
		MSElementDescrP	pTextOrNodeElmDscr,
		RotMatrixP	viewRMatrixP,
		DgnModelRefP	modelRef
	)

Drops a text (or text node) element to geometry.

If the text was view independent, and an orientation is provided, the resulting geometry will be transformed to that orientation.

Deprecated:

Get the element's DisplayHandler, and call Drop with the DropGeometry::OPTION_Text option.

ElementHandle   eh              (...);
DisplayHandlerP displayHandler  = eh.GetDisplayHandler ();
if (NULL == displayHandler)
    /* ERROR */

ElementAgenda agenda;
if (SUCCESS != displayHandler->Drop (eh, agenda, DropGeometry (DropGeometry::OPTION_Text)))
    /* ERROR */

// Work with the dropped elements inside the agenda. For instance, loop over the agenda, and call AddToModel to emit the dropped geometry to the file.

int mdlText_textFromNode	(	MSElementP	pElementOut,
		MSElementCP	elementIn
	)

Creates a text element template from a text node.

Deprecated:

The TextBlock API accepts either element type as a template, and will generate an element or node as required by content or formatting automatically. You should not have to manually deal with text element vs. node specifics.

See also

mdlTextNode_create for an example of creating a text element or node.

Remarks

Required Library: mdlbltin.lib

int mdlTextNode_create	(	MSElementP	pElementOut,
		MSElementP	pTemplateElement,
		DPoint3dP	dOrigin,
		RotMatrixP	rotMatrix,
		double *	lineSpacing,
		DgnPlatform::MSTextSize *	size,
		DgnPlatform::TextParam *	txtParams
	)

Creates a blank text node element.

Deprecated:

Use the TextBlock API to create text or text node elements; this API will create either element type based on the requirements of the content and formatting you provide. Note that the TextBlock API does not allow direct control over text element vs. text node; the most appropriate one is chosen. You thus do not have to create a blank text node first and fill it in; it is done in one operation now.

// If you want to start with active settings, or from any other DgnTextStyle object...
TextBlockPtr textBlock = TextBlock::Create (*DgnTextStyle::GetActive (*ISessionMgr::GetActiveDgnFile ()), *ISessionMgr::GetActiveDgnModelP ());

// -or- If you want to start from an existing template element...
ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

textBlock->Clear ();

// -or- If you want to start from scratch...
TextBlockPtr textBlock = TextBlock::Create (*ISessionMgr::GetActiveDgnModelP ());

// -or- You can manually configure the settings up front...

TextBlockPropertiesPtr  tbProps     = TextBlockProperties::Create (...);
ParagraphPropertiesPtr  paraProps   = ParagraphProperties::Create (...);
RunPropertiesPtr        runProps    = RunProperties::Create (...);

tbProps.Set... ();
paraProps.Set... ();
runProps.Set... ();

TextBlockPtr textBlock = TextBlock::Create (*tbProps, *paraProps, *runProps, *ISessionMgr::GetActiveDgnModelP ());

// Then tweak as desired (if you didn't set up properties up-front)...
// TextParamWide is split between TextBlockProperties, ParagraphProperties, and RunProperties. TextSizeParam (now simply a DPoint2d in UORs) is on RunProperties (via (Get|Set)FontSize).
TextBlockPropertiesPtr tbProps = textBlock->GetProperties ().Clone ();
tbProps->Set... ();
textBlock->SetProperties (*tbProps);

textBlock->GetParagraphPropertiesForAddR ().Set... ();
textBlock->GetRunPropertiesForAddR ().Set... ();

textBlock->SetUserOrigin (...);
textBlock->SetOrientation (...);

// Add text...
textBlock->AppendText (...);
textBlock->AppendEnterDataField (...);

// Create the element...
EditElementHandle eeh;
if (TextBlock::TO_ELEMENT_RESULT_Success != TextHandlerBase::CreateElement (eeh, NULL /* use the template if you have it */, *textBlock))
    /* ERROR */

// eeh now contains a text element (or node) that you can AddToModel etc.

Remarks

Required Library: mdlbltin.lib

int mdlTextNode_createEx	(	MSElementDescrH	nodeDescrPP,
		MSElementP	nodeTemplate,
		MSElementDescrP	textEdp,
		DPoint3dP	dOrigin,
		RotMatrixP	rotMatrix,
		DgnPlatform::TextSizeParam *	sizeParam,
		DgnPlatform::TextParamWide *	txtParams
	)

Creates a text node element, and appends the contents of the chain of text elements provided.

Note

The provided text elements are not transplanted to the new node; their formatting and contents are extracted and re-appended as new elements.

Deprecated:

Use the TextBlock API to create text or text node elements; this API will create either element type based on the requirements of the content and formatting you provide. Note that the TextBlock API does not allow direct control over text element vs. text node; the most appropriate one is chosen. You thus do not have to worry about creating nodes and filling them in.

See also

mdlTextNode_create for porting recommendations.

Remarks

Required Library: mdlbltin.lib

int mdlTextNode_createWide	(	MSElementP	out,
		MSElementP	in,
		DPoint3dP	userOrigin,
		RotMatrixP	rotMatrix,
		DgnPlatform::TextSizeParam *	size,
		DgnPlatform::TextParamWide *	txtParams
	)

Creates a blank text node element.

Deprecated:

Use the TextBlock API to create text or text node elements; this API will create either element type based on the requirements of the content and formatting you provide. Note that the TextBlock API does not allow direct control over text element vs. text node; the most appropriate one is chosen. You thus do not have to create a blank text node first and fill it in; it is done in one operation now.

See also

mdlTextNode_create for porting recommendations.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlTextNode_createWithStrings	(	MSElementDescrH	nodeDescrPP,
		MSElementCP	nodeTemplate,
		bvector< WString > const &	,
		DPoint3dCP	userOrigin,
		RotMatrixCP	rotMatrix,
		DgnPlatform::TextSizeParam const *	sizeParam,
		DgnPlatform::TextParamWide const *	txtParams,
		TextEDParamCP	textEDParam
	)

Creates a text node with the provided strings, inserting a paragraph break between each one.

Note

The MSWideChar parameter(s) have changed to WChar/WString (a.k.a. wchar_t). WChar is always Unicode, is a native Windows- and CRT-supported data type, and does not need to vary with the font used. Elements maybe still store locale-encoded text, but you no longer need to account for this when using the API.

Deprecated:

Use the TextBlock API to create text or text node elements; this API will create either element type based on the requirements of the content and formatting you provide. Note that the TextBlock API does not allow direct control over text element vs. text node; the most appropriate one is chosen.

See also

mdlTextNode_create for porting recommendations. When appending text, you can call textBlock->AppendParagraphBreak () or textBlock->AppendLineBreak () to create multiple lines.

Remarks

Required Library: mdlbltin.lib

StatusInt mdlTextNode_extract	(	DPoint3dP	userOrigin,
		RotMatrixP	rotMatrix,
		DgnPlatform::MSTextSize *	tileSize,
		double *	lineSpacing,
		DgnPlatform::TextParam *	txtParams,
		int *	nodeNumber,
		MSElementCP	in,
		MSElementDescrCP	edP
	)

Gets formatting from the provided text node.

The formatting stored in the node may or may not actually be used to display the child text elements. The actual display of text is governed by the formatting stored on the individual child text elements.

Deprecated:

It is recommended that you create a TextBlock out of the element, and query the properties from there. It should be noted that TextBlock does not expose a direct equivalent to the formatting data of the text node element itself; it will provide the formatting actually used to display the text (e.g. from the child text elements).

ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

// Often, getting the parameters was only required to modify the text and re-create it. If this is your goal, instead of acquiring the properties, mutate the TextBlock in-place and re-generate the element.
// There is no direct equivalent to getting the element origin (lower-left) from a TextBlock; only user origin is supported. The user origin is the data point / snap point used to create the text, and affects how it flows and positions itself as its content changes. Element origins were always lower-left, and failure to keep this concept synchronized with the user origin resulted in poorly positioned text.

WString     string      = textBlock->ToString ();
DPoint3d    userOrigin  = textBlock->GetUserOrigin ();
RotMatrix   rotMatrix   = textBlock->GetOrientation ();

// If the TextBlock came from a text element, querying the paragraph and run formatting at the beginning is sufficient (since it will not have heterogeneous formatting).
// Otherwise, the element could contain multiple different formats, and you must use a Caret to iterate over the runs and aggregate this information.
CaretPtr caret = textBlock->CreateStartCaret ();

// TextParamWide is split between TextBlockProperties, ParagraphProperties, and RunProperties. TextSizeParam (now simply a DPoint2d in UORs) is on RunProperties (via (Get|Set)FontSize). Line spacing is stored on ParagraphProperties. Node number is no longer directly exposed.
textBlock->GetProperties ().Get/Is... ();
caret->GetCurrentParagraphCP ()->GetProperties ().Get/Is... ();
caret->GetCurrentRunCP ()->GetProperties ().Get/Is... ();

// There is no direct equivalent to TextEDParam in TextBlock. You must iterate the runs and dynamic_cast to an EdfCharStream to get EDF information.

// To mutate the TextBlock, see methods such as TextBlock::Clear (), TextBlock::AppentText (), TextBlock::InsertText (), TextBlock::Remove (), TextBlock::SetParagraphPropertiesForAdd (), and TextBlock::SetRunPropertiesForAdd ().
// To create the updated element, see TextHandlerBase::CreateElement, then you can use standard EditElementHandle methods (such as EditElementHandle::ReplaceInModel ()).
//! 

Remarks

Required Library: mdlbltin.lib

StatusInt mdlTextNode_extractShape	(	Dpoint3d	rPoints[5],
		DPoint3dP	rOrigin,
		MSElementDescrP	edP,
		int	addsnaptol,
		int	view
	)

Computes fitted box points around a text node.

Deprecated:

It is recommended that you create a TextBlock out of the element, and call GetNominalRange. You may then transform this range as you wish (e.g. GetUserOrigin and GetOrientation), and create an array of points if that was actually the desired end result.

ElementHandle   eh          (...);
TextBlockPtr    textBlock   = TextHandlerBase::GetFirstTextPartValue (eh);

if (!textBlock.IsValid ())
    /* ERROR */

// This is the underlying range.
DRange3d nominalRange = textBlock->GetNominalRange ();

// You may then transform, extend, and prepare as you see fit. For example:
DPoint3d shapePts[5];
memset (shapePts, 0, sizeof (shapePts));
            
shapePts[0]    = nominalRange.low;
shapePts[2]    = nominalRange.high;
            
shapePts[1].x  = shapePts[2].x;
shapePts[1].y  = shapePts[0].y;
shapePts[3].x  = shapePts[0].x;
shapePts[3].y  = shapePts[2].y;
            
shapePts[4]    = shapePts[0];

Transform transform;
transform.InitFrom (TextBlock::GetOrientation (), TextBlock::GetUserOrigin ());

transform.Multiply (shapePts, shapePts, 5);

Remarks

Required Library: mdlbltin.lib

int mdlTextNode_extractWide	(	DPoint3dP	userOrigin,
		RotMatrixP	rotMatrix,
		DgnPlatform::TextSizeParam *	txtSizeParam,
		DgnPlatform::TextParamWide *	txtParams,
		MSElementCP	in,
		MSElementDescrCP	edP
	)

Gets formatting from the provided text node.

The formatting stored in the node may or may not actually be used to display the child text elements. The actual display of text is governed by the formatting stored on the individual child text elements.

Deprecated:

It is recommended that you create a TextBlock out of the element, and query the properties from there. It should be noted that TextBlock does not expose a direct equivalent to the formatting data of the text node element itself; it will provide the formatting actually used to display the text (e.g. from the child text elements).

See also

mdlTextNode_extract for porting recommendations.

Remarks

Required Library: mdlbltin.lib