Modules | Classes | Typedefs | Enumerations | Functions

The text module refers to element-based text, including the classes and interfaces that can be used to work both with text elements, and other element types that expose text. More...

Modules

 Text Utility Api
 
 Font Manager
 The DgnFontManager is the root for all font access.
 

Classes

struct  RunPropertiesBase
 Container for the common properties of runs of text. More...
 
struct  Caret
 Represents an insertable location within a TextBlock. More...
 
struct  CharStream
 In the TextBlock DOM, a collection of single-line, single-format characters. More...
 
struct  EdfCharStream
 Enter Data Fields (EDFs) are atomic placeholder runs of pre-defined length (number of characters). More...
 
struct  Fraction
 In the TextBlock DOM, a base class for stacked fractions representing a like-formatted numerator and denominator (supports the presence of both or either). More...
 
struct  NoBarFraction
 In the TextBlock DOM, a class for normal (non-diagonal) stacked fractions, where the numerator and denominator are stacked and horizontally left-aligned (with NO separator). More...
 
struct  HorizontalBarFraction
 In the TextBlock DOM, a class for normal (non-diagonal) stacked fractions, where the numerator and denominator are individually horizontally centered (with separator). More...
 
struct  DiagonalBarFraction
 In the TextBlock DOM, a class for diagonal stacked fractions, where the numerator and denominator are separated by a diagnoal line (hard-coded slant angle). More...
 
struct  IDgnTextStyleApplyable
 Interface that TextBlock DOM property objects use to work with DgnTextStyle objects. More...
 
struct  IndentationData
 Storage and utility class for managing a Paragraph object's indentation properties. More...
 
struct  ParagraphProperties
 Represents the properties that can be controlled on a per-Paragraph basis. More...
 
struct  Paragraph
 In the TextBlock DOM, a collection of lines and runs. More...
 
struct  Run
 In the TextBlock DOM, a base class for all other runs. More...
 
struct  RunProperties
 Describes the formatting and spacing paramters for a single run of text that TextBlock supports. More...
 
struct  TextBlockProperties
 Represents the properties that can be controlled on a per-TextBlock basis. More...
 
struct  TextBlock
 In the TextBlock DOM, this is the master object that represents a piece of text as a whole, and is the primary high-level object used to deal with multi-line, formatted text (and is also generally recommended for any text, regardless of complexity). More...
 
struct  ParagraphIterator
 An STL iterator-like wrapper around Caret, that allows you to easily iterate paragraphs. More...
 
struct  ParagraphRange
 Facilitates writing for-each loops for ParagraphIterator. More...
 
struct  RunIterator
 An STL iterator-like wrapper around Caret, that allows you to iterate runs. More...
 
struct  RunRange
 Facilitates writing for-each loops for RunIterator. More...
 
struct  TextField
 
struct  WhiteSpace
 In the TextBlock DOM, an abstract base class representing all whitespace types, and is not to be used directly. More...
 
struct  ParagraphBreak
 In the TextBlock DOM, a carriage return, or paragraph break. This kind of run is used to denote a hard carriage return, forcing the creation of a new paragraph (and hence a new line). More...
 
struct  LineBreak
 In the TextBlock DOM, a line feed, or line break. This kind of run is used to denote a hard line feed, forcing the creation of a new line in the same paragraph. This is different than transparent soft line feeds, which denote new lines based on word-wrapping. More...
 
struct  Tab
 In the TextBlock DOM, a tab. This kind of run is used to advance the following run to the next tab stop, as stored/computed by the current paragraph. More...
 
struct  TextString
 Used to draw a single-line collection of like-formatted characters; this class is targetted at performance, is immutable, and cannot create elements. More...
 
struct  TextStringProperties
 Describes the formatting and spacing paramters for a single run of text that TextString supports. More...
 

Typedefs

typedef RefCountedPtr< TextBlock > TextBlockPtr
 Smart pointer wrapper for TextBlock. More...
 
typedef RefCountedPtr
< TextBlockProperties > 
TextBlockPropertiesPtr
 Smart pointer wrapper for TextBlockProperties. More...
 
