DGN Text
The DGN text with which you're familiar as a MicroStation user is either a Text Element or a Text Node Element. The classes you will use with Python to manipulate, query and create DGN text elements are …
-
TextElemHandler -
TextNodeHandler -
TextBlock
Use the handlers to query text elements.
Use the TextBlock to create a text or text node element.
Use the TextBlock to insert a
Text Field.
When you want to create a text element, let the TextBlock do the work:
it decides what to create, whether a simple text element or a more complex text node.
TextBlock class
The
TextBlock class
is enigmatic: the Python API help lists its methods without telling you much.
The C++ MicroStationAPI help document is more verbose.
It provides this explanation,
which I've copied verbatim from that help document …
MicroStation API: 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).
As described in the Text module documentation, TextBlock consists of a DOM (Document Object Model). Elements of the DOM include Paragraph and Run objects. Internally, lines are also computed, but only affect layout, and are not directly exposed.
- Attention
- TextBlock objects are meant to have a short lifetime, and store information that can potentially become invalidated when retained for a long period of time (e.g. text style indices, or even DGN caches).
You can navigate and identify specific parts of the DOM via the Caret. To acquire a Caret, use CreateStartCaret or CreateEndCaret. You can then ask the Caret for specific information, such as its current paragraph and run, as well as navigate it in either direction. It is important to note that Caret objects merely store indices into the DOM; modifying a TextBlock potentially invalidates any existing Caret objects.
Any DOM objects you obtain from TextBlock are meant to be read-only, and are for reference only. You cannot instantiate DOM objects directly, but must instead ask TextBlock to create and append an object for you. See the Append... methods.
Enter Data Fields (EDFs; represented by EdfCharStream) are atomic runs. While you are free to have a Caret step into the individual characters of these runs for query purposes, you cannot inject characters into them (via Insert* methods), or delete portions of them (via Remove). If you attempt to do so, the API will round to one side or the other to preserve the atomic run.
TextBlock maintains 3 property structures: for itself (TextBlockProperties), and to use for any paragraphs and runs that are added (ParagraphProperties and RunProperties). You do not need to provide property structures each time you append a DOM node; these 'seed' properties are used until they are changed (see SetParagraphPropertiesForAdd and SetRunPropertiesForAdd).
TextBlock I/O:
- To acquire a TextBlock from an element, use the ITextQuery handler interface
- To modify the text of an element, use the ITextQuery and ITextEdit interfaces to get/set the text
- To create a free-standing text element from a TextBlock, use TextHandlerBase::CreateElement
