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.

textit.jpg

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:

{{XC, YC, 5*XC, 0}, Text, TEXTID_ElementLevel, ON, 0, "", ""}

Item Resource Specification

The text item is defined in a resource file with the following structure:

typedef struct ditem_textrsc
{
ULong commandNumber;
ULong commandSource;
long synonymsId;
ULong helpInfo;
ULong helpSource;
long itemHookId;
long itemHookArg;
byte maxSize; // max # of chars in field //
char formatToDisplay[16]; // conv to display from internal //
char formatToInternal[16]; // conv to internal from display //
char minimum[16]; // minimum value //
char maximum[16]; // maximum value //
ULong mask; // only used with integer types //
UShort attributes; // other attributes //
#if defined (resource)
char label[];
char accessStr[];
#else
long labelLength;
char label[1];
#endif
} DItem_TextRsc;

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.

{
CMD_ACTIVE_LEVEL, MCMD, NOSYNONYM, NOHELP, MHELP, NOHOOK, NOARG,
2, "%-ld", "%ld", "1", "63", 0xff, CONCAT, "Level:",
"tcb->ad1.params.actlev"
};

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.

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