typedef RefCountedPtr
< ParagraphProperties > 
ParagraphPropertiesPtr
 Smart pointer wrapper for ParagraphProperties. More...
 
typedef RefCountedPtr
< RunProperties > 
RunPropertiesPtr
 Smart pointer wrapper for RunProperties. More...
 
typedef RefCountedPtr
< IndentationData > 
IndentationDataPtr
 Smart pointer wrapper for IndentationData. More...
 
typedef RefCountedPtr< Caret > CaretPtr
 Smart pointer wrapper for Caret. More...
 
typedef RefCountedPtr< TextField > TextFieldPtr
 Smart pointer wrapper for TextField. More...
 
typedef RefCountedPtr< TextString > TextStringPtr
 Smart pointer wrapper for TextString. More...
 
typedef RefCountedPtr
< TextStringProperties > 
TextStringPropertiesPtr
 Smart pointer wrapper for TextStringProperties. More...
 

Enumerations

enum  DgnLineSpacingType { Exact = 0, Automatic = 1, ExactFromLineTop = 2, AtLeast = 3 }
 Line spacing types for MicroStation text elements. More...
 
enum  StackedFractionAlignment { Bottom = 0, Middle = 1, Top = 2, None = 3 }
 Describes how a fraction is aligned to neighboring runs. More...
 
enum  EdfJustification : byte { Left = 0xff, Center = 0x00, Right = 0x01 }
 If an EDF (Enter Data Field) does not have its entire length used, this describes how to align the text within the EDF. More...
 
enum  TextBlockToElementResult { TEXTBLOCK_TO_ELEMENT_RESULT_Success, TEXTBLOCK_TO_ELEMENT_RESULT_Error, TEXTBLOCK_TO_ELEMENT_RESULT_Empty }
 Describes the possible results from generating an element from a TextBlock. More...
 

Functions

DGNPLATFORM_EXPORT bool GetDisplayValue (WStringR displayValue) const
 Evaluate the property value in terms of its target and apply formatting. More...
 
DGNPLATFORM_EXPORT WString FormatValue (ECN::ECValueCR v, DgnECInstanceCR source, WCharCP accessString) const
 
DGNPLATFORM_EXPORT void SetFieldCreationContext (bool)
 
DGNPLATFORM_EXPORT
ECN::IECInstanceCP 
GetFormatter () const
 Returns the options describing how to format the field's display value, or nullptr if no special formatting options are defined. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreateForElement (DgnElementECInstanceCR instance, WCharCP accessString, ECN::IECInstanceCP formatter, DgnModelR model)
 Create a text field associated with a property of an element residing within the same model as the field or within a direct attachment of the field's model. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreateForModel (DgnECInstanceCR instance, WCharCP accessString, ECN::IECInstanceCP formatter)
 Create a text field associated with a property of a model, where the field resides within that model. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreateForFile (DgnECInstanceCR instance, WCharCP accessString, ECN::IECInstanceCP formatter, DgnModelR model)
 Create a text field associated with a property of a file. The DgnModel parameter specifies the model containing the field. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreatePlaceHolderForCell (ECN::ECPropertyCR ecproperty, ECN::IECInstanceCP formatter, DgnModelR model)
 Create a placeholder text field to be associated with the field's placement cell. The DgnModel parameter specifies the model containing the field. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreatePlaceHolderForSignatureCell (ECN::ECPropertyCR ecproperty, ECN::IECInstanceCP formatter, DgnModelR model)
 Create a placeholder text field to be associated with the digital signature cell into which the field will be placed. The DgnModel parameter specifies the model containing the field. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreatePlaceHolderForLink (ECN::ECPropertyCR ecproperty, ECN::IECInstanceCP formatter, WCharCP linkAncestorKey, DgnModelR model)
 Create a placeholder text field to be associated with a link attached to the cell at placement. The DgnModel parameter specifies the model containing the field. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreateForSheetIndex (DgnECInstanceCR instance, WCharCP accessString, DgnModelP textHostModel, ECN::IECInstanceCP formatter)
 Create a text field associated with a property of the sheet index that contains the given sheet model. The text field resides within the given sheet model. More...
 
