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... | |
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.
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.
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.
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.
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.
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:
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.
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.
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:
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.
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.
|
strong |
Line spacing types for MicroStation text elements.
|
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.
|
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.
enum TextBlockToElementResult |
Describes the possible results from generating an element from a TextBlock.
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). |
|
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 |
Create a text field associated with a property of a file. The DgnModel parameter specifies the model containing the field.
|
static |
Create a text field associated with a property of a model, where the field resides within that model.
|
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 |
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 |
Create a placeholder text field to be associated with the field's placement cell. The DgnModel parameter specifies the model containing the field.
|
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 |
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 | ) |