The text item allows editable text strings to be entered. The format of the string can be specified when external application variables are being modified by the text item.
The strings can be range checked against specified minimum and maximum string values. Custom validation can also be performed for an item by attaching a item hook function that processes the DITEM_MESSAGE_FOCUSOUT message. Horizontal scrolling allows the editing of more characters than would otherwise fit inside the text item. The standard undo, cut, copy, and paste operations are supported. Selecting of multiple characters can be done by dragging the mouse cursor through ranges of text.
Item List Specification
The DialogItemRsc field extent specifies the location of the beveled rectangle that contains the text to edit. Any label associated with the text item will be right-justified next to the left edge of this beveled rectangle. If width is 0, the width of the beveled rectangle is calculated with the maximum number of characters the text item can contain. An explicit width should be specified. If height is 0, as it normally should be, the height of the current dialog font will be used.
The type field should be set to Text.
The ID determines the DItem_TextRsc instance to load.
The attributes field can be ON or OFF and optionally combined with HIDDEN. It will usually be ON.
The itemArg field may be set to TEXT_MASK_LABELABOVE to specify that the label should appear above the beveled rectangle. Otherwise, itemArg should usually be set to 0.
The label field can override the label contained in the DItem_TextRsc instance.
The auxInfo field can currently override only the access string contained in the DItem_TextRsc instance.
The following is an example of a text item list specification:
Item Resource Specification
The text item is defined in a resource file with the following structure:
For consistency with MicroStation's dialog boxes, a text item's label should end with a colon. The DItem_TextRsc structure has the following unique fields. (See "Common item resource fields" for a description of any field not in this table)..
| Field | Description |
|---|---|
| maxSize | The maximum number of characters that this text item can edit. |
| formatToDisplay | A sprintf format string to convert the value of the variable specified by accessStr to a string. Usually, the '-' flag character should indicate left justification. For example, %-d left-justifies an integer. Use w to display the variable as a working units string. |
| formatToInternal | A sscanf format string to convert from the text item's string value to the format expected by the variable specified by accessStr. Interpretation of item contents formatToInternal value integer "%ld" floating point number "%lf" working units number "%w" single character "%c" string "" |
| minimum | A string that contains the minimum value of the text item. Specify an empty string (' ') for no minimum value. The minimum value should be specified in a format that the formatToInternal string can process. For example, if formatToInternal is ld, `0' means that the text item must be greater than or equal to 0. If the item's contents are interpreted in working units, the minimum string can be specified as a floating point number. |
| maximum | A string that contains the maximum value of the text item. Specify an empty string (' ') for no maximum. The maximum value should be specified in a format that the formatToInternal string can process. For example, if formatToInternal is ld, `100' means that the text item must be less than or equal to 100. If the item's contents are interpreted in working units, the minimum string can be specified as a floating point number. |
| mask | This field is used only when the text item's contents are interpreted as an integer. In this case, mask indicates which bits of the variable referenced by accessStr will be affected. For example, if mask is 0xF0, formatToInternal is ld, and the text item contains 3, the high nibble of the variable referenced by accessStr is set to 3. Usually, mask should be set to NOMASK (defined to be 0xFFFFFFFF), which indicates that the entire variable is affected. |
| attributes | A short integer that specifies text item characteristics. It is constructed by combining the constants from the following table with the logical OR operator. |
| attributes Value | Meaning |
|---|---|
| TEXT_CONCAT | If commandNumber is added to the end of MicroStation's input queue (usually because the user has moved the input focus out of the item), the text item contents will be included as the unparsed part of the command. For example, when the user tabs out of the "Level: text" item in the Element Attributes dialog box, the command number CMD_ACTIVE_LEVEL is placed on the input queue. In addition, since CONCAT is specified as the text item's attribute, the item's contents are appended to the command number. For example, suppose the text item contains the string "5". Tabbing out of the "Level: text" item simulates the user keying in ACTIVE LEVEL 5. |
| TEXT_NOCONCAT | If commandNumber is added to the end of MicroStation's input queue (usually because the user has moved the input focus out of the item), the contents of the text item will not be included as the unparsed part of the command. |
| TEXT_READONLY | The beveled rectangle around the text item will not be drawn. The user cannot change the text item contents. However, the text item will respond to DITEM_MESSAGE_SYNCHRONIZE messages. This attribute implements a read-back label that automatically changes its text contents depending on the state of some application variable. |
| TEXT_NORESETONERROR | This attribute instructs the item handler to not reset the displayed value of the text item when an error has been detected for the text item. |
| TEXT_ABBREVFILENAME | This attribute instructs the item handler to abbreviate the file name displayed in the text item so that the most significant portion of the file name (the right most display portion) is visible in the text item and the full name is preceeded with a "..." to indicate abbreviation. This attribute implies, and should only be used in, read-only text items. |
The following is an example of a text item resource. This item is used in the Element Attributes dialog box, and is defined in MicroStation's resource file.
Item hook function messages
The following messages are sent to item hook functions that are attached to text items:
DITEM_MESSAGE_CREATE
DITEM_MESSAGE_INIT
DITEM_MESSAGE_DESTROY
DITEM_MESSAGE_SYNCHRONIZE
DITEM_MESSAGE_FOCUSIN
DITEM_MESSAGE_FOCUSOUT
DITEM_MESSAGE_KEYSTROKE
DITEM_MESSAGE_POSTKEYSTROKE
DITEM_MESSAGE_GETSTATE
DITEM_MESSAGE_SETSTATE
DITEM_MESSAGE_STATECHANGED
DITEM_MESSAGE_QUEUECOMMAND
Text Item Functions
| Field | Description |
|---|---|
| mdlDialog_textGetRange | gets a text item's minimum and maximum range strings. |
| mdlDialog_textSetRange | sets the minimum and maximum range strings of a text item. |
| mdlDialog_textGetInfo | retrieves detailed information about a text item. |
| mdlDialog_textSetInfo | sets various aspects of a text item. |