static DGNPLATFORM_EXPORT
TextFieldPtr 
CreateForSheetIndexFolder (DgnECInstanceCR instance, WCharCP accessString, DgnModelP textHostModel, ECN::IECInstanceCP formatter)
 Create a text field associated with a property of the sheet index folder that contains the given sheet model. The text field resides within the given sheet model. More...
 

Detailed Description

The text module refers to element-based text, including the classes and interfaces that can be used to work both with text elements, and other element types that expose text.

Overview

Text in MicroStation takes many forms. For example, there are free-standing text elements, dimensions, notes, tags, as well as many other custom element types that contain text. The bulk of the text module documentation refers to a relatively abstract form of text that is supported by all of the above: the TextBlock. Free-standing text is represented by text node elements and text elements (henceforth referred to simply as text elements), and aside from being compatible with TextBlock are also input to the TextString object, which can be used to draw and measure text. Text in public interfaces is typically represented by the TextBlock class. TextBlock, aside from being a container for formatting and strings, can perform layout, and computes the origins of runs and lines based on formatting options.

Note
While MicroStation still supports locale-encoded fonts (e.g. MicroStation RSC fonts and non-Unifont SHX fonts), and the underlying file format still stores text in the locale of its font, the API strives to only deal in Unicode (specifically, UCS-2 encoding), and it will do required conversions only when necessary. Keep in mind that just because you can provide a Unicode string doesn't mean that the font you provided allows the piece of text to display all of the characters.

Generic Query/Edit

While text elements are used to store generic free-standing text, there are many other element types that can expose text for purposes of querying and/or editing. If you want to work with text at a level above specific element types, use the ITextQuery and ITextEdit interfaces (e.g. dynamic cast the handler to ITextQuery or ITextEdit; if you have an ElementHandle, see ElementHandle::GetITextQuery and ElementHandle::GetITextEdit). This utilizes TextBlock to transfer text data back and forth. The ITextQuery interface can also be used to identify free-standing text elements via ITextQuery::IsTextElement; this can be used to determine if an element can simply expose text, as opposed to actually being text.

Modifying Text

The primary class used for modifying text element data (including reading/writing free-standing text elements) is TextBlock. It is a high-level object that allows for mixed formatting and layout (e.g. for multiple lines), as well as many operations to modify its data. In the vast majority of cases, you will want to use TextBlock to read/write even text elements. A TextBlock will directly read/write both type 17 text elements and type 7 text node elements as appropriate. A TextBlock can also be provided to other high-level interfaces, and element types such as dimensions can process a TextBlock and create appropriate dimension elements.

Drawing and Measuring Text

The primary class used for drawing (and measuring) text is TextString. It is a performance-oriented immutable single-line collection of like-formatted characters, and can be created from text elements or from raw information (e.g. a Unicode string and TextStringProperties). A TextString can be thought of as analagous to a type 17 text element, although it cannot be used to generate such an element.

Text Block API

The Text Block API (centered around the TextBlock class) is meant to be the full-featured way to read, modify, and create text in MicroStation. It should replace all mdlText_*, mdlTextNode_*, and line arranger functionality. While this API was targetted at dealing with text elements, it is generic enough to support other element types that can expose text, even if they do not directly work with text elements. You should never attempt to deal directly with text elements (via the handler or otherwise); this API will ensure valid elements are written to the file, and will work around bad data if possible when reading from the file.

It is important to note that TextBlock objects are meant to be short-lived, and are only valid in the context of a single DgnModel. Storing TextBlock objects for long periods of time can potentially invalidate cached data, and attempting to mix and match TextBlock objects from different caches can lead to (at least) unit and color problems.

