Using the TextBlock Class
Q How do I create a DGN text element using Python?
Q How do I edit a DGN text element using Python?
Q How do I create a Text Field in a DGN text element using Python?
A Use a
TextBlock Class,
which can handle simple and complex text.
It works with TextElements, TextNodeElements and other DGN objects that contain text.
The TextBlock class also lets you insert and modify
Text Fields
in DGN text.
- 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
- To insert a
Text Field into text,
use the
TextBlock.InsertFieldmethod
MicroStationAPI Documentation
A TextBlock is an in-memory abstraction of structured text, using a
Document Object Model (DOM).
Here's what the MicroStationAPI help documentation tells us about it …
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
Examples
We use a TextBlock in these examples …
Questions
Post questions about MicroStation Python programming to the MicroStation Programming Forum.