The implementation details of the C++ objects that represent the pieces of the DOM are hidden, and the only way to 'own' any TextBlock-related objects to ask a factory method to give you a smart pointer. In most circumstances, providing an object you created to TextBlock will cause it to clone the object and own the copy; thus you cannot provide TextBlock an object, and modify it later hoping it will modify any internals of the TextBlock.

The classes you will most often use are:

TextBlock as a DOM (Document Object Model)

The TextBlock class represents a DOM of paragraphs, lines, and runs. A line is merely a layout concept, and is not directly exposed, so most discussion only involves TextBlock as a whole (which contains one or more paragraphs), paragraphs (which can be thought of as containing one or more runs), and runs. TextBlock as a whole is your primary mechanism for accessing document properties, as well as appending and modifying text. Paragraphs are relatively thin wrappers, and exist primarily to hold a small set of per-paragraph properties. Runs represent the most atomic units of the DOM, and can never span lines (or paragraphs). In a word-wrapped document, runs will be provided based on how the layout split the runs for word-wrapping.

Navigating the DOM

The primary object for navigating the DOM is the Caret. Just as with a text editor, a Caret is an indicator between two characters that indicates a position. This particular implementation tracks a single character index, but is generally treated as if the caret sits just before the character it indicates. Most methods used to edit a TextBlock accept one or more Caret objects to identify the region being modified. Caret objects are intrinsically associated with a TextBlock, and have getters to provide the current TextBlock, Paragraph, and Run they point at (if available). It also has several methods for moving carets in both directions.

Using TextBlock...

...To Read Text

To read text, you should acquire a TextBlock through ITextQuery, and then create one or more carets to traverse the DOM, extracting data as necessary. The pseudocode below shows a common loop to process a TextBlock:

// Ensure that the element can expose text.
// If you only want to process free-standing text elements, you can check textQueryHandler->IsTextElement (), which implies a single piece of text.
ITextQueryCP textQueryHandler = eh.GetITextQuery ();
if (NULL == textQueryHandler)
return;
// Some elements expose multiple pieces of text (e.g. dimensions); in general, you must be prepared to accept multiple pieces of text, unless textQueryHandler->IsTextElement ().
// Some element handlers (or associated APIs) will provide pieces of text via TextBlock through their own more specific getter methods, bestowing specific meanings to each piece of text.
textQueryHandler->GetTextPartIds (eh, *ITextQueryOptions::CreateDefault (), textPartIds);
for each (ITextPartIdPtr textPartId in textPartIds)
{
// Ask the handler for the specific piece of text.
// The TextBlock is in no way directly tied to the underlying textual data, and you must use ITextEdit::ReplaceText to actually modify the element.
TextBlockPtr textBlock = textQueryHandler->GetTextPart (eh, *textPartId);
// Each paragraph has unique properties, so to consume all properties, you must iterate paragraphs.
// You could also simply iterate runs and continually check to see if the paragraph or paragraph properties has changed.
for (CaretPtr paragraphCaret = textBlock->CreateStartCaret (); !paragraphCaret->IsAtEnd (); paragraphCaret->MoveToNextParagraph ())
{
// Perform logic to deal with the new paragraph; get the current paragraph using paragraphCaret->GetCurrentParagraphCP ().
CaretPtr runCaret = paragraphCaret->Clone ();
do
{
// Perform logic to deal with the new run; get the current run using runCaret->GetCurrentRunCP ().
// You will likely want to find a way to switch on run type in order to gather specific information about each (e.g. CharStream, Fraction, ParagraphBreak, LineBreak, and Tab).
}
while (SUCCESS == runCaret->MoveToNextRunInParagraph ());
}
}

...To Create Text

Free-standing text elements can be created by first creating a TextBlock, setting properties and adding runs, and then generating an element from it. See TextBlock::Create, and TextHandlerBase::CreateElement. TextBlock contains methods for adding specific kinds of runs (e.g. TextBlock::AppendText and TextBlock::AppendParagraphBreak). Additionally, the only DOM object you will create directly is the TextBlock itself; all other DOM objects will be created on your behalf (e.g. runs and paragraphs). The instance of the TextBlock stores a ParagraphProperties and a RunProperties that will be used when appending paragraphs and runs. All DOM objects added will assume these properties until you change them.

TextBlockPtr textBlock = TextBlock::Create (*myTextStyle, myDgnCache);
// Non-formatting information, such as origin and rotation, are accessed directly on TextBlock.
textBlock->SetUserOrigin (...);
textBlock->SetOrientation (...);
// Append the paragraphs, setting unique properties, and then adding their child runs.
foreach (ParagraphToAdd)
{
if (!textBlock->IsEmpty ())
textBlock->AppendParagraphBreak (...);
// If paragraph properties have changed...
ParagraphPropertiesPtr paraProps = ParagraphProperties::Create (...); // or textBlock->GetParagraphPropertiesForAdd ().Clone ();
paraProps->Set... (...);
...
textBlock->SetParagraphPropertiesForAdd (*paraProps);
// Append the runs.
foreach (RunToAdd in ParagraphToAdd)
{
// If run properties have changed...
RunPropertiesPtr runProps = RunProperties::Create (...); // or textBlock->GetRunPropertiesForAdd ().Clone ();
runProps->Set... (...);
...
textBlock->SetRunPropertiesForAdd (*runProps);
textBlock->AppendText (...);
// -or-
textBlock->AppendFraction (...);
// -or-
textBlock->AppendLineBreak (...);
// -or-
textBlock->AppendTab (...);
}
}
EditElementHandle eeh;
return ERROR;
return SUCCESS;

Typedef Documentation

typedef RefCountedPtr<Caret> CaretPtr

Smart pointer wrapper for Caret.

typedef RefCountedPtr<IndentationData> IndentationDataPtr

Smart pointer wrapper for IndentationData.

typedef RefCountedPtr<ParagraphProperties> ParagraphPropertiesPtr

Smart pointer wrapper for ParagraphProperties.

typedef RefCountedPtr<RunProperties> RunPropertiesPtr

Smart pointer wrapper for RunProperties.

typedef RefCountedPtr<TextBlockProperties> TextBlockPropertiesPtr

Smart pointer wrapper for TextBlockProperties.

typedef RefCountedPtr<TextBlock> TextBlockPtr

Smart pointer wrapper for TextBlock.

typedef RefCountedPtr<TextField> TextFieldPtr

Smart pointer wrapper for TextField.

typedef RefCountedPtr<TextStringProperties> TextStringPropertiesPtr

Smart pointer wrapper for TextStringProperties.

typedef RefCountedPtr<TextString> TextStringPtr

Smart pointer wrapper for TextString.

Enumeration Type Documentation

enum DgnLineSpacingType
strong

Line spacing types for MicroStation text elements.

Enumerator
Exact 

Displacement of subsequent line is the existing line's max cell box displacement above origin + value.

Automatic 

DO NOT USE; same as exact - exists to interpret old data.

ExactFromLineTop 

Emulates the DWG "exactly" / "exact from line top" line spacing type.

AtLeast 

Emulates the DWG "at least" line spacing type.

enum EdfJustification : byte
strong

If an EDF (Enter Data Field) does not have its entire length used, this describes how to align the text within the EDF.

For compliance with old data, you should typically check for center and right, and assume any other value is effectively left.

Enumerator
Left 

The unoccupied length is padded to the right with spaces.

Center 

The unoccupied length is padded to the left and right with spaces (with excess on the right if required)

Right 

The unoccupied length is padded to the left with spaces.

enum StackedFractionAlignment
strong

Describes how a fraction is aligned to neighboring runs.

Since fractions are typically taller than surrounding runs, this describes how smaller runs are arranged around the fraction. Although it's technically how other runs align to the fraction, this property is on the fraction itself.

Enumerator
Bottom 

Surrounding text's baseline matches the baseline of the denominator.

Middle 

Surrounding text is centered with the fraction (based on its cell box)

Top 

Surrounding text's cell box top matches the top of the fraction numerator's cell box.

None 

DO NOT USE; it is used an internal unitialized state; you could use it for similar, but don't pass around expecting any predictable to happen.

enum TextBlockToElementResult

Describes the possible results from generating an element from a TextBlock.

See also
TextHandlerBase::CreateElement.
Enumerator
TEXTBLOCK_TO_ELEMENT_RESULT_Success 

The operation completed successfully.

TEXTBLOCK_TO_ELEMENT_RESULT_Error 

An unknown failure occured; no element was created.

TEXTBLOCK_TO_ELEMENT_RESULT_Empty 

An element was not created because an empty TextBlock was provided (and it did not have the force text node flag).

Function Documentation

static DGNPLATFORM_EXPORT TextFieldPtr CreateForElement ( DgnElementECInstanceCR  instance,
WCharCP  accessString,
ECN::IECInstanceCP  formatter,
DgnModelR  model 
)
static

Create a text field associated with a property of an element residing within the same model as the field or within a direct attachment of the field's model.

static DGNPLATFORM_EXPORT TextFieldPtr CreateForFile ( DgnECInstanceCR  instance,
WCharCP  accessString,
ECN::IECInstanceCP  formatter,
DgnModelR  model 
)
static

Create a text field associated with a property of a file. The DgnModel parameter specifies the model containing the field.

static DGNPLATFORM_EXPORT TextFieldPtr CreateForModel ( DgnECInstanceCR  instance,
WCharCP  accessString,
ECN::IECInstanceCP  formatter 
)
static

Create a text field associated with a property of a model, where the field resides within that model.

static DGNPLATFORM_EXPORT TextFieldPtr CreateForSheetIndex ( DgnECInstanceCR  instance,
WCharCP  accessString,
DgnModelP  textHostModel,
ECN::IECInstanceCP  formatter 
)
static

Create a text field associated with a property of the sheet index that contains the given sheet model. The text field resides within the given sheet model.

static DGNPLATFORM_EXPORT TextFieldPtr CreateForSheetIndexFolder ( DgnECInstanceCR  instance,
WCharCP  accessString,
DgnModelP  textHostModel,
ECN::IECInstanceCP  formatter 
)
static

Create a text field associated with a property of the sheet index folder that contains the given sheet model. The text field resides within the given sheet model.

static DGNPLATFORM_EXPORT TextFieldPtr CreatePlaceHolderForCell ( ECN::ECPropertyCR  ecproperty,
ECN::IECInstanceCP  formatter,
DgnModelR  model 
)
static

Create a placeholder text field to be associated with the field's placement cell. The DgnModel parameter specifies the model containing the field.

static DGNPLATFORM_EXPORT TextFieldPtr CreatePlaceHolderForLink ( ECN::ECPropertyCR  ecproperty,
ECN::IECInstanceCP  formatter,
WCharCP  linkAncestorKey,
DgnModelR  model 
)
static

Create a placeholder text field to be associated with a link attached to the cell at placement. The DgnModel parameter specifies the model containing the field.

static DGNPLATFORM_EXPORT TextFieldPtr CreatePlaceHolderForSignatureCell ( ECN::ECPropertyCR  ecproperty,
ECN::IECInstanceCP  formatter,
DgnModelR  model 
)
static

Create a placeholder text field to be associated with the digital signature cell into which the field will be placed. The DgnModel parameter specifies the model containing the field.

DGNPLATFORM_EXPORT WString FormatValue ( ECN::ECValueCR  v,
DgnECInstanceCR  source,
WCharCP  accessString 
) const
DGNPLATFORM_EXPORT bool GetDisplayValue ( WStringR  displayValue) const

Evaluate the property value in terms of its target and apply formatting.

If the target could not be evaluated and this is a placeholder field, sets 'displayValue' to the access string and returns true If any other error occurs, sets 'displayValue' to "####" to indicate an invalid field and returns false

DGNPLATFORM_EXPORT ECN::IECInstanceCP GetFormatter ( ) const

Returns the options describing how to format the field's display value, or nullptr if no special formatting options are defined.

DGNPLATFORM_EXPORT void SetFieldCreationContext ( bool  )

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.